From 7f887bdc05765e357116f7f47cbbd9a4a1080333 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 27 Sep 2022 13:12:30 +0200 Subject: [PATCH 1/5] Move license out of Doxygen comment Signed-off-by: Gilles Peskine --- library/bignum_core.h | 3 +++ library/bignum_mod.h | 4 +++- library/bignum_mod_raw.h | 4 +++- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/library/bignum_core.h b/library/bignum_core.h index 8e227f8d8e..dc802ab4ef 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -6,6 +6,9 @@ * modules should use the high-level modular bignum interface (bignum_mod.h) * or the legacy bignum interface (bignum.h). * + */ + +/* * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 * diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 9d28bc7e45..982a9ac5c9 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -1,6 +1,8 @@ /** * Modular bignum functions - * + */ + +/* * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 * diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 7b3a0c177b..aba5d0699d 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -5,7 +5,9 @@ * module (bignum_mod.c) and the ECP module (ecp.c, ecp_curves.c). All other * modules should use the high-level modular bignum interface (bignum_mod.h) * or the legacy bignum interface (bignum.h). - * + */ + +/* * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 * From 7aab2fbe419ac06ad19185dd2caf3bf28f5c536e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 27 Sep 2022 13:19:13 +0200 Subject: [PATCH 2/5] Add a short description of what each module does There was already a short introduction to _who_ should use each module, but not to _what_ each module does. Signed-off-by: Gilles Peskine --- library/bignum_core.h | 5 +++++ library/bignum_mod.h | 2 ++ library/bignum_mod_raw.h | 6 ++++++ 3 files changed, 13 insertions(+) diff --git a/library/bignum_core.h b/library/bignum_core.h index dc802ab4ef..d64111b18e 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -6,6 +6,11 @@ * modules should use the high-level modular bignum interface (bignum_mod.h) * or the legacy bignum interface (bignum.h). * + * This module is about processing non-negative integers with a fixed upper + * bound that's of the form 2^#biL-1. Many operations treat these numbers + * as the principal representation of a number modulo 2^#biL or a smaller + * bound. + * */ /* diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 982a9ac5c9..c25eb87423 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -1,5 +1,7 @@ /** * Modular bignum functions + * + * This module implements operations on integers modulo some fixed modulus. */ /* diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index aba5d0699d..aef8a04e26 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -5,6 +5,12 @@ * module (bignum_mod.c) and the ECP module (ecp.c, ecp_curves.c). All other * modules should use the high-level modular bignum interface (bignum_mod.h) * or the legacy bignum interface (bignum.h). + * + * This is a low-level interface to operations on integers modulo which + * has no protection against passing invalid arguments such as arrays of + * the wrong size. The functions in bignum_mod.h provide a higher-level + * interface that includes protections against accidental misuse, at the + * expense of code size and sometimes more cumbersome memory management. */ /* From 2926484de15cfa6f26ff5a3c55ead699f3fba123 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 27 Sep 2022 13:19:50 +0200 Subject: [PATCH 3/5] Describe generic conventions for the bignum core module This commit codifies some conventions that result from the original design goals and others that have emerged after starting the implementation. * Value ranges * Bignum parameter naming and ordering * Sizes * Aliasing and overlap * Error handling Signed-off-by: Gilles Peskine --- library/bignum_core.h | 51 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/library/bignum_core.h b/library/bignum_core.h index d64111b18e..2274a8a904 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -11,6 +11,51 @@ * as the principal representation of a number modulo 2^#biL or a smaller * bound. * + * The functions in this module obey the following conventions unless + * explicitly indicated otherwise: + * + * - **Overflow**: some functions indicate overflow from the range + * [0, 2^#biL-1] by returning carry parameters, while others operate + * modulo and so cannot overflow. This should be clear from the function + * documentation. + * - **Bignum parameters**: Bignums are passed as pointers to an array of + * limbs. A limb has the type #mbedtls_mpi_uint. Unless otherwise specified: + * - Bignum parameters called \p A, \p B, ... are inputs, and are + * not modified by the function. + * - For operations modulo some number, the modulus is called \p N + * and is input-only. + * - Bignum parameters called \p X, \p Y are outputs or input-output. + * The initial content of output-only parameters is ignored. + * - Some functions use different names that reflect traditional + * naming of operands of certain operations (e.g. + * divisor/dividend/quotient/remainder). + * - \p T is a temporary storage area. The initial content of such + * parameter is ignored and the final content is unspecified. + * - **Bignum sizes**: bignum sizes are always expressed in limbs. + * Most functions work on bignums of a given size and take a single + * \p limbs parameter that applies to all parameters that are limb arrays. + * All bignum sizes must be at least 1 and must be significantly less than + * #SIZE_MAX. The behavior if a size is 0 is undefined. The behavior if the + * total size of all parameters overflows #SIZE_MAX is undefined. + * - **Parameter ordering**: for bignum parameters, outputs come before inputs. + * Temporaries come last. + * - **Aliasing**: in general, output bignums may be aliased to one or more + * inputs. As an exception, parameters that are documented as a modulus value + * may not be aliased to an output. Temporaries may not be aliased to + * any other parameter. + * - **Overlap**: apart from aliasing of limb array pointers (where two + * arguments are equal pointers), overlap is not supported and may result + * in undefined behavior. + * - **Error handling**: This is a low-level module. Functions generally do not + * try to protect against invalid arguments such as nonsensical sizes or + * null pointers. Note that some functions that operate on bignums of + * different sizes have constraints about their size, and violating those + * constraints may lead to buffer overflows. + * - **Modular representatives**: functions that operate modulo \p N expect + * all modular inputs to be in the range [0, \p N - 1] and guarantee outputs + * in the range [0, \p N - 1]. If an input is out of range, outputs are + * fully unspecified, though bignum values out of range should not cause + * buffer overflows (beware that this is not extensively tested). */ /* @@ -39,9 +84,9 @@ #include "mbedtls/bignum.h" #endif -#define ciL ( sizeof(mbedtls_mpi_uint) ) /* chars in limb */ -#define biL ( ciL << 3 ) /* bits in limb */ -#define biH ( ciL << 2 ) /* half limb size */ +#define ciL ( sizeof(mbedtls_mpi_uint) ) /** chars in limb */ +#define biL ( ciL << 3 ) /** bits in limb */ +#define biH ( ciL << 2 ) /** half limb size */ /* * Convert between bits/chars and number of limbs From 01af3ddc82e101974dd1e8b9c45ac909d9032c34 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 4 Oct 2022 16:23:29 +0200 Subject: [PATCH 4/5] Fixed confusion between number size and limb size; define limb Signed-off-by: Gilles Peskine --- library/bignum_core.h | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/library/bignum_core.h b/library/bignum_core.h index 2274a8a904..c64ce4e866 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -7,15 +7,17 @@ * or the legacy bignum interface (bignum.h). * * This module is about processing non-negative integers with a fixed upper - * bound that's of the form 2^#biL-1. Many operations treat these numbers - * as the principal representation of a number modulo 2^#biL or a smaller - * bound. + * bound that's of the form 2^n-1 where n is a multiple of #biL. + * These can be thought of integers written in base 2^#biL with a fixed + * number of digits. Digits in this base are called *limbs*. + * Many operations treat these numbers as the principal representation of + * a number modulo 2^n or a smaller bound. * * The functions in this module obey the following conventions unless * explicitly indicated otherwise: * * - **Overflow**: some functions indicate overflow from the range - * [0, 2^#biL-1] by returning carry parameters, while others operate + * [0, 2^n-1] by returning carry parameters, while others operate * modulo and so cannot overflow. This should be clear from the function * documentation. * - **Bignum parameters**: Bignums are passed as pointers to an array of From dcd1717f5f90abe1116e20b3b0924c700298a5ef Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 14 Oct 2022 17:14:20 +0200 Subject: [PATCH 5/5] Forbid aliasing outputs Aliasing between two outputs is hardly ever useful. Signed-off-by: Gilles Peskine --- library/bignum_core.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/bignum_core.h b/library/bignum_core.h index c64ce4e866..4426b92386 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -43,8 +43,8 @@ * Temporaries come last. * - **Aliasing**: in general, output bignums may be aliased to one or more * inputs. As an exception, parameters that are documented as a modulus value - * may not be aliased to an output. Temporaries may not be aliased to - * any other parameter. + * may not be aliased to an output. Outputs may not be aliased to one another. + * Temporaries may not be aliased to any other parameter. * - **Overlap**: apart from aliasing of limb array pointers (where two * arguments are equal pointers), overlap is not supported and may result * in undefined behavior.