From 7aab2fbe419ac06ad19185dd2caf3bf28f5c536e Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 27 Sep 2022 13:19:13 +0200 Subject: [PATCH] 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 dc802ab4e..d64111b18 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 982a9ac5c..c25eb8742 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 aba5d0699..aef8a04e2 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. */ /*