From 5e9d2e901904c3cf2c9ee8f89429ef74d0daf148 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Mon, 12 Dec 2022 14:00:25 +0000 Subject: [PATCH 01/12] Add conventions for bignum mod and mod_raw Signed-off-by: Werner Lewis --- library/bignum_mod.h | 55 ++++++++++++++++++++++++++++++++++++++++ library/bignum_mod_raw.h | 43 +++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 0a8f4d3d0c..ab00c93033 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -2,6 +2,61 @@ * Modular bignum functions * * This module implements operations on integers modulo some fixed modulus. + * + * The functions in this module obey the following conventions unless + * explicitly indicated otherwise: + * + * - **Modulus parameters**: the modulus is passed as a pointer to a structure + * of type #mbedtls_mpi_mod_modulus. The structure must be setup with an + * array of limbs storing the bignum value of the modulus. Unless otherwise + * specified, the modulus is called \p N and is input-only. + * - **Bignum parameters**: Bignums are passed as pointers to an array of + * limbs or to a #mbedtls_mpi_mod_residue structure. A limb has the type + * #mbedtls_mpi_uint. Residues must be initialized before use, and must be + * associated with the modulus \p N. Unless otherwise specified: + * - Bignum parameters called \p A, \p B, ... are inputs and are not + * modified by the function. These will have the type + * #mbedtls_mpi_mod_residue. + * - Bignum parameters called \p X, \p Y, ... are outputs or input-output. + * The initial content of output-only parameters is ignored. These will + * have the type #mbedtls_mpi_mod_residue. + * - Bignum parameters called \p P are inputs used to setup a modulus or + * residue. These must be pointers to an array of limbs. + * - \p T is a temporary storage area. The initial content of such + * parameter is ignored and the final content is unspecified. + * - Some functions use different names, such as \p R for the residue. + * - **Bignum sizes**: bignum sizes are always expressed in limbs. Both + * #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \p limbs + * member storing its size. Functions which take a limb array parameter + * must also take an associated \p limbs parameter specifying its size. + * All bignum sizes must be at least 1 and be significantly less than + * #SIZE_MAX. The behavior if a size is 0 may be undefined or an error + * may be returned. All bignum parameters must have the same size unless + * otherwise specified. + * - **Bignum representation**: the representation of inputs and outputs is + * specified by the \p int_rep field of the modulus. + * - **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. Modulus values may not be aliased to any other parameter. Outputs + * may not be aliased to one another. Temporaries may not be aliased to any + * other parameter. + * - **Overlap**: apart from aliasing of residue pointers (where two residue + * arguments are equal pointers), overlap is not supported and may result + * in undefined behavior. + * - **Error handling**: functions generally check compatability of input + * sizes. Most functions will not check that input values are in canonical + * form (i.e. that \p A < \p N), this is only checked during setup of a + * residue structure. + * - **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]. Residues are setup with an associated modulus, + * and operations are only guaranteed to work if the modulus is associated + * with all residue parameters. If a residue is passed with a modulus other + * than the one it is associated with, then it may be out of range. 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). */ /* diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 698119e19b..56e5cbc2ea 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -11,6 +11,49 @@ * 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. + * + * The functions in this module obey the following conventions unless + * explicitly indicated otherwise: + * - **Modulus parameters**: the modulus is passed as a pointer to a structure + * of type #mbedtls_mpi_mod_modulus. The structure must be setup with an + * array of limbs storing the bignum value of the modulus. Unless otherwise + * specified, the modulus is called \p N and is input-only. + * - **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. + * - Bignum parameters called \p X, \p Y are outputs or input-output. + * The initial content of output-only parameters is ignored. + * - \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 by the \p limbs + * member of the modulus argument. Any bignum parameters must have the same + * number of limbs as the modulus. 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. + * - **Bignum representation**: the representation of inputs and outputs is + * specified by the \p int_rep field of the modulus for arithmetic + * functions. Utility functions may allow for different representation. + * - **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. Modulus values may not be aliased to any other parameter. 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. + * - **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 passing bignums with a different size than the + * modulus may lead to buffer overflows. Some functions which allocate + * memory or handle reading/writing of bignums will return an error if + * memory allocation fails or if buffer sizes are invalid. + * - **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). */ /* From e1eb75dc992445837d1ca44cffa4cce9d8c7dc9e Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 13:45:49 +0000 Subject: [PATCH 02/12] Specify modulus constraints Signed-off-by: Werner Lewis --- library/bignum_mod.h | 7 ++++--- library/bignum_mod_raw.h | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index ab00c93033..f2fd7e2457 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -7,9 +7,10 @@ * explicitly indicated otherwise: * * - **Modulus parameters**: the modulus is passed as a pointer to a structure - * of type #mbedtls_mpi_mod_modulus. The structure must be setup with an - * array of limbs storing the bignum value of the modulus. Unless otherwise - * specified, the modulus is called \p N and is input-only. + * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an + * array of limbs storing the bignum value of the modulus. The modulus must + * be odd and is assumed to have no leading zeroes. The modulus is usually + * named \p N and is usually input-only. * - **Bignum parameters**: Bignums are passed as pointers to an array of * limbs or to a #mbedtls_mpi_mod_residue structure. A limb has the type * #mbedtls_mpi_uint. Residues must be initialized before use, and must be diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 56e5cbc2ea..7559ae8c63 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -15,9 +15,10 @@ * The functions in this module obey the following conventions unless * explicitly indicated otherwise: * - **Modulus parameters**: the modulus is passed as a pointer to a structure - * of type #mbedtls_mpi_mod_modulus. The structure must be setup with an - * array of limbs storing the bignum value of the modulus. Unless otherwise - * specified, the modulus is called \p N and is input-only. + * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an + * array of limbs storing the bignum value of the modulus. The modulus must + * be odd and is assumed to have no leading zeroes. The modulus is usually + * named \p N and is usually input-only. * - **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 From eac8be76d6b9376124fbda82d8b74386a8137f67 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 13:49:12 +0000 Subject: [PATCH 03/12] Remove unnecessary type comment Signed-off-by: Werner Lewis --- library/bignum_mod.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index f2fd7e2457..6599e11deb 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -16,8 +16,7 @@ * #mbedtls_mpi_uint. Residues must be initialized before use, and must be * associated with the modulus \p N. Unless otherwise specified: * - Bignum parameters called \p A, \p B, ... are inputs and are not - * modified by the function. These will have the type - * #mbedtls_mpi_mod_residue. + * modified by the function. * - Bignum parameters called \p X, \p Y, ... are outputs or input-output. * The initial content of output-only parameters is ignored. These will * have the type #mbedtls_mpi_mod_residue. From 945a165a3cf459adb99594699afc63e6c06a5ee8 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 15:24:46 +0000 Subject: [PATCH 04/12] Clarify output requirements Signed-off-by: Werner Lewis --- library/bignum_mod.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 6599e11deb..d7404aee8e 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -18,8 +18,8 @@ * - Bignum parameters called \p A, \p B, ... are inputs and are not * modified by the function. * - Bignum parameters called \p X, \p Y, ... are outputs or input-output. - * The initial content of output-only parameters is ignored. These will - * have the type #mbedtls_mpi_mod_residue. + * The initial bignum value of output-only parameters is ignored, but + * they must be set up and associated with the modulus \p N. * - Bignum parameters called \p P are inputs used to setup a modulus or * residue. These must be pointers to an array of limbs. * - \p T is a temporary storage area. The initial content of such From 2bd263da1e5f6aab327443a4d157dfc0189f0998 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 15:32:31 +0000 Subject: [PATCH 05/12] Fix grammar and spelling Signed-off-by: Werner Lewis --- library/bignum_mod.h | 6 +++--- library/bignum_mod_raw.h | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index d7404aee8e..f1067f0185 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -20,9 +20,9 @@ * - Bignum parameters called \p X, \p Y, ... are outputs or input-output. * The initial bignum value of output-only parameters is ignored, but * they must be set up and associated with the modulus \p N. - * - Bignum parameters called \p P are inputs used to setup a modulus or + * - Bignum parameters called \p P are inputs used to set up a modulus or * residue. These must be pointers to an array of limbs. - * - \p T is a temporary storage area. The initial content of such + * - \p T is a temporary storage area. The initial content of such a * parameter is ignored and the final content is unspecified. * - Some functions use different names, such as \p R for the residue. * - **Bignum sizes**: bignum sizes are always expressed in limbs. Both @@ -44,7 +44,7 @@ * - **Overlap**: apart from aliasing of residue pointers (where two residue * arguments are equal pointers), overlap is not supported and may result * in undefined behavior. - * - **Error handling**: functions generally check compatability of input + * - **Error handling**: functions generally check compatibility of input * sizes. Most functions will not check that input values are in canonical * form (i.e. that \p A < \p N), this is only checked during setup of a * residue structure. diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 7559ae8c63..bcdeaad6d2 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -25,7 +25,7 @@ * modified by the function. * - Bignum parameters called \p X, \p Y are outputs or input-output. * The initial content of output-only parameters is ignored. - * - \p T is a temporary storage area. The initial content of such + * - \p T is a temporary storage area. The initial content of such a * parameter is ignored and the final content is unspecified. * - **Bignum sizes**: bignum sizes are always expressed by the \p limbs * member of the modulus argument. Any bignum parameters must have the same From 2e70b9afef16db10022e37d82b8a3c43152c1471 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 15:48:31 +0000 Subject: [PATCH 06/12] Reword bignum sizes section Signed-off-by: Werner Lewis --- library/bignum_mod.h | 12 +++++------- library/bignum_mod_raw.h | 4 ++-- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index f1067f0185..67684bd677 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -26,13 +26,11 @@ * parameter is ignored and the final content is unspecified. * - Some functions use different names, such as \p R for the residue. * - **Bignum sizes**: bignum sizes are always expressed in limbs. Both - * #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \p limbs - * member storing its size. Functions which take a limb array parameter - * must also take an associated \p limbs parameter specifying its size. - * All bignum sizes must be at least 1 and be significantly less than - * #SIZE_MAX. The behavior if a size is 0 may be undefined or an error - * may be returned. All bignum parameters must have the same size unless - * otherwise specified. + * #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \c limbs + * member storing its size. All bignum parameters must have the same + * number of limbs as the modulus. 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. * - **Bignum representation**: the representation of inputs and outputs is * specified by the \p int_rep field of the modulus. * - **Parameter ordering**: for bignum parameters, outputs come before inputs. diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index bcdeaad6d2..ddb2d09564 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -27,8 +27,8 @@ * The initial content of output-only parameters is ignored. * - \p T is a temporary storage area. The initial content of such a * parameter is ignored and the final content is unspecified. - * - **Bignum sizes**: bignum sizes are always expressed by the \p limbs - * member of the modulus argument. Any bignum parameters must have the same + * - **Bignum sizes**: bignum sizes are usually expressed by the \c limbs + * member of the modulus argument. All bignum parameters must have the same * number of limbs as the modulus. 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. From a306886b3aa86db884d0d640ed278a6250c47245 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 15:57:12 +0000 Subject: [PATCH 07/12] Add modulus to parameter ordering Signed-off-by: Werner Lewis --- library/bignum_mod.h | 2 +- library/bignum_mod_raw.h | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 67684bd677..497f4b5b5a 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -34,7 +34,7 @@ * - **Bignum representation**: the representation of inputs and outputs is * specified by the \p int_rep field of the modulus. * - **Parameter ordering**: for bignum parameters, outputs come before inputs. - * Temporaries come last. + * The modulus is passed after residues. Temporaries come last. * - **Aliasing**: in general, output bignums may be aliased to one or more * inputs. Modulus values may not be aliased to any other parameter. Outputs * may not be aliased to one another. Temporaries may not be aliased to any diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index ddb2d09564..93df46f622 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -36,7 +36,8 @@ * specified by the \p int_rep field of the modulus for arithmetic * functions. Utility functions may allow for different representation. * - **Parameter ordering**: for bignum parameters, outputs come before inputs. - * Temporaries come last. + * The modulus is passed after other bignum input parameters. Temporaries + * come last. * - **Aliasing**: in general, output bignums may be aliased to one or more * inputs. Modulus values may not be aliased to any other parameter. Outputs * may not be aliased to one another. Temporaries may not be aliased to any From 1d89ebf548e55241617592c68045231b06c76213 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Wed, 14 Dec 2022 17:08:43 +0000 Subject: [PATCH 08/12] Clarify all functions operate modulo N Signed-off-by: Werner Lewis --- library/bignum_mod.h | 18 +++++++++--------- library/bignum_mod_raw.h | 10 +++++----- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 497f4b5b5a..a8e705e80a 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -46,15 +46,15 @@ * sizes. Most functions will not check that input values are in canonical * form (i.e. that \p A < \p N), this is only checked during setup of a * residue structure. - * - **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]. Residues are setup with an associated modulus, - * and operations are only guaranteed to work if the modulus is associated - * with all residue parameters. If a residue is passed with a modulus other - * than the one it is associated with, then it may be out of range. 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). + * - **Modular representatives**: all functions expect inputs to be in the + * range [0, \p N - 1] and guarantee outputs in the range [0, \p N - 1]. + * Residues are set up with an associated modulus, and operations are only + * guaranteed to work if the modulus is associated with all residue + * parameters. If a residue is passed with a modulus other than the one it + * is associated with, then it may be out of range. 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). */ /* diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 93df46f622..174cc6e56f 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -51,11 +51,11 @@ * modulus may lead to buffer overflows. Some functions which allocate * memory or handle reading/writing of bignums will return an error if * memory allocation fails or if buffer sizes are invalid. - * - **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). + * - **Modular representatives**: all functions expect 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). */ /* From 214ae643499fdaafedc169282de991bf1fe96f76 Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 15 Dec 2022 10:57:59 +0000 Subject: [PATCH 09/12] Replace \p with \c for non-parameter code typeset Signed-off-by: Werner Lewis --- library/bignum_mod.h | 22 +++++++++++----------- library/bignum_mod_raw.h | 12 ++++++------ 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index a8e705e80a..ee5e0bfb53 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -10,21 +10,21 @@ * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an * array of limbs storing the bignum value of the modulus. The modulus must * be odd and is assumed to have no leading zeroes. The modulus is usually - * named \p N and is usually input-only. + * named \c N and is usually input-only. * - **Bignum parameters**: Bignums are passed as pointers to an array of * limbs or to a #mbedtls_mpi_mod_residue structure. A limb has the type * #mbedtls_mpi_uint. Residues must be initialized before use, and must be - * associated with the modulus \p N. Unless otherwise specified: - * - Bignum parameters called \p A, \p B, ... are inputs and are not + * associated with the modulus \c N. Unless otherwise specified: + * - Bignum parameters called \c A, \c B, ... are inputs and are not * modified by the function. - * - Bignum parameters called \p X, \p Y, ... are outputs or input-output. + * - Bignum parameters called \c X, \c Y, ... are outputs or input-output. * The initial bignum value of output-only parameters is ignored, but - * they must be set up and associated with the modulus \p N. - * - Bignum parameters called \p P are inputs used to set up a modulus or + * they must be set up and associated with the modulus \c N. + * - Bignum parameters called \c P are inputs used to set up a modulus or * residue. These must be pointers to an array of limbs. - * - \p T is a temporary storage area. The initial content of such a + * - \c T is a temporary storage area. The initial content of such a * parameter is ignored and the final content is unspecified. - * - Some functions use different names, such as \p R for the residue. + * - Some functions use different names, such as \c R for the residue. * - **Bignum sizes**: bignum sizes are always expressed in limbs. Both * #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \c limbs * member storing its size. All bignum parameters must have the same @@ -32,7 +32,7 @@ * must be significantly less than #SIZE_MAX. The behavior if a size is 0 is * undefined. * - **Bignum representation**: the representation of inputs and outputs is - * specified by the \p int_rep field of the modulus. + * specified by the \c int_rep field of the modulus. * - **Parameter ordering**: for bignum parameters, outputs come before inputs. * The modulus is passed after residues. Temporaries come last. * - **Aliasing**: in general, output bignums may be aliased to one or more @@ -44,10 +44,10 @@ * in undefined behavior. * - **Error handling**: functions generally check compatibility of input * sizes. Most functions will not check that input values are in canonical - * form (i.e. that \p A < \p N), this is only checked during setup of a + * form (i.e. that \c A < \c N), this is only checked during setup of a * residue structure. * - **Modular representatives**: all functions expect inputs to be in the - * range [0, \p N - 1] and guarantee outputs in the range [0, \p N - 1]. + * range [0, \c N - 1] and guarantee outputs in the range [0, \c N - 1]. * Residues are set up with an associated modulus, and operations are only * guaranteed to work if the modulus is associated with all residue * parameters. If a residue is passed with a modulus other than the one it diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 174cc6e56f..6f424cabf5 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -18,14 +18,14 @@ * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an * array of limbs storing the bignum value of the modulus. The modulus must * be odd and is assumed to have no leading zeroes. The modulus is usually - * named \p N and is usually input-only. + * named \c N and is usually input-only. * - **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 + * - Bignum parameters called \c A, \c B, ... are inputs, and are not * modified by the function. - * - Bignum parameters called \p X, \p Y are outputs or input-output. + * - Bignum parameters called \c X, \c Y are outputs or input-output. * The initial content of output-only parameters is ignored. - * - \p T is a temporary storage area. The initial content of such a + * - \c T is a temporary storage area. The initial content of such a * parameter is ignored and the final content is unspecified. * - **Bignum sizes**: bignum sizes are usually expressed by the \c limbs * member of the modulus argument. All bignum parameters must have the same @@ -33,7 +33,7 @@ * must be significantly less than #SIZE_MAX. The behavior if a size is 0 is * undefined. * - **Bignum representation**: the representation of inputs and outputs is - * specified by the \p int_rep field of the modulus for arithmetic + * specified by the \c int_rep field of the modulus for arithmetic * functions. Utility functions may allow for different representation. * - **Parameter ordering**: for bignum parameters, outputs come before inputs. * The modulus is passed after other bignum input parameters. Temporaries @@ -52,7 +52,7 @@ * memory or handle reading/writing of bignums will return an error if * memory allocation fails or if buffer sizes are invalid. * - **Modular representatives**: all functions expect inputs to be in the - * range [0, \p N - 1] and guarantee outputs in the range [0, \p N - 1]. If + * range [0, \c N - 1] and guarantee outputs in the range [0, \c 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). From 0f644f48e92ec10ca7f7c9941dbcdcfd6faf6d3f Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 15 Dec 2022 14:13:32 +0000 Subject: [PATCH 10/12] Add output initialization requirement Signed-off-by: Werner Lewis --- library/bignum_mod.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index ee5e0bfb53..e03c9aa2ec 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -19,7 +19,9 @@ * modified by the function. * - Bignum parameters called \c X, \c Y, ... are outputs or input-output. * The initial bignum value of output-only parameters is ignored, but - * they must be set up and associated with the modulus \c N. + * they must be set up and associated with the modulus \c N. Some + * functions (typically constant-flow) require that the limbs in an + * output residue are initialized. * - Bignum parameters called \c P are inputs used to set up a modulus or * residue. These must be pointers to an array of limbs. * - \c T is a temporary storage area. The initial content of such a From 756a34aadcede47864e94329e65fc1538b21870e Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 15 Dec 2022 14:53:43 +0000 Subject: [PATCH 11/12] Use lower case for p and r Signed-off-by: Werner Lewis --- library/bignum_mod.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index e03c9aa2ec..96bbaca0fc 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -22,11 +22,11 @@ * they must be set up and associated with the modulus \c N. Some * functions (typically constant-flow) require that the limbs in an * output residue are initialized. - * - Bignum parameters called \c P are inputs used to set up a modulus or + * - Bignum parameters called \c p are inputs used to set up a modulus or * residue. These must be pointers to an array of limbs. * - \c T is a temporary storage area. The initial content of such a * parameter is ignored and the final content is unspecified. - * - Some functions use different names, such as \c R for the residue. + * - Some functions use different names, such as \c r for the residue. * - **Bignum sizes**: bignum sizes are always expressed in limbs. Both * #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \c limbs * member storing its size. All bignum parameters must have the same From 6bb49ba121353c1c079564ac86ebc9dc4047c50b Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 15 Dec 2022 16:58:44 +0000 Subject: [PATCH 12/12] Document const parameter conventions Signed-off-by: Werner Lewis --- library/bignum_mod.h | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 96bbaca0fc..bae671ca64 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -10,13 +10,15 @@ * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an * array of limbs storing the bignum value of the modulus. The modulus must * be odd and is assumed to have no leading zeroes. The modulus is usually - * named \c N and is usually input-only. + * named \c N and is usually input-only. Functions which take a parameter + * of type \c const #mbedtls_mpi_mod_modulus* must not modify its value. * - **Bignum parameters**: Bignums are passed as pointers to an array of * limbs or to a #mbedtls_mpi_mod_residue structure. A limb has the type * #mbedtls_mpi_uint. Residues must be initialized before use, and must be * associated with the modulus \c N. Unless otherwise specified: * - Bignum parameters called \c A, \c B, ... are inputs and are not - * modified by the function. + * modified by the function. Functions which take a parameter of + * type \c const #mbedtls_mpi_mod_residue* must not modify its value. * - Bignum parameters called \c X, \c Y, ... are outputs or input-output. * The initial bignum value of output-only parameters is ignored, but * they must be set up and associated with the modulus \c N. Some