From 5c799e88ef7011f61b34ca8926fe413db3dbbb5b Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Tue, 15 Oct 2019 21:05:05 +0200 Subject: [PATCH 01/20] don't build docs, manual is enough --- makefile | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/makefile b/makefile index de65c9c..df296de 100644 --- a/makefile +++ b/makefile @@ -133,7 +133,7 @@ pre_gen: sed -e 's/[[:blank:]]*$$//' mpi.c > pre_gen/mpi.c rm mpi.c -zipup: clean astyle new_file manual poster docs +zipup: clean astyle new_file manual poster @# Update the index, so diff-index won't fail in case the pdf has been created. @# As the pdf creation modifies the tex files, git sometimes detects the @# modified files, but misses that it's put back to its original version. @@ -145,12 +145,11 @@ zipup: clean astyle new_file manual poster docs @echo 'fixme check' -@(find libtommath-$(VERSION)/ -type f | xargs grep 'FIXM[E]') && echo '############## BEWARE: the "fixme" marker was found !!! ##############' || true mkdir -p libtommath-$(VERSION)/doc - cp doc/bn.pdf doc/tommath.pdf doc/poster.pdf libtommath-$(VERSION)/doc/ + cp doc/bn.pdf doc/poster.pdf libtommath-$(VERSION)/doc/ $(MAKE) -C libtommath-$(VERSION)/ pre_gen tar -c libtommath-$(VERSION)/ | xz -6e -c - > ltm-$(VERSION).tar.xz zip -9rq ltm-$(VERSION).zip libtommath-$(VERSION) cp doc/bn.pdf bn-$(VERSION).pdf - cp doc/tommath.pdf tommath-$(VERSION).pdf rm -rf libtommath-$(VERSION) gpg -b -a ltm-$(VERSION).tar.xz gpg -b -a ltm-$(VERSION).zip From 8adc90411a8afc6a8e4028557deff1c5b1361273 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Tue, 15 Oct 2019 21:09:43 +0200 Subject: [PATCH 02/20] bump version --- appveyor.yml | 2 +- doc/bn.tex | 2 +- makefile.unix | 2 +- makefile_include.mk | 6 +++--- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/appveyor.yml b/appveyor.yml index c4a13a0..7d85d3f 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,4 +1,4 @@ -version: 1.1.0-{build} +version: 1.2.0-{build} branches: only: - master diff --git a/doc/bn.tex b/doc/bn.tex index 3174187..a529038 100644 --- a/doc/bn.tex +++ b/doc/bn.tex @@ -50,7 +50,7 @@ \begin{document} \frontmatter \pagestyle{empty} -\title{LibTomMath User Manual \\ v1.1.0} +\title{LibTomMath User Manual \\ v1.2.0} \author{LibTom Projects \\ www.libtom.net} \maketitle This text, the library and the accompanying textbook are all hereby placed in the public domain. This book has been diff --git a/makefile.unix b/makefile.unix index 750be56..4cefc7e 100644 --- a/makefile.unix +++ b/makefile.unix @@ -21,7 +21,7 @@ RANLIB = ranlib CFLAGS = -O2 LDFLAGS = -VERSION = 1.1.0 +VERSION = 1.2.0 #Compilation flags LTM_CFLAGS = -I. $(CFLAGS) diff --git a/makefile_include.mk b/makefile_include.mk index cdf0fa7..a4b36b5 100644 --- a/makefile_include.mk +++ b/makefile_include.mk @@ -3,9 +3,9 @@ # #version of library -VERSION=1.1.0-develop -VERSION_PC=1.1.0 -VERSION_SO=2:0:1 +VERSION=1.2.0-rc1 +VERSION_PC=1.2.0 +VERSION_SO=3:0:1 PLATFORM := $(shell uname | sed -e 's/_.*//') From ef1675f1acb050c26e98ed149d7b01ec4fa441ac Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Wed, 16 Oct 2019 14:30:45 +0200 Subject: [PATCH 03/20] add missing indexes in doc --- doc/bn.tex | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/bn.tex b/doc/bn.tex index a529038..5937fee 100644 --- a/doc/bn.tex +++ b/doc/bn.tex @@ -825,7 +825,8 @@ int main(void) These functions can be used to set a constant with 32 or 64 bits. -\index{mp\_set\_int} +\index{mp\_set\_i32} \index{mp\_set\_u32} +\index{mp\_set\_i64} \index{mp\_set\_u64} \begin{alltt} void mp_set_i32 (mp_int * a, int32_t b); void mp_set_u32 (mp_int * a, uint32_t b); @@ -836,7 +837,8 @@ void mp_set_u64 (mp_int * a, uint64_t b); These functions assign the sign and value of the input \texttt{b} to \texttt{mp\_int a}. The value can be obtained again by calling the following functions. -\index{mp\_get\_int} +\index{mp\_get\_i32} \index{mp\_get\_u32} \index{mp\_get\_mag\_u32} +\index{mp\_get\_i64} \index{mp\_get\_u64} \index{mp\_get\_mag\_u64} \begin{alltt} int32_t mp_get_i32 (mp_int * a); uint32_t mp_get_u32 (mp_int * a); @@ -881,7 +883,7 @@ number == 654321 \subsection{Long Constants - platform dependant} -\index{mp\_set\_ulong} +\index{mp\_set\_l} \index{mp\_set\_ul} \begin{alltt} void mp_set_l (mp_int * a, long b); void mp_set_ul (mp_int * a, unsigned long b); @@ -891,7 +893,7 @@ This will assign the value of the platform-dependent sized variable $b$ to the m To retrieve the value, the following functions can be used. -\index{mp\_get\_ulong} +\index{mp\_get\_l} \index{mp\_get\_ul} \index{mp\_get\_mag\_ul} \begin{alltt} long mp_get_l (mp_int * a); unsigned long mp_get_ul (mp_int * a); @@ -902,7 +904,7 @@ This will return the least significant bits of the mp\_int $a$ that fit into a ` \subsection{Long Long Constants - platform dependant} -\index{mp\_set\_ulonglong} +\index{mp\_set\_ll} \index{mp\_set\_ull} \begin{alltt} void mp_set_ll (mp_int * a, long long b); void mp_set_ull (mp_int * a, unsigned long long b); @@ -912,7 +914,9 @@ This will assign the value of the platform-dependent sized variable $b$ to the m To retrieve the value, the following functions can be used. -\index{mp\_get\_ulonglong} +\index{mp\_get\_ll} +\index{mp\_get\_ull} +\index{mp\_get\_mag\_ull} \begin{alltt} long long mp_get_ll (mp_int * a); unsigned long long mp_get_ull (mp_int * a); @@ -2075,7 +2079,7 @@ mp\_prime\_is\_prime for details regarding the use of the argument $t$. Set $bb want only the next prime congruent to $3 \mbox{ mod } 4$, otherwise set it to zero to find any next prime. \section{Random Primes} -\index{mp\_prime\_random\_ex} +\index{mp\_prime\_rand} \begin{alltt} int mp_prime_rand(mp_int *a, int t, int size, int flags); From d4f5382cb250c1f8ea7060338a62c431b09e3a2b Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Wed, 16 Oct 2019 15:16:03 +0200 Subject: [PATCH 04/20] update changelog --- changes.txt | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/changes.txt b/changes.txt index aa0c64c..d9a4fbb 100644 --- a/changes.txt +++ b/changes.txt @@ -1,3 +1,33 @@ +XXX XXth, 2019 +v1.2.0 + -- A huge refactoring of the library happened - renaming, + deprecating and replacing existing functions by improved API's. + + All deprecated functions, macros and symbols are only marked as such + so this version is still API and ABI compatible to v1.x. + + -- Daniel Mendler was pushing for those changes and contributing a load of patches, + refactorings, code reviews and whatnotelse. + -- Christoph Zurnieden re-worked internals of the library, improved the performance, + did code reviews and wrote documentation. + -- Francois Perrad did some refactoring and took again care of linting the sources and + provided all fixes. + -- Jan Nijtmans, Karel Miko and Joachim Breitner contributed various patches. + + -- Private symbols can now be hidden for the shared library builds, disabled by default. + -- All API's follow a single code style, are prefixed the same etc. + -- Unified, safer and improved API's + -- Less magic numbers - return values (where appropriate) and most flags are now enums, + this was implemented in a backwards compatible way where return values were int. + -- Provide a whole set of setters&getters for different primitive types (long, uint32_t, etc.) + -- All those primitive setters are now optimized. + -- It's possible to automatically tune the cutoff values for Karatsuba&Toom-Cook + -- Added mp_decr() and mp_incr() + -- Added mp_log_u32() + -- Improved prime-checking + -- Improved Toom-Cook multiplication + + Jan 28th, 2019 v1.1.0 -- Christoph Zurnieden contributed FIPS 186.4 compliant From 29c597e0e3645187651b3eab8ea1c654cb5381dc Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Wed, 16 Oct 2019 15:35:05 +0200 Subject: [PATCH 05/20] mention `MP_WUR` in changelog [skip ci] --- changes.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changes.txt b/changes.txt index d9a4fbb..c49429d 100644 --- a/changes.txt +++ b/changes.txt @@ -19,6 +19,8 @@ v1.2.0 -- Unified, safer and improved API's -- Less magic numbers - return values (where appropriate) and most flags are now enums, this was implemented in a backwards compatible way where return values were int. + -- API's with return values are now by default marked as "warn on unsused result", this + can be disabled if required (which will most likely hide bugs), c.f. MP_WUR in tommath.h -- Provide a whole set of setters&getters for different primitive types (long, uint32_t, etc.) -- All those primitive setters are now optimized. -- It's possible to automatically tune the cutoff values for Karatsuba&Toom-Cook From 11ab738e38888498cd21ae5f8b7cea7e1891d360 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 17 Oct 2019 11:48:06 +0200 Subject: [PATCH 06/20] fix SO version --- makefile_include.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makefile_include.mk b/makefile_include.mk index a4b36b5..1c473bd 100644 --- a/makefile_include.mk +++ b/makefile_include.mk @@ -5,7 +5,7 @@ #version of library VERSION=1.2.0-rc1 VERSION_PC=1.2.0 -VERSION_SO=3:0:1 +VERSION_SO=3:0:2 PLATFORM := $(shell uname | sed -e 's/_.*//') From 45bef94f88054f8db290de28ddb007a818c32774 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 17 Oct 2019 12:22:11 +0200 Subject: [PATCH 07/20] bump version --- makefile_include.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makefile_include.mk b/makefile_include.mk index 1c473bd..00ae204 100644 --- a/makefile_include.mk +++ b/makefile_include.mk @@ -3,7 +3,7 @@ # #version of library -VERSION=1.2.0-rc1 +VERSION=1.2.0-rc2 VERSION_PC=1.2.0 VERSION_SO=3:0:2 From 21b4b012333c4c8401e5db1f24e7ca1e1a4e7ea0 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Thu, 17 Oct 2019 16:51:15 +0200 Subject: [PATCH 08/20] add MP_MALLOC etc. to changelog [skip ci] --- changes.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/changes.txt b/changes.txt index c49429d..6f44409 100644 --- a/changes.txt +++ b/changes.txt @@ -24,6 +24,9 @@ v1.2.0 -- Provide a whole set of setters&getters for different primitive types (long, uint32_t, etc.) -- All those primitive setters are now optimized. -- It's possible to automatically tune the cutoff values for Karatsuba&Toom-Cook + -- The custom allocators which were formerly known as XMALLOC(), XFREE() etc. are now available + as MP_MALLOC(), MP_REALLOC(), MP_CALLOC() and MP_FREE(). MP_REALLOC() and MP_FREE() now also + provide the allocated size to ease the usage of simple allocators without tracking. -- Added mp_decr() and mp_incr() -- Added mp_log_u32() -- Improved prime-checking From 6ba670909e43eebac01b27c0c3353e946beb7c41 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Fri, 18 Oct 2019 10:16:49 +0200 Subject: [PATCH 09/20] use labs() instead of abs() --- mtest/mpi.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mtest/mpi.c b/mtest/mpi.c index 95c3811..7e71ad6 100644 --- a/mtest/mpi.c +++ b/mtest/mpi.c @@ -494,7 +494,7 @@ void mp_set(mp_int *mp, mp_digit d) mp_err mp_set_int(mp_int *mp, long z) { int ix; - unsigned long v = abs(z); + unsigned long v = labs(z); mp_err res; ARGCHK(mp != NULL, MP_BADARG); From 785e32eb9cb0cecf6078927d970a7d665d26096e Mon Sep 17 00:00:00 2001 From: nijtmans Date: Fri, 18 Oct 2019 14:35:08 +0200 Subject: [PATCH 10/20] Move disabling of warning C4003 from makefile.msvc to tommath_private.h --- makefile.msvc | 2 +- tommath_private.h | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/makefile.msvc b/makefile.msvc index d282e93..d155bc6 100644 --- a/makefile.msvc +++ b/makefile.msvc @@ -14,7 +14,7 @@ PREFIX = c:\devel CFLAGS = /Ox #Compilation flags -LTM_CFLAGS = /nologo /I./ /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_DEPRECATE /D__STDC_WANT_SECURE_LIB__=1 /D_CRT_HAS_CXX17=0 /Wall /wd4146 /wd4127 /wd4710 /wd4711 /wd4820 /wd4003 /WX $(CFLAGS) +LTM_CFLAGS = /nologo /I./ /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_DEPRECATE /D__STDC_WANT_SECURE_LIB__=1 /D_CRT_HAS_CXX17=0 /Wall /wd4146 /wd4127 /wd4710 /wd4711 /wd4820 /WX $(CFLAGS) LTM_LDFLAGS = advapi32.lib #Libraries to be created (this makefile builds only static libraries) diff --git a/tommath_private.h b/tommath_private.h index 7c167a5..bc7d908 100644 --- a/tommath_private.h +++ b/tommath_private.h @@ -141,6 +141,9 @@ extern void MP_FREE(void *mem, size_t size); #endif /* feature detection macro */ +#ifdef _MSC_VER +#pragma warning(disable: 4003) +#endif #define MP_STRINGIZE(x) MP__STRINGIZE(x) #define MP__STRINGIZE(x) ""#x"" #define MP_HAS(x) (sizeof(MP_STRINGIZE(BN_##x##_C)) == 1u) From 7bba19e044dab06bd0ab6310d67a64b1b841181a Mon Sep 17 00:00:00 2001 From: nijtmans Date: Fri, 18 Oct 2019 14:53:42 +0200 Subject: [PATCH 11/20] Add comment --- tommath_private.h | 1 + 1 file changed, 1 insertion(+) diff --git a/tommath_private.h b/tommath_private.h index bc7d908..1a0096f 100644 --- a/tommath_private.h +++ b/tommath_private.h @@ -142,6 +142,7 @@ extern void MP_FREE(void *mem, size_t size); /* feature detection macro */ #ifdef _MSC_VER +/* Prevent false positive: not enough arguments for function-like macro invocation */ #pragma warning(disable: 4003) #endif #define MP_STRINGIZE(x) MP__STRINGIZE(x) From c54d603a9e85d29729ca32bf125bb6da875d39f8 Mon Sep 17 00:00:00 2001 From: nijtmans Date: Fri, 18 Oct 2019 15:21:28 +0200 Subject: [PATCH 12/20] Fix build with latest visual studio (2019) --- bn_s_mp_rand_platform.c | 7 ------- makefile.msvc | 2 +- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/bn_s_mp_rand_platform.c b/bn_s_mp_rand_platform.c index 07555db..27339bf 100644 --- a/bn_s_mp_rand_platform.c +++ b/bn_s_mp_rand_platform.c @@ -27,16 +27,9 @@ static mp_err s_read_arc4random(void *p, size_t n) #define ARM #endif -#ifdef _MSC_VER -# pragma warning(push) -# pragma warning (disable : 4668) -#endif #define WIN32_LEAN_AND_MEAN #include #include -#ifdef _MSC_VER -# pragma warning(pop) -#endif static mp_err s_read_wincsp(void *p, size_t n) { diff --git a/makefile.msvc b/makefile.msvc index d155bc6..aa8d8be 100644 --- a/makefile.msvc +++ b/makefile.msvc @@ -14,7 +14,7 @@ PREFIX = c:\devel CFLAGS = /Ox #Compilation flags -LTM_CFLAGS = /nologo /I./ /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_DEPRECATE /D__STDC_WANT_SECURE_LIB__=1 /D_CRT_HAS_CXX17=0 /Wall /wd4146 /wd4127 /wd4710 /wd4711 /wd4820 /WX $(CFLAGS) +LTM_CFLAGS = /nologo /I./ /D_CRT_SECURE_NO_WARNINGS /D_CRT_NONSTDC_NO_DEPRECATE /D__STDC_WANT_SECURE_LIB__=1 /D_CRT_HAS_CXX17=0 /Wall /wd4146 /wd4127 /wd4668 /wd4710 /wd4711 /wd4820 /wd5045 /WX $(CFLAGS) LTM_LDFLAGS = advapi32.lib #Libraries to be created (this makefile builds only static libraries) From 4bbadc4f9c9455a0daf7227c577e7f1272faa410 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Fri, 18 Oct 2019 15:41:53 +0200 Subject: [PATCH 13/20] add MSVC2019 build to appveyor [skip ci] --- appveyor.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/appveyor.yml b/appveyor.yml index 7d85d3f..efe4568 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -6,11 +6,13 @@ branches: - /^release/ - /^travis/ image: +- Visual Studio 2019 - Visual Studio 2017 - Visual Studio 2015 build_script: - cmd: >- - if "Visual Studio 2017"=="%APPVEYOR_BUILD_WORKER_IMAGE%" call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" + if "Visual Studio 2019"=="%APPVEYOR_BUILD_WORKER_IMAGE%" call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" + if "Visual Studio 2017"=="%APPVEYOR_BUILD_WORKER_IMAGE%" call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" if "Visual Studio 2015"=="%APPVEYOR_BUILD_WORKER_IMAGE%" call "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64 if "Visual Studio 2015"=="%APPVEYOR_BUILD_WORKER_IMAGE%" call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86_amd64 nmake -f makefile.msvc all From f8e9bd27f0b20e05b0ca15b11b2f4857ebc76080 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sun, 20 Oct 2019 15:38:32 +0200 Subject: [PATCH 14/20] Merge pull request #387 from fperrad/20191019_lint some linting (cherry picked from commit 8095b3b61240628f052153d6c37539955632564e) --- bn_mp_prime_next_prime.c | 7 ++++--- bn_s_mp_toom_mul.c | 3 ++- bn_s_mp_toom_sqr.c | 3 ++- etc/2kprime.c | 10 +++++----- etc/drprime.c | 13 +++++++------ etc/mersenne.c | 15 ++++++++------- etc/pprime.c | 5 +++-- etc/tune.c | 6 ++++-- tommath.h | 2 +- 9 files changed, 36 insertions(+), 28 deletions(-) diff --git a/bn_mp_prime_next_prime.c b/bn_mp_prime_next_prime.c index 1e971fa..d656565 100644 --- a/bn_mp_prime_next_prime.c +++ b/bn_mp_prime_next_prime.c @@ -10,9 +10,10 @@ */ mp_err mp_prime_next_prime(mp_int *a, int t, int bbs_style) { - int x, y, cmp; - mp_err err; - mp_bool res = MP_NO; + int x, y; + mp_ord cmp; + mp_err err; + mp_bool res = MP_NO; mp_digit res_tab[PRIVATE_MP_PRIME_TAB_SIZE], step, kstep; mp_int b; diff --git a/bn_s_mp_toom_mul.c b/bn_s_mp_toom_mul.c index 8efd803..86901b0 100644 --- a/bn_s_mp_toom_mul.c +++ b/bn_s_mp_toom_mul.c @@ -32,7 +32,8 @@ mp_err s_mp_toom_mul(const mp_int *a, const mp_int *b, mp_int *c) { mp_int S1, S2, T1, a0, a1, a2, b0, b1, b2; - int err, B, count; + int B, count; + mp_err err; /* init temps */ if ((err = mp_init_multi(&S1, &S2, &T1, NULL)) != MP_OKAY) { diff --git a/bn_s_mp_toom_sqr.c b/bn_s_mp_toom_sqr.c index 9eaa9d0..f2ffb30 100644 --- a/bn_s_mp_toom_sqr.c +++ b/bn_s_mp_toom_sqr.c @@ -22,7 +22,8 @@ mp_err s_mp_toom_sqr(const mp_int *a, mp_int *b) { mp_int S0, a0, a1, a2; mp_digit *tmpa, *tmpc; - mp_err err, B, count; + int B, count; + mp_err err; /* init temps */ diff --git a/etc/2kprime.c b/etc/2kprime.c index 55cb5f4..95ed2de 100644 --- a/etc/2kprime.c +++ b/etc/2kprime.c @@ -8,7 +8,7 @@ int main(void) { char buf[2000]; size_t x; - int y; + mp_bool y; mp_int q, p; FILE *out; clock_t t1; @@ -43,7 +43,7 @@ top: /* quick test on q */ mp_prime_is_prime(&q, 1, &y); - if (y == 0) { + if (y == MP_NO) { continue; } @@ -51,20 +51,20 @@ top: mp_sub_d(&q, 1uL, &p); mp_div_2(&p, &p); mp_prime_is_prime(&p, 3, &y); - if (y == 0) { + if (y == MP_NO) { continue; } /* test on q */ mp_prime_is_prime(&q, 3, &y); - if (y == 0) { + if (y == MP_NO) { continue; } break; } - if (y == 0) { + if (y == MP_NO) { ++sizes[x]; goto top; } diff --git a/etc/drprime.c b/etc/drprime.c index 146455e..64e31ef 100644 --- a/etc/drprime.c +++ b/etc/drprime.c @@ -5,7 +5,8 @@ static int sizes[] = { 1+256/MP_DIGIT_BIT, 1+512/MP_DIGIT_BIT, 1+768/MP_DIGIT_BI int main(void) { - int res, x, y; + mp_bool res; + int x, y; char buf[4096]; FILE *out; mp_int a, b; @@ -29,23 +30,23 @@ top: a.used = sizes[x]; /* now loop */ - res = 0; + res = MP_NO; for (;;) { a.dp[0] += 4uL; if (a.dp[0] >= MP_MASK) break; mp_prime_is_prime(&a, 1, &res); - if (res == 0) continue; + if (res == MP_NO) continue; printf("."); fflush(stdout); mp_sub_d(&a, 1uL, &b); mp_div_2(&b, &b); mp_prime_is_prime(&b, 3, &res); - if (res == 0) continue; + if (res == MP_NO) continue; mp_prime_is_prime(&a, 3, &res); - if (res == 1) break; + if (res == MP_YES) break; } - if (res != 1) { + if (res != MP_YES) { printf("Error not DR modulus\n"); sizes[x] += 1; goto top; diff --git a/etc/mersenne.c b/etc/mersenne.c index f6d7cb6..0c9f52f 100644 --- a/etc/mersenne.c +++ b/etc/mersenne.c @@ -5,12 +5,13 @@ #include #include -static int is_mersenne(long s, int *pp) +static mp_err is_mersenne(long s, mp_bool *pp) { mp_int n, u; - int res, k; + mp_err res; + int k; - *pp = 0; + *pp = MP_NO; if ((res = mp_init(&n)) != MP_OKAY) { return res; @@ -55,9 +56,9 @@ static int is_mersenne(long s, int *pp) } /* if u == 0 then its prime */ - if (mp_iszero(&u) == 1) { + if (mp_iszero(&u) == MP_YES) { mp_prime_is_prime(&n, 8, pp); - if (*pp != 1) printf("FAILURE\n"); + if (*pp != MP_YES) printf("FAILURE\n"); } res = MP_OKAY; @@ -102,7 +103,7 @@ static int isprime(long k) int main(void) { - int pp; + mp_bool pp; long k; clock_t tt; @@ -118,7 +119,7 @@ int main(void) return -1; } - if (pp == 1) { + if (pp == MP_YES) { /* count time */ tt = clock() - tt; diff --git a/etc/pprime.c b/etc/pprime.c index fa622f8..009a18c 100644 --- a/etc/pprime.c +++ b/etc/pprime.c @@ -179,10 +179,11 @@ static mp_digit prime_digit(void) /* makes a prime of at least k bits */ -static int pprime(int k, int li, mp_int *p, mp_int *q) +static mp_err pprime(int k, int li, mp_int *p, mp_int *q) { mp_int a, b, c, n, x, y, z, v; - int res, ii; + mp_err res; + int ii; static const mp_digit bases[] = { 2, 3, 5, 7, 11, 13, 17, 19 }; /* single digit ? */ diff --git a/etc/tune.c b/etc/tune.c index 057e372..bc2cdfe 100644 --- a/etc/tune.c +++ b/etc/tune.c @@ -61,7 +61,8 @@ static int s_offset = 1; #define s_mp_mul(a, b, c) s_mp_mul_digs(a, b, c, (a)->used + (b)->used + 1) static uint64_t s_time_mul(int size) { - int x, e; + int x; + mp_err e; mp_int a, b, c, d; uint64_t t1; @@ -106,7 +107,8 @@ LTM_ERR: static uint64_t s_time_sqr(int size) { - int x, e; + int x; + mp_err e; mp_int a, b, c; uint64_t t1; diff --git a/tommath.h b/tommath.h index 8dd3bb3..e87bb08 100644 --- a/tommath.h +++ b/tommath.h @@ -135,7 +135,7 @@ typedef enum { MP_MEM = -2, /* out of mem */ MP_VAL = -3, /* invalid input */ MP_ITER = -4, /* maximum iterations reached */ - MP_BUF = -5, /* buffer overflow, supplied buffer too small */ + MP_BUF = -5 /* buffer overflow, supplied buffer too small */ } mp_err; typedef enum { MP_LSB_FIRST = -1, From 17ca193fa70890033b35625ca44041c51171b50a Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sun, 20 Oct 2019 17:20:30 +0200 Subject: [PATCH 15/20] remove LTM book reuse `docs` make-target to build poster and manual fixes #383 --- doc/booker.pl | 296 --- doc/makefile | 19 +- doc/tommath.src | 6350 ----------------------------------------------- makefile | 4 +- 4 files changed, 4 insertions(+), 6665 deletions(-) delete mode 100644 doc/booker.pl delete mode 100644 doc/tommath.src diff --git a/doc/booker.pl b/doc/booker.pl deleted file mode 100644 index 13ccda4..0000000 --- a/doc/booker.pl +++ /dev/null @@ -1,296 +0,0 @@ -#!/bin/perl -# -#Used to prepare the book "tommath.src" for LaTeX by pre-processing it into a .tex file -# -#Essentially you write the "tommath.src" as normal LaTex except where you want code snippets you put -# -#EXAM,file -# -#This preprocessor will then open "file" and insert it as a verbatim copy. -# -#Tom St Denis -use strict; - -#get graphics type -my $graph; -if (shift =~ /PDF/) { - $graph = ""; -} else { - $graph = ".ps"; -} - -open(my $in, '<', 'tommath.src') or die "Can't open source file"; -open(my $out, '>', 'tommath.tex') or die "Can't open destination file"; - -print "Scanning for sections\n"; -my $chapter = 0; -my $section = 0; -my $subsection = 0; -my $x = 0; -my %index1; -my %index2; -my %index3; -while (<$in>) { - print "."; - if (!(++$x % 80)) { print "\n"; } - #update the headings - if (~($_ =~ /\*/)) { - if ($_ =~ /\\chapter\{.+}/) { - ++$chapter; - $section = $subsection = 0; - } elsif ($_ =~ /\\section\{.+}/) { - ++$section; - $subsection = 0; - } elsif ($_ =~ /\\subsection\{.+}/) { - ++$subsection; - } - } - - if ($_ =~ m/MARK/) { - my @m = split ',', $_; - chomp $m[1]; - $index1{$m[1]} = $chapter; - $index2{$m[1]} = $section; - $index3{$m[1]} = $subsection; - } -} -close $in; - -open($in, '<', 'tommath.src') or die "Can't open source file"; -my $readline = 0; -my $wroteline = 0; -my $srcline = 0; -my $totlines; -my @text; - -while (<$in>) { - ++$readline; - ++$srcline; - - if ($_ =~ m/MARK/) { - } elsif ($_ =~ m/EXAM/ || $_ =~ m/LIST/) { - my $skipheader; - if ($_ =~ m/EXAM/) { - $skipheader = 1; - } else { - $skipheader = 0; - } - - # EXAM,file - chomp($_); - my @m = split ',', $_; - open(my $src, '<', "../$m[1]") or die "Error:$srcline:Can't open source file $m[1]"; - - print "$srcline:Inserting $m[1]:"; - - my $line = 0; - my $tmp = $m[1]; - my $fun = $tmp; - $tmp =~ s/_/"\\_"/ge; - $fun =~ s/^bn_//; - $fun =~ s/\.c$//; - $fun =~ s/_/"\\_"/ge; - print {$out} "\\index{$fun}\\vspace{+3mm}\\begin{small}\n\\hspace{-5.1mm}{\\bf File}: $tmp\n\\vspace{-3mm}\n\\begin{alltt}\n"; - $wroteline += 5; - - if ($skipheader == 1) { - # scan till next end of comment, e.g. skip license - while (<$src>) { - if ($_ =~ /#ifdef BN/) { - printf {$out} ("%03d ", $line); - for ($x = 0; $x < length($_); $x++) { - print {$out} chr(vec($_, $x, 8)); - if ($x == 75) { - print {$out} "\n "; - ++$wroteline; - } - } - print {$out} "...\n"; - ++$wroteline; - } - $text[$line++] = $_; - last if ($_ =~ /libtom\.org/); - } - <$src>; - $text[$line++] = $_; - <$src>; - $text[$line++] = $_; - } - - my $inline = 0; - while (<$src>) { - $text[$line++] = $_; - ++$inline; - chomp($_); - $_ =~ s/\t/" "/ge; - $_ =~ s/{/"^{"/ge; - $_ =~ s/}/"^}"/ge; - $_ =~ s/\\/'\symbol{92}'/ge; - $_ =~ s/\^/"\\"/ge; - - printf {$out} ("%03d ", $line); - for ($x = 0; $x < length($_); $x++) { - print {$out} chr(vec($_, $x, 8)); - if ($x == 75) { - print {$out} "\n "; - ++$wroteline; - } - } - print {$out} "\n"; - ++$wroteline; - } - $totlines = $line; - print {$out} "\\end{alltt}\n\\end{small}\n"; - close $src; - print "$inline lines\n"; - $wroteline += 2; - } elsif ($_ =~ m/@\d+,.+@/) { - # line contains [number,text] - # e.g. @14,for (ix = 0)@ - my $txt = $_; - while ($txt =~ m/@\d+,.+@/) { - my @m = split '@', $txt; # splits into text, one, two - my @parms = split ',', $m[1]; # splits one,two into two elements - - # now search from $parms[0] down for $parms[1] - my $found; - my $found1 = 0; - my $found2 = 0; - my $foundline; - my $foundline1; - my $foundline2; - for (my $i = $parms[0]; $i < $totlines && $found1 == 0; $i++) { - if ($text[$i] =~ m/\Q$parms[1]\E/) { - $foundline1 = $i + 1; - $found1 = 1; - } - } - - # now search backwards - for (my $i = $parms[0] - 1; $i >= 0 && $found2 == 0; $i--) { - if ($text[$i] =~ m/\Q$parms[1]\E/) { - $foundline2 = $i + 1; - $found2 = 1; - } - } - - # now use the closest match or the first if tied - if ($found1 == 1 && $found2 == 0) { - $found = 1; - $foundline = $foundline1; - } elsif ($found1 == 0 && $found2 == 1) { - $found = 1; - $foundline = $foundline2; - } elsif ($found1 == 1 && $found2 == 1) { - $found = 1; - if (($foundline1 - $parms[0]) <= ($parms[0] - $foundline2)) { - $foundline = $foundline1; - } else { - $foundline = $foundline2; - } - } else { - $found = 0; - } - - # if found replace - if ($found == 1) { - my $delta = $parms[0] - $foundline; - print "Found replacement tag for \"$parms[1]\" on line $srcline which refers to line $foundline (delta $delta)\n"; - $_ =~ s/@\Q$m[1]\E@/$foundline/; - } else { - print "ERROR: The tag \"$parms[1]\" on line $srcline was not found in the most recently parsed source!\n"; - } - - # remake the rest of the line - $txt = ""; - for (my $i = 2; $i < scalar(@m); $i++) { - $txt = $txt . $m[$i] . "@"; - } - } - print {$out} $_; - ++$wroteline; - } elsif ($_ =~ /~.+~/) { - # line contains a ~text~ pair used to refer to indexing :-) - my $txt = $_; - while ($txt =~ /~.+~/) { - my @m = split '~', $txt; - - # word is the second position - my $word = $m[1]; - my $a = $index1{$word}; - my $b = $index2{$word}; - my $c = $index3{$word}; - - # if chapter (a) is zero it wasn't found - if ($a == 0) { - print "ERROR: the tag \"$word\" on line $srcline was not found previously marked.\n"; - } else { - # format the tag as x, x.y or x.y.z depending on the values - my $str = $a; - $str = $str . ".$b" if ($b != 0); - $str = $str . ".$c" if ($c != 0); - - if ($b == 0 && $c == 0) { - # its a chapter - if ($a <= 10) { - if ($a == 1) { - $str = "chapter one"; - } elsif ($a == 2) { - $str = "chapter two"; - } elsif ($a == 3) { - $str = "chapter three"; - } elsif ($a == 4) { - $str = "chapter four"; - } elsif ($a == 5) { - $str = "chapter five"; - } elsif ($a == 6) { - $str = "chapter six"; - } elsif ($a == 7) { - $str = "chapter seven"; - } elsif ($a == 8) { - $str = "chapter eight"; - } elsif ($a == 9) { - $str = "chapter nine"; - } elsif ($a == 10) { - $str = "chapter ten"; - } - } else { - $str = "chapter " . $str; - } - } else { - $str = "section " . $str if ($b != 0 && $c == 0); - $str = "sub-section " . $str if ($b != 0 && $c != 0); - } - - #substitute - $_ =~ s/~\Q$word\E~/$str/; - - print "Found replacement tag for marker \"$word\" on line $srcline which refers to $str\n"; - } - - # remake rest of the line - $txt = ""; - for (my $i = 2; $i < scalar(@m); $i++) { - $txt = $txt . $m[$i] . "~"; - } - } - print {$out} $_; - ++$wroteline; - } elsif ($_ =~ m/FIGU/) { - # FIGU,file,caption - chomp($_); - my @m = split ',', $_; - print {$out} "\\begin{center}\n\\begin{figure}[h]\n\\includegraphics{pics/$m[1]$graph}\n"; - print {$out} "\\caption{$m[2]}\n\\label{pic:$m[1]}\n\\end{figure}\n\\end{center}\n"; - $wroteline += 4; - } else { - print {$out} $_; - ++$wroteline; - } -} -print "Read $readline lines, wrote $wroteline lines\n"; - -close $out; -close $in; - -system('perl -pli -e "s/\s*$//" tommath.tex'); diff --git a/doc/makefile b/doc/makefile index e15db08..7eeb1f9 100644 --- a/doc/makefile +++ b/doc/makefile @@ -9,19 +9,10 @@ ifeq ($(PLATFORM), Darwin) err: $(error Docs can't be built on Mac) -docdvi poster docs mandvi manual: err +poster docs mandvi manual: err endif -# makes the LTM book DVI file, requires tetex, perl and makeindex [part of tetex I think] -docdvi: tommath.src - ${MAKE} -C pics/ MAKE=${MAKE} - echo "hello" ${silent_stdout} - perl booker.pl - touch tommath.ind - latex tommath ${silent_stdout} - latex tommath ${silent_stdout} - makeindex tommath - latex tommath ${silent_stdout} +docs: poster manual # poster, makes the single page PDF poster poster: poster.tex @@ -39,12 +30,6 @@ poster: poster.tex mv poster.bak poster.tex rm -f poster.aux poster.log poster.out -# makes the LTM book PDF file, requires tetex, cleans up the LaTeX temp files -docs: docdvi - dvipdf tommath - rm -f tommath.log tommath.aux tommath.dvi tommath.idx tommath.toc tommath.lof tommath.ind tommath.ilg - ${MAKE} -C pics/ clean MAKE=${MAKE} - #LTM user manual mandvi: bn.tex cp bn.tex bn.bak diff --git a/doc/tommath.src b/doc/tommath.src deleted file mode 100644 index b3f7909..0000000 --- a/doc/tommath.src +++ /dev/null @@ -1,6350 +0,0 @@ -\documentclass[b5paper]{book} -\usepackage{hyperref} -\usepackage{makeidx} -\usepackage{amssymb} -\usepackage{color} -\usepackage{alltt} -\usepackage{graphicx} -\usepackage{layout} -\def\union{\cup} -\def\intersect{\cap} -\def\getsrandom{\stackrel{\rm R}{\gets}} -\def\cross{\times} -\def\cat{\hspace{0.5em} \| \hspace{0.5em}} -\def\catn{$\|$} -\def\divides{\hspace{0.3em} | \hspace{0.3em}} -\def\nequiv{\not\equiv} -\def\approx{\raisebox{0.2ex}{\mbox{\small $\sim$}}} -\def\lcm{{\rm lcm}} -\def\gcd{{\rm gcd}} -\def\log{{\rm log}} -\def\ord{{\rm ord}} -\def\abs{{\mathit abs}} -\def\rep{{\mathit rep}} -\def\mod{{\mathit\ mod\ }} -\renewcommand{\pmod}[1]{\ ({\rm mod\ }{#1})} -\newcommand{\floor}[1]{\left\lfloor{#1}\right\rfloor} -\newcommand{\ceil}[1]{\left\lceil{#1}\right\rceil} -\def\Or{{\rm\ or\ }} -\def\And{{\rm\ and\ }} -\def\iff{\hspace{1em}\Longleftrightarrow\hspace{1em}} -\def\implies{\Rightarrow} -\def\undefined{{\rm ``undefined"}} -\def\Proof{\vspace{1ex}\noindent {\bf Proof:}\hspace{1em}} -\let\oldphi\phi -\def\phi{\varphi} -\def\Pr{{\rm Pr}} -\newcommand{\str}[1]{{\mathbf{#1}}} -\def\F{{\mathbb F}} -\def\N{{\mathbb N}} -\def\Z{{\mathbb Z}} -\def\R{{\mathbb R}} -\def\C{{\mathbb C}} -\def\Q{{\mathbb Q}} -\definecolor{DGray}{gray}{0.5} -\newcommand{\emailaddr}[1]{\mbox{$<${#1}$>$}} -\def\twiddle{\raisebox{0.3ex}{\mbox{\tiny $\sim$}}} -\def\gap{\vspace{0.5ex}} -\makeindex -\begin{document} -\frontmatter -\pagestyle{empty} -\title{Multi--Precision Math} -\author{\mbox{ -%\begin{small} -\begin{tabular}{c} -Tom St Denis \\ -Algonquin College \\ -\\ -Mads Rasmussen \\ -Open Communications Security \\ -\\ -Greg Rose \\ -QUALCOMM Australia \\ -\end{tabular} -%\end{small} -} -} -\maketitle -This text has been placed in the public domain. This text corresponds to the v0.39 release of the -LibTomMath project. - -This text is formatted to the international B5 paper size of 176mm wide by 250mm tall using the \LaTeX{} -{\em book} macro package and the Perl {\em booker} package. - -\tableofcontents -\listoffigures -\chapter*{Prefaces} -When I tell people about my LibTom projects and that I release them as public domain they are often puzzled. -They ask why I did it and especially why I continue to work on them for free. The best I can explain it is ``Because I can.'' -Which seems odd and perhaps too terse for adult conversation. I often qualify it with ``I am able, I am willing.'' which -perhaps explains it better. I am the first to admit there is not anything that special with what I have done. Perhaps -others can see that too and then we would have a society to be proud of. My LibTom projects are what I am doing to give -back to society in the form of tools and knowledge that can help others in their endeavours. - -I started writing this book because it was the most logical task to further my goal of open academia. The LibTomMath source -code itself was written to be easy to follow and learn from. There are times, however, where pure C source code does not -explain the algorithms properly. Hence this book. The book literally starts with the foundation of the library and works -itself outwards to the more complicated algorithms. The use of both pseudo--code and verbatim source code provides a duality -of ``theory'' and ``practice'' that the computer science students of the world shall appreciate. I never deviate too far -from relatively straightforward algebra and I hope that this book can be a valuable learning asset. - -This book and indeed much of the LibTom projects would not exist in their current form if it was not for a plethora -of kind people donating their time, resources and kind words to help support my work. Writing a text of significant -length (along with the source code) is a tiresome and lengthy process. Currently the LibTom project is four years old, -comprises of literally thousands of users and over 100,000 lines of source code, TeX and other material. People like Mads and Greg -were there at the beginning to encourage me to work well. It is amazing how timely validation from others can boost morale to -continue the project. Definitely my parents were there for me by providing room and board during the many months of work in 2003. - -To my many friends whom I have met through the years I thank you for the good times and the words of encouragement. I hope I -honour your kind gestures with this project. - -Open Source. Open Academia. Open Minds. - -\begin{flushright} Tom St Denis \end{flushright} - -\newpage -I found the opportunity to work with Tom appealing for several reasons, not only could I broaden my own horizons, but also -contribute to educate others facing the problem of having to handle big number mathematical calculations. - -This book is Tom's child and he has been caring and fostering the project ever since the beginning with a clear mind of -how he wanted the project to turn out. I have helped by proofreading the text and we have had several discussions about -the layout and language used. - -I hold a masters degree in cryptography from the University of Southern Denmark and have always been interested in the -practical aspects of cryptography. - -Having worked in the security consultancy business for several years in S\~{a}o Paulo, Brazil, I have been in touch with a -great deal of work in which multiple precision mathematics was needed. Understanding the possibilities for speeding up -multiple precision calculations is often very important since we deal with outdated machine architecture where modular -reductions, for example, become painfully slow. - -This text is for people who stop and wonder when first examining algorithms such as RSA for the first time and asks -themselves, ``You tell me this is only secure for large numbers, fine; but how do you implement these numbers?'' - -\begin{flushright} -Mads Rasmussen - -S\~{a}o Paulo - SP - -Brazil -\end{flushright} - -\newpage -It's all because I broke my leg. That just happened to be at about the same time that Tom asked for someone to review the section of the book about -Karatsuba multiplication. I was laid up, alone and immobile, and thought ``Why not?'' I vaguely knew what Karatsuba multiplication was, but not -really, so I thought I could help, learn, and stop myself from watching daytime cable TV, all at once. - -At the time of writing this, I've still not met Tom or Mads in meatspace. I've been following Tom's progress since his first splash on the -sci.crypt Usenet news group. I watched him go from a clueless newbie, to the cryptographic equivalent of a reformed smoker, to a real -contributor to the field, over a period of about two years. I've been impressed with his obvious intelligence, and astounded by his productivity. -Of course, he's young enough to be my own child, so he doesn't have my problems with staying awake. - -When I reviewed that single section of the book, in its very earliest form, I was very pleasantly surprised. So I decided to collaborate more fully, -and at least review all of it, and perhaps write some bits too. There's still a long way to go with it, and I have watched a number of close -friends go through the mill of publication, so I think that the way to go is longer than Tom thinks it is. Nevertheless, it's a good effort, -and I'm pleased to be involved with it. - -\begin{flushright} -Greg Rose, Sydney, Australia, June 2003. -\end{flushright} - -\mainmatter -\pagestyle{headings} -\chapter{Introduction} -\section{Multiple Precision Arithmetic} - -\subsection{What is Multiple Precision Arithmetic?} -When we think of long-hand arithmetic such as addition or multiplication we rarely consider the fact that we instinctively -raise or lower the precision of the numbers we are dealing with. For example, in decimal we almost immediate can -reason that $7$ times $6$ is $42$. However, $42$ has two digits of precision as opposed to one digit we started with. -Further multiplications of say $3$ result in a larger precision result $126$. In these few examples we have multiple -precisions for the numbers we are working with. Despite the various levels of precision a single subset\footnote{With the occasional optimization.} - of algorithms can be designed to accomodate them. - -By way of comparison a fixed or single precision operation would lose precision on various operations. For example, in -the decimal system with fixed precision $6 \cdot 7 = 2$. - -Essentially at the heart of computer based multiple precision arithmetic are the same long-hand algorithms taught in -schools to manually add, subtract, multiply and divide. - -\subsection{The Need for Multiple Precision Arithmetic} -The most prevalent need for multiple precision arithmetic, often referred to as ``bignum'' math, is within the implementation -of public-key cryptography algorithms. Algorithms such as RSA \cite{RSAREF} and Diffie-Hellman \cite{DHREF} require -integers of significant magnitude to resist known cryptanalytic attacks. For example, at the time of this writing a -typical RSA modulus would be at least greater than $10^{309}$. However, modern programming languages such as ISO C \cite{ISOC} and -Java \cite{JAVA} only provide instrinsic support for integers which are relatively small and single precision. - -\begin{figure}[!h] -\begin{center} -\begin{tabular}{|r|c|} -\hline \textbf{Data Type} & \textbf{Range} \\ -\hline char & $-128 \ldots 127$ \\ -\hline short & $-32768 \ldots 32767$ \\ -\hline long & $-2147483648 \ldots 2147483647$ \\ -\hline long long & $-9223372036854775808 \ldots 9223372036854775807$ \\ -\hline -\end{tabular} -\end{center} -\caption{Typical Data Types for the C Programming Language} -\label{fig:ISOC} -\end{figure} - -The largest data type guaranteed to be provided by the ISO C programming -language\footnote{As per the ISO C standard. However, each compiler vendor is allowed to augment the precision as they -see fit.} can only represent values up to $10^{19}$ as shown in figure \ref{fig:ISOC}. On its own the C language is -insufficient to accomodate the magnitude required for the problem at hand. An RSA modulus of magnitude $10^{19}$ could be -trivially factored\footnote{A Pollard-Rho factoring would take only $2^{16}$ time.} on the average desktop computer, -rendering any protocol based on the algorithm insecure. Multiple precision algorithms solve this very problem by -extending the range of representable integers while using single precision data types. - -Most advancements in fast multiple precision arithmetic stem from the need for faster and more efficient cryptographic -primitives. Faster modular reduction and exponentiation algorithms such as Barrett's algorithm, which have appeared in -various cryptographic journals, can render algorithms such as RSA and Diffie-Hellman more efficient. In fact, several -major companies such as RSA Security, Certicom and Entrust have built entire product lines on the implementation and -deployment of efficient algorithms. - -However, cryptography is not the only field of study that can benefit from fast multiple precision integer routines. -Another auxiliary use of multiple precision integers is high precision floating point data types. -The basic IEEE \cite{IEEE} standard floating point type is made up of an integer mantissa $q$, an exponent $e$ and a sign bit $s$. -Numbers are given in the form $n = q \cdot b^e \cdot -1^s$ where $b = 2$ is the most common base for IEEE. Since IEEE -floating point is meant to be implemented in hardware the precision of the mantissa is often fairly small -(\textit{23, 48 and 64 bits}). The mantissa is merely an integer and a multiple precision integer could be used to create -a mantissa of much larger precision than hardware alone can efficiently support. This approach could be useful where -scientific applications must minimize the total output error over long calculations. - -Yet another use for large integers is within arithmetic on polynomials of large characteristic (i.e. $GF(p)[x]$ for large $p$). -In fact the library discussed within this text has already been used to form a polynomial basis library\footnote{See \url{http://poly.libtomcrypt.org} for more details.}. - -\subsection{Benefits of Multiple Precision Arithmetic} -\index{precision} -The benefit of multiple precision representations over single or fixed precision representations is that -no precision is lost while representing the result of an operation which requires excess precision. For example, -the product of two $n$-bit integers requires at least $2n$ bits of precision to be represented faithfully. A multiple -precision algorithm would augment the precision of the destination to accomodate the result while a single precision system -would truncate excess bits to maintain a fixed level of precision. - -It is possible to implement algorithms which require large integers with fixed precision algorithms. For example, elliptic -curve cryptography (\textit{ECC}) is often implemented on smartcards by fixing the precision of the integers to the maximum -size the system will ever need. Such an approach can lead to vastly simpler algorithms which can accomodate the -integers required even if the host platform cannot natively accomodate them\footnote{For example, the average smartcard -processor has an 8 bit accumulator.}. However, as efficient as such an approach may be, the resulting source code is not -normally very flexible. It cannot, at runtime, accomodate inputs of higher magnitude than the designer anticipated. - -Multiple precision algorithms have the most overhead of any style of arithmetic. For the the most part the -overhead can be kept to a minimum with careful planning, but overall, it is not well suited for most memory starved -platforms. However, multiple precision algorithms do offer the most flexibility in terms of the magnitude of the -inputs. That is, the same algorithms based on multiple precision integers can accomodate any reasonable size input -without the designer's explicit forethought. This leads to lower cost of ownership for the code as it only has to -be written and tested once. - -\section{Purpose of This Text} -The purpose of this text is to instruct the reader regarding how to implement efficient multiple precision algorithms. -That is to not only explain a limited subset of the core theory behind the algorithms but also the various ``house keeping'' -elements that are neglected by authors of other texts on the subject. Several well reknowned texts \cite{TAOCPV2,HAC} -give considerably detailed explanations of the theoretical aspects of algorithms and often very little information -regarding the practical implementation aspects. - -In most cases how an algorithm is explained and how it is actually implemented are two very different concepts. For -example, the Handbook of Applied Cryptography (\textit{HAC}), algorithm 14.7 on page 594, gives a relatively simple -algorithm for performing multiple precision integer addition. However, the description lacks any discussion concerning -the fact that the two integer inputs may be of differing magnitudes. As a result the implementation is not as simple -as the text would lead people to believe. Similarly the division routine (\textit{algorithm 14.20, pp. 598}) does not -discuss how to handle sign or handle the dividend's decreasing magnitude in the main loop (\textit{step \#3}). - -Both texts also do not discuss several key optimal algorithms required such as ``Comba'' and Karatsuba multipliers -and fast modular inversion, which we consider practical oversights. These optimal algorithms are vital to achieve -any form of useful performance in non-trivial applications. - -To solve this problem the focus of this text is on the practical aspects of implementing a multiple precision integer -package. As a case study the ``LibTomMath''\footnote{Available at \url{http://math.libtomcrypt.com}} package is used -to demonstrate algorithms with real implementations\footnote{In the ISO C programming language.} that have been field -tested and work very well. The LibTomMath library is freely available on the Internet for all uses and this text -discusses a very large portion of the inner workings of the library. - -The algorithms that are presented will always include at least one ``pseudo-code'' description followed -by the actual C source code that implements the algorithm. The pseudo-code can be used to implement the same -algorithm in other programming languages as the reader sees fit. - -This text shall also serve as a walkthrough of the creation of multiple precision algorithms from scratch. Showing -the reader how the algorithms fit together as well as where to start on various taskings. - -\section{Discussion and Notation} -\subsection{Notation} -A multiple precision integer of $n$-digits shall be denoted as $x = (x_{n-1}, \ldots, x_1, x_0)_{ \beta }$ and represent -the integer $x \equiv \sum_{i=0}^{n-1} x_i\beta^i$. The elements of the array $x$ are said to be the radix $\beta$ digits -of the integer. For example, $x = (1,2,3)_{10}$ would represent the integer -$1\cdot 10^2 + 2\cdot10^1 + 3\cdot10^0 = 123$. - -\index{mp\_int} -The term ``mp\_int'' shall refer to a composite structure which contains the digits of the integer it represents, as well -as auxilary data required to manipulate the data. These additional members are discussed further in section -\ref{sec:MPINT}. For the purposes of this text a ``multiple precision integer'' and an ``mp\_int'' are assumed to be -synonymous. When an algorithm is specified to accept an mp\_int variable it is assumed the various auxliary data members -are present as well. An expression of the type \textit{variablename.item} implies that it should evaluate to the -member named ``item'' of the variable. For example, a string of characters may have a member ``length'' which would -evaluate to the number of characters in the string. If the string $a$ equals ``hello'' then it follows that -$a.length = 5$. - -For certain discussions more generic algorithms are presented to help the reader understand the final algorithm used -to solve a given problem. When an algorithm is described as accepting an integer input it is assumed the input is -a plain integer with no additional multiple-precision members. That is, algorithms that use integers as opposed to -mp\_ints as inputs do not concern themselves with the housekeeping operations required such as memory management. These -algorithms will be used to establish the relevant theory which will subsequently be used to describe a multiple -precision algorithm to solve the same problem. - -\subsection{Precision Notation} -The variable $\beta$ represents the radix of a single digit of a multiple precision integer and -must be of the form $q^p$ for $q, p \in \Z^+$. A single precision variable must be able to represent integers in -the range $0 \le x < q \beta$ while a double precision variable must be able to represent integers in the range -$0 \le x < q \beta^2$. The extra radix-$q$ factor allows additions and subtractions to proceed without truncation of the -carry. Since all modern computers are binary, it is assumed that $q$ is two. - -\index{mp\_digit} \index{mp\_word} -Within the source code that will be presented for each algorithm, the data type \textbf{mp\_digit} will represent -a single precision integer type, while, the data type \textbf{mp\_word} will represent a double precision integer type. In -several algorithms (notably the Comba routines) temporary results will be stored in arrays of double precision mp\_words. -For the purposes of this text $x_j$ will refer to the $j$'th digit of a single precision array and $\hat x_j$ will refer to -the $j$'th digit of a double precision array. Whenever an expression is to be assigned to a double precision -variable it is assumed that all single precision variables are promoted to double precision during the evaluation. -Expressions that are assigned to a single precision variable are truncated to fit within the precision of a single -precision data type. - -For example, if $\beta = 10^2$ a single precision data type may represent a value in the -range $0 \le x < 10^3$, while a double precision data type may represent a value in the range $0 \le x < 10^5$. Let -$a = 23$ and $b = 49$ represent two single precision variables. The single precision product shall be written -as $c \leftarrow a \cdot b$ while the double precision product shall be written as $\hat c \leftarrow a \cdot b$. -In this particular case, $\hat c = 1127$ and $c = 127$. The most significant digit of the product would not fit -in a single precision data type and as a result $c \ne \hat c$. - -\subsection{Algorithm Inputs and Outputs} -Within the algorithm descriptions all variables are assumed to be scalars of either single or double precision -as indicated. The only exception to this rule is when variables have been indicated to be of type mp\_int. This -distinction is important as scalars are often used as array indicies and various other counters. - -\subsection{Mathematical Expressions} -The $\lfloor \mbox{ } \rfloor$ brackets imply an expression truncated to an integer not greater than the expression -itself. For example, $\lfloor 5.7 \rfloor = 5$. Similarly the $\lceil \mbox{ } \rceil$ brackets imply an expression -rounded to an integer not less than the expression itself. For example, $\lceil 5.1 \rceil = 6$. Typically when -the $/$ division symbol is used the intention is to perform an integer division with truncation. For example, -$5/2 = 2$ which will often be written as $\lfloor 5/2 \rfloor = 2$ for clarity. When an expression is written as a -fraction a real value division is implied, for example ${5 \over 2} = 2.5$. - -The norm of a multiple precision integer, for example $\vert \vert x \vert \vert$, will be used to represent the number of digits in the representation -of the integer. For example, $\vert \vert 123 \vert \vert = 3$ and $\vert \vert 79452 \vert \vert = 5$. - -\subsection{Work Effort} -\index{big-Oh} -To measure the efficiency of the specified algorithms, a modified big-Oh notation is used. In this system all -single precision operations are considered to have the same cost\footnote{Except where explicitly noted.}. -That is a single precision addition, multiplication and division are assumed to take the same time to -complete. While this is generally not true in practice, it will simplify the discussions considerably. - -Some algorithms have slight advantages over others which is why some constants will not be removed in -the notation. For example, a normal baseline multiplication (section \ref{sec:basemult}) requires $O(n^2)$ work while a -baseline squaring (section \ref{sec:basesquare}) requires $O({{n^2 + n}\over 2})$ work. In standard big-Oh notation these -would both be said to be equivalent to $O(n^2)$. However, -in the context of the this text this is not the case as the magnitude of the inputs will typically be rather small. As a -result small constant factors in the work effort will make an observable difference in algorithm efficiency. - -All of the algorithms presented in this text have a polynomial time work level. That is, of the form -$O(n^k)$ for $n, k \in \Z^{+}$. This will help make useful comparisons in terms of the speed of the algorithms and how -various optimizations will help pay off in the long run. - -\section{Exercises} -Within the more advanced chapters a section will be set aside to give the reader some challenging exercises related to -the discussion at hand. These exercises are not designed to be prize winning problems, but instead to be thought -provoking. Wherever possible the problems are forward minded, stating problems that will be answered in subsequent -chapters. The reader is encouraged to finish the exercises as they appear to get a better understanding of the -subject material. - -That being said, the problems are designed to affirm knowledge of a particular subject matter. Students in particular -are encouraged to verify they can answer the problems correctly before moving on. - -Similar to the exercises of \cite[pp. ix]{TAOCPV2} these exercises are given a scoring system based on the difficulty of -the problem. However, unlike \cite{TAOCPV2} the problems do not get nearly as hard. The scoring of these -exercises ranges from one (the easiest) to five (the hardest). The following table sumarizes the -scoring system used. - -\begin{figure}[h] -\begin{center} -\begin{small} -\begin{tabular}{|c|l|} -\hline $\left [ 1 \right ]$ & An easy problem that should only take the reader a manner of \\ - & minutes to solve. Usually does not involve much computer time \\ - & to solve. \\ -\hline $\left [ 2 \right ]$ & An easy problem that involves a marginal amount of computer \\ - & time usage. Usually requires a program to be written to \\ - & solve the problem. \\ -\hline $\left [ 3 \right ]$ & A moderately hard problem that requires a non-trivial amount \\ - & of work. Usually involves trivial research and development of \\ - & new theory from the perspective of a student. \\ -\hline $\left [ 4 \right ]$ & A moderately hard problem that involves a non-trivial amount \\ - & of work and research, the solution to which will demonstrate \\ - & a higher mastery of the subject matter. \\ -\hline $\left [ 5 \right ]$ & A hard problem that involves concepts that are difficult for a \\ - & novice to solve. Solutions to these problems will demonstrate a \\ - & complete mastery of the given subject. \\ -\hline -\end{tabular} -\end{small} -\end{center} -\caption{Exercise Scoring System} -\end{figure} - -Problems at the first level are meant to be simple questions that the reader can answer quickly without programming a solution or -devising new theory. These problems are quick tests to see if the material is understood. Problems at the second level -are also designed to be easy but will require a program or algorithm to be implemented to arrive at the answer. These -two levels are essentially entry level questions. - -Problems at the third level are meant to be a bit more difficult than the first two levels. The answer is often -fairly obvious but arriving at an exacting solution requires some thought and skill. These problems will almost always -involve devising a new algorithm or implementing a variation of another algorithm previously presented. Readers who can -answer these questions will feel comfortable with the concepts behind the topic at hand. - -Problems at the fourth level are meant to be similar to those of the level three questions except they will require -additional research to be completed. The reader will most likely not know the answer right away, nor will the text provide -the exact details of the answer until a subsequent chapter. - -Problems at the fifth level are meant to be the hardest -problems relative to all the other problems in the chapter. People who can correctly answer fifth level problems have a -mastery of the subject matter at hand. - -Often problems will be tied together. The purpose of this is to start a chain of thought that will be discussed in future chapters. The reader -is encouraged to answer the follow-up problems and try to draw the relevance of problems. - -\section{Introduction to LibTomMath} - -\subsection{What is LibTomMath?} -LibTomMath is a free and open source multiple precision integer library written entirely in portable ISO C. By portable it -is meant that the library does not contain any code that is computer platform dependent or otherwise problematic to use on -any given platform. - -The library has been successfully tested under numerous operating systems including Unix\footnote{All of these -trademarks belong to their respective rightful owners.}, MacOS, Windows, Linux, PalmOS and on standalone hardware such -as the Gameboy Advance. The library is designed to contain enough functionality to be able to develop applications such -as public key cryptosystems and still maintain a relatively small footprint. - -\subsection{Goals of LibTomMath} - -Libraries which obtain the most efficiency are rarely written in a high level programming language such as C. However, -even though this library is written entirely in ISO C, considerable care has been taken to optimize the algorithm implementations within the -library. Specifically the code has been written to work well with the GNU C Compiler (\textit{GCC}) on both x86 and ARM -processors. Wherever possible, highly efficient algorithms, such as Karatsuba multiplication, sliding window -exponentiation and Montgomery reduction have been provided to make the library more efficient. - -Even with the nearly optimal and specialized algorithms that have been included the Application Programing Interface -(\textit{API}) has been kept as simple as possible. Often generic place holder routines will make use of specialized -algorithms automatically without the developer's specific attention. One such example is the generic multiplication -algorithm \textbf{mp\_mul()} which will automatically use Toom--Cook, Karatsuba, Comba or baseline multiplication -based on the magnitude of the inputs and the configuration of the library. - -Making LibTomMath as efficient as possible is not the only goal of the LibTomMath project. Ideally the library should -be source compatible with another popular library which makes it more attractive for developers to use. In this case the -MPI library was used as a API template for all the basic functions. MPI was chosen because it is another library that fits -in the same niche as LibTomMath. Even though LibTomMath uses MPI as the template for the function names and argument -passing conventions, it has been written from scratch by Tom St Denis. - -The project is also meant to act as a learning tool for students, the logic being that no easy-to-follow ``bignum'' -library exists which can be used to teach computer science students how to perform fast and reliable multiple precision -integer arithmetic. To this end the source code has been given quite a few comments and algorithm discussion points. - -\section{Choice of LibTomMath} -LibTomMath was chosen as the case study of this text not only because the author of both projects is one and the same but -for more worthy reasons. Other libraries such as GMP \cite{GMP}, MPI \cite{MPI}, LIP \cite{LIP} and OpenSSL -\cite{OPENSSL} have multiple precision integer arithmetic routines but would not be ideal for this text for -reasons that will be explained in the following sub-sections. - -\subsection{Code Base} -The LibTomMath code base is all portable ISO C source code. This means that there are no platform dependent conditional -segments of code littered throughout the source. This clean and uncluttered approach to the library means that a -developer can more readily discern the true intent of a given section of source code without trying to keep track of -what conditional code will be used. - -The code base of LibTomMath is well organized. Each function is in its own separate source code file -which allows the reader to find a given function very quickly. On average there are $76$ lines of code per source -file which makes the source very easily to follow. By comparison MPI and LIP are single file projects making code tracing -very hard. GMP has many conditional code segments which also hinder tracing. - -When compiled with GCC for the x86 processor and optimized for speed the entire library is approximately $100$KiB\footnote{The notation ``KiB'' means $2^{10}$ octets, similarly ``MiB'' means $2^{20}$ octets.} - which is fairly small compared to GMP (over $250$KiB). LibTomMath is slightly larger than MPI (which compiles to about -$50$KiB) but LibTomMath is also much faster and more complete than MPI. - -\subsection{API Simplicity} -LibTomMath is designed after the MPI library and shares the API design. Quite often programs that use MPI will build -with LibTomMath without change. The function names correlate directly to the action they perform. Almost all of the -functions share the same parameter passing convention. The learning curve is fairly shallow with the API provided -which is an extremely valuable benefit for the student and developer alike. - -The LIP library is an example of a library with an API that is awkward to work with. LIP uses function names that are often ``compressed'' to -illegible short hand. LibTomMath does not share this characteristic. - -The GMP library also does not return error codes. Instead it uses a POSIX.1 \cite{POSIX1} signal system where errors -are signaled to the host application. This happens to be the fastest approach but definitely not the most versatile. In -effect a math error (i.e. invalid input, heap error, etc) can cause a program to stop functioning which is definitely -undersireable in many situations. - -\subsection{Optimizations} -While LibTomMath is certainly not the fastest library (GMP often beats LibTomMath by a factor of two) it does -feature a set of optimal algorithms for tasks such as modular reduction, exponentiation, multiplication and squaring. GMP -and LIP also feature such optimizations while MPI only uses baseline algorithms with no optimizations. GMP lacks a few -of the additional modular reduction optimizations that LibTomMath features\footnote{At the time of this writing GMP -only had Barrett and Montgomery modular reduction algorithms.}. - -LibTomMath is almost always an order of magnitude faster than the MPI library at computationally expensive tasks such as modular -exponentiation. In the grand scheme of ``bignum'' libraries LibTomMath is faster than the average library and usually -slower than the best libraries such as GMP and OpenSSL by only a small factor. - -\subsection{Portability and Stability} -LibTomMath will build ``out of the box'' on any platform equipped with a modern version of the GNU C Compiler -(\textit{GCC}). This means that without changes the library will build without configuration or setting up any -variables. LIP and MPI will build ``out of the box'' as well but have numerous known bugs. Most notably the author of -MPI has recently stopped working on his library and LIP has long since been discontinued. - -GMP requires a configuration script to run and will not build out of the box. GMP and LibTomMath are still in active -development and are very stable across a variety of platforms. - -\subsection{Choice} -LibTomMath is a relatively compact, well documented, highly optimized and portable library which seems only natural for -the case study of this text. Various source files from the LibTomMath project will be included within the text. However, -the reader is encouraged to download their own copy of the library to actually be able to work with the library. - -\chapter{Getting Started} -\section{Library Basics} -The trick to writing any useful library of source code is to build a solid foundation and work outwards from it. First, -a problem along with allowable solution parameters should be identified and analyzed. In this particular case the -inability to accomodate multiple precision integers is the problem. Futhermore, the solution must be written -as portable source code that is reasonably efficient across several different computer platforms. - -After a foundation is formed the remainder of the library can be designed and implemented in a hierarchical fashion. -That is, to implement the lowest level dependencies first and work towards the most abstract functions last. For example, -before implementing a modular exponentiation algorithm one would implement a modular reduction algorithm. -By building outwards from a base foundation instead of using a parallel design methodology the resulting project is -highly modular. Being highly modular is a desirable property of any project as it often means the resulting product -has a small footprint and updates are easy to perform. - -Usually when I start a project I will begin with the header files. I define the data types I think I will need and -prototype the initial functions that are not dependent on other functions (within the library). After I -implement these base functions I prototype more dependent functions and implement them. The process repeats until -I implement all of the functions I require. For example, in the case of LibTomMath I implemented functions such as -mp\_init() well before I implemented mp\_mul() and even further before I implemented mp\_exptmod(). As an example as to -why this design works note that the Karatsuba and Toom-Cook multipliers were written \textit{after} the -dependent function mp\_exptmod() was written. Adding the new multiplication algorithms did not require changes to the -mp\_exptmod() function itself and lowered the total cost of ownership (\textit{so to speak}) and of development -for new algorithms. This methodology allows new algorithms to be tested in a complete framework with relative ease. - -FIGU,design_process,Design Flow of the First Few Original LibTomMath Functions. - -Only after the majority of the functions were in place did I pursue a less hierarchical approach to auditing and optimizing -the source code. For example, one day I may audit the multipliers and the next day the polynomial basis functions. - -It only makes sense to begin the text with the preliminary data types and support algorithms required as well. -This chapter discusses the core algorithms of the library which are the dependents for every other algorithm. - -\section{What is a Multiple Precision Integer?} -Recall that most programming languages, in particular ISO C \cite{ISOC}, only have fixed precision data types that on their own cannot -be used to represent values larger than their precision will allow. The purpose of multiple precision algorithms is -to use fixed precision data types to create and manipulate multiple precision integers which may represent values -that are very large. - -As a well known analogy, school children are taught how to form numbers larger than nine by prepending more radix ten digits. In the decimal system -the largest single digit value is $9$. However, by concatenating digits together larger numbers may be represented. Newly prepended digits -(\textit{to the left}) are said to be in a different power of ten column. That is, the number $123$ can be described as having a $1$ in the hundreds -column, $2$ in the tens column and $3$ in the ones column. Or more formally $123 = 1 \cdot 10^2 + 2 \cdot 10^1 + 3 \cdot 10^0$. Computer based -multiple precision arithmetic is essentially the same concept. Larger integers are represented by adjoining fixed -precision computer words with the exception that a different radix is used. - -What most people probably do not think about explicitly are the various other attributes that describe a multiple precision -integer. For example, the integer $154_{10}$ has two immediately obvious properties. First, the integer is positive, -that is the sign of this particular integer is positive as opposed to negative. Second, the integer has three digits in -its representation. There is an additional property that the integer posesses that does not concern pencil-and-paper -arithmetic. The third property is how many digits placeholders are available to hold the integer. - -The human analogy of this third property is ensuring there is enough space on the paper to write the integer. For example, -if one starts writing a large number too far to the right on a piece of paper they will have to erase it and move left. -Similarly, computer algorithms must maintain strict control over memory usage to ensure that the digits of an integer -will not exceed the allowed boundaries. These three properties make up what is known as a multiple precision -integer or mp\_int for short. - -\subsection{The mp\_int Structure} -\label{sec:MPINT} -The mp\_int structure is the ISO C based manifestation of what represents a multiple precision integer. The ISO C standard does not provide for -any such data type but it does provide for making composite data types known as structures. The following is the structure definition -used within LibTomMath. - -\index{mp\_int} -\begin{figure}[h] -\begin{center} -\begin{small} -%\begin{verbatim} -\begin{tabular}{|l|} -\hline -typedef struct \{ \\ -\hspace{3mm}int used, alloc, sign;\\ -\hspace{3mm}mp\_digit *dp;\\ -\} \textbf{mp\_int}; \\ -\hline -\end{tabular} -%\end{verbatim} -\end{small} -\caption{The mp\_int Structure} -\label{fig:mpint} -\end{center} -\end{figure} - -The mp\_int structure (fig. \ref{fig:mpint}) can be broken down as follows. - -\begin{enumerate} -\item The \textbf{used} parameter denotes how many digits of the array \textbf{dp} contain the digits used to represent -a given integer. The \textbf{used} count must be positive (or zero) and may not exceed the \textbf{alloc} count. - -\item The \textbf{alloc} parameter denotes how -many digits are available in the array to use by functions before it has to increase in size. When the \textbf{used} count -of a result would exceed the \textbf{alloc} count all of the algorithms will automatically increase the size of the -array to accommodate the precision of the result. - -\item The pointer \textbf{dp} points to a dynamically allocated array of digits that represent the given multiple -precision integer. It is padded with $(\textbf{alloc} - \textbf{used})$ zero digits. The array is maintained in a least -significant digit order. As a pencil and paper analogy the array is organized such that the right most digits are stored -first starting at the location indexed by zero\footnote{In C all arrays begin at zero.} in the array. For example, -if \textbf{dp} contains $\lbrace a, b, c, \ldots \rbrace$ where \textbf{dp}$_0 = a$, \textbf{dp}$_1 = b$, \textbf{dp}$_2 = c$, $\ldots$ then -it would represent the integer $a + b\beta + c\beta^2 + \ldots$ - -\index{MP\_ZPOS} \index{MP\_NEG} -\item The \textbf{sign} parameter denotes the sign as either zero/positive (\textbf{MP\_ZPOS}) or negative (\textbf{MP\_NEG}). -\end{enumerate} - -\subsubsection{Valid mp\_int Structures} -Several rules are placed on the state of an mp\_int structure and are assumed to be followed for reasons of efficiency. -The only exceptions are when the structure is passed to initialization functions such as mp\_init() and mp\_init\_copy(). - -\begin{enumerate} -\item The value of \textbf{alloc} may not be less than one. That is \textbf{dp} always points to a previously allocated -array of digits. -\item The value of \textbf{used} may not exceed \textbf{alloc} and must be greater than or equal to zero. -\item The value of \textbf{used} implies the digit at index $(used - 1)$ of the \textbf{dp} array is non-zero. That is, -leading zero digits in the most significant positions must be trimmed. - \begin{enumerate} - \item Digits in the \textbf{dp} array at and above the \textbf{used} location must be zero. - \end{enumerate} -\item The value of \textbf{sign} must be \textbf{MP\_ZPOS} if \textbf{used} is zero; -this represents the mp\_int value of zero. -\end{enumerate} - -\section{Argument Passing} -A convention of argument passing must be adopted early on in the development of any library. Making the function -prototypes consistent will help eliminate many headaches in the future as the library grows to significant complexity. -In LibTomMath the multiple precision integer functions accept parameters from left to right as pointers to mp\_int -structures. That means that the source (input) operands are placed on the left and the destination (output) on the right. -Consider the following examples. - -\begin{verbatim} - mp_mul(&a, &b, &c); /* c = a * b */ - mp_add(&a, &b, &a); /* a = a + b */ - mp_sqr(&a, &b); /* b = a * a */ -\end{verbatim} - -The left to right order is a fairly natural way to implement the functions since it lets the developer read aloud the -functions and make sense of them. For example, the first function would read ``multiply a and b and store in c''. - -Certain libraries (\textit{LIP by Lenstra for instance}) accept parameters the other way around, to mimic the order -of assignment expressions. That is, the destination (output) is on the left and arguments (inputs) are on the right. In -truth, it is entirely a matter of preference. In the case of LibTomMath the convention from the MPI library has been -adopted. - -Another very useful design consideration, provided for in LibTomMath, is whether to allow argument sources to also be a -destination. For example, the second example (\textit{mp\_add}) adds $a$ to $b$ and stores in $a$. This is an important -feature to implement since it allows the calling functions to cut down on the number of variables it must maintain. -However, to implement this feature specific care has to be given to ensure the destination is not modified before the -source is fully read. - -\section{Return Values} -A well implemented application, no matter what its purpose, should trap as many runtime errors as possible and return them -to the caller. By catching runtime errors a library can be guaranteed to prevent undefined behaviour. However, the end -developer can still manage to cause a library to crash. For example, by passing an invalid pointer an application may -fault by dereferencing memory not owned by the application. - -In the case of LibTomMath the only errors that are checked for are related to inappropriate inputs (division by zero for -instance) and memory allocation errors. It will not check that the mp\_int passed to any function is valid nor -will it check pointers for validity. Any function that can cause a runtime error will return an error code as an -\textbf{int} data type with one of the following values (fig \ref{fig:errcodes}). - -\index{MP\_OKAY} \index{MP\_VAL} \index{MP\_MEM} -\begin{figure}[h] -\begin{center} -\begin{tabular}{|l|l|} -\hline \textbf{Value} & \textbf{Meaning} \\ -\hline \textbf{MP\_OKAY} & The function was successful \\ -\hline \textbf{MP\_VAL} & One of the input value(s) was invalid \\ -\hline \textbf{MP\_MEM} & The function ran out of heap memory \\ -\hline -\end{tabular} -\end{center} -\caption{LibTomMath Error Codes} -\label{fig:errcodes} -\end{figure} - -When an error is detected within a function it should free any memory it allocated, often during the initialization of -temporary mp\_ints, and return as soon as possible. The goal is to leave the system in the same state it was when the -function was called. Error checking with this style of API is fairly simple. - -\begin{verbatim} - int err; - if ((err = mp_add(&a, &b, &c)) != MP_OKAY) { - printf("Error: %s\n", mp_error_to_string(err)); - exit(EXIT_FAILURE); - } -\end{verbatim} - -The GMP \cite{GMP} library uses C style \textit{signals} to flag errors which is of questionable use. Not all errors are fatal -and it was not deemed ideal by the author of LibTomMath to force developers to have signal handlers for such cases. - -\section{Initialization and Clearing} -The logical starting point when actually writing multiple precision integer functions is the initialization and -clearing of the mp\_int structures. These two algorithms will be used by the majority of the higher level algorithms. - -Given the basic mp\_int structure an initialization routine must first allocate memory to hold the digits of -the integer. Often it is optimal to allocate a sufficiently large pre-set number of digits even though -the initial integer will represent zero. If only a single digit were allocated quite a few subsequent re-allocations -would occur when operations are performed on the integers. There is a tradeoff between how many default digits to allocate -and how many re-allocations are tolerable. Obviously allocating an excessive amount of digits initially will waste -memory and become unmanageable. - -If the memory for the digits has been successfully allocated then the rest of the members of the structure must -be initialized. Since the initial state of an mp\_int is to represent the zero integer, the allocated digits must be set -to zero. The \textbf{used} count set to zero and \textbf{sign} set to \textbf{MP\_ZPOS}. - -\subsection{Initializing an mp\_int} -An mp\_int is said to be initialized if it is set to a valid, preferably default, state such that all of the members of the -structure are set to valid values. The mp\_init algorithm will perform such an action. - -\index{mp\_init} -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_init}. \\ -\textbf{Input}. An mp\_int $a$ \\ -\textbf{Output}. Allocate memory and initialize $a$ to a known valid mp\_int state. \\ -\hline \\ -1. Allocate memory for \textbf{MP\_PREC} digits. \\ -2. If the allocation failed return(\textit{MP\_MEM}) \\ -3. for $n$ from $0$ to $MP\_PREC - 1$ do \\ -\hspace{3mm}3.1 $a_n \leftarrow 0$\\ -4. $a.sign \leftarrow MP\_ZPOS$\\ -5. $a.used \leftarrow 0$\\ -6. $a.alloc \leftarrow MP\_PREC$\\ -7. Return(\textit{MP\_OKAY})\\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_init} -\end{figure} - -\textbf{Algorithm mp\_init.} -The purpose of this function is to initialize an mp\_int structure so that the rest of the library can properly -manipulte it. It is assumed that the input may not have had any of its members previously initialized which is certainly -a valid assumption if the input resides on the stack. - -Before any of the members such as \textbf{sign}, \textbf{used} or \textbf{alloc} are initialized the memory for -the digits is allocated. If this fails the function returns before setting any of the other members. The \textbf{MP\_PREC} -name represents a constant\footnote{Defined in the ``tommath.h'' header file within LibTomMath.} -used to dictate the minimum precision of newly initialized mp\_int integers. Ideally, it is at least equal to the smallest -precision number you'll be working with. - -Allocating a block of digits at first instead of a single digit has the benefit of lowering the number of usually slow -heap operations later functions will have to perform in the future. If \textbf{MP\_PREC} is set correctly the slack -memory and the number of heap operations will be trivial. - -Once the allocation has been made the digits have to be set to zero as well as the \textbf{used}, \textbf{sign} and -\textbf{alloc} members initialized. This ensures that the mp\_int will always represent the default state of zero regardless -of the original condition of the input. - -\textbf{Remark.} -This function introduces the idiosyncrasy that all iterative loops, commonly initiated with the ``for'' keyword, iterate incrementally -when the ``to'' keyword is placed between two expressions. For example, ``for $a$ from $b$ to $c$ do'' means that -a subsequent expression (or body of expressions) are to be evaluated upto $c - b$ times so long as $b \le c$. In each -iteration the variable $a$ is substituted for a new integer that lies inclusively between $b$ and $c$. If $b > c$ occured -the loop would not iterate. By contrast if the ``downto'' keyword were used in place of ``to'' the loop would iterate -decrementally. - -EXAM,bn_mp_init.c - -One immediate observation of this initializtion function is that it does not return a pointer to a mp\_int structure. It -is assumed that the caller has already allocated memory for the mp\_int structure, typically on the application stack. The -call to mp\_init() is used only to initialize the members of the structure to a known default state. - -Here we see (line @23,XMALLOC@) the memory allocation is performed first. This allows us to exit cleanly and quickly -if there is an error. If the allocation fails the routine will return \textbf{MP\_MEM} to the caller to indicate there -was a memory error. The function XMALLOC is what actually allocates the memory. Technically XMALLOC is not a function -but a macro defined in ``tommath.h``. By default, XMALLOC will evaluate to malloc() which is the C library's built--in -memory allocation routine. - -In order to assure the mp\_int is in a known state the digits must be set to zero. On most platforms this could have been -accomplished by using calloc() instead of malloc(). However, to correctly initialize a integer type to a given value in a -portable fashion you have to actually assign the value. The for loop (line @28,for@) performs this required -operation. - -After the memory has been successfully initialized the remainder of the members are initialized -(lines @29,used@ through @31,sign@) to their respective default states. At this point the algorithm has succeeded and -a success code is returned to the calling function. If this function returns \textbf{MP\_OKAY} it is safe to assume the -mp\_int structure has been properly initialized and is safe to use with other functions within the library. - -\subsection{Clearing an mp\_int} -When an mp\_int is no longer required by the application, the memory that has been allocated for its digits must be -returned to the application's memory pool with the mp\_clear algorithm. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_clear}. \\ -\textbf{Input}. An mp\_int $a$ \\ -\textbf{Output}. The memory for $a$ shall be deallocated. \\ -\hline \\ -1. If $a$ has been previously freed then return(\textit{MP\_OKAY}). \\ -2. for $n$ from 0 to $a.used - 1$ do \\ -\hspace{3mm}2.1 $a_n \leftarrow 0$ \\ -3. Free the memory allocated for the digits of $a$. \\ -4. $a.used \leftarrow 0$ \\ -5. $a.alloc \leftarrow 0$ \\ -6. $a.sign \leftarrow MP\_ZPOS$ \\ -7. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_clear} -\end{figure} - -\textbf{Algorithm mp\_clear.} -This algorithm accomplishes two goals. First, it clears the digits and the other mp\_int members. This ensures that -if a developer accidentally re-uses a cleared structure it is less likely to cause problems. The second goal -is to free the allocated memory. - -The logic behind the algorithm is extended by marking cleared mp\_int structures so that subsequent calls to this -algorithm will not try to free the memory multiple times. Cleared mp\_ints are detectable by having a pre-defined invalid -digit pointer \textbf{dp} setting. - -Once an mp\_int has been cleared the mp\_int structure is no longer in a valid state for any other algorithm -with the exception of algorithms mp\_init, mp\_init\_copy, mp\_init\_size and mp\_clear. - -EXAM,bn_mp_clear.c - -The algorithm only operates on the mp\_int if it hasn't been previously cleared. The if statement (line @23,a->dp != NULL@) -checks to see if the \textbf{dp} member is not \textbf{NULL}. If the mp\_int is a valid mp\_int then \textbf{dp} cannot be -\textbf{NULL} in which case the if statement will evaluate to true. - -The digits of the mp\_int are cleared by the for loop (line @25,for@) which assigns a zero to every digit. Similar to mp\_init() -the digits are assigned zero instead of using block memory operations (such as memset()) since this is more portable. - -The digits are deallocated off the heap via the XFREE macro. Similar to XMALLOC the XFREE macro actually evaluates to -a standard C library function. In this case the free() function. Since free() only deallocates the memory the pointer -still has to be reset to \textbf{NULL} manually (line @33,NULL@). - -Now that the digits have been cleared and deallocated the other members are set to their final values (lines @34,= 0@ and @35,ZPOS@). - -\section{Maintenance Algorithms} - -The previous sections describes how to initialize and clear an mp\_int structure. To further support operations -that are to be performed on mp\_int structures (such as addition and multiplication) the dependent algorithms must be -able to augment the precision of an mp\_int and -initialize mp\_ints with differing initial conditions. - -These algorithms complete the set of low level algorithms required to work with mp\_int structures in the higher level -algorithms such as addition, multiplication and modular exponentiation. - -\subsection{Augmenting an mp\_int's Precision} -When storing a value in an mp\_int structure, a sufficient number of digits must be available to accomodate the entire -result of an operation without loss of precision. Quite often the size of the array given by the \textbf{alloc} member -is large enough to simply increase the \textbf{used} digit count. However, when the size of the array is too small it -must be re-sized appropriately to accomodate the result. The mp\_grow algorithm will provide this functionality. - -\newpage\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_grow}. \\ -\textbf{Input}. An mp\_int $a$ and an integer $b$. \\ -\textbf{Output}. $a$ is expanded to accomodate $b$ digits. \\ -\hline \\ -1. if $a.alloc \ge b$ then return(\textit{MP\_OKAY}) \\ -2. $u \leftarrow b\mbox{ (mod }MP\_PREC\mbox{)}$ \\ -3. $v \leftarrow b + 2 \cdot MP\_PREC - u$ \\ -4. Re-allocate the array of digits $a$ to size $v$ \\ -5. If the allocation failed then return(\textit{MP\_MEM}). \\ -6. for n from a.alloc to $v - 1$ do \\ -\hspace{+3mm}6.1 $a_n \leftarrow 0$ \\ -7. $a.alloc \leftarrow v$ \\ -8. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_grow} -\end{figure} - -\textbf{Algorithm mp\_grow.} -It is ideal to prevent re-allocations from being performed if they are not required (step one). This is useful to -prevent mp\_ints from growing excessively in code that erroneously calls mp\_grow. - -The requested digit count is padded up to next multiple of \textbf{MP\_PREC} plus an additional \textbf{MP\_PREC} (steps two and three). -This helps prevent many trivial reallocations that would grow an mp\_int by trivially small values. - -It is assumed that the reallocation (step four) leaves the lower $a.alloc$ digits of the mp\_int intact. This is much -akin to how the \textit{realloc} function from the standard C library works. Since the newly allocated digits are -assumed to contain undefined values they are initially set to zero. - -EXAM,bn_mp_grow.c - -A quick optimization is to first determine if a memory re-allocation is required at all. The if statement (line @24,alloc@) checks -if the \textbf{alloc} member of the mp\_int is smaller than the requested digit count. If the count is not larger than \textbf{alloc} -the function skips the re-allocation part thus saving time. - -When a re-allocation is performed it is turned into an optimal request to save time in the future. The requested digit count is -padded upwards to 2nd multiple of \textbf{MP\_PREC} larger than \textbf{alloc} (line @25, size@). The XREALLOC function is used -to re-allocate the memory. As per the other functions XREALLOC is actually a macro which evaluates to realloc by default. The realloc -function leaves the base of the allocation intact which means the first \textbf{alloc} digits of the mp\_int are the same as before -the re-allocation. All that is left is to clear the newly allocated digits and return. - -Note that the re-allocation result is actually stored in a temporary pointer $tmp$. This is to allow this function to return -an error with a valid pointer. Earlier releases of the library stored the result of XREALLOC into the mp\_int $a$. That would -result in a memory leak if XREALLOC ever failed. - -\subsection{Initializing Variable Precision mp\_ints} -Occasionally the number of digits required will be known in advance of an initialization, based on, for example, the size -of input mp\_ints to a given algorithm. The purpose of algorithm mp\_init\_size is similar to mp\_init except that it -will allocate \textit{at least} a specified number of digits. - -\begin{figure}[h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_init\_size}. \\ -\textbf{Input}. An mp\_int $a$ and the requested number of digits $b$. \\ -\textbf{Output}. $a$ is initialized to hold at least $b$ digits. \\ -\hline \\ -1. $u \leftarrow b \mbox{ (mod }MP\_PREC\mbox{)}$ \\ -2. $v \leftarrow b + 2 \cdot MP\_PREC - u$ \\ -3. Allocate $v$ digits. \\ -4. for $n$ from $0$ to $v - 1$ do \\ -\hspace{3mm}4.1 $a_n \leftarrow 0$ \\ -5. $a.sign \leftarrow MP\_ZPOS$\\ -6. $a.used \leftarrow 0$\\ -7. $a.alloc \leftarrow v$\\ -8. Return(\textit{MP\_OKAY})\\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_init\_size} -\end{figure} - -\textbf{Algorithm mp\_init\_size.} -This algorithm will initialize an mp\_int structure $a$ like algorithm mp\_init with the exception that the number of -digits allocated can be controlled by the second input argument $b$. The input size is padded upwards so it is a -multiple of \textbf{MP\_PREC} plus an additional \textbf{MP\_PREC} digits. This padding is used to prevent trivial -allocations from becoming a bottleneck in the rest of the algorithms. - -Like algorithm mp\_init, the mp\_int structure is initialized to a default state representing the integer zero. This -particular algorithm is useful if it is known ahead of time the approximate size of the input. If the approximation is -correct no further memory re-allocations are required to work with the mp\_int. - -EXAM,bn_mp_init_size.c - -If the memory can be successfully allocated the mp\_int is placed in a default state representing the integer zero. Otherwise, the error code \textbf{MP\_MEM} will be -returned (line @27,return@). - -The digits are allocated with the malloc() function (line @27,XMALLOC@) and set to zero afterwards (line @38,for@). The -\textbf{used} count is set to zero, the \textbf{alloc} count set to the padded digit count and the \textbf{sign} flag set -to \textbf{MP\_ZPOS} to achieve a default valid mp\_int state (lines @29,used@, @30,alloc@ and @31,sign@). If the function -returns succesfully then it is correct to assume that the mp\_int structure is in a valid state for the remainder of the -functions to work with. - -\subsection{Multiple Integer Initializations and Clearings} -Occasionally a function will require a series of mp\_int data types to be made available simultaneously. -The purpose of algorithm mp\_init\_multi is to initialize a variable length array of mp\_int structures in a single -statement. It is essentially a shortcut to multiple initializations. - -\newpage\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_init\_multi}. \\ -\textbf{Input}. Variable length array $V_k$ of mp\_int variables of length $k$. \\ -\textbf{Output}. The array is initialized such that each mp\_int of $V_k$ is ready to use. \\ -\hline \\ -1. for $n$ from 0 to $k - 1$ do \\ -\hspace{+3mm}1.1. Initialize the mp\_int $V_n$ (\textit{mp\_init}) \\ -\hspace{+3mm}1.2. If initialization failed then do \\ -\hspace{+6mm}1.2.1. for $j$ from $0$ to $n$ do \\ -\hspace{+9mm}1.2.1.1. Free the mp\_int $V_j$ (\textit{mp\_clear}) \\ -\hspace{+6mm}1.2.2. Return(\textit{MP\_MEM}) \\ -2. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_init\_multi} -\end{figure} - -\textbf{Algorithm mp\_init\_multi.} -The algorithm will initialize the array of mp\_int variables one at a time. If a runtime error has been detected -(\textit{step 1.2}) all of the previously initialized variables are cleared. The goal is an ``all or nothing'' -initialization which allows for quick recovery from runtime errors. - -EXAM,bn_mp_init_multi.c - -This function intializes a variable length list of mp\_int structure pointers. However, instead of having the mp\_int -structures in an actual C array they are simply passed as arguments to the function. This function makes use of the -``...'' argument syntax of the C programming language. The list is terminated with a final \textbf{NULL} argument -appended on the right. - -The function uses the ``stdarg.h'' \textit{va} functions to step portably through the arguments to the function. A count -$n$ of succesfully initialized mp\_int structures is maintained (line @47,n++@) such that if a failure does occur, -the algorithm can backtrack and free the previously initialized structures (lines @27,if@ to @46,}@). - - -\subsection{Clamping Excess Digits} -When a function anticipates a result will be $n$ digits it is simpler to assume this is true within the body of -the function instead of checking during the computation. For example, a multiplication of a $i$ digit number by a -$j$ digit produces a result of at most $i + j$ digits. It is entirely possible that the result is $i + j - 1$ -though, with no final carry into the last position. However, suppose the destination had to be first expanded -(\textit{via mp\_grow}) to accomodate $i + j - 1$ digits than further expanded to accomodate the final carry. -That would be a considerable waste of time since heap operations are relatively slow. - -The ideal solution is to always assume the result is $i + j$ and fix up the \textbf{used} count after the function -terminates. This way a single heap operation (\textit{at most}) is required. However, if the result was not checked -there would be an excess high order zero digit. - -For example, suppose the product of two integers was $x_n = (0x_{n-1}x_{n-2}...x_0)_{\beta}$. The leading zero digit -will not contribute to the precision of the result. In fact, through subsequent operations more leading zero digits would -accumulate to the point the size of the integer would be prohibitive. As a result even though the precision is very -low the representation is excessively large. - -The mp\_clamp algorithm is designed to solve this very problem. It will trim high-order zeros by decrementing the -\textbf{used} count until a non-zero most significant digit is found. Also in this system, zero is considered to be a -positive number which means that if the \textbf{used} count is decremented to zero, the sign must be set to -\textbf{MP\_ZPOS}. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_clamp}. \\ -\textbf{Input}. An mp\_int $a$ \\ -\textbf{Output}. Any excess leading zero digits of $a$ are removed \\ -\hline \\ -1. while $a.used > 0$ and $a_{a.used - 1} = 0$ do \\ -\hspace{+3mm}1.1 $a.used \leftarrow a.used - 1$ \\ -2. if $a.used = 0$ then do \\ -\hspace{+3mm}2.1 $a.sign \leftarrow MP\_ZPOS$ \\ -\hline \\ -\end{tabular} -\end{center} -\caption{Algorithm mp\_clamp} -\end{figure} - -\textbf{Algorithm mp\_clamp.} -As can be expected this algorithm is very simple. The loop on step one is expected to iterate only once or twice at -the most. For example, this will happen in cases where there is not a carry to fill the last position. Step two fixes the sign for -when all of the digits are zero to ensure that the mp\_int is valid at all times. - -EXAM,bn_mp_clamp.c - -Note on line @27,while@ how to test for the \textbf{used} count is made on the left of the \&\& operator. In the C programming -language the terms to \&\& are evaluated left to right with a boolean short-circuit if any condition fails. This is -important since if the \textbf{used} is zero the test on the right would fetch below the array. That is obviously -undesirable. The parenthesis on line @28,a->used@ is used to make sure the \textbf{used} count is decremented and not -the pointer ``a''. - -\section*{Exercises} -\begin{tabular}{cl} -$\left [ 1 \right ]$ & Discuss the relevance of the \textbf{used} member of the mp\_int structure. \\ - & \\ -$\left [ 1 \right ]$ & Discuss the consequences of not using padding when performing allocations. \\ - & \\ -$\left [ 2 \right ]$ & Estimate an ideal value for \textbf{MP\_PREC} when performing 1024-bit RSA \\ - & encryption when $\beta = 2^{28}$. \\ - & \\ -$\left [ 1 \right ]$ & Discuss the relevance of the algorithm mp\_clamp. What does it prevent? \\ - & \\ -$\left [ 1 \right ]$ & Give an example of when the algorithm mp\_init\_copy might be useful. \\ - & \\ -\end{tabular} - - -%%% -% CHAPTER FOUR -%%% - -\chapter{Basic Operations} - -\section{Introduction} -In the previous chapter a series of low level algorithms were established that dealt with initializing and maintaining -mp\_int structures. This chapter will discuss another set of seemingly non-algebraic algorithms which will form the low -level basis of the entire library. While these algorithm are relatively trivial it is important to understand how they -work before proceeding since these algorithms will be used almost intrinsically in the following chapters. - -The algorithms in this chapter deal primarily with more ``programmer'' related tasks such as creating copies of -mp\_int structures, assigning small values to mp\_int structures and comparisons of the values mp\_int structures -represent. - -\section{Assigning Values to mp\_int Structures} -\subsection{Copying an mp\_int} -Assigning the value that a given mp\_int structure represents to another mp\_int structure shall be known as making -a copy for the purposes of this text. The copy of the mp\_int will be a separate entity that represents the same -value as the mp\_int it was copied from. The mp\_copy algorithm provides this functionality. - -\newpage\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_copy}. \\ -\textbf{Input}. An mp\_int $a$ and $b$. \\ -\textbf{Output}. Store a copy of $a$ in $b$. \\ -\hline \\ -1. If $b.alloc < a.used$ then grow $b$ to $a.used$ digits. (\textit{mp\_grow}) \\ -2. for $n$ from 0 to $a.used - 1$ do \\ -\hspace{3mm}2.1 $b_{n} \leftarrow a_{n}$ \\ -3. for $n$ from $a.used$ to $b.used - 1$ do \\ -\hspace{3mm}3.1 $b_{n} \leftarrow 0$ \\ -4. $b.used \leftarrow a.used$ \\ -5. $b.sign \leftarrow a.sign$ \\ -6. return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_copy} -\end{figure} - -\textbf{Algorithm mp\_copy.} -This algorithm copies the mp\_int $a$ such that upon succesful termination of the algorithm the mp\_int $b$ will -represent the same integer as the mp\_int $a$. The mp\_int $b$ shall be a complete and distinct copy of the -mp\_int $a$ meaing that the mp\_int $a$ can be modified and it shall not affect the value of the mp\_int $b$. - -If $b$ does not have enough room for the digits of $a$ it must first have its precision augmented via the mp\_grow -algorithm. The digits of $a$ are copied over the digits of $b$ and any excess digits of $b$ are set to zero (step two -and three). The \textbf{used} and \textbf{sign} members of $a$ are finally copied over the respective members of -$b$. - -\textbf{Remark.} This algorithm also introduces a new idiosyncrasy that will be used throughout the rest of the -text. The error return codes of other algorithms are not explicitly checked in the pseudo-code presented. For example, in -step one of the mp\_copy algorithm the return of mp\_grow is not explicitly checked to ensure it succeeded. Text space is -limited so it is assumed that if a algorithm fails it will clear all temporarily allocated mp\_ints and return -the error code itself. However, the C code presented will demonstrate all of the error handling logic required to -implement the pseudo-code. - -EXAM,bn_mp_copy.c - -Occasionally a dependent algorithm may copy an mp\_int effectively into itself such as when the input and output -mp\_int structures passed to a function are one and the same. For this case it is optimal to return immediately without -copying digits (line @24,a == b@). - -The mp\_int $b$ must have enough digits to accomodate the used digits of the mp\_int $a$. If $b.alloc$ is less than -$a.used$ the algorithm mp\_grow is used to augment the precision of $b$ (lines @29,alloc@ to @33,}@). In order to -simplify the inner loop that copies the digits from $a$ to $b$, two aliases $tmpa$ and $tmpb$ point directly at the digits -of the mp\_ints $a$ and $b$ respectively. These aliases (lines @42,tmpa@ and @45,tmpb@) allow the compiler to access the digits without first dereferencing the -mp\_int pointers and then subsequently the pointer to the digits. - -After the aliases are established the digits from $a$ are copied into $b$ (lines @48,for@ to @50,}@) and then the excess -digits of $b$ are set to zero (lines @53,for@ to @55,}@). Both ``for'' loops make use of the pointer aliases and in -fact the alias for $b$ is carried through into the second ``for'' loop to clear the excess digits. This optimization -allows the alias to stay in a machine register fairly easy between the two loops. - -\textbf{Remarks.} The use of pointer aliases is an implementation methodology first introduced in this function that will -be used considerably in other functions. Technically, a pointer alias is simply a short hand alias used to lower the -number of pointer dereferencing operations required to access data. For example, a for loop may resemble - -\begin{alltt} -for (x = 0; x < 100; x++) \{ - a->num[4]->dp[x] = 0; -\} -\end{alltt} - -This could be re-written using aliases as - -\begin{alltt} -mp_digit *tmpa; -a = a->num[4]->dp; -for (x = 0; x < 100; x++) \{ - *a++ = 0; -\} -\end{alltt} - -In this case an alias is used to access the -array of digits within an mp\_int structure directly. It may seem that a pointer alias is strictly not required -as a compiler may optimize out the redundant pointer operations. However, there are two dominant reasons to use aliases. - -The first reason is that most compilers will not effectively optimize pointer arithmetic. For example, some optimizations -may work for the Microsoft Visual C++ compiler (MSVC) and not for the GNU C Compiler (GCC). Also some optimizations may -work for GCC and not MSVC. As such it is ideal to find a common ground for as many compilers as possible. Pointer -aliases optimize the code considerably before the compiler even reads the source code which means the end compiled code -stands a better chance of being faster. - -The second reason is that pointer aliases often can make an algorithm simpler to read. Consider the first ``for'' -loop of the function mp\_copy() re-written to not use pointer aliases. - -\begin{alltt} - /* copy all the digits */ - for (n = 0; n < a->used; n++) \{ - b->dp[n] = a->dp[n]; - \} -\end{alltt} - -Whether this code is harder to read depends strongly on the individual. However, it is quantifiably slightly more -complicated as there are four variables within the statement instead of just two. - -\subsubsection{Nested Statements} -Another commonly used technique in the source routines is that certain sections of code are nested. This is used in -particular with the pointer aliases to highlight code phases. For example, a Comba multiplier (discussed in chapter six) -will typically have three different phases. First the temporaries are initialized, then the columns calculated and -finally the carries are propagated. In this example the middle column production phase will typically be nested as it -uses temporary variables and aliases the most. - -The nesting also simplies the source code as variables that are nested are only valid for their scope. As a result -the various temporary variables required do not propagate into other sections of code. - - -\subsection{Creating a Clone} -Another common operation is to make a local temporary copy of an mp\_int argument. To initialize an mp\_int -and then copy another existing mp\_int into the newly intialized mp\_int will be known as creating a clone. This is -useful within functions that need to modify an argument but do not wish to actually modify the original copy. The -mp\_init\_copy algorithm has been designed to help perform this task. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_init\_copy}. \\ -\textbf{Input}. An mp\_int $a$ and $b$\\ -\textbf{Output}. $a$ is initialized to be a copy of $b$. \\ -\hline \\ -1. Init $a$. (\textit{mp\_init}) \\ -2. Copy $b$ to $a$. (\textit{mp\_copy}) \\ -3. Return the status of the copy operation. \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_init\_copy} -\end{figure} - -\textbf{Algorithm mp\_init\_copy.} -This algorithm will initialize an mp\_int variable and copy another previously initialized mp\_int variable into it. As -such this algorithm will perform two operations in one step. - -EXAM,bn_mp_init_copy.c - -This will initialize \textbf{a} and make it a verbatim copy of the contents of \textbf{b}. Note that -\textbf{a} will have its own memory allocated which means that \textbf{b} may be cleared after the call -and \textbf{a} will be left intact. - -\section{Zeroing an Integer} -Reseting an mp\_int to the default state is a common step in many algorithms. The mp\_zero algorithm will be the algorithm used to -perform this task. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_zero}. \\ -\textbf{Input}. An mp\_int $a$ \\ -\textbf{Output}. Zero the contents of $a$ \\ -\hline \\ -1. $a.used \leftarrow 0$ \\ -2. $a.sign \leftarrow$ MP\_ZPOS \\ -3. for $n$ from 0 to $a.alloc - 1$ do \\ -\hspace{3mm}3.1 $a_n \leftarrow 0$ \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_zero} -\end{figure} - -\textbf{Algorithm mp\_zero.} -This algorithm simply resets a mp\_int to the default state. - -EXAM,bn_mp_zero.c - -After the function is completed, all of the digits are zeroed, the \textbf{used} count is zeroed and the -\textbf{sign} variable is set to \textbf{MP\_ZPOS}. - -\section{Sign Manipulation} -\subsection{Absolute Value} -With the mp\_int representation of an integer, calculating the absolute value is trivial. The mp\_abs algorithm will compute -the absolute value of an mp\_int. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_abs}. \\ -\textbf{Input}. An mp\_int $a$ \\ -\textbf{Output}. Computes $b = \vert a \vert$ \\ -\hline \\ -1. Copy $a$ to $b$. (\textit{mp\_copy}) \\ -2. If the copy failed return(\textit{MP\_MEM}). \\ -3. $b.sign \leftarrow MP\_ZPOS$ \\ -4. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_abs} -\end{figure} - -\textbf{Algorithm mp\_abs.} -This algorithm computes the absolute of an mp\_int input. First it copies $a$ over $b$. This is an example of an -algorithm where the check in mp\_copy that determines if the source and destination are equal proves useful. This allows, -for instance, the developer to pass the same mp\_int as the source and destination to this function without addition -logic to handle it. - -EXAM,bn_mp_abs.c - -This fairly trivial algorithm first eliminates non--required duplications (line @27,a != b@) and then sets the -\textbf{sign} flag to \textbf{MP\_ZPOS}. - -\subsection{Integer Negation} -With the mp\_int representation of an integer, calculating the negation is also trivial. The mp\_neg algorithm will compute -the negative of an mp\_int input. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_neg}. \\ -\textbf{Input}. An mp\_int $a$ \\ -\textbf{Output}. Computes $b = -a$ \\ -\hline \\ -1. Copy $a$ to $b$. (\textit{mp\_copy}) \\ -2. If the copy failed return(\textit{MP\_MEM}). \\ -3. If $a.used = 0$ then return(\textit{MP\_OKAY}). \\ -4. If $a.sign = MP\_ZPOS$ then do \\ -\hspace{3mm}4.1 $b.sign = MP\_NEG$. \\ -5. else do \\ -\hspace{3mm}5.1 $b.sign = MP\_ZPOS$. \\ -6. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_neg} -\end{figure} - -\textbf{Algorithm mp\_neg.} -This algorithm computes the negation of an input. First it copies $a$ over $b$. If $a$ has no used digits then -the algorithm returns immediately. Otherwise it flips the sign flag and stores the result in $b$. Note that if -$a$ had no digits then it must be positive by definition. Had step three been omitted then the algorithm would return -zero as negative. - -EXAM,bn_mp_neg.c - -Like mp\_abs() this function avoids non--required duplications (line @21,a != b@) and then sets the sign. We -have to make sure that only non--zero values get a \textbf{sign} of \textbf{MP\_NEG}. If the mp\_int is zero -than the \textbf{sign} is hard--coded to \textbf{MP\_ZPOS}. - -\section{Small Constants} -\subsection{Setting Small Constants} -Often a mp\_int must be set to a relatively small value such as $1$ or $2$. For these cases the mp\_set algorithm is useful. - -\newpage\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_set}. \\ -\textbf{Input}. An mp\_int $a$ and a digit $b$ \\ -\textbf{Output}. Make $a$ equivalent to $b$ \\ -\hline \\ -1. Zero $a$ (\textit{mp\_zero}). \\ -2. $a_0 \leftarrow b \mbox{ (mod }\beta\mbox{)}$ \\ -3. $a.used \leftarrow \left \lbrace \begin{array}{ll} - 1 & \mbox{if }a_0 > 0 \\ - 0 & \mbox{if }a_0 = 0 - \end{array} \right .$ \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_set} -\end{figure} - -\textbf{Algorithm mp\_set.} -This algorithm sets a mp\_int to a small single digit value. Step number 1 ensures that the integer is reset to the default state. The -single digit is set (\textit{modulo $\beta$}) and the \textbf{used} count is adjusted accordingly. - -EXAM,bn_mp_set.c - -First we zero (line @21,mp_zero@) the mp\_int to make sure that the other members are initialized for a -small positive constant. mp\_zero() ensures that the \textbf{sign} is positive and the \textbf{used} count -is zero. Next we set the digit and reduce it modulo $\beta$ (line @22,MP_MASK@). After this step we have to -check if the resulting digit is zero or not. If it is not then we set the \textbf{used} count to one, otherwise -to zero. - -We can quickly reduce modulo $\beta$ since it is of the form $2^k$ and a quick binary AND operation with -$2^k - 1$ will perform the same operation. - -One important limitation of this function is that it will only set one digit. The size of a digit is not fixed, meaning source that uses -this function should take that into account. Only trivially small constants can be set using this function. - -\subsection{Setting Large Constants} -To overcome the limitations of the mp\_set algorithm the mp\_set\_int algorithm is ideal. It accepts a ``long'' -data type as input and will always treat it as a 32-bit integer. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_set\_int}. \\ -\textbf{Input}. An mp\_int $a$ and a ``long'' integer $b$ \\ -\textbf{Output}. Make $a$ equivalent to $b$ \\ -\hline \\ -1. Zero $a$ (\textit{mp\_zero}) \\ -2. for $n$ from 0 to 7 do \\ -\hspace{3mm}2.1 $a \leftarrow a \cdot 16$ (\textit{mp\_mul2d}) \\ -\hspace{3mm}2.2 $u \leftarrow \lfloor b / 2^{4(7 - n)} \rfloor \mbox{ (mod }16\mbox{)}$\\ -\hspace{3mm}2.3 $a_0 \leftarrow a_0 + u$ \\ -\hspace{3mm}2.4 $a.used \leftarrow a.used + 1$ \\ -3. Clamp excess used digits (\textit{mp\_clamp}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_set\_int} -\end{figure} - -\textbf{Algorithm mp\_set\_int.} -The algorithm performs eight iterations of a simple loop where in each iteration four bits from the source are added to the -mp\_int. Step 2.1 will multiply the current result by sixteen making room for four more bits in the less significant positions. In step 2.2 the -next four bits from the source are extracted and are added to the mp\_int. The \textbf{used} digit count is -incremented to reflect the addition. The \textbf{used} digit counter is incremented since if any of the leading digits were zero the mp\_int would have -zero digits used and the newly added four bits would be ignored. - -Excess zero digits are trimmed in steps 2.1 and 3 by using higher level algorithms mp\_mul2d and mp\_clamp. - -EXAM,bn_mp_set_int.c - -This function sets four bits of the number at a time to handle all practical \textbf{DIGIT\_BIT} sizes. The weird -addition on line @38,a->used@ ensures that the newly added in bits are added to the number of digits. While it may not -seem obvious as to why the digit counter does not grow exceedingly large it is because of the shift on line @27,mp_mul_2d@ -as well as the call to mp\_clamp() on line @40,mp_clamp@. Both functions will clamp excess leading digits which keeps -the number of used digits low. - -\section{Comparisons} -\subsection{Unsigned Comparisions} -Comparing a multiple precision integer is performed with the exact same algorithm used to compare two decimal numbers. For example, -to compare $1,234$ to $1,264$ the digits are extracted by their positions. That is we compare $1 \cdot 10^3 + 2 \cdot 10^2 + 3 \cdot 10^1 + 4 \cdot 10^0$ -to $1 \cdot 10^3 + 2 \cdot 10^2 + 6 \cdot 10^1 + 4 \cdot 10^0$ by comparing single digits at a time starting with the highest magnitude -positions. If any leading digit of one integer is greater than a digit in the same position of another integer then obviously it must be greater. - -The first comparision routine that will be developed is the unsigned magnitude compare which will perform a comparison based on the digits of two -mp\_int variables alone. It will ignore the sign of the two inputs. Such a function is useful when an absolute comparison is required or if the -signs are known to agree in advance. - -To facilitate working with the results of the comparison functions three constants are required. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{|r|l|} -\hline \textbf{Constant} & \textbf{Meaning} \\ -\hline \textbf{MP\_GT} & Greater Than \\ -\hline \textbf{MP\_EQ} & Equal To \\ -\hline \textbf{MP\_LT} & Less Than \\ -\hline -\end{tabular} -\end{center} -\caption{Comparison Return Codes} -\end{figure} - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_cmp\_mag}. \\ -\textbf{Input}. Two mp\_ints $a$ and $b$. \\ -\textbf{Output}. Unsigned comparison results ($a$ to the left of $b$). \\ -\hline \\ -1. If $a.used > b.used$ then return(\textit{MP\_GT}) \\ -2. If $a.used < b.used$ then return(\textit{MP\_LT}) \\ -3. for n from $a.used - 1$ to 0 do \\ -\hspace{+3mm}3.1 if $a_n > b_n$ then return(\textit{MP\_GT}) \\ -\hspace{+3mm}3.2 if $a_n < b_n$ then return(\textit{MP\_LT}) \\ -4. Return(\textit{MP\_EQ}) \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_cmp\_mag} -\end{figure} - -\textbf{Algorithm mp\_cmp\_mag.} -By saying ``$a$ to the left of $b$'' it is meant that the comparison is with respect to $a$, that is if $a$ is greater than $b$ it will return -\textbf{MP\_GT} and similar with respect to when $a = b$ and $a < b$. The first two steps compare the number of digits used in both $a$ and $b$. -Obviously if the digit counts differ there would be an imaginary zero digit in the smaller number where the leading digit of the larger number is. -If both have the same number of digits than the actual digits themselves must be compared starting at the leading digit. - -By step three both inputs must have the same number of digits so its safe to start from either $a.used - 1$ or $b.used - 1$ and count down to -the zero'th digit. If after all of the digits have been compared, no difference is found, the algorithm returns \textbf{MP\_EQ}. - -EXAM,bn_mp_cmp_mag.c - -The two if statements (lines @24,if@ and @28,if@) compare the number of digits in the two inputs. These two are -performed before all of the digits are compared since it is a very cheap test to perform and can potentially save -considerable time. The implementation given is also not valid without those two statements. $b.alloc$ may be -smaller than $a.used$, meaning that undefined values will be read from $b$ past the end of the array of digits. - - - -\subsection{Signed Comparisons} -Comparing with sign considerations is also fairly critical in several routines (\textit{division for example}). Based on an unsigned magnitude -comparison a trivial signed comparison algorithm can be written. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_cmp}. \\ -\textbf{Input}. Two mp\_ints $a$ and $b$ \\ -\textbf{Output}. Signed Comparison Results ($a$ to the left of $b$) \\ -\hline \\ -1. if $a.sign = MP\_NEG$ and $b.sign = MP\_ZPOS$ then return(\textit{MP\_LT}) \\ -2. if $a.sign = MP\_ZPOS$ and $b.sign = MP\_NEG$ then return(\textit{MP\_GT}) \\ -3. if $a.sign = MP\_NEG$ then \\ -\hspace{+3mm}3.1 Return the unsigned comparison of $b$ and $a$ (\textit{mp\_cmp\_mag}) \\ -4 Otherwise \\ -\hspace{+3mm}4.1 Return the unsigned comparison of $a$ and $b$ \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_cmp} -\end{figure} - -\textbf{Algorithm mp\_cmp.} -The first two steps compare the signs of the two inputs. If the signs do not agree then it can return right away with the appropriate -comparison code. When the signs are equal the digits of the inputs must be compared to determine the correct result. In step -three the unsigned comparision flips the order of the arguments since they are both negative. For instance, if $-a > -b$ then -$\vert a \vert < \vert b \vert$. Step number four will compare the two when they are both positive. - -EXAM,bn_mp_cmp.c - -The two if statements (lines @22,if@ and @26,if@) perform the initial sign comparison. If the signs are not the equal then which ever -has the positive sign is larger. The inputs are compared (line @30,if@) based on magnitudes. If the signs were both -negative then the unsigned comparison is performed in the opposite direction (line @31,mp_cmp_mag@). Otherwise, the signs are assumed to -be both positive and a forward direction unsigned comparison is performed. - -\section*{Exercises} -\begin{tabular}{cl} -$\left [ 2 \right ]$ & Modify algorithm mp\_set\_int to accept as input a variable length array of bits. \\ - & \\ -$\left [ 3 \right ]$ & Give the probability that algorithm mp\_cmp\_mag will have to compare $k$ digits \\ - & of two random digits (of equal magnitude) before a difference is found. \\ - & \\ -$\left [ 1 \right ]$ & Suggest a simple method to speed up the implementation of mp\_cmp\_mag based \\ - & on the observations made in the previous problem. \\ - & -\end{tabular} - -\chapter{Basic Arithmetic} -\section{Introduction} -At this point algorithms for initialization, clearing, zeroing, copying, comparing and setting small constants have been -established. The next logical set of algorithms to develop are addition, subtraction and digit shifting algorithms. These -algorithms make use of the lower level algorithms and are the cruicial building block for the multiplication algorithms. It is very important -that these algorithms are highly optimized. On their own they are simple $O(n)$ algorithms but they can be called from higher level algorithms -which easily places them at $O(n^2)$ or even $O(n^3)$ work levels. - -MARK,SHIFTS -All of the algorithms within this chapter make use of the logical bit shift operations denoted by $<<$ and $>>$ for left and right -logical shifts respectively. A logical shift is analogous to sliding the decimal point of radix-10 representations. For example, the real -number $0.9345$ is equivalent to $93.45\%$ which is found by sliding the the decimal two places to the right (\textit{multiplying by $\beta^2 = 10^2$}). -Algebraically a binary logical shift is equivalent to a division or multiplication by a power of two. -For example, $a << k = a \cdot 2^k$ while $a >> k = \lfloor a/2^k \rfloor$. - -One significant difference between a logical shift and the way decimals are shifted is that digits below the zero'th position are removed -from the number. For example, consider $1101_2 >> 1$ using decimal notation this would produce $110.1_2$. However, with a logical shift the -result is $110_2$. - -\section{Addition and Subtraction} -In common twos complement fixed precision arithmetic negative numbers are easily represented by subtraction from the modulus. For example, with 32-bit integers -$a - b\mbox{ (mod }2^{32}\mbox{)}$ is the same as $a + (2^{32} - b) \mbox{ (mod }2^{32}\mbox{)}$ since $2^{32} \equiv 0 \mbox{ (mod }2^{32}\mbox{)}$. -As a result subtraction can be performed with a trivial series of logical operations and an addition. - -However, in multiple precision arithmetic negative numbers are not represented in the same way. Instead a sign flag is used to keep track of the -sign of the integer. As a result signed addition and subtraction are actually implemented as conditional usage of lower level addition or -subtraction algorithms with the sign fixed up appropriately. - -The lower level algorithms will add or subtract integers without regard to the sign flag. That is they will add or subtract the magnitude of -the integers respectively. - -\subsection{Low Level Addition} -An unsigned addition of multiple precision integers is performed with the same long-hand algorithm used to add decimal numbers. That is to add the -trailing digits first and propagate the resulting carry upwards. Since this is a lower level algorithm the name will have a ``s\_'' prefix. -Historically that convention stems from the MPI library where ``s\_'' stood for static functions that were hidden from the developer entirely. - -\newpage -\begin{figure}[!h] -\begin{center} -\begin{small} -\begin{tabular}{l} -\hline Algorithm \textbf{s\_mp\_add}. \\ -\textbf{Input}. Two mp\_ints $a$ and $b$ \\ -\textbf{Output}. The unsigned addition $c = \vert a \vert + \vert b \vert$. \\ -\hline \\ -1. if $a.used > b.used$ then \\ -\hspace{+3mm}1.1 $min \leftarrow b.used$ \\ -\hspace{+3mm}1.2 $max \leftarrow a.used$ \\ -\hspace{+3mm}1.3 $x \leftarrow a$ \\ -2. else \\ -\hspace{+3mm}2.1 $min \leftarrow a.used$ \\ -\hspace{+3mm}2.2 $max \leftarrow b.used$ \\ -\hspace{+3mm}2.3 $x \leftarrow b$ \\ -3. If $c.alloc < max + 1$ then grow $c$ to hold at least $max + 1$ digits (\textit{mp\_grow}) \\ -4. $oldused \leftarrow c.used$ \\ -5. $c.used \leftarrow max + 1$ \\ -6. $u \leftarrow 0$ \\ -7. for $n$ from $0$ to $min - 1$ do \\ -\hspace{+3mm}7.1 $c_n \leftarrow a_n + b_n + u$ \\ -\hspace{+3mm}7.2 $u \leftarrow c_n >> lg(\beta)$ \\ -\hspace{+3mm}7.3 $c_n \leftarrow c_n \mbox{ (mod }\beta\mbox{)}$ \\ -8. if $min \ne max$ then do \\ -\hspace{+3mm}8.1 for $n$ from $min$ to $max - 1$ do \\ -\hspace{+6mm}8.1.1 $c_n \leftarrow x_n + u$ \\ -\hspace{+6mm}8.1.2 $u \leftarrow c_n >> lg(\beta)$ \\ -\hspace{+6mm}8.1.3 $c_n \leftarrow c_n \mbox{ (mod }\beta\mbox{)}$ \\ -9. $c_{max} \leftarrow u$ \\ -10. if $olduse > max$ then \\ -\hspace{+3mm}10.1 for $n$ from $max + 1$ to $oldused - 1$ do \\ -\hspace{+6mm}10.1.1 $c_n \leftarrow 0$ \\ -11. Clamp excess digits in $c$. (\textit{mp\_clamp}) \\ -12. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{small} -\end{center} -\caption{Algorithm s\_mp\_add} -\end{figure} - -\textbf{Algorithm s\_mp\_add.} -This algorithm is loosely based on algorithm 14.7 of HAC \cite[pp. 594]{HAC} but has been extended to allow the inputs to have different magnitudes. -Coincidentally the description of algorithm A in Knuth \cite[pp. 266]{TAOCPV2} shares the same deficiency as the algorithm from \cite{HAC}. Even the -MIX pseudo machine code presented by Knuth \cite[pp. 266-267]{TAOCPV2} is incapable of handling inputs which are of different magnitudes. - -The first thing that has to be accomplished is to sort out which of the two inputs is the largest. The addition logic -will simply add all of the smallest input to the largest input and store that first part of the result in the -destination. Then it will apply a simpler addition loop to excess digits of the larger input. - -The first two steps will handle sorting the inputs such that $min$ and $max$ hold the digit counts of the two -inputs. The variable $x$ will be an mp\_int alias for the largest input or the second input $b$ if they have the -same number of digits. After the inputs are sorted the destination $c$ is grown as required to accomodate the sum -of the two inputs. The original \textbf{used} count of $c$ is copied and set to the new used count. - -At this point the first addition loop will go through as many digit positions that both inputs have. The carry -variable $\mu$ is set to zero outside the loop. Inside the loop an ``addition'' step requires three statements to produce -one digit of the summand. First -two digits from $a$ and $b$ are added together along with the carry $\mu$. The carry of this step is extracted and stored -in $\mu$ and finally the digit of the result $c_n$ is truncated within the range $0 \le c_n < \beta$. - -Now all of the digit positions that both inputs have in common have been exhausted. If $min \ne max$ then $x$ is an alias -for one of the inputs that has more digits. A simplified addition loop is then used to essentially copy the remaining digits -and the carry to the destination. - -The final carry is stored in $c_{max}$ and digits above $max$ upto $oldused$ are zeroed which completes the addition. - - -EXAM,bn_s_mp_add.c - -We first sort (lines @27,if@ to @35,}@) the inputs based on magnitude and determine the $min$ and $max$ variables. -Note that $x$ is a pointer to an mp\_int assigned to the largest input, in effect it is a local alias. Next we -grow the destination (@37,init@ to @42,}@) ensure that it can accomodate the result of the addition. - -Similar to the implementation of mp\_copy this function uses the braced code and local aliases coding style. The three aliases that are on -lines @56,tmpa@, @59,tmpb@ and @62,tmpc@ represent the two inputs and destination variables respectively. These aliases are used to ensure the -compiler does not have to dereference $a$, $b$ or $c$ (respectively) to access the digits of the respective mp\_int. - -The initial carry $u$ will be cleared (line @65,u = 0@), note that $u$ is of type mp\_digit which ensures type -compatibility within the implementation. The initial addition (line @66,for@ to @75,}@) adds digits from -both inputs until the smallest input runs out of digits. Similarly the conditional addition loop -(line @81,for@ to @90,}@) adds the remaining digits from the larger of the two inputs. The addition is finished -with the final carry being stored in $tmpc$ (line @94,tmpc++@). Note the ``++'' operator within the same expression. -After line @94,tmpc++@, $tmpc$ will point to the $c.used$'th digit of the mp\_int $c$. This is useful -for the next loop (line @97,for@ to @99,}@) which set any old upper digits to zero. - -\subsection{Low Level Subtraction} -The low level unsigned subtraction algorithm is very similar to the low level unsigned addition algorithm. The principle difference is that the -unsigned subtraction algorithm requires the result to be positive. That is when computing $a - b$ the condition $\vert a \vert \ge \vert b\vert$ must -be met for this algorithm to function properly. Keep in mind this low level algorithm is not meant to be used in higher level algorithms directly. -This algorithm as will be shown can be used to create functional signed addition and subtraction algorithms. - -MARK,GAMMA - -For this algorithm a new variable is required to make the description simpler. Recall from section 1.3.1 that a mp\_digit must be able to represent -the range $0 \le x < 2\beta$ for the algorithms to work correctly. However, it is allowable that a mp\_digit represent a larger range of values. For -this algorithm we will assume that the variable $\gamma$ represents the number of bits available in a -mp\_digit (\textit{this implies $2^{\gamma} > \beta$}). - -For example, the default for LibTomMath is to use a ``unsigned long'' for the mp\_digit ``type'' while $\beta = 2^{28}$. In ISO C an ``unsigned long'' -data type must be able to represent $0 \le x < 2^{32}$ meaning that in this case $\gamma \ge 32$. - -\newpage\begin{figure}[!h] -\begin{center} -\begin{small} -\begin{tabular}{l} -\hline Algorithm \textbf{s\_mp\_sub}. \\ -\textbf{Input}. Two mp\_ints $a$ and $b$ ($\vert a \vert \ge \vert b \vert$) \\ -\textbf{Output}. The unsigned subtraction $c = \vert a \vert - \vert b \vert$. \\ -\hline \\ -1. $min \leftarrow b.used$ \\ -2. $max \leftarrow a.used$ \\ -3. If $c.alloc < max$ then grow $c$ to hold at least $max$ digits. (\textit{mp\_grow}) \\ -4. $oldused \leftarrow c.used$ \\ -5. $c.used \leftarrow max$ \\ -6. $u \leftarrow 0$ \\ -7. for $n$ from $0$ to $min - 1$ do \\ -\hspace{3mm}7.1 $c_n \leftarrow a_n - b_n - u$ \\ -\hspace{3mm}7.2 $u \leftarrow c_n >> (\gamma - 1)$ \\ -\hspace{3mm}7.3 $c_n \leftarrow c_n \mbox{ (mod }\beta\mbox{)}$ \\ -8. if $min < max$ then do \\ -\hspace{3mm}8.1 for $n$ from $min$ to $max - 1$ do \\ -\hspace{6mm}8.1.1 $c_n \leftarrow a_n - u$ \\ -\hspace{6mm}8.1.2 $u \leftarrow c_n >> (\gamma - 1)$ \\ -\hspace{6mm}8.1.3 $c_n \leftarrow c_n \mbox{ (mod }\beta\mbox{)}$ \\ -9. if $oldused > max$ then do \\ -\hspace{3mm}9.1 for $n$ from $max$ to $oldused - 1$ do \\ -\hspace{6mm}9.1.1 $c_n \leftarrow 0$ \\ -10. Clamp excess digits of $c$. (\textit{mp\_clamp}). \\ -11. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{small} -\end{center} -\caption{Algorithm s\_mp\_sub} -\end{figure} - -\textbf{Algorithm s\_mp\_sub.} -This algorithm performs the unsigned subtraction of two mp\_int variables under the restriction that the result must be positive. That is when -passing variables $a$ and $b$ the condition that $\vert a \vert \ge \vert b \vert$ must be met for the algorithm to function correctly. This -algorithm is loosely based on algorithm 14.9 \cite[pp. 595]{HAC} and is similar to algorithm S in \cite[pp. 267]{TAOCPV2} as well. As was the case -of the algorithm s\_mp\_add both other references lack discussion concerning various practical details such as when the inputs differ in magnitude. - -The initial sorting of the inputs is trivial in this algorithm since $a$ is guaranteed to have at least the same magnitude of $b$. Steps 1 and 2 -set the $min$ and $max$ variables. Unlike the addition routine there is guaranteed to be no carry which means that the final result can be at -most $max$ digits in length as opposed to $max + 1$. Similar to the addition algorithm the \textbf{used} count of $c$ is copied locally and -set to the maximal count for the operation. - -The subtraction loop that begins on step seven is essentially the same as the addition loop of algorithm s\_mp\_add except single precision -subtraction is used instead. Note the use of the $\gamma$ variable to extract the carry (\textit{also known as the borrow}) within the subtraction -loops. Under the assumption that two's complement single precision arithmetic is used this will successfully extract the desired carry. - -For example, consider subtracting $0101_2$ from $0100_2$ where $\gamma = 4$ and $\beta = 2$. The least significant bit will force a carry upwards to -the third bit which will be set to zero after the borrow. After the very first bit has been subtracted $4 - 1 \equiv 0011_2$ will remain, When the -third bit of $0101_2$ is subtracted from the result it will cause another carry. In this case though the carry will be forced to propagate all the -way to the most significant bit. - -Recall that $\beta < 2^{\gamma}$. This means that if a carry does occur just before the $lg(\beta)$'th bit it will propagate all the way to the most -significant bit. Thus, the high order bits of the mp\_digit that are not part of the actual digit will either be all zero, or all one. All that -is needed is a single zero or one bit for the carry. Therefore a single logical shift right by $\gamma - 1$ positions is sufficient to extract the -carry. This method of carry extraction may seem awkward but the reason for it becomes apparent when the implementation is discussed. - -If $b$ has a smaller magnitude than $a$ then step 9 will force the carry and copy operation to propagate through the larger input $a$ into $c$. Step -10 will ensure that any leading digits of $c$ above the $max$'th position are zeroed. - -EXAM,bn_s_mp_sub.c - -Like low level addition we ``sort'' the inputs. Except in this case the sorting is hardcoded -(lines @24,min@ and @25,max@). In reality the $min$ and $max$ variables are only aliases and are only -used to make the source code easier to read. Again the pointer alias optimization is used -within this algorithm. The aliases $tmpa$, $tmpb$ and $tmpc$ are initialized -(lines @42,tmpa@, @43,tmpb@ and @44,tmpc@) for $a$, $b$ and $c$ respectively. - -The first subtraction loop (lines @47,u = 0@ through @61,}@) subtract digits from both inputs until the smaller of -the two inputs has been exhausted. As remarked earlier there is an implementation reason for using the ``awkward'' -method of extracting the carry (line @57, >>@). The traditional method for extracting the carry would be to shift -by $lg(\beta)$ positions and logically AND the least significant bit. The AND operation is required because all of -the bits above the $\lg(\beta)$'th bit will be set to one after a carry occurs from subtraction. This carry -extraction requires two relatively cheap operations to extract the carry. The other method is to simply shift the -most significant bit to the least significant bit thus extracting the carry with a single cheap operation. This -optimization only works on twos compliment machines which is a safe assumption to make. - -If $a$ has a larger magnitude than $b$ an additional loop (lines @64,for@ through @73,}@) is required to propagate -the carry through $a$ and copy the result to $c$. - -\subsection{High Level Addition} -Now that both lower level addition and subtraction algorithms have been established an effective high level signed addition algorithm can be -established. This high level addition algorithm will be what other algorithms and developers will use to perform addition of mp\_int data -types. - -Recall from section 5.2 that an mp\_int represents an integer with an unsigned mantissa (\textit{the array of digits}) and a \textbf{sign} -flag. A high level addition is actually performed as a series of eight separate cases which can be optimized down to three unique cases. - -\begin{figure}[!h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_add}. \\ -\textbf{Input}. Two mp\_ints $a$ and $b$ \\ -\textbf{Output}. The signed addition $c = a + b$. \\ -\hline \\ -1. if $a.sign = b.sign$ then do \\ -\hspace{3mm}1.1 $c.sign \leftarrow a.sign$ \\ -\hspace{3mm}1.2 $c \leftarrow \vert a \vert + \vert b \vert$ (\textit{s\_mp\_add})\\ -2. else do \\ -\hspace{3mm}2.1 if $\vert a \vert < \vert b \vert$ then do (\textit{mp\_cmp\_mag}) \\ -\hspace{6mm}2.1.1 $c.sign \leftarrow b.sign$ \\ -\hspace{6mm}2.1.2 $c \leftarrow \vert b \vert - \vert a \vert$ (\textit{s\_mp\_sub}) \\ -\hspace{3mm}2.2 else do \\ -\hspace{6mm}2.2.1 $c.sign \leftarrow a.sign$ \\ -\hspace{6mm}2.2.2 $c \leftarrow \vert a \vert - \vert b \vert$ \\ -3. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_add} -\end{figure} - -\textbf{Algorithm mp\_add.} -This algorithm performs the signed addition of two mp\_int variables. There is no reference algorithm to draw upon from -either \cite{TAOCPV2} or \cite{HAC} since they both only provide unsigned operations. The algorithm is fairly -straightforward but restricted since subtraction can only produce positive results. - -\begin{figure}[h] -\begin{small} -\begin{center} -\begin{tabular}{|c|c|c|c|c|} -\hline \textbf{Sign of $a$} & \textbf{Sign of $b$} & \textbf{$\vert a \vert > \vert b \vert $} & \textbf{Unsigned Operation} & \textbf{Result Sign Flag} \\ -\hline $+$ & $+$ & Yes & $c = a + b$ & $a.sign$ \\ -\hline $+$ & $+$ & No & $c = a + b$ & $a.sign$ \\ -\hline $-$ & $-$ & Yes & $c = a + b$ & $a.sign$ \\ -\hline $-$ & $-$ & No & $c = a + b$ & $a.sign$ \\ -\hline &&&&\\ - -\hline $+$ & $-$ & No & $c = b - a$ & $b.sign$ \\ -\hline $-$ & $+$ & No & $c = b - a$ & $b.sign$ \\ - -\hline &&&&\\ - -\hline $+$ & $-$ & Yes & $c = a - b$ & $a.sign$ \\ -\hline $-$ & $+$ & Yes & $c = a - b$ & $a.sign$ \\ - -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Addition Guide Chart} -\label{fig:AddChart} -\end{figure} - -Figure~\ref{fig:AddChart} lists all of the eight possible input combinations and is sorted to show that only three -specific cases need to be handled. The return code of the unsigned operations at step 1.2, 2.1.2 and 2.2.2 are -forwarded to step three to check for errors. This simplifies the description of the algorithm considerably and best -follows how the implementation actually was achieved. - -Also note how the \textbf{sign} is set before the unsigned addition or subtraction is performed. Recall from the descriptions of algorithms -s\_mp\_add and s\_mp\_sub that the mp\_clamp function is used at the end to trim excess digits. The mp\_clamp algorithm will set the \textbf{sign} -to \textbf{MP\_ZPOS} when the \textbf{used} digit count reaches zero. - -For example, consider performing $-a + a$ with algorithm mp\_add. By the description of the algorithm the sign is set to \textbf{MP\_NEG} which would -produce a result of $-0$. However, since the sign is set first then the unsigned addition is performed the subsequent usage of algorithm mp\_clamp -within algorithm s\_mp\_add will force $-0$ to become $0$. - -EXAM,bn_mp_add.c - -The source code follows the algorithm fairly closely. The most notable new source code addition is the usage of the $res$ integer variable which -is used to pass result of the unsigned operations forward. Unlike in the algorithm, the variable $res$ is merely returned as is without -explicitly checking it and returning the constant \textbf{MP\_OKAY}. The observation is this algorithm will succeed or fail only if the lower -level functions do so. Returning their return code is sufficient. - -\subsection{High Level Subtraction} -The high level signed subtraction algorithm is essentially the same as the high level signed addition algorithm. - -\newpage\begin{figure}[!h] -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_sub}. \\ -\textbf{Input}. Two mp\_ints $a$ and $b$ \\ -\textbf{Output}. The signed subtraction $c = a - b$. \\ -\hline \\ -1. if $a.sign \ne b.sign$ then do \\ -\hspace{3mm}1.1 $c.sign \leftarrow a.sign$ \\ -\hspace{3mm}1.2 $c \leftarrow \vert a \vert + \vert b \vert$ (\textit{s\_mp\_add}) \\ -2. else do \\ -\hspace{3mm}2.1 if $\vert a \vert \ge \vert b \vert$ then do (\textit{mp\_cmp\_mag}) \\ -\hspace{6mm}2.1.1 $c.sign \leftarrow a.sign$ \\ -\hspace{6mm}2.1.2 $c \leftarrow \vert a \vert - \vert b \vert$ (\textit{s\_mp\_sub}) \\ -\hspace{3mm}2.2 else do \\ -\hspace{6mm}2.2.1 $c.sign \leftarrow \left \lbrace \begin{array}{ll} - MP\_ZPOS & \mbox{if }a.sign = MP\_NEG \\ - MP\_NEG & \mbox{otherwise} \\ - \end{array} \right .$ \\ -\hspace{6mm}2.2.2 $c \leftarrow \vert b \vert - \vert a \vert$ \\ -3. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\caption{Algorithm mp\_sub} -\end{figure} - -\textbf{Algorithm mp\_sub.} -This algorithm performs the signed subtraction of two inputs. Similar to algorithm mp\_add there is no reference in either \cite{TAOCPV2} or -\cite{HAC}. Also this algorithm is restricted by algorithm s\_mp\_sub. Chart \ref{fig:SubChart} lists the eight possible inputs and -the operations required. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{|c|c|c|c|c|} -\hline \textbf{Sign of $a$} & \textbf{Sign of $b$} & \textbf{$\vert a \vert \ge \vert b \vert $} & \textbf{Unsigned Operation} & \textbf{Result Sign Flag} \\ -\hline $+$ & $-$ & Yes & $c = a + b$ & $a.sign$ \\ -\hline $+$ & $-$ & No & $c = a + b$ & $a.sign$ \\ -\hline $-$ & $+$ & Yes & $c = a + b$ & $a.sign$ \\ -\hline $-$ & $+$ & No & $c = a + b$ & $a.sign$ \\ -\hline &&&& \\ -\hline $+$ & $+$ & Yes & $c = a - b$ & $a.sign$ \\ -\hline $-$ & $-$ & Yes & $c = a - b$ & $a.sign$ \\ -\hline &&&& \\ -\hline $+$ & $+$ & No & $c = b - a$ & $\mbox{opposite of }a.sign$ \\ -\hline $-$ & $-$ & No & $c = b - a$ & $\mbox{opposite of }a.sign$ \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Subtraction Guide Chart} -\label{fig:SubChart} -\end{figure} - -Similar to the case of algorithm mp\_add the \textbf{sign} is set first before the unsigned addition or subtraction. That is to prevent the -algorithm from producing $-a - -a = -0$ as a result. - -EXAM,bn_mp_sub.c - -Much like the implementation of algorithm mp\_add the variable $res$ is used to catch the return code of the unsigned addition or subtraction operations -and forward it to the end of the function. On line @38, != MP_LT@ the ``not equal to'' \textbf{MP\_LT} expression is used to emulate a -``greater than or equal to'' comparison. - -\section{Bit and Digit Shifting} -MARK,POLY -It is quite common to think of a multiple precision integer as a polynomial in $x$, that is $y = f(\beta)$ where $f(x) = \sum_{i=0}^{n-1} a_i x^i$. -This notation arises within discussion of Montgomery and Diminished Radix Reduction as well as Karatsuba multiplication and squaring. - -In order to facilitate operations on polynomials in $x$ as above a series of simple ``digit'' algorithms have to be established. That is to shift -the digits left or right as well to shift individual bits of the digits left and right. It is important to note that not all ``shift'' operations -are on radix-$\beta$ digits. - -\subsection{Multiplication by Two} - -In a binary system where the radix is a power of two multiplication by two not only arises often in other algorithms it is a fairly efficient -operation to perform. A single precision logical shift left is sufficient to multiply a single digit by two. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_mul\_2}. \\ -\textbf{Input}. One mp\_int $a$ \\ -\textbf{Output}. $b = 2a$. \\ -\hline \\ -1. If $b.alloc < a.used + 1$ then grow $b$ to hold $a.used + 1$ digits. (\textit{mp\_grow}) \\ -2. $oldused \leftarrow b.used$ \\ -3. $b.used \leftarrow a.used$ \\ -4. $r \leftarrow 0$ \\ -5. for $n$ from 0 to $a.used - 1$ do \\ -\hspace{3mm}5.1 $rr \leftarrow a_n >> (lg(\beta) - 1)$ \\ -\hspace{3mm}5.2 $b_n \leftarrow (a_n << 1) + r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}5.3 $r \leftarrow rr$ \\ -6. If $r \ne 0$ then do \\ -\hspace{3mm}6.1 $b_{n + 1} \leftarrow r$ \\ -\hspace{3mm}6.2 $b.used \leftarrow b.used + 1$ \\ -7. If $b.used < oldused - 1$ then do \\ -\hspace{3mm}7.1 for $n$ from $b.used$ to $oldused - 1$ do \\ -\hspace{6mm}7.1.1 $b_n \leftarrow 0$ \\ -8. $b.sign \leftarrow a.sign$ \\ -9. Return(\textit{MP\_OKAY}).\\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_mul\_2} -\end{figure} - -\textbf{Algorithm mp\_mul\_2.} -This algorithm will quickly multiply a mp\_int by two provided $\beta$ is a power of two. Neither \cite{TAOCPV2} nor \cite{HAC} describe such -an algorithm despite the fact it arises often in other algorithms. The algorithm is setup much like the lower level algorithm s\_mp\_add since -it is for all intents and purposes equivalent to the operation $b = \vert a \vert + \vert a \vert$. - -Step 1 and 2 grow the input as required to accomodate the maximum number of \textbf{used} digits in the result. The initial \textbf{used} count -is set to $a.used$ at step 4. Only if there is a final carry will the \textbf{used} count require adjustment. - -Step 6 is an optimization implementation of the addition loop for this specific case. That is since the two values being added together -are the same there is no need to perform two reads from the digits of $a$. Step 6.1 performs a single precision shift on the current digit $a_n$ to -obtain what will be the carry for the next iteration. Step 6.2 calculates the $n$'th digit of the result as single precision shift of $a_n$ plus -the previous carry. Recall from ~SHIFTS~ that $a_n << 1$ is equivalent to $a_n \cdot 2$. An iteration of the addition loop is finished with -forwarding the carry to the next iteration. - -Step 7 takes care of any final carry by setting the $a.used$'th digit of the result to the carry and augmenting the \textbf{used} count of $b$. -Step 8 clears any leading digits of $b$ in case it originally had a larger magnitude than $a$. - -EXAM,bn_mp_mul_2.c - -This implementation is essentially an optimized implementation of s\_mp\_add for the case of doubling an input. The only noteworthy difference -is the use of the logical shift operator on line @52,<<@ to perform a single precision doubling. - -\subsection{Division by Two} -A division by two can just as easily be accomplished with a logical shift right as multiplication by two can be with a logical shift left. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_div\_2}. \\ -\textbf{Input}. One mp\_int $a$ \\ -\textbf{Output}. $b = a/2$. \\ -\hline \\ -1. If $b.alloc < a.used$ then grow $b$ to hold $a.used$ digits. (\textit{mp\_grow}) \\ -2. If the reallocation failed return(\textit{MP\_MEM}). \\ -3. $oldused \leftarrow b.used$ \\ -4. $b.used \leftarrow a.used$ \\ -5. $r \leftarrow 0$ \\ -6. for $n$ from $b.used - 1$ to $0$ do \\ -\hspace{3mm}6.1 $rr \leftarrow a_n \mbox{ (mod }2\mbox{)}$\\ -\hspace{3mm}6.2 $b_n \leftarrow (a_n >> 1) + (r << (lg(\beta) - 1)) \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}6.3 $r \leftarrow rr$ \\ -7. If $b.used < oldused - 1$ then do \\ -\hspace{3mm}7.1 for $n$ from $b.used$ to $oldused - 1$ do \\ -\hspace{6mm}7.1.1 $b_n \leftarrow 0$ \\ -8. $b.sign \leftarrow a.sign$ \\ -9. Clamp excess digits of $b$. (\textit{mp\_clamp}) \\ -10. Return(\textit{MP\_OKAY}).\\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_div\_2} -\end{figure} - -\textbf{Algorithm mp\_div\_2.} -This algorithm will divide an mp\_int by two using logical shifts to the right. Like mp\_mul\_2 it uses a modified low level addition -core as the basis of the algorithm. Unlike mp\_mul\_2 the shift operations work from the leading digit to the trailing digit. The algorithm -could be written to work from the trailing digit to the leading digit however, it would have to stop one short of $a.used - 1$ digits to prevent -reading past the end of the array of digits. - -Essentially the loop at step 6 is similar to that of mp\_mul\_2 except the logical shifts go in the opposite direction and the carry is at the -least significant bit not the most significant bit. - -EXAM,bn_mp_div_2.c - -\section{Polynomial Basis Operations} -Recall from ~POLY~ that any integer can be represented as a polynomial in $x$ as $y = f(\beta)$. Such a representation is also known as -the polynomial basis \cite[pp. 48]{ROSE}. Given such a notation a multiplication or division by $x$ amounts to shifting whole digits a single -place. The need for such operations arises in several other higher level algorithms such as Barrett and Montgomery reduction, integer -division and Karatsuba multiplication. - -Converting from an array of digits to polynomial basis is very simple. Consider the integer $y \equiv (a_2, a_1, a_0)_{\beta}$ and recall that -$y = \sum_{i=0}^{2} a_i \beta^i$. Simply replace $\beta$ with $x$ and the expression is in polynomial basis. For example, $f(x) = 8x + 9$ is the -polynomial basis representation for $89$ using radix ten. That is, $f(10) = 8(10) + 9 = 89$. - -\subsection{Multiplication by $x$} - -Given a polynomial in $x$ such as $f(x) = a_n x^n + a_{n-1} x^{n-1} + ... + a_0$ multiplying by $x$ amounts to shifting the coefficients up one -degree. In this case $f(x) \cdot x = a_n x^{n+1} + a_{n-1} x^n + ... + a_0 x$. From a scalar basis point of view multiplying by $x$ is equivalent to -multiplying by the integer $\beta$. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_lshd}. \\ -\textbf{Input}. One mp\_int $a$ and an integer $b$ \\ -\textbf{Output}. $a \leftarrow a \cdot \beta^b$ (equivalent to multiplication by $x^b$). \\ -\hline \\ -1. If $b \le 0$ then return(\textit{MP\_OKAY}). \\ -2. If $a.alloc < a.used + b$ then grow $a$ to at least $a.used + b$ digits. (\textit{mp\_grow}). \\ -3. If the reallocation failed return(\textit{MP\_MEM}). \\ -4. $a.used \leftarrow a.used + b$ \\ -5. $i \leftarrow a.used - 1$ \\ -6. $j \leftarrow a.used - 1 - b$ \\ -7. for $n$ from $a.used - 1$ to $b$ do \\ -\hspace{3mm}7.1 $a_{i} \leftarrow a_{j}$ \\ -\hspace{3mm}7.2 $i \leftarrow i - 1$ \\ -\hspace{3mm}7.3 $j \leftarrow j - 1$ \\ -8. for $n$ from 0 to $b - 1$ do \\ -\hspace{3mm}8.1 $a_n \leftarrow 0$ \\ -9. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_lshd} -\end{figure} - -\textbf{Algorithm mp\_lshd.} -This algorithm multiplies an mp\_int by the $b$'th power of $x$. This is equivalent to multiplying by $\beta^b$. The algorithm differs -from the other algorithms presented so far as it performs the operation in place instead storing the result in a separate location. The -motivation behind this change is due to the way this function is typically used. Algorithms such as mp\_add store the result in an optionally -different third mp\_int because the original inputs are often still required. Algorithm mp\_lshd (\textit{and similarly algorithm mp\_rshd}) is -typically used on values where the original value is no longer required. The algorithm will return success immediately if -$b \le 0$ since the rest of algorithm is only valid when $b > 0$. - -First the destination $a$ is grown as required to accomodate the result. The counters $i$ and $j$ are used to form a \textit{sliding window} over -the digits of $a$ of length $b$. The head of the sliding window is at $i$ (\textit{the leading digit}) and the tail at $j$ (\textit{the trailing digit}). -The loop on step 7 copies the digit from the tail to the head. In each iteration the window is moved down one digit. The last loop on -step 8 sets the lower $b$ digits to zero. - -\newpage -FIGU,sliding_window,Sliding Window Movement - -EXAM,bn_mp_lshd.c - -The if statement (line @24,if@) ensures that the $b$ variable is greater than zero since we do not interpret negative -shift counts properly. The \textbf{used} count is incremented by $b$ before the copy loop begins. This elminates -the need for an additional variable in the for loop. The variable $top$ (line @42,top@) is an alias -for the leading digit while $bottom$ (line @45,bottom@) is an alias for the trailing edge. The aliases form a -window of exactly $b$ digits over the input. - -\subsection{Division by $x$} - -Division by powers of $x$ is easily achieved by shifting the digits right and removing any that will end up to the right of the zero'th digit. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_rshd}. \\ -\textbf{Input}. One mp\_int $a$ and an integer $b$ \\ -\textbf{Output}. $a \leftarrow a / \beta^b$ (Divide by $x^b$). \\ -\hline \\ -1. If $b \le 0$ then return. \\ -2. If $a.used \le b$ then do \\ -\hspace{3mm}2.1 Zero $a$. (\textit{mp\_zero}). \\ -\hspace{3mm}2.2 Return. \\ -3. $i \leftarrow 0$ \\ -4. $j \leftarrow b$ \\ -5. for $n$ from 0 to $a.used - b - 1$ do \\ -\hspace{3mm}5.1 $a_i \leftarrow a_j$ \\ -\hspace{3mm}5.2 $i \leftarrow i + 1$ \\ -\hspace{3mm}5.3 $j \leftarrow j + 1$ \\ -6. for $n$ from $a.used - b$ to $a.used - 1$ do \\ -\hspace{3mm}6.1 $a_n \leftarrow 0$ \\ -7. $a.used \leftarrow a.used - b$ \\ -8. Return. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_rshd} -\end{figure} - -\textbf{Algorithm mp\_rshd.} -This algorithm divides the input in place by the $b$'th power of $x$. It is analogous to dividing by a $\beta^b$ but much quicker since -it does not require single precision division. This algorithm does not actually return an error code as it cannot fail. - -If the input $b$ is less than one the algorithm quickly returns without performing any work. If the \textbf{used} count is less than or equal -to the shift count $b$ then it will simply zero the input and return. - -After the trivial cases of inputs have been handled the sliding window is setup. Much like the case of algorithm mp\_lshd a sliding window that -is $b$ digits wide is used to copy the digits. Unlike mp\_lshd the window slides in the opposite direction from the trailing to the leading digit. -Also the digits are copied from the leading to the trailing edge. - -Once the window copy is complete the upper digits must be zeroed and the \textbf{used} count decremented. - -EXAM,bn_mp_rshd.c - -The only noteworthy element of this routine is the lack of a return type since it cannot fail. Like mp\_lshd() we -form a sliding window except we copy in the other direction. After the window (line @59,for (;@) we then zero -the upper digits of the input to make sure the result is correct. - -\section{Powers of Two} - -Now that algorithms for moving single bits as well as whole digits exist algorithms for moving the ``in between'' distances are required. For -example, to quickly multiply by $2^k$ for any $k$ without using a full multiplier algorithm would prove useful. Instead of performing single -shifts $k$ times to achieve a multiplication by $2^{\pm k}$ a mixture of whole digit shifting and partial digit shifting is employed. - -\subsection{Multiplication by Power of Two} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_mul\_2d}. \\ -\textbf{Input}. One mp\_int $a$ and an integer $b$ \\ -\textbf{Output}. $c \leftarrow a \cdot 2^b$. \\ -\hline \\ -1. $c \leftarrow a$. (\textit{mp\_copy}) \\ -2. If $c.alloc < c.used + \lfloor b / lg(\beta) \rfloor + 2$ then grow $c$ accordingly. \\ -3. If the reallocation failed return(\textit{MP\_MEM}). \\ -4. If $b \ge lg(\beta)$ then \\ -\hspace{3mm}4.1 $c \leftarrow c \cdot \beta^{\lfloor b / lg(\beta) \rfloor}$ (\textit{mp\_lshd}). \\ -\hspace{3mm}4.2 If step 4.1 failed return(\textit{MP\_MEM}). \\ -5. $d \leftarrow b \mbox{ (mod }lg(\beta)\mbox{)}$ \\ -6. If $d \ne 0$ then do \\ -\hspace{3mm}6.1 $mask \leftarrow 2^d$ \\ -\hspace{3mm}6.2 $r \leftarrow 0$ \\ -\hspace{3mm}6.3 for $n$ from $0$ to $c.used - 1$ do \\ -\hspace{6mm}6.3.1 $rr \leftarrow c_n >> (lg(\beta) - d) \mbox{ (mod }mask\mbox{)}$ \\ -\hspace{6mm}6.3.2 $c_n \leftarrow (c_n << d) + r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{6mm}6.3.3 $r \leftarrow rr$ \\ -\hspace{3mm}6.4 If $r > 0$ then do \\ -\hspace{6mm}6.4.1 $c_{c.used} \leftarrow r$ \\ -\hspace{6mm}6.4.2 $c.used \leftarrow c.used + 1$ \\ -7. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_mul\_2d} -\end{figure} - -\textbf{Algorithm mp\_mul\_2d.} -This algorithm multiplies $a$ by $2^b$ and stores the result in $c$. The algorithm uses algorithm mp\_lshd and a derivative of algorithm mp\_mul\_2 to -quickly compute the product. - -First the algorithm will multiply $a$ by $x^{\lfloor b / lg(\beta) \rfloor}$ which will ensure that the remainder multiplicand is less than -$\beta$. For example, if $b = 37$ and $\beta = 2^{28}$ then this step will multiply by $x$ leaving a multiplication by $2^{37 - 28} = 2^{9}$ -left. - -After the digits have been shifted appropriately at most $lg(\beta) - 1$ shifts are left to perform. Step 5 calculates the number of remaining shifts -required. If it is non-zero a modified shift loop is used to calculate the remaining product. -Essentially the loop is a generic version of algorithm mp\_mul\_2 designed to handle any shift count in the range $1 \le x < lg(\beta)$. The $mask$ -variable is used to extract the upper $d$ bits to form the carry for the next iteration. - -This algorithm is loosely measured as a $O(2n)$ algorithm which means that if the input is $n$-digits that it takes $2n$ ``time'' to -complete. It is possible to optimize this algorithm down to a $O(n)$ algorithm at a cost of making the algorithm slightly harder to follow. - -EXAM,bn_mp_mul_2d.c - -The shifting is performed in--place which means the first step (line @24,a != c@) is to copy the input to the -destination. We avoid calling mp\_copy() by making sure the mp\_ints are different. The destination then -has to be grown (line @31,grow@) to accomodate the result. - -If the shift count $b$ is larger than $lg(\beta)$ then a call to mp\_lshd() is used to handle all of the multiples -of $lg(\beta)$. Leaving only a remaining shift of $lg(\beta) - 1$ or fewer bits left. Inside the actual shift -loop (lines @45,if@ to @76,}@) we make use of pre--computed values $shift$ and $mask$. These are used to -extract the carry bit(s) to pass into the next iteration of the loop. The $r$ and $rr$ variables form a -chain between consecutive iterations to propagate the carry. - -\subsection{Division by Power of Two} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_div\_2d}. \\ -\textbf{Input}. One mp\_int $a$ and an integer $b$ \\ -\textbf{Output}. $c \leftarrow \lfloor a / 2^b \rfloor, d \leftarrow a \mbox{ (mod }2^b\mbox{)}$. \\ -\hline \\ -1. If $b \le 0$ then do \\ -\hspace{3mm}1.1 $c \leftarrow a$ (\textit{mp\_copy}) \\ -\hspace{3mm}1.2 $d \leftarrow 0$ (\textit{mp\_zero}) \\ -\hspace{3mm}1.3 Return(\textit{MP\_OKAY}). \\ -2. $c \leftarrow a$ \\ -3. $d \leftarrow a \mbox{ (mod }2^b\mbox{)}$ (\textit{mp\_mod\_2d}) \\ -4. If $b \ge lg(\beta)$ then do \\ -\hspace{3mm}4.1 $c \leftarrow \lfloor c/\beta^{\lfloor b/lg(\beta) \rfloor} \rfloor$ (\textit{mp\_rshd}). \\ -5. $k \leftarrow b \mbox{ (mod }lg(\beta)\mbox{)}$ \\ -6. If $k \ne 0$ then do \\ -\hspace{3mm}6.1 $mask \leftarrow 2^k$ \\ -\hspace{3mm}6.2 $r \leftarrow 0$ \\ -\hspace{3mm}6.3 for $n$ from $c.used - 1$ to $0$ do \\ -\hspace{6mm}6.3.1 $rr \leftarrow c_n \mbox{ (mod }mask\mbox{)}$ \\ -\hspace{6mm}6.3.2 $c_n \leftarrow (c_n >> k) + (r << (lg(\beta) - k))$ \\ -\hspace{6mm}6.3.3 $r \leftarrow rr$ \\ -7. Clamp excess digits of $c$. (\textit{mp\_clamp}) \\ -8. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_div\_2d} -\end{figure} - -\textbf{Algorithm mp\_div\_2d.} -This algorithm will divide an input $a$ by $2^b$ and produce the quotient and remainder. The algorithm is designed much like algorithm -mp\_mul\_2d by first using whole digit shifts then single precision shifts. This algorithm will also produce the remainder of the division -by using algorithm mp\_mod\_2d. - -EXAM,bn_mp_div_2d.c - -The implementation of algorithm mp\_div\_2d is slightly different than the algorithm specifies. The remainder $d$ may be optionally -ignored by passing \textbf{NULL} as the pointer to the mp\_int variable. The temporary mp\_int variable $t$ is used to hold the -result of the remainder operation until the end. This allows $d$ and $a$ to represent the same mp\_int without modifying $a$ before -the quotient is obtained. - -The remainder of the source code is essentially the same as the source code for mp\_mul\_2d. The only significant difference is -the direction of the shifts. - -\subsection{Remainder of Division by Power of Two} - -The last algorithm in the series of polynomial basis power of two algorithms is calculating the remainder of division by $2^b$. This -algorithm benefits from the fact that in twos complement arithmetic $a \mbox{ (mod }2^b\mbox{)}$ is the same as $a$ AND $2^b - 1$. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_mod\_2d}. \\ -\textbf{Input}. One mp\_int $a$ and an integer $b$ \\ -\textbf{Output}. $c \leftarrow a \mbox{ (mod }2^b\mbox{)}$. \\ -\hline \\ -1. If $b \le 0$ then do \\ -\hspace{3mm}1.1 $c \leftarrow 0$ (\textit{mp\_zero}) \\ -\hspace{3mm}1.2 Return(\textit{MP\_OKAY}). \\ -2. If $b > a.used \cdot lg(\beta)$ then do \\ -\hspace{3mm}2.1 $c \leftarrow a$ (\textit{mp\_copy}) \\ -\hspace{3mm}2.2 Return the result of step 2.1. \\ -3. $c \leftarrow a$ \\ -4. If step 3 failed return(\textit{MP\_MEM}). \\ -5. for $n$ from $\lceil b / lg(\beta) \rceil$ to $c.used$ do \\ -\hspace{3mm}5.1 $c_n \leftarrow 0$ \\ -6. $k \leftarrow b \mbox{ (mod }lg(\beta)\mbox{)}$ \\ -7. $c_{\lfloor b / lg(\beta) \rfloor} \leftarrow c_{\lfloor b / lg(\beta) \rfloor} \mbox{ (mod }2^{k}\mbox{)}$. \\ -8. Clamp excess digits of $c$. (\textit{mp\_clamp}) \\ -9. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_mod\_2d} -\end{figure} - -\textbf{Algorithm mp\_mod\_2d.} -This algorithm will quickly calculate the value of $a \mbox{ (mod }2^b\mbox{)}$. First if $b$ is less than or equal to zero the -result is set to zero. If $b$ is greater than the number of bits in $a$ then it simply copies $a$ to $c$ and returns. Otherwise, $a$ -is copied to $b$, leading digits are removed and the remaining leading digit is trimed to the exact bit count. - -EXAM,bn_mp_mod_2d.c - -We first avoid cases of $b \le 0$ by simply mp\_zero()'ing the destination in such cases. Next if $2^b$ is larger -than the input we just mp\_copy() the input and return right away. After this point we know we must actually -perform some work to produce the remainder. - -Recalling that reducing modulo $2^k$ and a binary ``and'' with $2^k - 1$ are numerically equivalent we can quickly reduce -the number. First we zero any digits above the last digit in $2^b$ (line @41,for@). Next we reduce the -leading digit of both (line @45,&=@) and then mp\_clamp(). - -\section*{Exercises} -\begin{tabular}{cl} -$\left [ 3 \right ] $ & Devise an algorithm that performs $a \cdot 2^b$ for generic values of $b$ \\ - & in $O(n)$ time. \\ - &\\ -$\left [ 3 \right ] $ & Devise an efficient algorithm to multiply by small low hamming \\ - & weight values such as $3$, $5$ and $9$. Extend it to handle all values \\ - & upto $64$ with a hamming weight less than three. \\ - &\\ -$\left [ 2 \right ] $ & Modify the preceding algorithm to handle values of the form \\ - & $2^k - 1$ as well. \\ - &\\ -$\left [ 3 \right ] $ & Using only algorithms mp\_mul\_2, mp\_div\_2 and mp\_add create an \\ - & algorithm to multiply two integers in roughly $O(2n^2)$ time for \\ - & any $n$-bit input. Note that the time of addition is ignored in the \\ - & calculation. \\ - & \\ -$\left [ 5 \right ] $ & Improve the previous algorithm to have a working time of at most \\ - & $O \left (2^{(k-1)}n + \left ({2n^2 \over k} \right ) \right )$ for an appropriate choice of $k$. Again ignore \\ - & the cost of addition. \\ - & \\ -$\left [ 2 \right ] $ & Devise a chart to find optimal values of $k$ for the previous problem \\ - & for $n = 64 \ldots 1024$ in steps of $64$. \\ - & \\ -$\left [ 2 \right ] $ & Using only algorithms mp\_abs and mp\_sub devise another method for \\ - & calculating the result of a signed comparison. \\ - & -\end{tabular} - -\chapter{Multiplication and Squaring} -\section{The Multipliers} -For most number theoretic problems including certain public key cryptographic algorithms, the ``multipliers'' form the most important subset of -algorithms of any multiple precision integer package. The set of multiplier algorithms include integer multiplication, squaring and modular reduction -where in each of the algorithms single precision multiplication is the dominant operation performed. This chapter will discuss integer multiplication -and squaring, leaving modular reductions for the subsequent chapter. - -The importance of the multiplier algorithms is for the most part driven by the fact that certain popular public key algorithms are based on modular -exponentiation, that is computing $d \equiv a^b \mbox{ (mod }c\mbox{)}$ for some arbitrary choice of $a$, $b$, $c$ and $d$. During a modular -exponentiation the majority\footnote{Roughly speaking a modular exponentiation will spend about 40\% of the time performing modular reductions, -35\% of the time performing squaring and 25\% of the time performing multiplications.} of the processor time is spent performing single precision -multiplications. - -For centuries general purpose multiplication has required a lengthly $O(n^2)$ process, whereby each digit of one multiplicand has to be multiplied -against every digit of the other multiplicand. Traditional long-hand multiplication is based on this process; while the techniques can differ the -overall algorithm used is essentially the same. Only ``recently'' have faster algorithms been studied. First Karatsuba multiplication was discovered in -1962. This algorithm can multiply two numbers with considerably fewer single precision multiplications when compared to the long-hand approach. -This technique led to the discovery of polynomial basis algorithms (\textit{good reference?}) and subquently Fourier Transform based solutions. - -\section{Multiplication} -\subsection{The Baseline Multiplication} -\label{sec:basemult} -\index{baseline multiplication} -Computing the product of two integers in software can be achieved using a trivial adaptation of the standard $O(n^2)$ long-hand multiplication -algorithm that school children are taught. The algorithm is considered an $O(n^2)$ algorithm since for two $n$-digit inputs $n^2$ single precision -multiplications are required. More specifically for a $m$ and $n$ digit input $m \cdot n$ single precision multiplications are required. To -simplify most discussions, it will be assumed that the inputs have comparable number of digits. - -The ``baseline multiplication'' algorithm is designed to act as the ``catch-all'' algorithm, only to be used when the faster algorithms cannot be -used. This algorithm does not use any particularly interesting optimizations and should ideally be avoided if possible. One important -facet of this algorithm, is that it has been modified to only produce a certain amount of output digits as resolution. The importance of this -modification will become evident during the discussion of Barrett modular reduction. Recall that for a $n$ and $m$ digit input the product -will be at most $n + m$ digits. Therefore, this algorithm can be reduced to a full multiplier by having it produce $n + m$ digits of the product. - -Recall from ~GAMMA~ the definition of $\gamma$ as the number of bits in the type \textbf{mp\_digit}. We shall now extend the variable set to -include $\alpha$ which shall represent the number of bits in the type \textbf{mp\_word}. This implies that $2^{\alpha} > 2 \cdot \beta^2$. The -constant $\delta = 2^{\alpha - 2lg(\beta)}$ will represent the maximal weight of any column in a product (\textit{see ~COMBA~ for more information}). - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{s\_mp\_mul\_digs}. \\ -\textbf{Input}. mp\_int $a$, mp\_int $b$ and an integer $digs$ \\ -\textbf{Output}. $c \leftarrow \vert a \vert \cdot \vert b \vert \mbox{ (mod }\beta^{digs}\mbox{)}$. \\ -\hline \\ -1. If min$(a.used, b.used) < \delta$ then do \\ -\hspace{3mm}1.1 Calculate $c = \vert a \vert \cdot \vert b \vert$ by the Comba method (\textit{see algorithm~\ref{fig:COMBAMULT}}). \\ -\hspace{3mm}1.2 Return the result of step 1.1 \\ -\\ -Allocate and initialize a temporary mp\_int. \\ -2. Init $t$ to be of size $digs$ \\ -3. If step 2 failed return(\textit{MP\_MEM}). \\ -4. $t.used \leftarrow digs$ \\ -\\ -Compute the product. \\ -5. for $ix$ from $0$ to $a.used - 1$ do \\ -\hspace{3mm}5.1 $u \leftarrow 0$ \\ -\hspace{3mm}5.2 $pb \leftarrow \mbox{min}(b.used, digs - ix)$ \\ -\hspace{3mm}5.3 If $pb < 1$ then goto step 6. \\ -\hspace{3mm}5.4 for $iy$ from $0$ to $pb - 1$ do \\ -\hspace{6mm}5.4.1 $\hat r \leftarrow t_{iy + ix} + a_{ix} \cdot b_{iy} + u$ \\ -\hspace{6mm}5.4.2 $t_{iy + ix} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{6mm}5.4.3 $u \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -\hspace{3mm}5.5 if $ix + pb < digs$ then do \\ -\hspace{6mm}5.5.1 $t_{ix + pb} \leftarrow u$ \\ -6. Clamp excess digits of $t$. \\ -7. Swap $c$ with $t$ \\ -8. Clear $t$ \\ -9. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm s\_mp\_mul\_digs} -\end{figure} - -\textbf{Algorithm s\_mp\_mul\_digs.} -This algorithm computes the unsigned product of two inputs $a$ and $b$, limited to an output precision of $digs$ digits. While it may seem -a bit awkward to modify the function from its simple $O(n^2)$ description, the usefulness of partial multipliers will arise in a subsequent -algorithm. The algorithm is loosely based on algorithm 14.12 from \cite[pp. 595]{HAC} and is similar to Algorithm M of Knuth \cite[pp. 268]{TAOCPV2}. -Algorithm s\_mp\_mul\_digs differs from these cited references since it can produce a variable output precision regardless of the precision of the -inputs. - -The first thing this algorithm checks for is whether a Comba multiplier can be used instead. If the minimum digit count of either -input is less than $\delta$, then the Comba method may be used instead. After the Comba method is ruled out, the baseline algorithm begins. A -temporary mp\_int variable $t$ is used to hold the intermediate result of the product. This allows the algorithm to be used to -compute products when either $a = c$ or $b = c$ without overwriting the inputs. - -All of step 5 is the infamous $O(n^2)$ multiplication loop slightly modified to only produce upto $digs$ digits of output. The $pb$ variable -is given the count of digits to read from $b$ inside the nested loop. If $pb \le 1$ then no more output digits can be produced and the algorithm -will exit the loop. The best way to think of the loops are as a series of $pb \times 1$ multiplications. That is, in each pass of the -innermost loop $a_{ix}$ is multiplied against $b$ and the result is added (\textit{with an appropriate shift}) to $t$. - -For example, consider multiplying $576$ by $241$. That is equivalent to computing $10^0(1)(576) + 10^1(4)(576) + 10^2(2)(576)$ which is best -visualized in the following table. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{|c|c|c|c|c|c|l|} -\hline && & 5 & 7 & 6 & \\ -\hline $\times$&& & 2 & 4 & 1 & \\ -\hline &&&&&&\\ - && & 5 & 7 & 6 & $10^0(1)(576)$ \\ - &2 & 3 & 6 & 1 & 6 & $10^1(4)(576) + 10^0(1)(576)$ \\ - 1 & 3 & 8 & 8 & 1 & 6 & $10^2(2)(576) + 10^1(4)(576) + 10^0(1)(576)$ \\ -\hline -\end{tabular} -\end{center} -\caption{Long-Hand Multiplication Diagram} -\end{figure} - -Each row of the product is added to the result after being shifted to the left (\textit{multiplied by a power of the radix}) by the appropriate -count. That is in pass $ix$ of the inner loop the product is added starting at the $ix$'th digit of the reult. - -Step 5.4.1 introduces the hat symbol (\textit{e.g. $\hat r$}) which represents a double precision variable. The multiplication on that step -is assumed to be a double wide output single precision multiplication. That is, two single precision variables are multiplied to produce a -double precision result. The step is somewhat optimized from a long-hand multiplication algorithm because the carry from the addition in step -5.4.1 is propagated through the nested loop. If the carry was not propagated immediately it would overflow the single precision digit -$t_{ix+iy}$ and the result would be lost. - -At step 5.5 the nested loop is finished and any carry that was left over should be forwarded. The carry does not have to be added to the $ix+pb$'th -digit since that digit is assumed to be zero at this point. However, if $ix + pb \ge digs$ the carry is not set as it would make the result -exceed the precision requested. - -EXAM,bn_s_mp_mul_digs.c - -First we determine (line @30,if@) if the Comba method can be used first since it's faster. The conditions for -sing the Comba routine are that min$(a.used, b.used) < \delta$ and the number of digits of output is less than -\textbf{MP\_WARRAY}. This new constant is used to control the stack usage in the Comba routines. By default it is -set to $\delta$ but can be reduced when memory is at a premium. - -If we cannot use the Comba method we proceed to setup the baseline routine. We allocate the the destination mp\_int -$t$ (line @36,init@) to the exact size of the output to avoid further re--allocations. At this point we now -begin the $O(n^2)$ loop. - -This implementation of multiplication has the caveat that it can be trimmed to only produce a variable number of -digits as output. In each iteration of the outer loop the $pb$ variable is set (line @48,MIN@) to the maximum -number of inner loop iterations. - -Inside the inner loop we calculate $\hat r$ as the mp\_word product of the two mp\_digits and the addition of the -carry from the previous iteration. A particularly important observation is that most modern optimizing -C compilers (GCC for instance) can recognize that a $N \times N \rightarrow 2N$ multiplication is all that -is required for the product. In x86 terms for example, this means using the MUL instruction. - -Each digit of the product is stored in turn (line @68,tmpt@) and the carry propagated (line @71,>>@) to the -next iteration. - -\subsection{Faster Multiplication by the ``Comba'' Method} -MARK,COMBA - -One of the huge drawbacks of the ``baseline'' algorithms is that at the $O(n^2)$ level the carry must be -computed and propagated upwards. This makes the nested loop very sequential and hard to unroll and implement -in parallel. The ``Comba'' \cite{COMBA} method is named after little known (\textit{in cryptographic venues}) Paul G. -Comba who described a method of implementing fast multipliers that do not require nested carry fixup operations. As an -interesting aside it seems that Paul Barrett describes a similar technique in his 1986 paper \cite{BARRETT} written -five years before. - -At the heart of the Comba technique is once again the long-hand algorithm. Except in this case a slight -twist is placed on how the columns of the result are produced. In the standard long-hand algorithm rows of products -are produced then added together to form the final result. In the baseline algorithm the columns are added together -after each iteration to get the result instantaneously. - -In the Comba algorithm the columns of the result are produced entirely independently of each other. That is at -the $O(n^2)$ level a simple multiplication and addition step is performed. The carries of the columns are propagated -after the nested loop to reduce the amount of work requiored. Succintly the first step of the algorithm is to compute -the product vector $\vec x$ as follows. - -\begin{equation} -\vec x_n = \sum_{i+j = n} a_ib_j, \forall n \in \lbrace 0, 1, 2, \ldots, i + j \rbrace -\end{equation} - -Where $\vec x_n$ is the $n'th$ column of the output vector. Consider the following example which computes the vector $\vec x$ for the multiplication -of $576$ and $241$. - -\newpage\begin{figure}[h] -\begin{small} -\begin{center} -\begin{tabular}{|c|c|c|c|c|c|} - \hline & & 5 & 7 & 6 & First Input\\ - \hline $\times$ & & 2 & 4 & 1 & Second Input\\ -\hline & & $1 \cdot 5 = 5$ & $1 \cdot 7 = 7$ & $1 \cdot 6 = 6$ & First pass \\ - & $4 \cdot 5 = 20$ & $4 \cdot 7+5=33$ & $4 \cdot 6+7=31$ & 6 & Second pass \\ - $2 \cdot 5 = 10$ & $2 \cdot 7 + 20 = 34$ & $2 \cdot 6+33=45$ & 31 & 6 & Third pass \\ -\hline 10 & 34 & 45 & 31 & 6 & Final Result \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Comba Multiplication Diagram} -\end{figure} - -At this point the vector $x = \left < 10, 34, 45, 31, 6 \right >$ is the result of the first step of the Comba multipler. -Now the columns must be fixed by propagating the carry upwards. The resultant vector will have one extra dimension over the input vector which is -congruent to adding a leading zero digit. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Comba Fixup}. \\ -\textbf{Input}. Vector $\vec x$ of dimension $k$ \\ -\textbf{Output}. Vector $\vec x$ such that the carries have been propagated. \\ -\hline \\ -1. for $n$ from $0$ to $k - 1$ do \\ -\hspace{3mm}1.1 $\vec x_{n+1} \leftarrow \vec x_{n+1} + \lfloor \vec x_{n}/\beta \rfloor$ \\ -\hspace{3mm}1.2 $\vec x_{n} \leftarrow \vec x_{n} \mbox{ (mod }\beta\mbox{)}$ \\ -2. Return($\vec x$). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Comba Fixup} -\end{figure} - -With that algorithm and $k = 5$ and $\beta = 10$ the following vector is produced $\vec x= \left < 1, 3, 8, 8, 1, 6 \right >$. In this case -$241 \cdot 576$ is in fact $138816$ and the procedure succeeded. If the algorithm is correct and as will be demonstrated shortly more -efficient than the baseline algorithm why not simply always use this algorithm? - -\subsubsection{Column Weight.} -At the nested $O(n^2)$ level the Comba method adds the product of two single precision variables to each column of the output -independently. A serious obstacle is if the carry is lost, due to lack of precision before the algorithm has a chance to fix -the carries. For example, in the multiplication of two three-digit numbers the third column of output will be the sum of -three single precision multiplications. If the precision of the accumulator for the output digits is less then $3 \cdot (\beta - 1)^2$ then -an overflow can occur and the carry information will be lost. For any $m$ and $n$ digit inputs the maximum weight of any column is -min$(m, n)$ which is fairly obvious. - -The maximum number of terms in any column of a product is known as the ``column weight'' and strictly governs when the algorithm can be used. Recall -from earlier that a double precision type has $\alpha$ bits of resolution and a single precision digit has $lg(\beta)$ bits of precision. Given these -two quantities we must not violate the following - -\begin{equation} -k \cdot \left (\beta - 1 \right )^2 < 2^{\alpha} -\end{equation} - -Which reduces to - -\begin{equation} -k \cdot \left ( \beta^2 - 2\beta + 1 \right ) < 2^{\alpha} -\end{equation} - -Let $\rho = lg(\beta)$ represent the number of bits in a single precision digit. By further re-arrangement of the equation the final solution is -found. - -\begin{equation} -k < {{2^{\alpha}} \over {\left (2^{2\rho} - 2^{\rho + 1} + 1 \right )}} -\end{equation} - -The defaults for LibTomMath are $\beta = 2^{28}$ and $\alpha = 2^{64}$ which means that $k$ is bounded by $k < 257$. In this configuration -the smaller input may not have more than $256$ digits if the Comba method is to be used. This is quite satisfactory for most applications since -$256$ digits would allow for numbers in the range of $0 \le x < 2^{7168}$ which, is much larger than most public key cryptographic algorithms require. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{fast\_s\_mp\_mul\_digs}. \\ -\textbf{Input}. mp\_int $a$, mp\_int $b$ and an integer $digs$ \\ -\textbf{Output}. $c \leftarrow \vert a \vert \cdot \vert b \vert \mbox{ (mod }\beta^{digs}\mbox{)}$. \\ -\hline \\ -Place an array of \textbf{MP\_WARRAY} single precision digits named $W$ on the stack. \\ -1. If $c.alloc < digs$ then grow $c$ to $digs$ digits. (\textit{mp\_grow}) \\ -2. If step 1 failed return(\textit{MP\_MEM}).\\ -\\ -3. $pa \leftarrow \mbox{MIN}(digs, a.used + b.used)$ \\ -\\ -4. $\_ \hat W \leftarrow 0$ \\ -5. for $ix$ from 0 to $pa - 1$ do \\ -\hspace{3mm}5.1 $ty \leftarrow \mbox{MIN}(b.used - 1, ix)$ \\ -\hspace{3mm}5.2 $tx \leftarrow ix - ty$ \\ -\hspace{3mm}5.3 $iy \leftarrow \mbox{MIN}(a.used - tx, ty + 1)$ \\ -\hspace{3mm}5.4 for $iz$ from 0 to $iy - 1$ do \\ -\hspace{6mm}5.4.1 $\_ \hat W \leftarrow \_ \hat W + a_{tx+iy}b_{ty-iy}$ \\ -\hspace{3mm}5.5 $W_{ix} \leftarrow \_ \hat W (\mbox{mod }\beta)$\\ -\hspace{3mm}5.6 $\_ \hat W \leftarrow \lfloor \_ \hat W / \beta \rfloor$ \\ -\\ -6. $oldused \leftarrow c.used$ \\ -7. $c.used \leftarrow digs$ \\ -8. for $ix$ from $0$ to $pa$ do \\ -\hspace{3mm}8.1 $c_{ix} \leftarrow W_{ix}$ \\ -9. for $ix$ from $pa + 1$ to $oldused - 1$ do \\ -\hspace{3mm}9.1 $c_{ix} \leftarrow 0$ \\ -\\ -10. Clamp $c$. \\ -11. Return MP\_OKAY. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm fast\_s\_mp\_mul\_digs} -\label{fig:COMBAMULT} -\end{figure} - -\textbf{Algorithm fast\_s\_mp\_mul\_digs.} -This algorithm performs the unsigned multiplication of $a$ and $b$ using the Comba method limited to $digs$ digits of precision. - -The outer loop of this algorithm is more complicated than that of the baseline multiplier. This is because on the inside of the -loop we want to produce one column per pass. This allows the accumulator $\_ \hat W$ to be placed in CPU registers and -reduce the memory bandwidth to two \textbf{mp\_digit} reads per iteration. - -The $ty$ variable is set to the minimum count of $ix$ or the number of digits in $b$. That way if $a$ has more digits than -$b$ this will be limited to $b.used - 1$. The $tx$ variable is set to the to the distance past $b.used$ the variable -$ix$ is. This is used for the immediately subsequent statement where we find $iy$. - -The variable $iy$ is the minimum digits we can read from either $a$ or $b$ before running out. Computing one column at a time -means we have to scan one integer upwards and the other downwards. $a$ starts at $tx$ and $b$ starts at $ty$. In each -pass we are producing the $ix$'th output column and we note that $tx + ty = ix$. As we move $tx$ upwards we have to -move $ty$ downards so the equality remains valid. The $iy$ variable is the number of iterations until -$tx \ge a.used$ or $ty < 0$ occurs. - -After every inner pass we store the lower half of the accumulator into $W_{ix}$ and then propagate the carry of the accumulator -into the next round by dividing $\_ \hat W$ by $\beta$. - -To measure the benefits of the Comba method over the baseline method consider the number of operations that are required. If the -cost in terms of time of a multiply and addition is $p$ and the cost of a carry propagation is $q$ then a baseline multiplication would require -$O \left ((p + q)n^2 \right )$ time to multiply two $n$-digit numbers. The Comba method requires only $O(pn^2 + qn)$ time, however in practice, -the speed increase is actually much more. With $O(n)$ space the algorithm can be reduced to $O(pn + qn)$ time by implementing the $n$ multiply -and addition operations in the nested loop in parallel. - -EXAM,bn_s_mp_mul_digs_fast.c - -As per the pseudo--code we first calculate $pa$ (line @47,MIN@) as the number of digits to output. Next we begin the outer loop -to produce the individual columns of the product. We use the two aliases $tmpx$ and $tmpy$ (lines @61,tmpx@, @62,tmpy@) to point -inside the two multiplicands quickly. - -The inner loop (lines @70,for@ to @72,}@) of this implementation is where the tradeoff come into play. Originally this comba -implementation was ``row--major'' which means it adds to each of the columns in each pass. After the outer loop it would then fix -the carries. This was very fast except it had an annoying drawback. You had to read a mp\_word and two mp\_digits and write -one mp\_word per iteration. On processors such as the Athlon XP and P4 this did not matter much since the cache bandwidth -is very high and it can keep the ALU fed with data. It did, however, matter on older and embedded cpus where cache is often -slower and also often doesn't exist. This new algorithm only performs two reads per iteration under the assumption that the -compiler has aliased $\_ \hat W$ to a CPU register. - -After the inner loop we store the current accumulator in $W$ and shift $\_ \hat W$ (lines @75,W[ix]@, @78,>>@) to forward it as -a carry for the next pass. After the outer loop we use the final carry (line @82,W[ix]@) as the last digit of the product. - -\subsection{Polynomial Basis Multiplication} -To break the $O(n^2)$ barrier in multiplication requires a completely different look at integer multiplication. In the following algorithms -the use of polynomial basis representation for two integers $a$ and $b$ as $f(x) = \sum_{i=0}^{n} a_i x^i$ and -$g(x) = \sum_{i=0}^{n} b_i x^i$ respectively, is required. In this system both $f(x)$ and $g(x)$ have $n + 1$ terms and are of the $n$'th degree. - -The product $a \cdot b \equiv f(x)g(x)$ is the polynomial $W(x) = \sum_{i=0}^{2n} w_i x^i$. The coefficients $w_i$ will -directly yield the desired product when $\beta$ is substituted for $x$. The direct solution to solve for the $2n + 1$ coefficients -requires $O(n^2)$ time and would in practice be slower than the Comba technique. - -However, numerical analysis theory indicates that only $2n + 1$ distinct points in $W(x)$ are required to determine the values of the $2n + 1$ unknown -coefficients. This means by finding $\zeta_y = W(y)$ for $2n + 1$ small values of $y$ the coefficients of $W(x)$ can be found with -Gaussian elimination. This technique is also occasionally refered to as the \textit{interpolation technique} (\textit{references please...}) since in -effect an interpolation based on $2n + 1$ points will yield a polynomial equivalent to $W(x)$. - -The coefficients of the polynomial $W(x)$ are unknown which makes finding $W(y)$ for any value of $y$ impossible. However, since -$W(x) = f(x)g(x)$ the equivalent $\zeta_y = f(y) g(y)$ can be used in its place. The benefit of this technique stems from the -fact that $f(y)$ and $g(y)$ are much smaller than either $a$ or $b$ respectively. As a result finding the $2n + 1$ relations required -by multiplying $f(y)g(y)$ involves multiplying integers that are much smaller than either of the inputs. - -When picking points to gather relations there are always three obvious points to choose, $y = 0, 1$ and $ \infty$. The $\zeta_0$ term -is simply the product $W(0) = w_0 = a_0 \cdot b_0$. The $\zeta_1$ term is the product -$W(1) = \left (\sum_{i = 0}^{n} a_i \right ) \left (\sum_{i = 0}^{n} b_i \right )$. The third point $\zeta_{\infty}$ is less obvious but rather -simple to explain. The $2n + 1$'th coefficient of $W(x)$ is numerically equivalent to the most significant column in an integer multiplication. -The point at $\infty$ is used symbolically to represent the most significant column, that is $W(\infty) = w_{2n} = a_nb_n$. Note that the -points at $y = 0$ and $\infty$ yield the coefficients $w_0$ and $w_{2n}$ directly. - -If more points are required they should be of small values and powers of two such as $2^q$ and the related \textit{mirror points} -$\left (2^q \right )^{2n} \cdot \zeta_{2^{-q}}$ for small values of $q$. The term ``mirror point'' stems from the fact that -$\left (2^q \right )^{2n} \cdot \zeta_{2^{-q}}$ can be calculated in the exact opposite fashion as $\zeta_{2^q}$. For -example, when $n = 2$ and $q = 1$ then following two equations are equivalent to the point $\zeta_{2}$ and its mirror. - -\begin{eqnarray} -\zeta_{2} = f(2)g(2) = (4a_2 + 2a_1 + a_0)(4b_2 + 2b_1 + b_0) \nonumber \\ -16 \cdot \zeta_{1 \over 2} = 4f({1\over 2}) \cdot 4g({1 \over 2}) = (a_2 + 2a_1 + 4a_0)(b_2 + 2b_1 + 4b_0) -\end{eqnarray} - -Using such points will allow the values of $f(y)$ and $g(y)$ to be independently calculated using only left shifts. For example, when $n = 2$ the -polynomial $f(2^q)$ is equal to $2^q((2^qa_2) + a_1) + a_0$. This technique of polynomial representation is known as Horner's method. - -As a general rule of the algorithm when the inputs are split into $n$ parts each there are $2n - 1$ multiplications. Each multiplication is of -multiplicands that have $n$ times fewer digits than the inputs. The asymptotic running time of this algorithm is -$O \left ( k^{lg_n(2n - 1)} \right )$ for $k$ digit inputs (\textit{assuming they have the same number of digits}). Figure~\ref{fig:exponent} -summarizes the exponents for various values of $n$. - -\begin{figure} -\begin{center} -\begin{tabular}{|c|c|c|} -\hline \textbf{Split into $n$ Parts} & \textbf{Exponent} & \textbf{Notes}\\ -\hline $2$ & $1.584962501$ & This is Karatsuba Multiplication. \\ -\hline $3$ & $1.464973520$ & This is Toom-Cook Multiplication. \\ -\hline $4$ & $1.403677461$ &\\ -\hline $5$ & $1.365212389$ &\\ -\hline $10$ & $1.278753601$ &\\ -\hline $100$ & $1.149426538$ &\\ -\hline $1000$ & $1.100270931$ &\\ -\hline $10000$ & $1.075252070$ &\\ -\hline -\end{tabular} -\end{center} -\caption{Asymptotic Running Time of Polynomial Basis Multiplication} -\label{fig:exponent} -\end{figure} - -At first it may seem like a good idea to choose $n = 1000$ since the exponent is approximately $1.1$. However, the overhead -of solving for the 2001 terms of $W(x)$ will certainly consume any savings the algorithm could offer for all but exceedingly large -numbers. - -\subsubsection{Cutoff Point} -The polynomial basis multiplication algorithms all require fewer single precision multiplications than a straight Comba approach. However, -the algorithms incur an overhead (\textit{at the $O(n)$ work level}) since they require a system of equations to be solved. This makes the -polynomial basis approach more costly to use with small inputs. - -Let $m$ represent the number of digits in the multiplicands (\textit{assume both multiplicands have the same number of digits}). There exists a -point $y$ such that when $m < y$ the polynomial basis algorithms are more costly than Comba, when $m = y$ they are roughly the same cost and -when $m > y$ the Comba methods are slower than the polynomial basis algorithms. - -The exact location of $y$ depends on several key architectural elements of the computer platform in question. - -\begin{enumerate} -\item The ratio of clock cycles for single precision multiplication versus other simpler operations such as addition, shifting, etc. For example -on the AMD Athlon the ratio is roughly $17 : 1$ while on the Intel P4 it is $29 : 1$. The higher the ratio in favour of multiplication the lower -the cutoff point $y$ will be. - -\item The complexity of the linear system of equations (\textit{for the coefficients of $W(x)$}) is. Generally speaking as the number of splits -grows the complexity grows substantially. Ideally solving the system will only involve addition, subtraction and shifting of integers. This -directly reflects on the ratio previous mentioned. - -\item To a lesser extent memory bandwidth and function call overheads. Provided the values are in the processor cache this is less of an -influence over the cutoff point. - -\end{enumerate} - -A clean cutoff point separation occurs when a point $y$ is found such that all of the cutoff point conditions are met. For example, if the point -is too low then there will be values of $m$ such that $m > y$ and the Comba method is still faster. Finding the cutoff points is fairly simple when -a high resolution timer is available. - -\subsection{Karatsuba Multiplication} -Karatsuba \cite{KARA} multiplication when originally proposed in 1962 was among the first set of algorithms to break the $O(n^2)$ barrier for -general purpose multiplication. Given two polynomial basis representations $f(x) = ax + b$ and $g(x) = cx + d$, Karatsuba proved with -light algebra \cite{KARAP} that the following polynomial is equivalent to multiplication of the two integers the polynomials represent. - -\begin{equation} -f(x) \cdot g(x) = acx^2 + ((a + b)(c + d) - (ac + bd))x + bd -\end{equation} - -Using the observation that $ac$ and $bd$ could be re-used only three half sized multiplications would be required to produce the product. Applying -this algorithm recursively, the work factor becomes $O(n^{lg(3)})$ which is substantially better than the work factor $O(n^2)$ of the Comba technique. It turns -out what Karatsuba did not know or at least did not publish was that this is simply polynomial basis multiplication with the points -$\zeta_0$, $\zeta_{\infty}$ and $\zeta_{1}$. Consider the resultant system of equations. - -\begin{center} -\begin{tabular}{rcrcrcrc} -$\zeta_{0}$ & $=$ & & & & & $w_0$ \\ -$\zeta_{1}$ & $=$ & $w_2$ & $+$ & $w_1$ & $+$ & $w_0$ \\ -$\zeta_{\infty}$ & $=$ & $w_2$ & & & & \\ -\end{tabular} -\end{center} - -By adding the first and last equation to the equation in the middle the term $w_1$ can be isolated and all three coefficients solved for. The simplicity -of this system of equations has made Karatsuba fairly popular. In fact the cutoff point is often fairly low\footnote{With LibTomMath 0.18 it is 70 and 109 digits for the Intel P4 and AMD Athlon respectively.} -making it an ideal algorithm to speed up certain public key cryptosystems such as RSA and Diffie-Hellman. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_karatsuba\_mul}. \\ -\textbf{Input}. mp\_int $a$ and mp\_int $b$ \\ -\textbf{Output}. $c \leftarrow \vert a \vert \cdot \vert b \vert$ \\ -\hline \\ -1. Init the following mp\_int variables: $x0$, $x1$, $y0$, $y1$, $t1$, $x0y0$, $x1y1$.\\ -2. If step 2 failed then return(\textit{MP\_MEM}). \\ -\\ -Split the input. e.g. $a = x1 \cdot \beta^B + x0$ \\ -3. $B \leftarrow \mbox{min}(a.used, b.used)/2$ \\ -4. $x0 \leftarrow a \mbox{ (mod }\beta^B\mbox{)}$ (\textit{mp\_mod\_2d}) \\ -5. $y0 \leftarrow b \mbox{ (mod }\beta^B\mbox{)}$ \\ -6. $x1 \leftarrow \lfloor a / \beta^B \rfloor$ (\textit{mp\_rshd}) \\ -7. $y1 \leftarrow \lfloor b / \beta^B \rfloor$ \\ -\\ -Calculate the three products. \\ -8. $x0y0 \leftarrow x0 \cdot y0$ (\textit{mp\_mul}) \\ -9. $x1y1 \leftarrow x1 \cdot y1$ \\ -10. $t1 \leftarrow x1 + x0$ (\textit{mp\_add}) \\ -11. $x0 \leftarrow y1 + y0$ \\ -12. $t1 \leftarrow t1 \cdot x0$ \\ -\\ -Calculate the middle term. \\ -13. $x0 \leftarrow x0y0 + x1y1$ \\ -14. $t1 \leftarrow t1 - x0$ (\textit{s\_mp\_sub}) \\ -\\ -Calculate the final product. \\ -15. $t1 \leftarrow t1 \cdot \beta^B$ (\textit{mp\_lshd}) \\ -16. $x1y1 \leftarrow x1y1 \cdot \beta^{2B}$ \\ -17. $t1 \leftarrow x0y0 + t1$ \\ -18. $c \leftarrow t1 + x1y1$ \\ -19. Clear all of the temporary variables. \\ -20. Return(\textit{MP\_OKAY}).\\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_karatsuba\_mul} -\end{figure} - -\textbf{Algorithm mp\_karatsuba\_mul.} -This algorithm computes the unsigned product of two inputs using the Karatsuba multiplication algorithm. It is loosely based on the description -from Knuth \cite[pp. 294-295]{TAOCPV2}. - -\index{radix point} -In order to split the two inputs into their respective halves, a suitable \textit{radix point} must be chosen. The radix point chosen must -be used for both of the inputs meaning that it must be smaller than the smallest input. Step 3 chooses the radix point $B$ as half of the -smallest input \textbf{used} count. After the radix point is chosen the inputs are split into lower and upper halves. Step 4 and 5 -compute the lower halves. Step 6 and 7 computer the upper halves. - -After the halves have been computed the three intermediate half-size products must be computed. Step 8 and 9 compute the trivial products -$x0 \cdot y0$ and $x1 \cdot y1$. The mp\_int $x0$ is used as a temporary variable after $x1 + x0$ has been computed. By using $x0$ instead -of an additional temporary variable, the algorithm can avoid an addition memory allocation operation. - -The remaining steps 13 through 18 compute the Karatsuba polynomial through a variety of digit shifting and addition operations. - -EXAM,bn_s_mp_karatsuba_mul.c - -The new coding element in this routine, not seen in previous routines, is the usage of goto statements. The conventional -wisdom is that goto statements should be avoided. This is generally true, however when every single function call can fail, it makes sense -to handle error recovery with a single piece of code. Lines @61,if@ to @75,if@ handle initializing all of the temporary variables -required. Note how each of the if statements goes to a different label in case of failure. This allows the routine to correctly free only -the temporaries that have been successfully allocated so far. - -The temporary variables are all initialized using the mp\_init\_size routine since they are expected to be large. This saves the -additional reallocation that would have been necessary. Also $x0$, $x1$, $y0$ and $y1$ have to be able to hold at least their respective -number of digits for the next section of code. - -The first algebraic portion of the algorithm is to split the two inputs into their halves. However, instead of using mp\_mod\_2d and mp\_rshd -to extract the halves, the respective code has been placed inline within the body of the function. To initialize the halves, the \textbf{used} and -\textbf{sign} members are copied first. The first for loop on line @98,for@ copies the lower halves. Since they are both the same magnitude it -is simpler to calculate both lower halves in a single loop. The for loop on lines @104,for@ and @109,for@ calculate the upper halves $x1$ and -$y1$ respectively. - -By inlining the calculation of the halves, the Karatsuba multiplier has a slightly lower overhead and can be used for smaller magnitude inputs. - -When line @152,err@ is reached, the algorithm has completed succesfully. The ``error status'' variable $err$ is set to \textbf{MP\_OKAY} so that -the same code that handles errors can be used to clear the temporary variables and return. - -\subsection{Toom-Cook $3$-Way Multiplication} -Toom-Cook $3$-Way \cite{TOOM} multiplication is essentially the polynomial basis algorithm for $n = 2$ except that the points are -chosen such that $\zeta$ is easy to compute and the resulting system of equations easy to reduce. Here, the points $\zeta_{0}$, -$16 \cdot \zeta_{1 \over 2}$, $\zeta_1$, $\zeta_2$ and $\zeta_{\infty}$ make up the five required points to solve for the coefficients -of the $W(x)$. - -With the five relations that Toom-Cook specifies, the following system of equations is formed. - -\begin{center} -\begin{tabular}{rcrcrcrcrcr} -$\zeta_0$ & $=$ & $0w_4$ & $+$ & $0w_3$ & $+$ & $0w_2$ & $+$ & $0w_1$ & $+$ & $1w_0$ \\ -$16 \cdot \zeta_{1 \over 2}$ & $=$ & $1w_4$ & $+$ & $2w_3$ & $+$ & $4w_2$ & $+$ & $8w_1$ & $+$ & $16w_0$ \\ -$\zeta_1$ & $=$ & $1w_4$ & $+$ & $1w_3$ & $+$ & $1w_2$ & $+$ & $1w_1$ & $+$ & $1w_0$ \\ -$\zeta_2$ & $=$ & $16w_4$ & $+$ & $8w_3$ & $+$ & $4w_2$ & $+$ & $2w_1$ & $+$ & $1w_0$ \\ -$\zeta_{\infty}$ & $=$ & $1w_4$ & $+$ & $0w_3$ & $+$ & $0w_2$ & $+$ & $0w_1$ & $+$ & $0w_0$ \\ -\end{tabular} -\end{center} - -A trivial solution to this matrix requires $12$ subtractions, two multiplications by a small power of two, two divisions by a small power -of two, two divisions by three and one multiplication by three. All of these $19$ sub-operations require less than quadratic time, meaning that -the algorithm can be faster than a baseline multiplication. However, the greater complexity of this algorithm places the cutoff point -(\textbf{TOOM\_MUL\_CUTOFF}) where Toom-Cook becomes more efficient much higher than the Karatsuba cutoff point. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_toom\_mul}. \\ -\textbf{Input}. mp\_int $a$ and mp\_int $b$ \\ -\textbf{Output}. $c \leftarrow a \cdot b $ \\ -\hline \\ -Split $a$ and $b$ into three pieces. E.g. $a = a_2 \beta^{2k} + a_1 \beta^{k} + a_0$ \\ -1. $k \leftarrow \lfloor \mbox{min}(a.used, b.used) / 3 \rfloor$ \\ -2. $a_0 \leftarrow a \mbox{ (mod }\beta^{k}\mbox{)}$ \\ -3. $a_1 \leftarrow \lfloor a / \beta^k \rfloor$, $a_1 \leftarrow a_1 \mbox{ (mod }\beta^{k}\mbox{)}$ \\ -4. $a_2 \leftarrow \lfloor a / \beta^{2k} \rfloor$, $a_2 \leftarrow a_2 \mbox{ (mod }\beta^{k}\mbox{)}$ \\ -5. $b_0 \leftarrow a \mbox{ (mod }\beta^{k}\mbox{)}$ \\ -6. $b_1 \leftarrow \lfloor a / \beta^k \rfloor$, $b_1 \leftarrow b_1 \mbox{ (mod }\beta^{k}\mbox{)}$ \\ -7. $b_2 \leftarrow \lfloor a / \beta^{2k} \rfloor$, $b_2 \leftarrow b_2 \mbox{ (mod }\beta^{k}\mbox{)}$ \\ -\\ -Find the five equations for $w_0, w_1, ..., w_4$. \\ -8. $w_0 \leftarrow a_0 \cdot b_0$ \\ -9. $w_4 \leftarrow a_2 \cdot b_2$ \\ -10. $tmp_1 \leftarrow 2 \cdot a_0$, $tmp_1 \leftarrow a_1 + tmp_1$, $tmp_1 \leftarrow 2 \cdot tmp_1$, $tmp_1 \leftarrow tmp_1 + a_2$ \\ -11. $tmp_2 \leftarrow 2 \cdot b_0$, $tmp_2 \leftarrow b_1 + tmp_2$, $tmp_2 \leftarrow 2 \cdot tmp_2$, $tmp_2 \leftarrow tmp_2 + b_2$ \\ -12. $w_1 \leftarrow tmp_1 \cdot tmp_2$ \\ -13. $tmp_1 \leftarrow 2 \cdot a_2$, $tmp_1 \leftarrow a_1 + tmp_1$, $tmp_1 \leftarrow 2 \cdot tmp_1$, $tmp_1 \leftarrow tmp_1 + a_0$ \\ -14. $tmp_2 \leftarrow 2 \cdot b_2$, $tmp_2 \leftarrow b_1 + tmp_2$, $tmp_2 \leftarrow 2 \cdot tmp_2$, $tmp_2 \leftarrow tmp_2 + b_0$ \\ -15. $w_3 \leftarrow tmp_1 \cdot tmp_2$ \\ -16. $tmp_1 \leftarrow a_0 + a_1$, $tmp_1 \leftarrow tmp_1 + a_2$, $tmp_2 \leftarrow b_0 + b_1$, $tmp_2 \leftarrow tmp_2 + b_2$ \\ -17. $w_2 \leftarrow tmp_1 \cdot tmp_2$ \\ -\\ -Continued on the next page.\\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_toom\_mul} -\end{figure} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_toom\_mul} (continued). \\ -\textbf{Input}. mp\_int $a$ and mp\_int $b$ \\ -\textbf{Output}. $c \leftarrow a \cdot b $ \\ -\hline \\ -Now solve the system of equations. \\ -18. $w_1 \leftarrow w_4 - w_1$, $w_3 \leftarrow w_3 - w_0$ \\ -19. $w_1 \leftarrow \lfloor w_1 / 2 \rfloor$, $w_3 \leftarrow \lfloor w_3 / 2 \rfloor$ \\ -20. $w_2 \leftarrow w_2 - w_0$, $w_2 \leftarrow w_2 - w_4$ \\ -21. $w_1 \leftarrow w_1 - w_2$, $w_3 \leftarrow w_3 - w_2$ \\ -22. $tmp_1 \leftarrow 8 \cdot w_0$, $w_1 \leftarrow w_1 - tmp_1$, $tmp_1 \leftarrow 8 \cdot w_4$, $w_3 \leftarrow w_3 - tmp_1$ \\ -23. $w_2 \leftarrow 3 \cdot w_2$, $w_2 \leftarrow w_2 - w_1$, $w_2 \leftarrow w_2 - w_3$ \\ -24. $w_1 \leftarrow w_1 - w_2$, $w_3 \leftarrow w_3 - w_2$ \\ -25. $w_1 \leftarrow \lfloor w_1 / 3 \rfloor, w_3 \leftarrow \lfloor w_3 / 3 \rfloor$ \\ -\\ -Now substitute $\beta^k$ for $x$ by shifting $w_0, w_1, ..., w_4$. \\ -26. for $n$ from $1$ to $4$ do \\ -\hspace{3mm}26.1 $w_n \leftarrow w_n \cdot \beta^{nk}$ \\ -27. $c \leftarrow w_0 + w_1$, $c \leftarrow c + w_2$, $c \leftarrow c + w_3$, $c \leftarrow c + w_4$ \\ -28. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_toom\_mul (continued)} -\end{figure} - -\textbf{Algorithm mp\_toom\_mul.} -This algorithm computes the product of two mp\_int variables $a$ and $b$ using the Toom-Cook approach. Compared to the Karatsuba multiplication, this -algorithm has a lower asymptotic running time of approximately $O(n^{1.464})$ but at an obvious cost in overhead. In this -description, several statements have been compounded to save space. The intention is that the statements are executed from left to right across -any given step. - -The two inputs $a$ and $b$ are first split into three $k$-digit integers $a_0, a_1, a_2$ and $b_0, b_1, b_2$ respectively. From these smaller -integers the coefficients of the polynomial basis representations $f(x)$ and $g(x)$ are known and can be used to find the relations required. - -The first two relations $w_0$ and $w_4$ are the points $\zeta_{0}$ and $\zeta_{\infty}$ respectively. The relation $w_1, w_2$ and $w_3$ correspond -to the points $16 \cdot \zeta_{1 \over 2}, \zeta_{2}$ and $\zeta_{1}$ respectively. These are found using logical shifts to independently find -$f(y)$ and $g(y)$ which significantly speeds up the algorithm. - -After the five relations $w_0, w_1, \ldots, w_4$ have been computed, the system they represent must be solved in order for the unknown coefficients -$w_1, w_2$ and $w_3$ to be isolated. The steps 18 through 25 perform the system reduction required as previously described. Each step of -the reduction represents the comparable matrix operation that would be performed had this been performed by pencil. For example, step 18 indicates -that row $1$ must be subtracted from row $4$ and simultaneously row $0$ subtracted from row $3$. - -Once the coeffients have been isolated, the polynomial $W(x) = \sum_{i=0}^{2n} w_i x^i$ is known. By substituting $\beta^{k}$ for $x$, the integer -result $a \cdot b$ is produced. - -EXAM,bn_s_mp_toom_mul.c - -The first obvious thing to note is that this algorithm is complicated. The complexity is worth it if you are multiplying very -large numbers. For example, a 10,000 digit multiplication takes approximaly 99,282,205 fewer single precision multiplications with -Toom--Cook than a Comba or baseline approach (this is a savings of more than 99$\%$). For most ``crypto'' sized numbers this -algorithm is not practical as Karatsuba has a much lower cutoff point. - -First we split $a$ and $b$ into three roughly equal portions. This has been accomplished (lines @40,mod@ to @69,rshd@) with -combinations of mp\_rshd() and mp\_mod\_2d() function calls. At this point $a = a2 \cdot \beta^2 + a1 \cdot \beta + a0$ and similiarly -for $b$. - -Next we compute the five points $w0, w1, w2, w3$ and $w4$. Recall that $w0$ and $w4$ can be computed directly from the portions so -we get those out of the way first (lines @72,mul@ and @77,mul@). Next we compute $w1, w2$ and $w3$ using Horners method. - -After this point we solve for the actual values of $w1, w2$ and $w3$ by reducing the $5 \times 5$ system which is relatively -straight forward. - -\subsection{Signed Multiplication} -Now that algorithms to handle multiplications of every useful dimensions have been developed, a rather simple finishing touch is required. So far all -of the multiplication algorithms have been unsigned multiplications which leaves only a signed multiplication algorithm to be established. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_mul}. \\ -\textbf{Input}. mp\_int $a$ and mp\_int $b$ \\ -\textbf{Output}. $c \leftarrow a \cdot b$ \\ -\hline \\ -1. If $a.sign = b.sign$ then \\ -\hspace{3mm}1.1 $sign = MP\_ZPOS$ \\ -2. else \\ -\hspace{3mm}2.1 $sign = MP\_ZNEG$ \\ -3. If min$(a.used, b.used) \ge TOOM\_MUL\_CUTOFF$ then \\ -\hspace{3mm}3.1 $c \leftarrow a \cdot b$ using algorithm mp\_toom\_mul \\ -4. else if min$(a.used, b.used) \ge KARATSUBA\_MUL\_CUTOFF$ then \\ -\hspace{3mm}4.1 $c \leftarrow a \cdot b$ using algorithm mp\_karatsuba\_mul \\ -5. else \\ -\hspace{3mm}5.1 $digs \leftarrow a.used + b.used + 1$ \\ -\hspace{3mm}5.2 If $digs < MP\_ARRAY$ and min$(a.used, b.used) \le \delta$ then \\ -\hspace{6mm}5.2.1 $c \leftarrow a \cdot b \mbox{ (mod }\beta^{digs}\mbox{)}$ using algorithm fast\_s\_mp\_mul\_digs. \\ -\hspace{3mm}5.3 else \\ -\hspace{6mm}5.3.1 $c \leftarrow a \cdot b \mbox{ (mod }\beta^{digs}\mbox{)}$ using algorithm s\_mp\_mul\_digs. \\ -6. $c.sign \leftarrow sign$ \\ -7. Return the result of the unsigned multiplication performed. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_mul} -\end{figure} - -\textbf{Algorithm mp\_mul.} -This algorithm performs the signed multiplication of two inputs. It will make use of any of the three unsigned multiplication algorithms -available when the input is of appropriate size. The \textbf{sign} of the result is not set until the end of the algorithm since algorithm -s\_mp\_mul\_digs will clear it. - -EXAM,bn_mp_mul.c - -The implementation is rather simplistic and is not particularly noteworthy. Line @22,?@ computes the sign of the result using the ``?'' -operator from the C programming language. Line @37,<<@ computes $\delta$ using the fact that $1 << k$ is equal to $2^k$. - -\section{Squaring} -\label{sec:basesquare} - -Squaring is a special case of multiplication where both multiplicands are equal. At first it may seem like there is no significant optimization -available but in fact there is. Consider the multiplication of $576$ against $241$. In total there will be nine single precision multiplications -performed which are $1\cdot 6$, $1 \cdot 7$, $1 \cdot 5$, $4 \cdot 6$, $4 \cdot 7$, $4 \cdot 5$, $2 \cdot 6$, $2 \cdot 7$ and $2 \cdot 5$. Now consider -the multiplication of $123$ against $123$. The nine products are $3 \cdot 3$, $3 \cdot 2$, $3 \cdot 1$, $2 \cdot 3$, $2 \cdot 2$, $2 \cdot 1$, -$1 \cdot 3$, $1 \cdot 2$ and $1 \cdot 1$. On closer inspection some of the products are equivalent. For example, $3 \cdot 2 = 2 \cdot 3$ -and $3 \cdot 1 = 1 \cdot 3$. - -For any $n$-digit input, there are ${{\left (n^2 + n \right)}\over 2}$ possible unique single precision multiplications required compared to the $n^2$ -required for multiplication. The following diagram gives an example of the operations required. - -\begin{figure}[h] -\begin{center} -\begin{tabular}{ccccc|c} -&&1&2&3&\\ -$\times$ &&1&2&3&\\ -\hline && $3 \cdot 1$ & $3 \cdot 2$ & $3 \cdot 3$ & Row 0\\ - & $2 \cdot 1$ & $2 \cdot 2$ & $2 \cdot 3$ && Row 1 \\ - $1 \cdot 1$ & $1 \cdot 2$ & $1 \cdot 3$ &&& Row 2 \\ -\end{tabular} -\end{center} -\caption{Squaring Optimization Diagram} -\end{figure} - -MARK,SQUARE -Starting from zero and numbering the columns from right to left a very simple pattern becomes obvious. For the purposes of this discussion let $x$ -represent the number being squared. The first observation is that in row $k$ the $2k$'th column of the product has a $\left (x_k \right)^2$ term in it. - -The second observation is that every column $j$ in row $k$ where $j \ne 2k$ is part of a double product. Every non-square term of a column will -appear twice hence the name ``double product''. Every odd column is made up entirely of double products. In fact every column is made up of double -products and at most one square (\textit{see the exercise section}). - -The third and final observation is that for row $k$ the first unique non-square term, that is, one that hasn't already appeared in an earlier row, -occurs at column $2k + 1$. For example, on row $1$ of the previous squaring, column one is part of the double product with column one from row zero. -Column two of row one is a square and column three is the first unique column. - -\subsection{The Baseline Squaring Algorithm} -The baseline squaring algorithm is meant to be a catch-all squaring algorithm. It will handle any of the input sizes that the faster routines -will not handle. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{s\_mp\_sqr}. \\ -\textbf{Input}. mp\_int $a$ \\ -\textbf{Output}. $b \leftarrow a^2$ \\ -\hline \\ -1. Init a temporary mp\_int of at least $2 \cdot a.used +1$ digits. (\textit{mp\_init\_size}) \\ -2. If step 1 failed return(\textit{MP\_MEM}) \\ -3. $t.used \leftarrow 2 \cdot a.used + 1$ \\ -4. For $ix$ from 0 to $a.used - 1$ do \\ -\hspace{3mm}Calculate the square. \\ -\hspace{3mm}4.1 $\hat r \leftarrow t_{2ix} + \left (a_{ix} \right )^2$ \\ -\hspace{3mm}4.2 $t_{2ix} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}Calculate the double products after the square. \\ -\hspace{3mm}4.3 $u \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -\hspace{3mm}4.4 For $iy$ from $ix + 1$ to $a.used - 1$ do \\ -\hspace{6mm}4.4.1 $\hat r \leftarrow 2 \cdot a_{ix}a_{iy} + t_{ix + iy} + u$ \\ -\hspace{6mm}4.4.2 $t_{ix + iy} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{6mm}4.4.3 $u \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -\hspace{3mm}Set the last carry. \\ -\hspace{3mm}4.5 While $u > 0$ do \\ -\hspace{6mm}4.5.1 $iy \leftarrow iy + 1$ \\ -\hspace{6mm}4.5.2 $\hat r \leftarrow t_{ix + iy} + u$ \\ -\hspace{6mm}4.5.3 $t_{ix + iy} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{6mm}4.5.4 $u \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -5. Clamp excess digits of $t$. (\textit{mp\_clamp}) \\ -6. Exchange $b$ and $t$. \\ -7. Clear $t$ (\textit{mp\_clear}) \\ -8. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm s\_mp\_sqr} -\end{figure} - -\textbf{Algorithm s\_mp\_sqr.} -This algorithm computes the square of an input using the three observations on squaring. It is based fairly faithfully on algorithm 14.16 of HAC -\cite[pp.596-597]{HAC}. Similar to algorithm s\_mp\_mul\_digs, a temporary mp\_int is allocated to hold the result of the squaring. This allows the -destination mp\_int to be the same as the source mp\_int. - -The outer loop of this algorithm begins on step 4. It is best to think of the outer loop as walking down the rows of the partial results, while -the inner loop computes the columns of the partial result. Step 4.1 and 4.2 compute the square term for each row, and step 4.3 and 4.4 propagate -the carry and compute the double products. - -The requirement that a mp\_word be able to represent the range $0 \le x < 2 \beta^2$ arises from this -very algorithm. The product $a_{ix}a_{iy}$ will lie in the range $0 \le x \le \beta^2 - 2\beta + 1$ which is obviously less than $\beta^2$ meaning that -when it is multiplied by two, it can be properly represented by a mp\_word. - -Similar to algorithm s\_mp\_mul\_digs, after every pass of the inner loop, the destination is correctly set to the sum of all of the partial -results calculated so far. This involves expensive carry propagation which will be eliminated in the next algorithm. - -EXAM,bn_s_mp_sqr.c - -Inside the outer loop (line @32,for@) the square term is calculated on line @35,r =@. The carry (line @42,>>@) has been -extracted from the mp\_word accumulator using a right shift. Aliases for $a_{ix}$ and $t_{ix+iy}$ are initialized -(lines @45,tmpx@ and @48,tmpt@) to simplify the inner loop. The doubling is performed using two -additions (line @57,r + r@) since it is usually faster than shifting, if not at least as fast. - -The important observation is that the inner loop does not begin at $iy = 0$ like for multiplication. As such the inner loops -get progressively shorter as the algorithm proceeds. This is what leads to the savings compared to using a multiplication to -square a number. - -\subsection{Faster Squaring by the ``Comba'' Method} -A major drawback to the baseline method is the requirement for single precision shifting inside the $O(n^2)$ nested loop. Squaring has an additional -drawback that it must double the product inside the inner loop as well. As for multiplication, the Comba technique can be used to eliminate these -performance hazards. - -The first obvious solution is to make an array of mp\_words which will hold all of the columns. This will indeed eliminate all of the carry -propagation operations from the inner loop. However, the inner product must still be doubled $O(n^2)$ times. The solution stems from the simple fact -that $2a + 2b + 2c = 2(a + b + c)$. That is the sum of all of the double products is equal to double the sum of all the products. For example, -$ab + ba + ac + ca = 2ab + 2ac = 2(ab + ac)$. - -However, we cannot simply double all of the columns, since the squares appear only once per row. The most practical solution is to have two -mp\_word arrays. One array will hold the squares and the other array will hold the double products. With both arrays the doubling and -carry propagation can be moved to a $O(n)$ work level outside the $O(n^2)$ level. In this case, we have an even simpler solution in mind. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{fast\_s\_mp\_sqr}. \\ -\textbf{Input}. mp\_int $a$ \\ -\textbf{Output}. $b \leftarrow a^2$ \\ -\hline \\ -Place an array of \textbf{MP\_WARRAY} mp\_digits named $W$ on the stack. \\ -1. If $b.alloc < 2a.used + 1$ then grow $b$ to $2a.used + 1$ digits. (\textit{mp\_grow}). \\ -2. If step 1 failed return(\textit{MP\_MEM}). \\ -\\ -3. $pa \leftarrow 2 \cdot a.used$ \\ -4. $\hat W1 \leftarrow 0$ \\ -5. for $ix$ from $0$ to $pa - 1$ do \\ -\hspace{3mm}5.1 $\_ \hat W \leftarrow 0$ \\ -\hspace{3mm}5.2 $ty \leftarrow \mbox{MIN}(a.used - 1, ix)$ \\ -\hspace{3mm}5.3 $tx \leftarrow ix - ty$ \\ -\hspace{3mm}5.4 $iy \leftarrow \mbox{MIN}(a.used - tx, ty + 1)$ \\ -\hspace{3mm}5.5 $iy \leftarrow \mbox{MIN}(iy, \lfloor \left (ty - tx + 1 \right )/2 \rfloor)$ \\ -\hspace{3mm}5.6 for $iz$ from $0$ to $iz - 1$ do \\ -\hspace{6mm}5.6.1 $\_ \hat W \leftarrow \_ \hat W + a_{tx + iz}a_{ty - iz}$ \\ -\hspace{3mm}5.7 $\_ \hat W \leftarrow 2 \cdot \_ \hat W + \hat W1$ \\ -\hspace{3mm}5.8 if $ix$ is even then \\ -\hspace{6mm}5.8.1 $\_ \hat W \leftarrow \_ \hat W + \left ( a_{\lfloor ix/2 \rfloor}\right )^2$ \\ -\hspace{3mm}5.9 $W_{ix} \leftarrow \_ \hat W (\mbox{mod }\beta)$ \\ -\hspace{3mm}5.10 $\hat W1 \leftarrow \lfloor \_ \hat W / \beta \rfloor$ \\ -\\ -6. $oldused \leftarrow b.used$ \\ -7. $b.used \leftarrow 2 \cdot a.used$ \\ -8. for $ix$ from $0$ to $pa - 1$ do \\ -\hspace{3mm}8.1 $b_{ix} \leftarrow W_{ix}$ \\ -9. for $ix$ from $pa$ to $oldused - 1$ do \\ -\hspace{3mm}9.1 $b_{ix} \leftarrow 0$ \\ -10. Clamp excess digits from $b$. (\textit{mp\_clamp}) \\ -11. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm fast\_s\_mp\_sqr} -\end{figure} - -\textbf{Algorithm fast\_s\_mp\_sqr.} -This algorithm computes the square of an input using the Comba technique. It is designed to be a replacement for algorithm -s\_mp\_sqr when the number of input digits is less than \textbf{MP\_WARRAY} and less than $\delta \over 2$. -This algorithm is very similar to the Comba multiplier except with a few key differences we shall make note of. - -First, we have an accumulator and carry variables $\_ \hat W$ and $\hat W1$ respectively. This is because the inner loop -products are to be doubled. If we had added the previous carry in we would be doubling too much. Next we perform an -addition MIN condition on $iy$ (step 5.5) to prevent overlapping digits. For example, $a_3 \cdot a_5$ is equal -$a_5 \cdot a_3$. Whereas in the multiplication case we would have $5 < a.used$ and $3 \ge 0$ is maintained since we double the sum -of the products just outside the inner loop we have to avoid doing this. This is also a good thing since we perform -fewer multiplications and the routine ends up being faster. - -Finally the last difference is the addition of the ``square'' term outside the inner loop (step 5.8). We add in the square -only to even outputs and it is the square of the term at the $\lfloor ix / 2 \rfloor$ position. - -EXAM,bn_s_mp_sqr_fast.c - -This implementation is essentially a copy of Comba multiplication with the appropriate changes added to make it faster for -the special case of squaring. - -\subsection{Polynomial Basis Squaring} -The same algorithm that performs optimal polynomial basis multiplication can be used to perform polynomial basis squaring. The minor exception -is that $\zeta_y = f(y)g(y)$ is actually equivalent to $\zeta_y = f(y)^2$ since $f(y) = g(y)$. Instead of performing $2n + 1$ -multiplications to find the $\zeta$ relations, squaring operations are performed instead. - -\subsection{Karatsuba Squaring} -Let $f(x) = ax + b$ represent the polynomial basis representation of a number to square. -Let $h(x) = \left ( f(x) \right )^2$ represent the square of the polynomial. The Karatsuba equation can be modified to square a -number with the following equation. - -\begin{equation} -h(x) = a^2x^2 + \left ((a + b)^2 - (a^2 + b^2) \right )x + b^2 -\end{equation} - -Upon closer inspection this equation only requires the calculation of three half-sized squares: $a^2$, $b^2$ and $(a + b)^2$. As in -Karatsuba multiplication, this algorithm can be applied recursively on the input and will achieve an asymptotic running time of -$O \left ( n^{lg(3)} \right )$. - -If the asymptotic times of Karatsuba squaring and multiplication are the same, why not simply use the multiplication algorithm -instead? The answer to this arises from the cutoff point for squaring. As in multiplication there exists a cutoff point, at which the -time required for a Comba based squaring and a Karatsuba based squaring meet. Due to the overhead inherent in the Karatsuba method, the cutoff -point is fairly high. For example, on an AMD Athlon XP processor with $\beta = 2^{28}$, the cutoff point is around 127 digits. - -Consider squaring a 200 digit number with this technique. It will be split into two 100 digit halves which are subsequently squared. -The 100 digit halves will not be squared using Karatsuba, but instead using the faster Comba based squaring algorithm. If Karatsuba multiplication -were used instead, the 100 digit numbers would be squared with a slower Comba based multiplication. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_karatsuba\_sqr}. \\ -\textbf{Input}. mp\_int $a$ \\ -\textbf{Output}. $b \leftarrow a^2$ \\ -\hline \\ -1. Initialize the following temporary mp\_ints: $x0$, $x1$, $t1$, $t2$, $x0x0$ and $x1x1$. \\ -2. If any of the initializations on step 1 failed return(\textit{MP\_MEM}). \\ -\\ -Split the input. e.g. $a = x1\beta^B + x0$ \\ -3. $B \leftarrow \lfloor a.used / 2 \rfloor$ \\ -4. $x0 \leftarrow a \mbox{ (mod }\beta^B\mbox{)}$ (\textit{mp\_mod\_2d}) \\ -5. $x1 \leftarrow \lfloor a / \beta^B \rfloor$ (\textit{mp\_lshd}) \\ -\\ -Calculate the three squares. \\ -6. $x0x0 \leftarrow x0^2$ (\textit{mp\_sqr}) \\ -7. $x1x1 \leftarrow x1^2$ \\ -8. $t1 \leftarrow x1 + x0$ (\textit{s\_mp\_add}) \\ -9. $t1 \leftarrow t1^2$ \\ -\\ -Compute the middle term. \\ -10. $t2 \leftarrow x0x0 + x1x1$ (\textit{s\_mp\_add}) \\ -11. $t1 \leftarrow t1 - t2$ \\ -\\ -Compute final product. \\ -12. $t1 \leftarrow t1\beta^B$ (\textit{mp\_lshd}) \\ -13. $x1x1 \leftarrow x1x1\beta^{2B}$ \\ -14. $t1 \leftarrow t1 + x0x0$ \\ -15. $b \leftarrow t1 + x1x1$ \\ -16. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_karatsuba\_sqr} -\end{figure} - -\textbf{Algorithm mp\_karatsuba\_sqr.} -This algorithm computes the square of an input $a$ using the Karatsuba technique. This algorithm is very similar to the Karatsuba based -multiplication algorithm with the exception that the three half-size multiplications have been replaced with three half-size squarings. - -The radix point for squaring is simply placed exactly in the middle of the digits when the input has an odd number of digits, otherwise it is -placed just below the middle. Step 3, 4 and 5 compute the two halves required using $B$ -as the radix point. The first two squares in steps 6 and 7 are rather straightforward while the last square is of a more compact form. - -By expanding $\left (x1 + x0 \right )^2$, the $x1^2$ and $x0^2$ terms in the middle disappear, that is $(x0 - x1)^2 - (x1^2 + x0^2) = 2 \cdot x0 \cdot x1$. -Now if $5n$ single precision additions and a squaring of $n$-digits is faster than multiplying two $n$-digit numbers and doubling then -this method is faster. Assuming no further recursions occur, the difference can be estimated with the following inequality. - -Let $p$ represent the cost of a single precision addition and $q$ the cost of a single precision multiplication both in terms of time\footnote{Or -machine clock cycles.}. - -\begin{equation} -5pn +{{q(n^2 + n)} \over 2} \le pn + qn^2 -\end{equation} - -For example, on an AMD Athlon XP processor $p = {1 \over 3}$ and $q = 6$. This implies that the following inequality should hold. -\begin{center} -\begin{tabular}{rcl} -${5n \over 3} + 3n^2 + 3n$ & $<$ & ${n \over 3} + 6n^2$ \\ -${5 \over 3} + 3n + 3$ & $<$ & ${1 \over 3} + 6n$ \\ -${13 \over 9}$ & $<$ & $n$ \\ -\end{tabular} -\end{center} - -This results in a cutoff point around $n = 2$. As a consequence it is actually faster to compute the middle term the ``long way'' on processors -where multiplication is substantially slower\footnote{On the Athlon there is a 1:17 ratio between clock cycles for addition and multiplication. On -the Intel P4 processor this ratio is 1:29 making this method even more beneficial. The only common exception is the ARMv4 processor which has a -ratio of 1:7. } than simpler operations such as addition. - -EXAM,bn_s_mp_karatsuba_sqr.c - -This implementation is largely based on the implementation of algorithm mp\_karatsuba\_mul. It uses the same inline style to copy and -shift the input into the two halves. The loop from line @54,{@ to line @70,}@ has been modified since only one input exists. The \textbf{used} -count of both $x0$ and $x1$ is fixed up and $x0$ is clamped before the calculations begin. At this point $x1$ and $x0$ are valid equivalents -to the respective halves as if mp\_rshd and mp\_mod\_2d had been used. - -By inlining the copy and shift operations the cutoff point for Karatsuba multiplication can be lowered. On the Athlon the cutoff point -is exactly at the point where Comba squaring can no longer be used (\textit{128 digits}). On slower processors such as the Intel P4 -it is actually below the Comba limit (\textit{at 110 digits}). - -This routine uses the same error trap coding style as mp\_karatsuba\_sqr. As the temporary variables are initialized errors are -redirected to the error trap higher up. If the algorithm completes without error the error code is set to \textbf{MP\_OKAY} and -mp\_clears are executed normally. - -\subsection{Toom-Cook Squaring} -The Toom-Cook squaring algorithm mp\_toom\_sqr is heavily based on the algorithm mp\_toom\_mul with the exception that squarings are used -instead of multiplication to find the five relations. The reader is encouraged to read the description of the latter algorithm and try to -derive their own Toom-Cook squaring algorithm. - -\subsection{High Level Squaring} -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_sqr}. \\ -\textbf{Input}. mp\_int $a$ \\ -\textbf{Output}. $b \leftarrow a^2$ \\ -\hline \\ -1. If $a.used \ge TOOM\_SQR\_CUTOFF$ then \\ -\hspace{3mm}1.1 $b \leftarrow a^2$ using algorithm mp\_toom\_sqr \\ -2. else if $a.used \ge KARATSUBA\_SQR\_CUTOFF$ then \\ -\hspace{3mm}2.1 $b \leftarrow a^2$ using algorithm mp\_karatsuba\_sqr \\ -3. else \\ -\hspace{3mm}3.1 $digs \leftarrow a.used + b.used + 1$ \\ -\hspace{3mm}3.2 If $digs < MP\_ARRAY$ and $a.used \le \delta$ then \\ -\hspace{6mm}3.2.1 $b \leftarrow a^2$ using algorithm fast\_s\_mp\_sqr. \\ -\hspace{3mm}3.3 else \\ -\hspace{6mm}3.3.1 $b \leftarrow a^2$ using algorithm s\_mp\_sqr. \\ -4. $b.sign \leftarrow MP\_ZPOS$ \\ -5. Return the result of the unsigned squaring performed. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_sqr} -\end{figure} - -\textbf{Algorithm mp\_sqr.} -This algorithm computes the square of the input using one of four different algorithms. If the input is very large and has at least -\textbf{TOOM\_SQR\_CUTOFF} or \textbf{KARATSUBA\_SQR\_CUTOFF} digits then either the Toom-Cook or the Karatsuba Squaring algorithm is used. If -neither of the polynomial basis algorithms should be used then either the Comba or baseline algorithm is used. - -EXAM,bn_mp_sqr.c - -\section*{Exercises} -\begin{tabular}{cl} -$\left [ 3 \right ] $ & Devise an efficient algorithm for selection of the radix point to handle inputs \\ - & that have different number of digits in Karatsuba multiplication. \\ - & \\ -$\left [ 2 \right ] $ & In ~SQUARE~ the fact that every column of a squaring is made up \\ - & of double products and at most one square is stated. Prove this statement. \\ - & \\ -$\left [ 3 \right ] $ & Prove the equation for Karatsuba squaring. \\ - & \\ -$\left [ 1 \right ] $ & Prove that Karatsuba squaring requires $O \left (n^{lg(3)} \right )$ time. \\ - & \\ -$\left [ 2 \right ] $ & Determine the minimal ratio between addition and multiplication clock cycles \\ - & required for equation $6.7$ to be true. \\ - & \\ -$\left [ 3 \right ] $ & Implement a threaded version of Comba multiplication (and squaring) where you \\ - & compute subsets of the columns in each thread. Determine a cutoff point where \\ - & it is effective and add the logic to mp\_mul() and mp\_sqr(). \\ - &\\ -$\left [ 4 \right ] $ & Same as the previous but also modify the Karatsuba and Toom-Cook. You must \\ - & increase the throughput of mp\_exptmod() for random odd moduli in the range \\ - & $512 \ldots 4096$ bits significantly ($> 2x$) to complete this challenge. \\ - & \\ -\end{tabular} - -\chapter{Modular Reduction} -MARK,REDUCTION -\section{Basics of Modular Reduction} -\index{modular residue} -Modular reduction is an operation that arises quite often within public key cryptography algorithms and various number theoretic algorithms, -such as factoring. Modular reduction algorithms are the third class of algorithms of the ``multipliers'' set. A number $a$ is said to be \textit{reduced} -modulo another number $b$ by finding the remainder of the division $a/b$. Full integer division with remainder is a topic to be covered -in~\ref{sec:division}. - -Modular reduction is equivalent to solving for $r$ in the following equation. $a = bq + r$ where $q = \lfloor a/b \rfloor$. The result -$r$ is said to be ``congruent to $a$ modulo $b$'' which is also written as $r \equiv a \mbox{ (mod }b\mbox{)}$. In other vernacular $r$ is known as the -``modular residue'' which leads to ``quadratic residue''\footnote{That's fancy talk for $b \equiv a^2 \mbox{ (mod }p\mbox{)}$.} and -other forms of residues. - -Modular reductions are normally used to create either finite groups, rings or fields. The most common usage for performance driven modular reductions -is in modular exponentiation algorithms. That is to compute $d = a^b \mbox{ (mod }c\mbox{)}$ as fast as possible. This operation is used in the -RSA and Diffie-Hellman public key algorithms, for example. Modular multiplication and squaring also appears as a fundamental operation in -elliptic curve cryptographic algorithms. As will be discussed in the subsequent chapter there exist fast algorithms for computing modular -exponentiations without having to perform (\textit{in this example}) $b - 1$ multiplications. These algorithms will produce partial results in the -range $0 \le x < c^2$ which can be taken advantage of to create several efficient algorithms. They have also been used to create redundancy check -algorithms known as CRCs, error correction codes such as Reed-Solomon and solve a variety of number theoeretic problems. - -\section{The Barrett Reduction} -The Barrett reduction algorithm \cite{BARRETT} was inspired by fast division algorithms which multiply by the reciprocal to emulate -division. Barretts observation was that the residue $c$ of $a$ modulo $b$ is equal to - -\begin{equation} -c = a - b \cdot \lfloor a/b \rfloor -\end{equation} - -Since algorithms such as modular exponentiation would be using the same modulus extensively, typical DSP\footnote{It is worth noting that Barrett's paper -targeted the DSP56K processor.} intuition would indicate the next step would be to replace $a/b$ by a multiplication by the reciprocal. However, -DSP intuition on its own will not work as these numbers are considerably larger than the precision of common DSP floating point data types. -It would take another common optimization to optimize the algorithm. - -\subsection{Fixed Point Arithmetic} -The trick used to optimize the above equation is based on a technique of emulating floating point data types with fixed precision integers. Fixed -point arithmetic would become very popular as it greatly optimize the ``3d-shooter'' genre of games in the mid 1990s when floating point units were -fairly slow if not unavailable. The idea behind fixed point arithmetic is to take a normal $k$-bit integer data type and break it into $p$-bit -integer and a $q$-bit fraction part (\textit{where $p+q = k$}). - -In this system a $k$-bit integer $n$ would actually represent $n/2^q$. For example, with $q = 4$ the integer $n = 37$ would actually represent the -value $2.3125$. To multiply two fixed point numbers the integers are multiplied using traditional arithmetic and subsequently normalized by -moving the implied decimal point back to where it should be. For example, with $q = 4$ to multiply the integers $9$ and $5$ they must be converted -to fixed point first by multiplying by $2^q$. Let $a = 9(2^q)$ represent the fixed point representation of $9$ and $b = 5(2^q)$ represent the -fixed point representation of $5$. The product $ab$ is equal to $45(2^{2q})$ which when normalized by dividing by $2^q$ produces $45(2^q)$. - -This technique became popular since a normal integer multiplication and logical shift right are the only required operations to perform a multiplication -of two fixed point numbers. Using fixed point arithmetic, division can be easily approximated by multiplying by the reciprocal. If $2^q$ is -equivalent to one than $2^q/b$ is equivalent to the fixed point approximation of $1/b$ using real arithmetic. Using this fact dividing an integer -$a$ by another integer $b$ can be achieved with the following expression. - -\begin{equation} -\lfloor a / b \rfloor \mbox{ }\approx\mbox{ } \lfloor (a \cdot \lfloor 2^q / b \rfloor)/2^q \rfloor -\end{equation} - -The precision of the division is proportional to the value of $q$. If the divisor $b$ is used frequently as is the case with -modular exponentiation pre-computing $2^q/b$ will allow a division to be performed with a multiplication and a right shift. Both operations -are considerably faster than division on most processors. - -Consider dividing $19$ by $5$. The correct result is $\lfloor 19/5 \rfloor = 3$. With $q = 3$ the reciprocal is $\lfloor 2^q/5 \rfloor = 1$ which -leads to a product of $19$ which when divided by $2^q$ produces $2$. However, with $q = 4$ the reciprocal is $\lfloor 2^q/5 \rfloor = 3$ and -the result of the emulated division is $\lfloor 3 \cdot 19 / 2^q \rfloor = 3$ which is correct. The value of $2^q$ must be close to or ideally -larger than the dividend. In effect if $a$ is the dividend then $q$ should allow $0 \le \lfloor a/2^q \rfloor \le 1$ in order for this approach -to work correctly. Plugging this form of divison into the original equation the following modular residue equation arises. - -\begin{equation} -c = a - b \cdot \lfloor (a \cdot \lfloor 2^q / b \rfloor)/2^q \rfloor -\end{equation} - -Using the notation from \cite{BARRETT} the value of $\lfloor 2^q / b \rfloor$ will be represented by the $\mu$ symbol. Using the $\mu$ -variable also helps re-inforce the idea that it is meant to be computed once and re-used. - -\begin{equation} -c = a - b \cdot \lfloor (a \cdot \mu)/2^q \rfloor -\end{equation} - -Provided that $2^q \ge a$ this algorithm will produce a quotient that is either exactly correct or off by a value of one. In the context of Barrett -reduction the value of $a$ is bound by $0 \le a \le (b - 1)^2$ meaning that $2^q \ge b^2$ is sufficient to ensure the reciprocal will have enough -precision. - -Let $n$ represent the number of digits in $b$. This algorithm requires approximately $2n^2$ single precision multiplications to produce the quotient and -another $n^2$ single precision multiplications to find the residue. In total $3n^2$ single precision multiplications are required to -reduce the number. - -For example, if $b = 1179677$ and $q = 41$ ($2^q > b^2$), then the reciprocal $\mu$ is equal to $\lfloor 2^q / b \rfloor = 1864089$. Consider reducing -$a = 180388626447$ modulo $b$ using the above reduction equation. The quotient using the new formula is $\lfloor (a \cdot \mu) / 2^q \rfloor = 152913$. -By subtracting $152913b$ from $a$ the correct residue $a \equiv 677346 \mbox{ (mod }b\mbox{)}$ is found. - -\subsection{Choosing a Radix Point} -Using the fixed point representation a modular reduction can be performed with $3n^2$ single precision multiplications. If that were the best -that could be achieved a full division\footnote{A division requires approximately $O(2cn^2)$ single precision multiplications for a small value of $c$. -See~\ref{sec:division} for further details.} might as well be used in its place. The key to optimizing the reduction is to reduce the precision of -the initial multiplication that finds the quotient. - -Let $a$ represent the number of which the residue is sought. Let $b$ represent the modulus used to find the residue. Let $m$ represent -the number of digits in $b$. For the purposes of this discussion we will assume that the number of digits in $a$ is $2m$, which is generally true if -two $m$-digit numbers have been multiplied. Dividing $a$ by $b$ is the same as dividing a $2m$ digit integer by a $m$ digit integer. Digits below the -$m - 1$'th digit of $a$ will contribute at most a value of $1$ to the quotient because $\beta^k < b$ for any $0 \le k \le m - 1$. Another way to -express this is by re-writing $a$ as two parts. If $a' \equiv a \mbox{ (mod }b^m\mbox{)}$ and $a'' = a - a'$ then -${a \over b} \equiv {{a' + a''} \over b}$ which is equivalent to ${a' \over b} + {a'' \over b}$. Since $a'$ is bound to be less than $b$ the quotient -is bound by $0 \le {a' \over b} < 1$. - -Since the digits of $a'$ do not contribute much to the quotient the observation is that they might as well be zero. However, if the digits -``might as well be zero'' they might as well not be there in the first place. Let $q_0 = \lfloor a/\beta^{m-1} \rfloor$ represent the input -with the irrelevant digits trimmed. Now the modular reduction is trimmed to the almost equivalent equation - -\begin{equation} -c = a - b \cdot \lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor -\end{equation} - -Note that the original divisor $2^q$ has been replaced with $\beta^{m+1}$ where in this case $q$ is a multiple of $lg(\beta)$. Also note that the -exponent on the divisor when added to the amount $q_0$ was shifted by equals $2m$. If the optimization had not been performed the divisor -would have the exponent $2m$ so in the end the exponents do ``add up''. Using the above equation the quotient -$\lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor$ can be off from the true quotient by at most two. The original fixed point quotient can be off -by as much as one (\textit{provided the radix point is chosen suitably}) and now that the lower irrelevent digits have been trimmed the quotient -can be off by an additional value of one for a total of at most two. This implies that -$0 \le a - b \cdot \lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor < 3b$. By first subtracting $b$ times the quotient and then conditionally subtracting -$b$ once or twice the residue is found. - -The quotient is now found using $(m + 1)(m) = m^2 + m$ single precision multiplications and the residue with an additional $m^2$ single -precision multiplications, ignoring the subtractions required. In total $2m^2 + m$ single precision multiplications are required to find the residue. -This is considerably faster than the original attempt. - -For example, let $\beta = 10$ represent the radix of the digits. Let $b = 9999$ represent the modulus which implies $m = 4$. Let $a = 99929878$ -represent the value of which the residue is desired. In this case $q = 8$ since $10^7 < 9999^2$ meaning that $\mu = \lfloor \beta^{q}/b \rfloor = 10001$. -With the new observation the multiplicand for the quotient is equal to $q_0 = \lfloor a / \beta^{m - 1} \rfloor = 99929$. The quotient is then -$\lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor = 9993$. Subtracting $9993b$ from $a$ and the correct residue $a \equiv 9871 \mbox{ (mod }b\mbox{)}$ -is found. - -\subsection{Trimming the Quotient} -So far the reduction algorithm has been optimized from $3m^2$ single precision multiplications down to $2m^2 + m$ single precision multiplications. As -it stands now the algorithm is already fairly fast compared to a full integer division algorithm. However, there is still room for -optimization. - -After the first multiplication inside the quotient ($q_0 \cdot \mu$) the value is shifted right by $m + 1$ places effectively nullifying the lower -half of the product. It would be nice to be able to remove those digits from the product to effectively cut down the number of single precision -multiplications. If the number of digits in the modulus $m$ is far less than $\beta$ a full product is not required for the algorithm to work properly. -In fact the lower $m - 2$ digits will not affect the upper half of the product at all and do not need to be computed. - -The value of $\mu$ is a $m$-digit number and $q_0$ is a $m + 1$ digit number. Using a full multiplier $(m + 1)(m) = m^2 + m$ single precision -multiplications would be required. Using a multiplier that will only produce digits at and above the $m - 1$'th digit reduces the number -of single precision multiplications to ${m^2 + m} \over 2$ single precision multiplications. - -\subsection{Trimming the Residue} -After the quotient has been calculated it is used to reduce the input. As previously noted the algorithm is not exact and it can be off by a small -multiple of the modulus, that is $0 \le a - b \cdot \lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor < 3b$. If $b$ is $m$ digits than the -result of reduction equation is a value of at most $m + 1$ digits (\textit{provided $3 < \beta$}) implying that the upper $m - 1$ digits are -implicitly zero. - -The next optimization arises from this very fact. Instead of computing $b \cdot \lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor$ using a full -$O(m^2)$ multiplication algorithm only the lower $m+1$ digits of the product have to be computed. Similarly the value of $a$ can -be reduced modulo $\beta^{m+1}$ before the multiple of $b$ is subtracted which simplifes the subtraction as well. A multiplication that produces -only the lower $m+1$ digits requires ${m^2 + 3m - 2} \over 2$ single precision multiplications. - -With both optimizations in place the algorithm is the algorithm Barrett proposed. It requires $m^2 + 2m - 1$ single precision multiplications which -is considerably faster than the straightforward $3m^2$ method. - -\subsection{The Barrett Algorithm} -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_reduce}. \\ -\textbf{Input}. mp\_int $a$, mp\_int $b$ and $\mu = \lfloor \beta^{2m}/b \rfloor, m = \lceil lg_{\beta}(b) \rceil, (0 \le a < b^2, b > 1)$ \\ -\textbf{Output}. $a \mbox{ (mod }b\mbox{)}$ \\ -\hline \\ -Let $m$ represent the number of digits in $b$. \\ -1. Make a copy of $a$ and store it in $q$. (\textit{mp\_init\_copy}) \\ -2. $q \leftarrow \lfloor q / \beta^{m - 1} \rfloor$ (\textit{mp\_rshd}) \\ -\\ -Produce the quotient. \\ -3. $q \leftarrow q \cdot \mu$ (\textit{note: only produce digits at or above $m-1$}) \\ -4. $q \leftarrow \lfloor q / \beta^{m + 1} \rfloor$ \\ -\\ -Subtract the multiple of modulus from the input. \\ -5. $a \leftarrow a \mbox{ (mod }\beta^{m+1}\mbox{)}$ (\textit{mp\_mod\_2d}) \\ -6. $q \leftarrow q \cdot b \mbox{ (mod }\beta^{m+1}\mbox{)}$ (\textit{s\_mp\_mul\_digs}) \\ -7. $a \leftarrow a - q$ (\textit{mp\_sub}) \\ -\\ -Add $\beta^{m+1}$ if a carry occured. \\ -8. If $a < 0$ then (\textit{mp\_cmp\_d}) \\ -\hspace{3mm}8.1 $q \leftarrow 1$ (\textit{mp\_set}) \\ -\hspace{3mm}8.2 $q \leftarrow q \cdot \beta^{m+1}$ (\textit{mp\_lshd}) \\ -\hspace{3mm}8.3 $a \leftarrow a + q$ \\ -\\ -Now subtract the modulus if the residue is too large (e.g. quotient too small). \\ -9. While $a \ge b$ do (\textit{mp\_cmp}) \\ -\hspace{3mm}9.1 $c \leftarrow a - b$ \\ -10. Clear $q$. \\ -11. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_reduce} -\end{figure} - -\textbf{Algorithm mp\_reduce.} -This algorithm will reduce the input $a$ modulo $b$ in place using the Barrett algorithm. It is loosely based on algorithm 14.42 of HAC -\cite[pp. 602]{HAC} which is based on the paper from Paul Barrett \cite{BARRETT}. The algorithm has several restrictions and assumptions which must -be adhered to for the algorithm to work. - -First the modulus $b$ is assumed to be positive and greater than one. If the modulus were less than or equal to one than subtracting -a multiple of it would either accomplish nothing or actually enlarge the input. The input $a$ must be in the range $0 \le a < b^2$ in order -for the quotient to have enough precision. If $a$ is the product of two numbers that were already reduced modulo $b$, this will not be a problem. -Technically the algorithm will still work if $a \ge b^2$ but it will take much longer to finish. The value of $\mu$ is passed as an argument to this -algorithm and is assumed to be calculated and stored before the algorithm is used. - -Recall that the multiplication for the quotient on step 3 must only produce digits at or above the $m-1$'th position. An algorithm called -$s\_mp\_mul\_high\_digs$ which has not been presented is used to accomplish this task. The algorithm is based on $s\_mp\_mul\_digs$ except that -instead of stopping at a given level of precision it starts at a given level of precision. This optimal algorithm can only be used if the number -of digits in $b$ is very much smaller than $\beta$. - -While it is known that -$a \ge b \cdot \lfloor (q_0 \cdot \mu) / \beta^{m+1} \rfloor$ only the lower $m+1$ digits are being used to compute the residue, so an implied -``borrow'' from the higher digits might leave a negative result. After the multiple of the modulus has been subtracted from $a$ the residue must be -fixed up in case it is negative. The invariant $\beta^{m+1}$ must be added to the residue to make it positive again. - -The while loop at step 9 will subtract $b$ until the residue is less than $b$. If the algorithm is performed correctly this step is -performed at most twice, and on average once. However, if $a \ge b^2$ than it will iterate substantially more times than it should. - -EXAM,bn_mp_reduce.c - -The first multiplication that determines the quotient can be performed by only producing the digits from $m - 1$ and up. This essentially halves -the number of single precision multiplications required. However, the optimization is only safe if $\beta$ is much larger than the number of digits -in the modulus. In the source code this is evaluated on lines @36,if@ to @44,}@ where algorithm s\_mp\_mul\_high\_digs is used when it is -safe to do so. - -\subsection{The Barrett Setup Algorithm} -In order to use algorithm mp\_reduce the value of $\mu$ must be calculated in advance. Ideally this value should be computed once and stored for -future use so that the Barrett algorithm can be used without delay. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_reduce\_setup}. \\ -\textbf{Input}. mp\_int $a$ ($a > 1$) \\ -\textbf{Output}. $\mu \leftarrow \lfloor \beta^{2m}/a \rfloor$ \\ -\hline \\ -1. $\mu \leftarrow 2^{2 \cdot lg(\beta) \cdot m}$ (\textit{mp\_2expt}) \\ -2. $\mu \leftarrow \lfloor \mu / b \rfloor$ (\textit{mp\_div}) \\ -3. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_reduce\_setup} -\end{figure} - -\textbf{Algorithm mp\_reduce\_setup.} -This algorithm computes the reciprocal $\mu$ required for Barrett reduction. First $\beta^{2m}$ is calculated as $2^{2 \cdot lg(\beta) \cdot m}$ which -is equivalent and much faster. The final value is computed by taking the integer quotient of $\lfloor \mu / b \rfloor$. - -EXAM,bn_mp_reduce_setup.c - -This simple routine calculates the reciprocal $\mu$ required by Barrett reduction. Note the extended usage of algorithm mp\_div where the variable -which would received the remainder is passed as NULL. As will be discussed in~\ref{sec:division} the division routine allows both the quotient and the -remainder to be passed as NULL meaning to ignore the value. - -\section{The Montgomery Reduction} -Montgomery reduction\footnote{Thanks to Niels Ferguson for his insightful explanation of the algorithm.} \cite{MONT} is by far the most interesting -form of reduction in common use. It computes a modular residue which is not actually equal to the residue of the input yet instead equal to a -residue times a constant. However, as perplexing as this may sound the algorithm is relatively simple and very efficient. - -Throughout this entire section the variable $n$ will represent the modulus used to form the residue. As will be discussed shortly the value of -$n$ must be odd. The variable $x$ will represent the quantity of which the residue is sought. Similar to the Barrett algorithm the input -is restricted to $0 \le x < n^2$. To begin the description some simple number theory facts must be established. - -\textbf{Fact 1.} Adding $n$ to $x$ does not change the residue since in effect it adds one to the quotient $\lfloor x / n \rfloor$. Another way -to explain this is that $n$ is (\textit{or multiples of $n$ are}) congruent to zero modulo $n$. Adding zero will not change the value of the residue. - -\textbf{Fact 2.} If $x$ is even then performing a division by two in $\Z$ is congruent to $x \cdot 2^{-1} \mbox{ (mod }n\mbox{)}$. Actually -this is an application of the fact that if $x$ is evenly divisible by any $k \in \Z$ then division in $\Z$ will be congruent to -multiplication by $k^{-1}$ modulo $n$. - -From these two simple facts the following simple algorithm can be derived. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Montgomery Reduction}. \\ -\textbf{Input}. Integer $x$, $n$ and $k$ \\ -\textbf{Output}. $2^{-k}x \mbox{ (mod }n\mbox{)}$ \\ -\hline \\ -1. for $t$ from $1$ to $k$ do \\ -\hspace{3mm}1.1 If $x$ is odd then \\ -\hspace{6mm}1.1.1 $x \leftarrow x + n$ \\ -\hspace{3mm}1.2 $x \leftarrow x/2$ \\ -2. Return $x$. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Montgomery Reduction} -\end{figure} - -The algorithm reduces the input one bit at a time using the two congruencies stated previously. Inside the loop $n$, which is odd, is -added to $x$ if $x$ is odd. This forces $x$ to be even which allows the division by two in $\Z$ to be congruent to a modular division by two. Since -$x$ is assumed to be initially much larger than $n$ the addition of $n$ will contribute an insignificant magnitude to $x$. Let $r$ represent the -final result of the Montgomery algorithm. If $k > lg(n)$ and $0 \le x < n^2$ then the final result is limited to -$0 \le r < \lfloor x/2^k \rfloor + n$. As a result at most a single subtraction is required to get the residue desired. - -\begin{figure}[h] -\begin{small} -\begin{center} -\begin{tabular}{|c|l|} -\hline \textbf{Step number ($t$)} & \textbf{Result ($x$)} \\ -\hline $1$ & $x + n = 5812$, $x/2 = 2906$ \\ -\hline $2$ & $x/2 = 1453$ \\ -\hline $3$ & $x + n = 1710$, $x/2 = 855$ \\ -\hline $4$ & $x + n = 1112$, $x/2 = 556$ \\ -\hline $5$ & $x/2 = 278$ \\ -\hline $6$ & $x/2 = 139$ \\ -\hline $7$ & $x + n = 396$, $x/2 = 198$ \\ -\hline $8$ & $x/2 = 99$ \\ -\hline $9$ & $x + n = 356$, $x/2 = 178$ \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Example of Montgomery Reduction (I)} -\label{fig:MONT1} -\end{figure} - -Consider the example in figure~\ref{fig:MONT1} which reduces $x = 5555$ modulo $n = 257$ when $k = 9$ (note $\beta^k = 512$ which is larger than $n$). The result of -the algorithm $r = 178$ is congruent to the value of $2^{-9} \cdot 5555 \mbox{ (mod }257\mbox{)}$. When $r$ is multiplied by $2^9$ modulo $257$ the correct residue -$r \equiv 158$ is produced. - -Let $k = \lfloor lg(n) \rfloor + 1$ represent the number of bits in $n$. The current algorithm requires $2k^2$ single precision shifts -and $k^2$ single precision additions. At this rate the algorithm is most certainly slower than Barrett reduction and not terribly useful. -Fortunately there exists an alternative representation of the algorithm. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Montgomery Reduction} (modified I). \\ -\textbf{Input}. Integer $x$, $n$ and $k$ ($2^k > n$) \\ -\textbf{Output}. $2^{-k}x \mbox{ (mod }n\mbox{)}$ \\ -\hline \\ -1. for $t$ from $1$ to $k$ do \\ -\hspace{3mm}1.1 If the $t$'th bit of $x$ is one then \\ -\hspace{6mm}1.1.1 $x \leftarrow x + 2^tn$ \\ -2. Return $x/2^k$. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Montgomery Reduction (modified I)} -\end{figure} - -This algorithm is equivalent since $2^tn$ is a multiple of $n$ and the lower $k$ bits of $x$ are zero by step 2. The number of single -precision shifts has now been reduced from $2k^2$ to $k^2 + k$ which is only a small improvement. - -\begin{figure}[h] -\begin{small} -\begin{center} -\begin{tabular}{|c|l|r|} -\hline \textbf{Step number ($t$)} & \textbf{Result ($x$)} & \textbf{Result ($x$) in Binary} \\ -\hline -- & $5555$ & $1010110110011$ \\ -\hline $1$ & $x + 2^{0}n = 5812$ & $1011010110100$ \\ -\hline $2$ & $5812$ & $1011010110100$ \\ -\hline $3$ & $x + 2^{2}n = 6840$ & $1101010111000$ \\ -\hline $4$ & $x + 2^{3}n = 8896$ & $10001011000000$ \\ -\hline $5$ & $8896$ & $10001011000000$ \\ -\hline $6$ & $8896$ & $10001011000000$ \\ -\hline $7$ & $x + 2^{6}n = 25344$ & $110001100000000$ \\ -\hline $8$ & $25344$ & $110001100000000$ \\ -\hline $9$ & $x + 2^{7}n = 91136$ & $10110010000000000$ \\ -\hline -- & $x/2^k = 178$ & \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Example of Montgomery Reduction (II)} -\label{fig:MONT2} -\end{figure} - -Figure~\ref{fig:MONT2} demonstrates the modified algorithm reducing $x = 5555$ modulo $n = 257$ with $k = 9$. -With this algorithm a single shift right at the end is the only right shift required to reduce the input instead of $k$ right shifts inside the -loop. Note that for the iterations $t = 2, 5, 6$ and $8$ where the result $x$ is not changed. In those iterations the $t$'th bit of $x$ is -zero and the appropriate multiple of $n$ does not need to be added to force the $t$'th bit of the result to zero. - -\subsection{Digit Based Montgomery Reduction} -Instead of computing the reduction on a bit-by-bit basis it is actually much faster to compute it on digit-by-digit basis. Consider the -previous algorithm re-written to compute the Montgomery reduction in this new fashion. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Montgomery Reduction} (modified II). \\ -\textbf{Input}. Integer $x$, $n$ and $k$ ($\beta^k > n$) \\ -\textbf{Output}. $\beta^{-k}x \mbox{ (mod }n\mbox{)}$ \\ -\hline \\ -1. for $t$ from $0$ to $k - 1$ do \\ -\hspace{3mm}1.1 $x \leftarrow x + \mu n \beta^t$ \\ -2. Return $x/\beta^k$. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Montgomery Reduction (modified II)} -\end{figure} - -The value $\mu n \beta^t$ is a multiple of the modulus $n$ meaning that it will not change the residue. If the first digit of -the value $\mu n \beta^t$ equals the negative (modulo $\beta$) of the $t$'th digit of $x$ then the addition will result in a zero digit. This -problem breaks down to solving the following congruency. - -\begin{center} -\begin{tabular}{rcl} -$x_t + \mu n_0$ & $\equiv$ & $0 \mbox{ (mod }\beta\mbox{)}$ \\ -$\mu n_0$ & $\equiv$ & $-x_t \mbox{ (mod }\beta\mbox{)}$ \\ -$\mu$ & $\equiv$ & $-x_t/n_0 \mbox{ (mod }\beta\mbox{)}$ \\ -\end{tabular} -\end{center} - -In each iteration of the loop on step 1 a new value of $\mu$ must be calculated. The value of $-1/n_0 \mbox{ (mod }\beta\mbox{)}$ is used -extensively in this algorithm and should be precomputed. Let $\rho$ represent the negative of the modular inverse of $n_0$ modulo $\beta$. - -For example, let $\beta = 10$ represent the radix. Let $n = 17$ represent the modulus which implies $k = 2$ and $\rho \equiv 7$. Let $x = 33$ -represent the value to reduce. - -\newpage\begin{figure} -\begin{center} -\begin{tabular}{|c|c|c|} -\hline \textbf{Step ($t$)} & \textbf{Value of $x$} & \textbf{Value of $\mu$} \\ -\hline -- & $33$ & --\\ -\hline $0$ & $33 + \mu n = 50$ & $1$ \\ -\hline $1$ & $50 + \mu n \beta = 900$ & $5$ \\ -\hline -\end{tabular} -\end{center} -\caption{Example of Montgomery Reduction} -\end{figure} - -The final result $900$ is then divided by $\beta^k$ to produce the final result $9$. The first observation is that $9 \nequiv x \mbox{ (mod }n\mbox{)}$ -which implies the result is not the modular residue of $x$ modulo $n$. However, recall that the residue is actually multiplied by $\beta^{-k}$ in -the algorithm. To get the true residue the value must be multiplied by $\beta^k$. In this case $\beta^k \equiv 15 \mbox{ (mod }n\mbox{)}$ and -the correct residue is $9 \cdot 15 \equiv 16 \mbox{ (mod }n\mbox{)}$. - -\subsection{Baseline Montgomery Reduction} -The baseline Montgomery reduction algorithm will produce the residue for any size input. It is designed to be a catch-all algororithm for -Montgomery reductions. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_montgomery\_reduce}. \\ -\textbf{Input}. mp\_int $x$, mp\_int $n$ and a digit $\rho \equiv -1/n_0 \mbox{ (mod }n\mbox{)}$. \\ -\hspace{11.5mm}($0 \le x < n^2, n > 1, (n, \beta) = 1, \beta^k > n$) \\ -\textbf{Output}. $\beta^{-k}x \mbox{ (mod }n\mbox{)}$ \\ -\hline \\ -1. $digs \leftarrow 2n.used + 1$ \\ -2. If $digs < MP\_ARRAY$ and $m.used < \delta$ then \\ -\hspace{3mm}2.1 Use algorithm fast\_mp\_montgomery\_reduce instead. \\ -\\ -Setup $x$ for the reduction. \\ -3. If $x.alloc < digs$ then grow $x$ to $digs$ digits. \\ -4. $x.used \leftarrow digs$ \\ -\\ -Eliminate the lower $k$ digits. \\ -5. For $ix$ from $0$ to $k - 1$ do \\ -\hspace{3mm}5.1 $\mu \leftarrow x_{ix} \cdot \rho \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}5.2 $u \leftarrow 0$ \\ -\hspace{3mm}5.3 For $iy$ from $0$ to $k - 1$ do \\ -\hspace{6mm}5.3.1 $\hat r \leftarrow \mu n_{iy} + x_{ix + iy} + u$ \\ -\hspace{6mm}5.3.2 $x_{ix + iy} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{6mm}5.3.3 $u \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -\hspace{3mm}5.4 While $u > 0$ do \\ -\hspace{6mm}5.4.1 $iy \leftarrow iy + 1$ \\ -\hspace{6mm}5.4.2 $x_{ix + iy} \leftarrow x_{ix + iy} + u$ \\ -\hspace{6mm}5.4.3 $u \leftarrow \lfloor x_{ix+iy} / \beta \rfloor$ \\ -\hspace{6mm}5.4.4 $x_{ix + iy} \leftarrow x_{ix+iy} \mbox{ (mod }\beta\mbox{)}$ \\ -\\ -Divide by $\beta^k$ and fix up as required. \\ -6. $x \leftarrow \lfloor x / \beta^k \rfloor$ \\ -7. If $x \ge n$ then \\ -\hspace{3mm}7.1 $x \leftarrow x - n$ \\ -8. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_montgomery\_reduce} -\end{figure} - -\textbf{Algorithm mp\_montgomery\_reduce.} -This algorithm reduces the input $x$ modulo $n$ in place using the Montgomery reduction algorithm. The algorithm is loosely based -on algorithm 14.32 of \cite[pp.601]{HAC} except it merges the multiplication of $\mu n \beta^t$ with the addition in the inner loop. The -restrictions on this algorithm are fairly easy to adapt to. First $0 \le x < n^2$ bounds the input to numbers in the same range as -for the Barrett algorithm. Additionally if $n > 1$ and $n$ is odd there will exist a modular inverse $\rho$. $\rho$ must be calculated in -advance of this algorithm. Finally the variable $k$ is fixed and a pseudonym for $n.used$. - -Step 2 decides whether a faster Montgomery algorithm can be used. It is based on the Comba technique meaning that there are limits on -the size of the input. This algorithm is discussed in ~COMBARED~. - -Step 5 is the main reduction loop of the algorithm. The value of $\mu$ is calculated once per iteration in the outer loop. The inner loop -calculates $x + \mu n \beta^{ix}$ by multiplying $\mu n$ and adding the result to $x$ shifted by $ix$ digits. Both the addition and -multiplication are performed in the same loop to save time and memory. Step 5.4 will handle any additional carries that escape the inner loop. - -Using a quick inspection this algorithm requires $n$ single precision multiplications for the outer loop and $n^2$ single precision multiplications -in the inner loop. In total $n^2 + n$ single precision multiplications which compares favourably to Barrett at $n^2 + 2n - 1$ single precision -multiplications. - -EXAM,bn_mp_montgomery_reduce.c - -This is the baseline implementation of the Montgomery reduction algorithm. Lines @30,digs@ to @35,}@ determine if the Comba based -routine can be used instead. Line @47,mu@ computes the value of $\mu$ for that particular iteration of the outer loop. - -The multiplication $\mu n \beta^{ix}$ is performed in one step in the inner loop. The alias $tmpx$ refers to the $ix$'th digit of $x$ and -the alias $tmpn$ refers to the modulus $n$. - -\subsection{Faster ``Comba'' Montgomery Reduction} -MARK,COMBARED - -The Montgomery reduction requires fewer single precision multiplications than a Barrett reduction, however it is much slower due to the serial -nature of the inner loop. The Barrett reduction algorithm requires two slightly modified multipliers which can be implemented with the Comba -technique. The Montgomery reduction algorithm cannot directly use the Comba technique to any significant advantage since the inner loop calculates -a $k \times 1$ product $k$ times. - -The biggest obstacle is that at the $ix$'th iteration of the outer loop the value of $x_{ix}$ is required to calculate $\mu$. This means the -carries from $0$ to $ix - 1$ must have been propagated upwards to form a valid $ix$'th digit. The solution as it turns out is very simple. -Perform a Comba like multiplier and inside the outer loop just after the inner loop fix up the $ix + 1$'th digit by forwarding the carry. - -With this change in place the Montgomery reduction algorithm can be performed with a Comba style multiplication loop which substantially increases -the speed of the algorithm. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{fast\_mp\_montgomery\_reduce}. \\ -\textbf{Input}. mp\_int $x$, mp\_int $n$ and a digit $\rho \equiv -1/n_0 \mbox{ (mod }n\mbox{)}$. \\ -\hspace{11.5mm}($0 \le x < n^2, n > 1, (n, \beta) = 1, \beta^k > n$) \\ -\textbf{Output}. $\beta^{-k}x \mbox{ (mod }n\mbox{)}$ \\ -\hline \\ -Place an array of \textbf{MP\_WARRAY} mp\_word variables called $\hat W$ on the stack. \\ -1. if $x.alloc < n.used + 1$ then grow $x$ to $n.used + 1$ digits. \\ -Copy the digits of $x$ into the array $\hat W$ \\ -2. For $ix$ from $0$ to $x.used - 1$ do \\ -\hspace{3mm}2.1 $\hat W_{ix} \leftarrow x_{ix}$ \\ -3. For $ix$ from $x.used$ to $2n.used - 1$ do \\ -\hspace{3mm}3.1 $\hat W_{ix} \leftarrow 0$ \\ -Elimiate the lower $k$ digits. \\ -4. for $ix$ from $0$ to $n.used - 1$ do \\ -\hspace{3mm}4.1 $\mu \leftarrow \hat W_{ix} \cdot \rho \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}4.2 For $iy$ from $0$ to $n.used - 1$ do \\ -\hspace{6mm}4.2.1 $\hat W_{iy + ix} \leftarrow \hat W_{iy + ix} + \mu \cdot n_{iy}$ \\ -\hspace{3mm}4.3 $\hat W_{ix + 1} \leftarrow \hat W_{ix + 1} + \lfloor \hat W_{ix} / \beta \rfloor$ \\ -Propagate carries upwards. \\ -5. for $ix$ from $n.used$ to $2n.used + 1$ do \\ -\hspace{3mm}5.1 $\hat W_{ix + 1} \leftarrow \hat W_{ix + 1} + \lfloor \hat W_{ix} / \beta \rfloor$ \\ -Shift right and reduce modulo $\beta$ simultaneously. \\ -6. for $ix$ from $0$ to $n.used + 1$ do \\ -\hspace{3mm}6.1 $x_{ix} \leftarrow \hat W_{ix + n.used} \mbox{ (mod }\beta\mbox{)}$ \\ -Zero excess digits and fixup $x$. \\ -7. if $x.used > n.used + 1$ then do \\ -\hspace{3mm}7.1 for $ix$ from $n.used + 1$ to $x.used - 1$ do \\ -\hspace{6mm}7.1.1 $x_{ix} \leftarrow 0$ \\ -8. $x.used \leftarrow n.used + 1$ \\ -9. Clamp excessive digits of $x$. \\ -10. If $x \ge n$ then \\ -\hspace{3mm}10.1 $x \leftarrow x - n$ \\ -11. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm fast\_mp\_montgomery\_reduce} -\end{figure} - -\textbf{Algorithm fast\_mp\_montgomery\_reduce.} -This algorithm will compute the Montgomery reduction of $x$ modulo $n$ using the Comba technique. It is on most computer platforms significantly -faster than algorithm mp\_montgomery\_reduce and algorithm mp\_reduce (\textit{Barrett reduction}). The algorithm has the same restrictions -on the input as the baseline reduction algorithm. An additional two restrictions are imposed on this algorithm. The number of digits $k$ in the -the modulus $n$ must not violate $MP\_WARRAY > 2k +1$ and $n < \delta$. When $\beta = 2^{28}$ this algorithm can be used to reduce modulo -a modulus of at most $3,556$ bits in length. - -As in the other Comba reduction algorithms there is a $\hat W$ array which stores the columns of the product. It is initially filled with the -contents of $x$ with the excess digits zeroed. The reduction loop is very similar the to the baseline loop at heart. The multiplication on step -4.1 can be single precision only since $ab \mbox{ (mod }\beta\mbox{)} \equiv (a \mbox{ mod }\beta)(b \mbox{ mod }\beta)$. Some multipliers such -as those on the ARM processors take a variable length time to complete depending on the number of bytes of result it must produce. By performing -a single precision multiplication instead half the amount of time is spent. - -Also note that digit $\hat W_{ix}$ must have the carry from the $ix - 1$'th digit propagated upwards in order for this to work. That is what step -4.3 will do. In effect over the $n.used$ iterations of the outer loop the $n.used$'th lower columns all have the their carries propagated forwards. Note -how the upper bits of those same words are not reduced modulo $\beta$. This is because those values will be discarded shortly and there is no -point. - -Step 5 will propagate the remainder of the carries upwards. On step 6 the columns are reduced modulo $\beta$ and shifted simultaneously as they are -stored in the destination $x$. - -EXAM,bn_s_mp_montgomery_reduce_fast.c - -The $\hat W$ array is first filled with digits of $x$ on line @49,for@ then the rest of the digits are zeroed on line @54,for@. Both loops share -the same alias variables to make the code easier to read. - -The value of $\mu$ is calculated in an interesting fashion. First the value $\hat W_{ix}$ is reduced modulo $\beta$ and cast to a mp\_digit. This -forces the compiler to use a single precision multiplication and prevents any concerns about loss of precision. Line @101,>>@ fixes the carry -for the next iteration of the loop by propagating the carry from $\hat W_{ix}$ to $\hat W_{ix+1}$. - -The for loop on line @113,for@ propagates the rest of the carries upwards through the columns. The for loop on line @126,for@ reduces the columns -modulo $\beta$ and shifts them $k$ places at the same time. The alias $\_ \hat W$ actually refers to the array $\hat W$ starting at the $n.used$'th -digit, that is $\_ \hat W_{t} = \hat W_{n.used + t}$. - -\subsection{Montgomery Setup} -To calculate the variable $\rho$ a relatively simple algorithm will be required. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_montgomery\_setup}. \\ -\textbf{Input}. mp\_int $n$ ($n > 1$ and $(n, 2) = 1$) \\ -\textbf{Output}. $\rho \equiv -1/n_0 \mbox{ (mod }\beta\mbox{)}$ \\ -\hline \\ -1. $b \leftarrow n_0$ \\ -2. If $b$ is even return(\textit{MP\_VAL}) \\ -3. $x \leftarrow (((b + 2) \mbox{ AND } 4) << 1) + b$ \\ -4. for $k$ from 0 to $\lceil lg(lg(\beta)) \rceil - 2$ do \\ -\hspace{3mm}4.1 $x \leftarrow x \cdot (2 - bx)$ \\ -5. $\rho \leftarrow \beta - x \mbox{ (mod }\beta\mbox{)}$ \\ -6. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_montgomery\_setup} -\end{figure} - -\textbf{Algorithm mp\_montgomery\_setup.} -This algorithm will calculate the value of $\rho$ required within the Montgomery reduction algorithms. It uses a very interesting trick -to calculate $1/n_0$ when $\beta$ is a power of two. - -EXAM,bn_mp_montgomery_setup.c - -This source code computes the value of $\rho$ required to perform Montgomery reduction. It has been modified to avoid performing excess -multiplications when $\beta$ is not the default 28-bits. - -\section{The Diminished Radix Algorithm} -The Diminished Radix method of modular reduction \cite{DRMET} is a fairly clever technique which can be more efficient than either the Barrett -or Montgomery methods for certain forms of moduli. The technique is based on the following simple congruence. - -\begin{equation} -(x \mbox{ mod } n) + k \lfloor x / n \rfloor \equiv x \mbox{ (mod }(n - k)\mbox{)} -\end{equation} - -This observation was used in the MMB \cite{MMB} block cipher to create a diffusion primitive. It used the fact that if $n = 2^{31}$ and $k=1$ that -then a x86 multiplier could produce the 62-bit product and use the ``shrd'' instruction to perform a double-precision right shift. The proof -of the above equation is very simple. First write $x$ in the product form. - -\begin{equation} -x = qn + r -\end{equation} - -Now reduce both sides modulo $(n - k)$. - -\begin{equation} -x \equiv qk + r \mbox{ (mod }(n-k)\mbox{)} -\end{equation} - -The variable $n$ reduces modulo $n - k$ to $k$. By putting $q = \lfloor x/n \rfloor$ and $r = x \mbox{ mod } n$ -into the equation the original congruence is reproduced, thus concluding the proof. The following algorithm is based on this observation. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Diminished Radix Reduction}. \\ -\textbf{Input}. Integer $x$, $n$, $k$ \\ -\textbf{Output}. $x \mbox{ mod } (n - k)$ \\ -\hline \\ -1. $q \leftarrow \lfloor x / n \rfloor$ \\ -2. $q \leftarrow k \cdot q$ \\ -3. $x \leftarrow x \mbox{ (mod }n\mbox{)}$ \\ -4. $x \leftarrow x + q$ \\ -5. If $x \ge (n - k)$ then \\ -\hspace{3mm}5.1 $x \leftarrow x - (n - k)$ \\ -\hspace{3mm}5.2 Goto step 1. \\ -6. Return $x$ \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Diminished Radix Reduction} -\label{fig:DR} -\end{figure} - -This algorithm will reduce $x$ modulo $n - k$ and return the residue. If $0 \le x < (n - k)^2$ then the algorithm will loop almost always -once or twice and occasionally three times. For simplicity sake the value of $x$ is bounded by the following simple polynomial. - -\begin{equation} -0 \le x < n^2 + k^2 - 2nk -\end{equation} - -The true bound is $0 \le x < (n - k - 1)^2$ but this has quite a few more terms. The value of $q$ after step 1 is bounded by the following. - -\begin{equation} -q < n - 2k - k^2/n -\end{equation} - -Since $k^2$ is going to be considerably smaller than $n$ that term will always be zero. The value of $x$ after step 3 is bounded trivially as -$0 \le x < n$. By step four the sum $x + q$ is bounded by - -\begin{equation} -0 \le q + x < (k + 1)n - 2k^2 - 1 -\end{equation} - -With a second pass $q$ will be loosely bounded by $0 \le q < k^2$ after step 2 while $x$ will still be loosely bounded by $0 \le x < n$ after step 3. After the second pass it is highly unlike that the -sum in step 4 will exceed $n - k$. In practice fewer than three passes of the algorithm are required to reduce virtually every input in the -range $0 \le x < (n - k - 1)^2$. - -\begin{figure} -\begin{small} -\begin{center} -\begin{tabular}{|l|} -\hline -$x = 123456789, n = 256, k = 3$ \\ -\hline $q \leftarrow \lfloor x/n \rfloor = 482253$ \\ -$q \leftarrow q*k = 1446759$ \\ -$x \leftarrow x \mbox{ mod } n = 21$ \\ -$x \leftarrow x + q = 1446780$ \\ -$x \leftarrow x - (n - k) = 1446527$ \\ -\hline -$q \leftarrow \lfloor x/n \rfloor = 5650$ \\ -$q \leftarrow q*k = 16950$ \\ -$x \leftarrow x \mbox{ mod } n = 127$ \\ -$x \leftarrow x + q = 17077$ \\ -$x \leftarrow x - (n - k) = 16824$ \\ -\hline -$q \leftarrow \lfloor x/n \rfloor = 65$ \\ -$q \leftarrow q*k = 195$ \\ -$x \leftarrow x \mbox{ mod } n = 184$ \\ -$x \leftarrow x + q = 379$ \\ -$x \leftarrow x - (n - k) = 126$ \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Example Diminished Radix Reduction} -\label{fig:EXDR} -\end{figure} - -Figure~\ref{fig:EXDR} demonstrates the reduction of $x = 123456789$ modulo $n - k = 253$ when $n = 256$ and $k = 3$. Note that even while $x$ -is considerably larger than $(n - k - 1)^2 = 63504$ the algorithm still converges on the modular residue exceedingly fast. In this case only -three passes were required to find the residue $x \equiv 126$. - - -\subsection{Choice of Moduli} -On the surface this algorithm looks like a very expensive algorithm. It requires a couple of subtractions followed by multiplication and other -modular reductions. The usefulness of this algorithm becomes exceedingly clear when an appropriate modulus is chosen. - -Division in general is a very expensive operation to perform. The one exception is when the division is by a power of the radix of representation used. -Division by ten for example is simple for pencil and paper mathematics since it amounts to shifting the decimal place to the right. Similarly division -by two (\textit{or powers of two}) is very simple for binary computers to perform. It would therefore seem logical to choose $n$ of the form $2^p$ -which would imply that $\lfloor x / n \rfloor$ is a simple shift of $x$ right $p$ bits. - -However, there is one operation related to division of power of twos that is even faster than this. If $n = \beta^p$ then the division may be -performed by moving whole digits to the right $p$ places. In practice division by $\beta^p$ is much faster than division by $2^p$ for any $p$. -Also with the choice of $n = \beta^p$ reducing $x$ modulo $n$ merely requires zeroing the digits above the $p-1$'th digit of $x$. - -Throughout the next section the term ``restricted modulus'' will refer to a modulus of the form $\beta^p - k$ whereas the term ``unrestricted -modulus'' will refer to a modulus of the form $2^p - k$. The word ``restricted'' in this case refers to the fact that it is based on the -$2^p$ logic except $p$ must be a multiple of $lg(\beta)$. - -\subsection{Choice of $k$} -Now that division and reduction (\textit{step 1 and 3 of figure~\ref{fig:DR}}) have been optimized to simple digit operations the multiplication by $k$ -in step 2 is the most expensive operation. Fortunately the choice of $k$ is not terribly limited. For all intents and purposes it might -as well be a single digit. The smaller the value of $k$ is the faster the algorithm will be. - -\subsection{Restricted Diminished Radix Reduction} -The restricted Diminished Radix algorithm can quickly reduce an input modulo a modulus of the form $n = \beta^p - k$. This algorithm can reduce -an input $x$ within the range $0 \le x < n^2$ using only a couple passes of the algorithm demonstrated in figure~\ref{fig:DR}. The implementation -of this algorithm has been optimized to avoid additional overhead associated with a division by $\beta^p$, the multiplication by $k$ or the addition -of $x$ and $q$. The resulting algorithm is very efficient and can lead to substantial improvements over Barrett and Montgomery reduction when modular -exponentiations are performed. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_dr\_reduce}. \\ -\textbf{Input}. mp\_int $x$, $n$ and a mp\_digit $k = \beta - n_0$ \\ -\hspace{11.5mm}($0 \le x < n^2$, $n > 1$, $0 < k < \beta$) \\ -\textbf{Output}. $x \mbox{ mod } n$ \\ -\hline \\ -1. $m \leftarrow n.used$ \\ -2. If $x.alloc < 2m$ then grow $x$ to $2m$ digits. \\ -3. $\mu \leftarrow 0$ \\ -4. for $i$ from $0$ to $m - 1$ do \\ -\hspace{3mm}4.1 $\hat r \leftarrow k \cdot x_{m+i} + x_{i} + \mu$ \\ -\hspace{3mm}4.2 $x_{i} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}4.3 $\mu \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -5. $x_{m} \leftarrow \mu$ \\ -6. for $i$ from $m + 1$ to $x.used - 1$ do \\ -\hspace{3mm}6.1 $x_{i} \leftarrow 0$ \\ -7. Clamp excess digits of $x$. \\ -8. If $x \ge n$ then \\ -\hspace{3mm}8.1 $x \leftarrow x - n$ \\ -\hspace{3mm}8.2 Goto step 3. \\ -9. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_dr\_reduce} -\end{figure} - -\textbf{Algorithm mp\_dr\_reduce.} -This algorithm will perform the Dimished Radix reduction of $x$ modulo $n$. It has similar restrictions to that of the Barrett reduction -with the addition that $n$ must be of the form $n = \beta^m - k$ where $0 < k <\beta$. - -This algorithm essentially implements the pseudo-code in figure~\ref{fig:DR} except with a slight optimization. The division by $\beta^m$, multiplication by $k$ -and addition of $x \mbox{ mod }\beta^m$ are all performed simultaneously inside the loop on step 4. The division by $\beta^m$ is emulated by accessing -the term at the $m+i$'th position which is subsequently multiplied by $k$ and added to the term at the $i$'th position. After the loop the $m$'th -digit is set to the carry and the upper digits are zeroed. Steps 5 and 6 emulate the reduction modulo $\beta^m$ that should have happend to -$x$ before the addition of the multiple of the upper half. - -At step 8 if $x$ is still larger than $n$ another pass of the algorithm is required. First $n$ is subtracted from $x$ and then the algorithm resumes -at step 3. - -EXAM,bn_mp_dr_reduce.c - -The first step is to grow $x$ as required to $2m$ digits since the reduction is performed in place on $x$. The label on line @49,top:@ is where -the algorithm will resume if further reduction passes are required. In theory it could be placed at the top of the function however, the size of -the modulus and question of whether $x$ is large enough are invariant after the first pass meaning that it would be a waste of time. - -The aliases $tmpx1$ and $tmpx2$ refer to the digits of $x$ where the latter is offset by $m$ digits. By reading digits from $x$ offset by $m$ digits -a division by $\beta^m$ can be simulated virtually for free. The loop on line @61,for@ performs the bulk of the work (\textit{corresponds to step 4 of algorithm 7.11}) -in this algorithm. - -By line @68,mu@ the pointer $tmpx1$ points to the $m$'th digit of $x$ which is where the final carry will be placed. Similarly by line @71,for@ the -same pointer will point to the $m+1$'th digit where the zeroes will be placed. - -Since the algorithm is only valid if both $x$ and $n$ are greater than zero an unsigned comparison suffices to determine if another pass is required. -With the same logic at line @82,sub@ the value of $x$ is known to be greater than or equal to $n$ meaning that an unsigned subtraction can be used -as well. Since the destination of the subtraction is the larger of the inputs the call to algorithm s\_mp\_sub cannot fail and the return code -does not need to be checked. - -\subsubsection{Setup} -To setup the restricted Diminished Radix algorithm the value $k = \beta - n_0$ is required. This algorithm is not really complicated but provided for -completeness. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_dr\_setup}. \\ -\textbf{Input}. mp\_int $n$ \\ -\textbf{Output}. $k = \beta - n_0$ \\ -\hline \\ -1. $k \leftarrow \beta - n_0$ \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_dr\_setup} -\end{figure} - -EXAM,bn_mp_dr_setup.c - -\subsubsection{Modulus Detection} -Another algorithm which will be useful is the ability to detect a restricted Diminished Radix modulus. An integer is said to be -of restricted Diminished Radix form if all of the digits are equal to $\beta - 1$ except the trailing digit which may be any value. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_dr\_is\_modulus}. \\ -\textbf{Input}. mp\_int $n$ \\ -\textbf{Output}. $1$ if $n$ is in D.R form, $0$ otherwise \\ -\hline -1. If $n.used < 2$ then return($0$). \\ -2. for $ix$ from $1$ to $n.used - 1$ do \\ -\hspace{3mm}2.1 If $n_{ix} \ne \beta - 1$ return($0$). \\ -3. Return($1$). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_dr\_is\_modulus} -\end{figure} - -\textbf{Algorithm mp\_dr\_is\_modulus.} -This algorithm determines if a value is in Diminished Radix form. Step 1 rejects obvious cases where fewer than two digits are -in the mp\_int. Step 2 tests all but the first digit to see if they are equal to $\beta - 1$. If the algorithm manages to get to -step 3 then $n$ must be of Diminished Radix form. - -EXAM,bn_mp_dr_is_modulus.c - -\subsection{Unrestricted Diminished Radix Reduction} -The unrestricted Diminished Radix algorithm allows modular reductions to be performed when the modulus is of the form $2^p - k$. This algorithm -is a straightforward adaptation of algorithm~\ref{fig:DR}. - -In general the restricted Diminished Radix reduction algorithm is much faster since it has considerably lower overhead. However, this new -algorithm is much faster than either Montgomery or Barrett reduction when the moduli are of the appropriate form. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_reduce\_2k}. \\ -\textbf{Input}. mp\_int $a$ and $n$. mp\_digit $k$ \\ -\hspace{11.5mm}($a \ge 0$, $n > 1$, $0 < k < \beta$, $n + k$ is a power of two) \\ -\textbf{Output}. $a \mbox{ (mod }n\mbox{)}$ \\ -\hline -1. $p \leftarrow \lceil lg(n) \rceil$ (\textit{mp\_count\_bits}) \\ -2. While $a \ge n$ do \\ -\hspace{3mm}2.1 $q \leftarrow \lfloor a / 2^p \rfloor$ (\textit{mp\_div\_2d}) \\ -\hspace{3mm}2.2 $a \leftarrow a \mbox{ (mod }2^p\mbox{)}$ (\textit{mp\_mod\_2d}) \\ -\hspace{3mm}2.3 $q \leftarrow q \cdot k$ (\textit{mp\_mul\_d}) \\ -\hspace{3mm}2.4 $a \leftarrow a - q$ (\textit{s\_mp\_sub}) \\ -\hspace{3mm}2.5 If $a \ge n$ then do \\ -\hspace{6mm}2.5.1 $a \leftarrow a - n$ \\ -3. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_reduce\_2k} -\end{figure} - -\textbf{Algorithm mp\_reduce\_2k.} -This algorithm quickly reduces an input $a$ modulo an unrestricted Diminished Radix modulus $n$. Division by $2^p$ is emulated with a right -shift which makes the algorithm fairly inexpensive to use. - -EXAM,bn_mp_reduce_2k.c - -The algorithm mp\_count\_bits calculates the number of bits in an mp\_int which is used to find the initial value of $p$. The call to mp\_div\_2d -on line @31,mp_div_2d@ calculates both the quotient $q$ and the remainder $a$ required. By doing both in a single function call the code size -is kept fairly small. The multiplication by $k$ is only performed if $k > 1$. This allows reductions modulo $2^p - 1$ to be performed without -any multiplications. - -The unsigned s\_mp\_add, mp\_cmp\_mag and s\_mp\_sub are used in place of their full sign counterparts since the inputs are only valid if they are -positive. By using the unsigned versions the overhead is kept to a minimum. - -\subsubsection{Unrestricted Setup} -To setup this reduction algorithm the value of $k = 2^p - n$ is required. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_reduce\_2k\_setup}. \\ -\textbf{Input}. mp\_int $n$ \\ -\textbf{Output}. $k = 2^p - n$ \\ -\hline -1. $p \leftarrow \lceil lg(n) \rceil$ (\textit{mp\_count\_bits}) \\ -2. $x \leftarrow 2^p$ (\textit{mp\_2expt}) \\ -3. $x \leftarrow x - n$ (\textit{mp\_sub}) \\ -4. $k \leftarrow x_0$ \\ -5. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_reduce\_2k\_setup} -\end{figure} - -\textbf{Algorithm mp\_reduce\_2k\_setup.} -This algorithm computes the value of $k$ required for the algorithm mp\_reduce\_2k. By making a temporary variable $x$ equal to $2^p$ a subtraction -is sufficient to solve for $k$. Alternatively if $n$ has more than one digit the value of $k$ is simply $\beta - n_0$. - -EXAM,bn_mp_reduce_2k_setup.c - -\subsubsection{Unrestricted Detection} -An integer $n$ is a valid unrestricted Diminished Radix modulus if either of the following are true. - -\begin{enumerate} -\item The number has only one digit. -\item The number has more than one digit and every bit from the $\beta$'th to the most significant is one. -\end{enumerate} - -If either condition is true than there is a power of two $2^p$ such that $0 < 2^p - n < \beta$. If the input is only -one digit than it will always be of the correct form. Otherwise all of the bits above the first digit must be one. This arises from the fact -that there will be value of $k$ that when added to the modulus causes a carry in the first digit which propagates all the way to the most -significant bit. The resulting sum will be a power of two. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_reduce\_is\_2k}. \\ -\textbf{Input}. mp\_int $n$ \\ -\textbf{Output}. $1$ if of proper form, $0$ otherwise \\ -\hline -1. If $n.used = 0$ then return($0$). \\ -2. If $n.used = 1$ then return($1$). \\ -3. $p \leftarrow \lceil lg(n) \rceil$ (\textit{mp\_count\_bits}) \\ -4. for $x$ from $lg(\beta)$ to $p$ do \\ -\hspace{3mm}4.1 If the ($x \mbox{ mod }lg(\beta)$)'th bit of the $\lfloor x / lg(\beta) \rfloor$ of $n$ is zero then return($0$). \\ -5. Return($1$). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_reduce\_is\_2k} -\end{figure} - -\textbf{Algorithm mp\_reduce\_is\_2k.} -This algorithm quickly determines if a modulus is of the form required for algorithm mp\_reduce\_2k to function properly. - -EXAM,bn_mp_reduce_is_2k.c - - - -\section{Algorithm Comparison} -So far three very different algorithms for modular reduction have been discussed. Each of the algorithms have their own strengths and weaknesses -that makes having such a selection very useful. The following table sumarizes the three algorithms along with comparisons of work factors. Since -all three algorithms have the restriction that $0 \le x < n^2$ and $n > 1$ those limitations are not included in the table. - -\begin{center} -\begin{small} -\begin{tabular}{|c|c|c|c|c|c|} -\hline \textbf{Method} & \textbf{Work Required} & \textbf{Limitations} & \textbf{$m = 8$} & \textbf{$m = 32$} & \textbf{$m = 64$} \\ -\hline Barrett & $m^2 + 2m - 1$ & None & $79$ & $1087$ & $4223$ \\ -\hline Montgomery & $m^2 + m$ & $n$ must be odd & $72$ & $1056$ & $4160$ \\ -\hline D.R. & $2m$ & $n = \beta^m - k$ & $16$ & $64$ & $128$ \\ -\hline -\end{tabular} -\end{small} -\end{center} - -In theory Montgomery and Barrett reductions would require roughly the same amount of time to complete. However, in practice since Montgomery -reduction can be written as a single function with the Comba technique it is much faster. Barrett reduction suffers from the overhead of -calling the half precision multipliers, addition and division by $\beta$ algorithms. - -For almost every cryptographic algorithm Montgomery reduction is the algorithm of choice. The one set of algorithms where Diminished Radix reduction truly -shines are based on the discrete logarithm problem such as Diffie-Hellman \cite{DHREF} and ElGamal \cite{ELGAMALREF}. In these algorithms -primes of the form $\beta^m - k$ can be found and shared amongst users. These primes will allow the Diminished Radix algorithm to be used in -modular exponentiation to greatly speed up the operation. - - - -\section*{Exercises} -\begin{tabular}{cl} -$\left [ 3 \right ]$ & Prove that the ``trick'' in algorithm mp\_montgomery\_setup actually \\ - & calculates the correct value of $\rho$. \\ - & \\ -$\left [ 2 \right ]$ & Devise an algorithm to reduce modulo $n + k$ for small $k$ quickly. \\ - & \\ -$\left [ 4 \right ]$ & Prove that the pseudo-code algorithm ``Diminished Radix Reduction'' \\ - & (\textit{figure~\ref{fig:DR}}) terminates. Also prove the probability that it will \\ - & terminate within $1 \le k \le 10$ iterations. \\ - & \\ -\end{tabular} - - -\chapter{Exponentiation} -Exponentiation is the operation of raising one variable to the power of another, for example, $a^b$. A variant of exponentiation, computed -in a finite field or ring, is called modular exponentiation. This latter style of operation is typically used in public key -cryptosystems such as RSA and Diffie-Hellman. The ability to quickly compute modular exponentiations is of great benefit to any -such cryptosystem and many methods have been sought to speed it up. - -\section{Exponentiation Basics} -A trivial algorithm would simply multiply $a$ against itself $b - 1$ times to compute the exponentiation desired. However, as $b$ grows in size -the number of multiplications becomes prohibitive. Imagine what would happen if $b$ $\approx$ $2^{1024}$ as is the case when computing an RSA signature -with a $1024$-bit key. Such a calculation could never be completed as it would take simply far too long. - -Fortunately there is a very simple algorithm based on the laws of exponents. Recall that $lg_a(a^b) = b$ and that $lg_a(a^ba^c) = b + c$ which -are two trivial relationships between the base and the exponent. Let $b_i$ represent the $i$'th bit of $b$ starting from the least -significant bit. If $b$ is a $k$-bit integer than the following equation is true. - -\begin{equation} -a^b = \prod_{i=0}^{k-1} a^{2^i \cdot b_i} -\end{equation} - -By taking the base $a$ logarithm of both sides of the equation the following equation is the result. - -\begin{equation} -b = \sum_{i=0}^{k-1}2^i \cdot b_i -\end{equation} - -The term $a^{2^i}$ can be found from the $i - 1$'th term by squaring the term since $\left ( a^{2^i} \right )^2$ is equal to -$a^{2^{i+1}}$. This observation forms the basis of essentially all fast exponentiation algorithms. It requires $k$ squarings and on average -$k \over 2$ multiplications to compute the result. This is indeed quite an improvement over simply multiplying by $a$ a total of $b-1$ times. - -While this current method is a considerable speed up there are further improvements to be made. For example, the $a^{2^i}$ term does not need to -be computed in an auxilary variable. Consider the following equivalent algorithm. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Left to Right Exponentiation}. \\ -\textbf{Input}. Integer $a$, $b$ and $k$ \\ -\textbf{Output}. $c = a^b$ \\ -\hline \\ -1. $c \leftarrow 1$ \\ -2. for $i$ from $k - 1$ to $0$ do \\ -\hspace{3mm}2.1 $c \leftarrow c^2$ \\ -\hspace{3mm}2.2 $c \leftarrow c \cdot a^{b_i}$ \\ -3. Return $c$. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Left to Right Exponentiation} -\label{fig:LTOR} -\end{figure} - -This algorithm starts from the most significant bit and works towards the least significant bit. When the $i$'th bit of $b$ is set $a$ is -multiplied against the current product. In each iteration the product is squared which doubles the exponent of the individual terms of the -product. - -For example, let $b = 101100_2 \equiv 44_{10}$. The following chart demonstrates the actions of the algorithm. - -\newpage\begin{figure} -\begin{center} -\begin{tabular}{|c|c|} -\hline \textbf{Value of $i$} & \textbf{Value of $c$} \\ -\hline - & $1$ \\ -\hline $5$ & $a$ \\ -\hline $4$ & $a^2$ \\ -\hline $3$ & $a^4 \cdot a$ \\ -\hline $2$ & $a^8 \cdot a^2 \cdot a$ \\ -\hline $1$ & $a^{16} \cdot a^4 \cdot a^2$ \\ -\hline $0$ & $a^{32} \cdot a^8 \cdot a^4$ \\ -\hline -\end{tabular} -\end{center} -\caption{Example of Left to Right Exponentiation} -\end{figure} - -When the product $a^{32} \cdot a^8 \cdot a^4$ is simplified it is equal $a^{44}$ which is the desired exponentiation. This particular algorithm is -called ``Left to Right'' because it reads the exponent in that order. All of the exponentiation algorithms that will be presented are of this nature. - -\subsection{Single Digit Exponentiation} -The first algorithm in the series of exponentiation algorithms will be an unbounded algorithm where the exponent is a single digit. It is intended -to be used when a small power of an input is required (\textit{e.g. $a^5$}). It is faster than simply multiplying $b - 1$ times for all values of -$b$ that are greater than three. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_expt\_d}. \\ -\textbf{Input}. mp\_int $a$ and mp\_digit $b$ \\ -\textbf{Output}. $c = a^b$ \\ -\hline \\ -1. $g \leftarrow a$ (\textit{mp\_init\_copy}) \\ -2. $c \leftarrow 1$ (\textit{mp\_set}) \\ -3. for $x$ from 1 to $lg(\beta)$ do \\ -\hspace{3mm}3.1 $c \leftarrow c^2$ (\textit{mp\_sqr}) \\ -\hspace{3mm}3.2 If $b$ AND $2^{lg(\beta) - 1} \ne 0$ then \\ -\hspace{6mm}3.2.1 $c \leftarrow c \cdot g$ (\textit{mp\_mul}) \\ -\hspace{3mm}3.3 $b \leftarrow b << 1$ \\ -4. Clear $g$. \\ -5. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_expt\_d} -\end{figure} - -\textbf{Algorithm mp\_expt\_d.} -This algorithm computes the value of $a$ raised to the power of a single digit $b$. It uses the left to right exponentiation algorithm to -quickly compute the exponentiation. It is loosely based on algorithm 14.79 of HAC \cite[pp. 615]{HAC} with the difference that the -exponent is a fixed width. - -A copy of $a$ is made first to allow destination variable $c$ be the same as the source variable $a$. The result is set to the initial value of -$1$ in the subsequent step. - -Inside the loop the exponent is read from the most significant bit first down to the least significant bit. First $c$ is invariably squared -on step 3.1. In the following step if the most significant bit of $b$ is one the copy of $a$ is multiplied against $c$. The value -of $b$ is shifted left one bit to make the next bit down from the most signficant bit the new most significant bit. In effect each -iteration of the loop moves the bits of the exponent $b$ upwards to the most significant location. - -EXAM,bn_mp_expt_d_ex.c - -This describes only the algorithm that is used when the parameter $fast$ is $0$. Line @31,mp_set@ sets the initial value of the result to $1$. Next the loop on line @54,for@ steps through each bit of the exponent starting from -the most significant down towards the least significant. The invariant squaring operation placed on line @333,mp_sqr@ is performed first. After -the squaring the result $c$ is multiplied by the base $g$ if and only if the most significant bit of the exponent is set. The shift on line -@69,<<@ moves all of the bits of the exponent upwards towards the most significant location. - -\section{$k$-ary Exponentiation} -When calculating an exponentiation the most time consuming bottleneck is the multiplications which are in general a small factor -slower than squaring. Recall from the previous algorithm that $b_{i}$ refers to the $i$'th bit of the exponent $b$. Suppose instead it referred to -the $i$'th $k$-bit digit of the exponent of $b$. For $k = 1$ the definitions are synonymous and for $k > 1$ algorithm~\ref{fig:KARY} -computes the same exponentiation. A group of $k$ bits from the exponent is called a \textit{window}. That is it is a small window on only a -portion of the entire exponent. Consider the following modification to the basic left to right exponentiation algorithm. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{$k$-ary Exponentiation}. \\ -\textbf{Input}. Integer $a$, $b$, $k$ and $t$ \\ -\textbf{Output}. $c = a^b$ \\ -\hline \\ -1. $c \leftarrow 1$ \\ -2. for $i$ from $t - 1$ to $0$ do \\ -\hspace{3mm}2.1 $c \leftarrow c^{2^k} $ \\ -\hspace{3mm}2.2 Extract the $i$'th $k$-bit word from $b$ and store it in $g$. \\ -\hspace{3mm}2.3 $c \leftarrow c \cdot a^g$ \\ -3. Return $c$. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{$k$-ary Exponentiation} -\label{fig:KARY} -\end{figure} - -The squaring on step 2.1 can be calculated by squaring the value $c$ successively $k$ times. If the values of $a^g$ for $0 < g < 2^k$ have been -precomputed this algorithm requires only $t$ multiplications and $tk$ squarings. The table can be generated with $2^{k - 1} - 1$ squarings and -$2^{k - 1} + 1$ multiplications. This algorithm assumes that the number of bits in the exponent is evenly divisible by $k$. -However, when it is not the remaining $0 < x \le k - 1$ bits can be handled with algorithm~\ref{fig:LTOR}. - -Suppose $k = 4$ and $t = 100$. This modified algorithm will require $109$ multiplications and $408$ squarings to compute the exponentiation. The -original algorithm would on average have required $200$ multiplications and $400$ squrings to compute the same value. The total number of squarings -has increased slightly but the number of multiplications has nearly halved. - -\subsection{Optimal Values of $k$} -An optimal value of $k$ will minimize $2^{k} + \lceil n / k \rceil + n - 1$ for a fixed number of bits in the exponent $n$. The simplest -approach is to brute force search amongst the values $k = 2, 3, \ldots, 8$ for the lowest result. Table~\ref{fig:OPTK} lists optimal values of $k$ -for various exponent sizes and compares the number of multiplication and squarings required against algorithm~\ref{fig:LTOR}. - -\begin{figure}[h] -\begin{center} -\begin{small} -\begin{tabular}{|c|c|c|c|c|c|} -\hline \textbf{Exponent (bits)} & \textbf{Optimal $k$} & \textbf{Work at $k$} & \textbf{Work with ~\ref{fig:LTOR}} \\ -\hline $16$ & $2$ & $27$ & $24$ \\ -\hline $32$ & $3$ & $49$ & $48$ \\ -\hline $64$ & $3$ & $92$ & $96$ \\ -\hline $128$ & $4$ & $175$ & $192$ \\ -\hline $256$ & $4$ & $335$ & $384$ \\ -\hline $512$ & $5$ & $645$ & $768$ \\ -\hline $1024$ & $6$ & $1257$ & $1536$ \\ -\hline $2048$ & $6$ & $2452$ & $3072$ \\ -\hline $4096$ & $7$ & $4808$ & $6144$ \\ -\hline -\end{tabular} -\end{small} -\end{center} -\caption{Optimal Values of $k$ for $k$-ary Exponentiation} -\label{fig:OPTK} -\end{figure} - -\subsection{Sliding-Window Exponentiation} -A simple modification to the previous algorithm is only generate the upper half of the table in the range $2^{k-1} \le g < 2^k$. Essentially -this is a table for all values of $g$ where the most significant bit of $g$ is a one. However, in order for this to be allowed in the -algorithm values of $g$ in the range $0 \le g < 2^{k-1}$ must be avoided. - -Table~\ref{fig:OPTK2} lists optimal values of $k$ for various exponent sizes and compares the work required against algorithm {\ref{fig:KARY}}. - -\begin{figure}[h] -\begin{center} -\begin{small} -\begin{tabular}{|c|c|c|c|c|c|} -\hline \textbf{Exponent (bits)} & \textbf{Optimal $k$} & \textbf{Work at $k$} & \textbf{Work with ~\ref{fig:KARY}} \\ -\hline $16$ & $3$ & $24$ & $27$ \\ -\hline $32$ & $3$ & $45$ & $49$ \\ -\hline $64$ & $4$ & $87$ & $92$ \\ -\hline $128$ & $4$ & $167$ & $175$ \\ -\hline $256$ & $5$ & $322$ & $335$ \\ -\hline $512$ & $6$ & $628$ & $645$ \\ -\hline $1024$ & $6$ & $1225$ & $1257$ \\ -\hline $2048$ & $7$ & $2403$ & $2452$ \\ -\hline $4096$ & $8$ & $4735$ & $4808$ \\ -\hline -\end{tabular} -\end{small} -\end{center} -\caption{Optimal Values of $k$ for Sliding Window Exponentiation} -\label{fig:OPTK2} -\end{figure} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Sliding Window $k$-ary Exponentiation}. \\ -\textbf{Input}. Integer $a$, $b$, $k$ and $t$ \\ -\textbf{Output}. $c = a^b$ \\ -\hline \\ -1. $c \leftarrow 1$ \\ -2. for $i$ from $t - 1$ to $0$ do \\ -\hspace{3mm}2.1 If the $i$'th bit of $b$ is a zero then \\ -\hspace{6mm}2.1.1 $c \leftarrow c^2$ \\ -\hspace{3mm}2.2 else do \\ -\hspace{6mm}2.2.1 $c \leftarrow c^{2^k}$ \\ -\hspace{6mm}2.2.2 Extract the $k$ bits from $(b_{i}b_{i-1}\ldots b_{i-(k-1)})$ and store it in $g$. \\ -\hspace{6mm}2.2.3 $c \leftarrow c \cdot a^g$ \\ -\hspace{6mm}2.2.4 $i \leftarrow i - k$ \\ -3. Return $c$. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Sliding Window $k$-ary Exponentiation} -\end{figure} - -Similar to the previous algorithm this algorithm must have a special handler when fewer than $k$ bits are left in the exponent. While this -algorithm requires the same number of squarings it can potentially have fewer multiplications. The pre-computed table $a^g$ is also half -the size as the previous table. - -Consider the exponent $b = 111101011001000_2 \equiv 31432_{10}$ with $k = 3$ using both algorithms. The first algorithm will divide the exponent up as -the following five $3$-bit words $b \equiv \left ( 111, 101, 011, 001, 000 \right )_{2}$. The second algorithm will break the -exponent as $b \equiv \left ( 111, 101, 0, 110, 0, 100, 0 \right )_{2}$. The single digit $0$ in the second representation are where -a single squaring took place instead of a squaring and multiplication. In total the first method requires $10$ multiplications and $18$ -squarings. The second method requires $8$ multiplications and $18$ squarings. - -In general the sliding window method is never slower than the generic $k$-ary method and often it is slightly faster. - -\section{Modular Exponentiation} - -Modular exponentiation is essentially computing the power of a base within a finite field or ring. For example, computing -$d \equiv a^b \mbox{ (mod }c\mbox{)}$ is a modular exponentiation. Instead of first computing $a^b$ and then reducing it -modulo $c$ the intermediate result is reduced modulo $c$ after every squaring or multiplication operation. - -This guarantees that any intermediate result is bounded by $0 \le d \le c^2 - 2c + 1$ and can be reduced modulo $c$ quickly using -one of the algorithms presented in ~REDUCTION~. - -Before the actual modular exponentiation algorithm can be written a wrapper algorithm must be written first. This algorithm -will allow the exponent $b$ to be negative which is computed as $c \equiv \left (1 / a \right )^{\vert b \vert} \mbox{(mod }d\mbox{)}$. The -value of $(1/a) \mbox{ mod }c$ is computed using the modular inverse (\textit{see \ref{sec:modinv}}). If no inverse exists the algorithm -terminates with an error. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_exptmod}. \\ -\textbf{Input}. mp\_int $a$, $b$ and $c$ \\ -\textbf{Output}. $y \equiv g^x \mbox{ (mod }p\mbox{)}$ \\ -\hline \\ -1. If $c.sign = MP\_NEG$ return(\textit{MP\_VAL}). \\ -2. If $b.sign = MP\_NEG$ then \\ -\hspace{3mm}2.1 $g' \leftarrow g^{-1} \mbox{ (mod }c\mbox{)}$ \\ -\hspace{3mm}2.2 $x' \leftarrow \vert x \vert$ \\ -\hspace{3mm}2.3 Compute $d \equiv g'^{x'} \mbox{ (mod }c\mbox{)}$ via recursion. \\ -3. if $p$ is odd \textbf{OR} $p$ is a D.R. modulus then \\ -\hspace{3mm}3.1 Compute $y \equiv g^{x} \mbox{ (mod }p\mbox{)}$ via algorithm mp\_exptmod\_fast. \\ -4. else \\ -\hspace{3mm}4.1 Compute $y \equiv g^{x} \mbox{ (mod }p\mbox{)}$ via algorithm s\_mp\_exptmod. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_exptmod} -\end{figure} - -\textbf{Algorithm mp\_exptmod.} -The first algorithm which actually performs modular exponentiation is algorithm s\_mp\_exptmod. It is a sliding window $k$-ary algorithm -which uses Barrett reduction to reduce the product modulo $p$. The second algorithm mp\_exptmod\_fast performs the same operation -except it uses either Montgomery or Diminished Radix reduction. The two latter reduction algorithms are clumped in the same exponentiation -algorithm since their arguments are essentially the same (\textit{two mp\_ints and one mp\_digit}). - -EXAM,bn_mp_exptmod.c - -In order to keep the algorithms in a known state the first step on line @29,if@ is to reject any negative modulus as input. If the exponent is -negative the algorithm tries to perform a modular exponentiation with the modular inverse of the base $G$. The temporary variable $tmpG$ is assigned -the modular inverse of $G$ and $tmpX$ is assigned the absolute value of $X$. The algorithm will recuse with these new values with a positive -exponent. - -If the exponent is positive the algorithm resumes the exponentiation. Line @63,dr_@ determines if the modulus is of the restricted Diminished Radix -form. If it is not line @65,reduce@ attempts to determine if it is of a unrestricted Diminished Radix form. The integer $dr$ will take on one -of three values. - -\begin{enumerate} -\item $dr = 0$ means that the modulus is not of either restricted or unrestricted Diminished Radix form. -\item $dr = 1$ means that the modulus is of restricted Diminished Radix form. -\item $dr = 2$ means that the modulus is of unrestricted Diminished Radix form. -\end{enumerate} - -Line @69,if@ determines if the fast modular exponentiation algorithm can be used. It is allowed if $dr \ne 0$ or if the modulus is odd. Otherwise, -the slower s\_mp\_exptmod algorithm is used which uses Barrett reduction. - -\subsection{Barrett Modular Exponentiation} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{s\_mp\_exptmod}. \\ -\textbf{Input}. mp\_int $a$, $b$ and $c$ \\ -\textbf{Output}. $y \equiv g^x \mbox{ (mod }p\mbox{)}$ \\ -\hline \\ -1. $k \leftarrow lg(x)$ \\ -2. $winsize \leftarrow \left \lbrace \begin{array}{ll} - 2 & \mbox{if }k \le 7 \\ - 3 & \mbox{if }7 < k \le 36 \\ - 4 & \mbox{if }36 < k \le 140 \\ - 5 & \mbox{if }140 < k \le 450 \\ - 6 & \mbox{if }450 < k \le 1303 \\ - 7 & \mbox{if }1303 < k \le 3529 \\ - 8 & \mbox{if }3529 < k \\ - \end{array} \right .$ \\ -3. Initialize $2^{winsize}$ mp\_ints in an array named $M$ and one mp\_int named $\mu$ \\ -4. Calculate the $\mu$ required for Barrett Reduction (\textit{mp\_reduce\_setup}). \\ -5. $M_1 \leftarrow g \mbox{ (mod }p\mbox{)}$ \\ -\\ -Setup the table of small powers of $g$. First find $g^{2^{winsize}}$ and then all multiples of it. \\ -6. $k \leftarrow 2^{winsize - 1}$ \\ -7. $M_{k} \leftarrow M_1$ \\ -8. for $ix$ from 0 to $winsize - 2$ do \\ -\hspace{3mm}8.1 $M_k \leftarrow \left ( M_k \right )^2$ (\textit{mp\_sqr}) \\ -\hspace{3mm}8.2 $M_k \leftarrow M_k \mbox{ (mod }p\mbox{)}$ (\textit{mp\_reduce}) \\ -9. for $ix$ from $2^{winsize - 1} + 1$ to $2^{winsize} - 1$ do \\ -\hspace{3mm}9.1 $M_{ix} \leftarrow M_{ix - 1} \cdot M_{1}$ (\textit{mp\_mul}) \\ -\hspace{3mm}9.2 $M_{ix} \leftarrow M_{ix} \mbox{ (mod }p\mbox{)}$ (\textit{mp\_reduce}) \\ -10. $res \leftarrow 1$ \\ -\\ -Start Sliding Window. \\ -11. $mode \leftarrow 0, bitcnt \leftarrow 1, buf \leftarrow 0, digidx \leftarrow x.used - 1, bitcpy \leftarrow 0, bitbuf \leftarrow 0$ \\ -12. Loop \\ -\hspace{3mm}12.1 $bitcnt \leftarrow bitcnt - 1$ \\ -\hspace{3mm}12.2 If $bitcnt = 0$ then do \\ -\hspace{6mm}12.2.1 If $digidx = -1$ goto step 13. \\ -\hspace{6mm}12.2.2 $buf \leftarrow x_{digidx}$ \\ -\hspace{6mm}12.2.3 $digidx \leftarrow digidx - 1$ \\ -\hspace{6mm}12.2.4 $bitcnt \leftarrow lg(\beta)$ \\ -Continued on next page. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm s\_mp\_exptmod} -\end{figure} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{s\_mp\_exptmod} (\textit{continued}). \\ -\textbf{Input}. mp\_int $a$, $b$ and $c$ \\ -\textbf{Output}. $y \equiv g^x \mbox{ (mod }p\mbox{)}$ \\ -\hline \\ -\hspace{3mm}12.3 $y \leftarrow (buf >> (lg(\beta) - 1))$ AND $1$ \\ -\hspace{3mm}12.4 $buf \leftarrow buf << 1$ \\ -\hspace{3mm}12.5 if $mode = 0$ and $y = 0$ then goto step 12. \\ -\hspace{3mm}12.6 if $mode = 1$ and $y = 0$ then do \\ -\hspace{6mm}12.6.1 $res \leftarrow res^2$ \\ -\hspace{6mm}12.6.2 $res \leftarrow res \mbox{ (mod }p\mbox{)}$ \\ -\hspace{6mm}12.6.3 Goto step 12. \\ -\hspace{3mm}12.7 $bitcpy \leftarrow bitcpy + 1$ \\ -\hspace{3mm}12.8 $bitbuf \leftarrow bitbuf + (y << (winsize - bitcpy))$ \\ -\hspace{3mm}12.9 $mode \leftarrow 2$ \\ -\hspace{3mm}12.10 If $bitcpy = winsize$ then do \\ -\hspace{6mm}Window is full so perform the squarings and single multiplication. \\ -\hspace{6mm}12.10.1 for $ix$ from $0$ to $winsize -1$ do \\ -\hspace{9mm}12.10.1.1 $res \leftarrow res^2$ \\ -\hspace{9mm}12.10.1.2 $res \leftarrow res \mbox{ (mod }p\mbox{)}$ \\ -\hspace{6mm}12.10.2 $res \leftarrow res \cdot M_{bitbuf}$ \\ -\hspace{6mm}12.10.3 $res \leftarrow res \mbox{ (mod }p\mbox{)}$ \\ -\hspace{6mm}Reset the window. \\ -\hspace{6mm}12.10.4 $bitcpy \leftarrow 0, bitbuf \leftarrow 0, mode \leftarrow 1$ \\ -\\ -No more windows left. Check for residual bits of exponent. \\ -13. If $mode = 2$ and $bitcpy > 0$ then do \\ -\hspace{3mm}13.1 for $ix$ form $0$ to $bitcpy - 1$ do \\ -\hspace{6mm}13.1.1 $res \leftarrow res^2$ \\ -\hspace{6mm}13.1.2 $res \leftarrow res \mbox{ (mod }p\mbox{)}$ \\ -\hspace{6mm}13.1.3 $bitbuf \leftarrow bitbuf << 1$ \\ -\hspace{6mm}13.1.4 If $bitbuf$ AND $2^{winsize} \ne 0$ then do \\ -\hspace{9mm}13.1.4.1 $res \leftarrow res \cdot M_{1}$ \\ -\hspace{9mm}13.1.4.2 $res \leftarrow res \mbox{ (mod }p\mbox{)}$ \\ -14. $y \leftarrow res$ \\ -15. Clear $res$, $mu$ and the $M$ array. \\ -16. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm s\_mp\_exptmod (continued)} -\end{figure} - -\textbf{Algorithm s\_mp\_exptmod.} -This algorithm computes the $x$'th power of $g$ modulo $p$ and stores the result in $y$. It takes advantage of the Barrett reduction -algorithm to keep the product small throughout the algorithm. - -The first two steps determine the optimal window size based on the number of bits in the exponent. The larger the exponent the -larger the window size becomes. After a window size $winsize$ has been chosen an array of $2^{winsize}$ mp\_int variables is allocated. This -table will hold the values of $g^x \mbox{ (mod }p\mbox{)}$ for $2^{winsize - 1} \le x < 2^{winsize}$. - -After the table is allocated the first power of $g$ is found. Since $g \ge p$ is allowed it must be first reduced modulo $p$ to make -the rest of the algorithm more efficient. The first element of the table at $2^{winsize - 1}$ is found by squaring $M_1$ successively $winsize - 2$ -times. The rest of the table elements are found by multiplying the previous element by $M_1$ modulo $p$. - -Now that the table is available the sliding window may begin. The following list describes the functions of all the variables in the window. -\begin{enumerate} -\item The variable $mode$ dictates how the bits of the exponent are interpreted. -\begin{enumerate} - \item When $mode = 0$ the bits are ignored since no non-zero bit of the exponent has been seen yet. For example, if the exponent were simply - $1$ then there would be $lg(\beta) - 1$ zero bits before the first non-zero bit. In this case bits are ignored until a non-zero bit is found. - \item When $mode = 1$ a non-zero bit has been seen before and a new $winsize$-bit window has not been formed yet. In this mode leading $0$ bits - are read and a single squaring is performed. If a non-zero bit is read a new window is created. - \item When $mode = 2$ the algorithm is in the middle of forming a window and new bits are appended to the window from the most significant bit - downwards. -\end{enumerate} -\item The variable $bitcnt$ indicates how many bits are left in the current digit of the exponent left to be read. When it reaches zero a new digit - is fetched from the exponent. -\item The variable $buf$ holds the currently read digit of the exponent. -\item The variable $digidx$ is an index into the exponents digits. It starts at the leading digit $x.used - 1$ and moves towards the trailing digit. -\item The variable $bitcpy$ indicates how many bits are in the currently formed window. When it reaches $winsize$ the window is flushed and - the appropriate operations performed. -\item The variable $bitbuf$ holds the current bits of the window being formed. -\end{enumerate} - -All of step 12 is the window processing loop. It will iterate while there are digits available form the exponent to read. The first step -inside this loop is to extract a new digit if no more bits are available in the current digit. If there are no bits left a new digit is -read and if there are no digits left than the loop terminates. - -After a digit is made available step 12.3 will extract the most significant bit of the current digit and move all other bits in the digit -upwards. In effect the digit is read from most significant bit to least significant bit and since the digits are read from leading to -trailing edges the entire exponent is read from most significant bit to least significant bit. - -At step 12.5 if the $mode$ and currently extracted bit $y$ are both zero the bit is ignored and the next bit is read. This prevents the -algorithm from having to perform trivial squaring and reduction operations before the first non-zero bit is read. Step 12.6 and 12.7-10 handle -the two cases of $mode = 1$ and $mode = 2$ respectively. - -FIGU,expt_state,Sliding Window State Diagram - -By step 13 there are no more digits left in the exponent. However, there may be partial bits in the window left. If $mode = 2$ then -a Left-to-Right algorithm is used to process the remaining few bits. - -EXAM,bn_s_mp_exptmod.c - -Lines @31,if@ through @45,}@ determine the optimal window size based on the length of the exponent in bits. The window divisions are sorted -from smallest to greatest so that in each \textbf{if} statement only one condition must be tested. For example, by the \textbf{if} statement -on line @37,if@ the value of $x$ is already known to be greater than $140$. - -The conditional piece of code beginning on line @42,ifdef@ allows the window size to be restricted to five bits. This logic is used to ensure -the table of precomputed powers of $G$ remains relatively small. - -The for loop on line @60,for@ initializes the $M$ array while lines @71,mp_init@ and @75,mp_reduce@ through @85,}@ initialize the reduction -function that will be used for this modulus. - --- More later. - -\section{Quick Power of Two} -Calculating $b = 2^a$ can be performed much quicker than with any of the previous algorithms. Recall that a logical shift left $m << k$ is -equivalent to $m \cdot 2^k$. By this logic when $m = 1$ a quick power of two can be achieved. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_2expt}. \\ -\textbf{Input}. integer $b$ \\ -\textbf{Output}. $a \leftarrow 2^b$ \\ -\hline \\ -1. $a \leftarrow 0$ \\ -2. If $a.alloc < \lfloor b / lg(\beta) \rfloor + 1$ then grow $a$ appropriately. \\ -3. $a.used \leftarrow \lfloor b / lg(\beta) \rfloor + 1$ \\ -4. $a_{\lfloor b / lg(\beta) \rfloor} \leftarrow 1 << (b \mbox{ mod } lg(\beta))$ \\ -5. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_2expt} -\end{figure} - -\textbf{Algorithm mp\_2expt.} - -EXAM,bn_mp_2expt.c - -\chapter{Higher Level Algorithms} - -This chapter discusses the various higher level algorithms that are required to complete a well rounded multiple precision integer package. These -routines are less performance oriented than the algorithms of chapters five, six and seven but are no less important. - -The first section describes a method of integer division with remainder that is universally well known. It provides the signed division logic -for the package. The subsequent section discusses a set of algorithms which allow a single digit to be the 2nd operand for a variety of operations. -These algorithms serve mostly to simplify other algorithms where small constants are required. The last two sections discuss how to manipulate -various representations of integers. For example, converting from an mp\_int to a string of character. - -\section{Integer Division with Remainder} -\label{sec:division} - -Integer division aside from modular exponentiation is the most intensive algorithm to compute. Like addition, subtraction and multiplication -the basis of this algorithm is the long-hand division algorithm taught to school children. Throughout this discussion several common variables -will be used. Let $x$ represent the divisor and $y$ represent the dividend. Let $q$ represent the integer quotient $\lfloor y / x \rfloor$ and -let $r$ represent the remainder $r = y - x \lfloor y / x \rfloor$. The following simple algorithm will be used to start the discussion. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Radix-$\beta$ Integer Division}. \\ -\textbf{Input}. integer $x$ and $y$ \\ -\textbf{Output}. $q = \lfloor y/x\rfloor, r = y - xq$ \\ -\hline \\ -1. $q \leftarrow 0$ \\ -2. $n \leftarrow \vert \vert y \vert \vert - \vert \vert x \vert \vert$ \\ -3. for $t$ from $n$ down to $0$ do \\ -\hspace{3mm}3.1 Maximize $k$ such that $kx\beta^t$ is less than or equal to $y$ and $(k + 1)x\beta^t$ is greater. \\ -\hspace{3mm}3.2 $q \leftarrow q + k\beta^t$ \\ -\hspace{3mm}3.3 $y \leftarrow y - kx\beta^t$ \\ -4. $r \leftarrow y$ \\ -5. Return($q, r$) \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Radix-$\beta$ Integer Division} -\label{fig:raddiv} -\end{figure} - -As children we are taught this very simple algorithm for the case of $\beta = 10$. Almost instinctively several optimizations are taught for which -their reason of existing are never explained. For this example let $y = 5471$ represent the dividend and $x = 23$ represent the divisor. - -To find the first digit of the quotient the value of $k$ must be maximized such that $kx\beta^t$ is less than or equal to $y$ and -simultaneously $(k + 1)x\beta^t$ is greater than $y$. Implicitly $k$ is the maximum value the $t$'th digit of the quotient may have. The habitual method -used to find the maximum is to ``eyeball'' the two numbers, typically only the leading digits and quickly estimate a quotient. By only using leading -digits a much simpler division may be used to form an educated guess at what the value must be. In this case $k = \lfloor 54/23\rfloor = 2$ quickly -arises as a possible solution. Indeed $2x\beta^2 = 4600$ is less than $y = 5471$ and simultaneously $(k + 1)x\beta^2 = 6900$ is larger than $y$. -As a result $k\beta^2$ is added to the quotient which now equals $q = 200$ and $4600$ is subtracted from $y$ to give a remainder of $y = 841$. - -Again this process is repeated to produce the quotient digit $k = 3$ which makes the quotient $q = 200 + 3\beta = 230$ and the remainder -$y = 841 - 3x\beta = 181$. Finally the last iteration of the loop produces $k = 7$ which leads to the quotient $q = 230 + 7 = 237$ and the -remainder $y = 181 - 7x = 20$. The final quotient and remainder found are $q = 237$ and $r = y = 20$ which are indeed correct since -$237 \cdot 23 + 20 = 5471$ is true. - -\subsection{Quotient Estimation} -\label{sec:divest} -As alluded to earlier the quotient digit $k$ can be estimated from only the leading digits of both the divisor and dividend. When $p$ leading -digits are used from both the divisor and dividend to form an estimation the accuracy of the estimation rises as $p$ grows. Technically -speaking the estimation is based on assuming the lower $\vert \vert y \vert \vert - p$ and $\vert \vert x \vert \vert - p$ lower digits of the -dividend and divisor are zero. - -The value of the estimation may off by a few values in either direction and in general is fairly correct. A simplification \cite[pp. 271]{TAOCPV2} -of the estimation technique is to use $t + 1$ digits of the dividend and $t$ digits of the divisor, in particularly when $t = 1$. The estimate -using this technique is never too small. For the following proof let $t = \vert \vert y \vert \vert - 1$ and $s = \vert \vert x \vert \vert - 1$ -represent the most significant digits of the dividend and divisor respectively. - -\textbf{Proof.}\textit{ The quotient $\hat k = \lfloor (y_t\beta + y_{t-1}) / x_s \rfloor$ is greater than or equal to -$k = \lfloor y / (x \cdot \beta^{\vert \vert y \vert \vert - \vert \vert x \vert \vert - 1}) \rfloor$. } -The first obvious case is when $\hat k = \beta - 1$ in which case the proof is concluded since the real quotient cannot be larger. For all other -cases $\hat k = \lfloor (y_t\beta + y_{t-1}) / x_s \rfloor$ and $\hat k x_s \ge y_t\beta + y_{t-1} - x_s + 1$. The latter portion of the inequalility -$-x_s + 1$ arises from the fact that a truncated integer division will give the same quotient for at most $x_s - 1$ values. Next a series of -inequalities will prove the hypothesis. - -\begin{equation} -y - \hat k x \le y - \hat k x_s\beta^s -\end{equation} - -This is trivially true since $x \ge x_s\beta^s$. Next we replace $\hat kx_s\beta^s$ by the previous inequality for $\hat kx_s$. - -\begin{equation} -y - \hat k x \le y_t\beta^t + \ldots + y_0 - (y_t\beta^t + y_{t-1}\beta^{t-1} - x_s\beta^t + \beta^s) -\end{equation} - -By simplifying the previous inequality the following inequality is formed. - -\begin{equation} -y - \hat k x \le y_{t-2}\beta^{t-2} + \ldots + y_0 + x_s\beta^s - \beta^s -\end{equation} - -Subsequently, - -\begin{equation} -y_{t-2}\beta^{t-2} + \ldots + y_0 + x_s\beta^s - \beta^s < x_s\beta^s \le x -\end{equation} - -Which proves that $y - \hat kx \le x$ and by consequence $\hat k \ge k$ which concludes the proof. \textbf{QED} - - -\subsection{Normalized Integers} -For the purposes of division a normalized input is when the divisors leading digit $x_n$ is greater than or equal to $\beta / 2$. By multiplying both -$x$ and $y$ by $j = \lfloor (\beta / 2) / x_n \rfloor$ the quotient remains unchanged and the remainder is simply $j$ times the original -remainder. The purpose of normalization is to ensure the leading digit of the divisor is sufficiently large such that the estimated quotient will -lie in the domain of a single digit. Consider the maximum dividend $(\beta - 1) \cdot \beta + (\beta - 1)$ and the minimum divisor $\beta / 2$. - -\begin{equation} -{{\beta^2 - 1} \over { \beta / 2}} \le 2\beta - {2 \over \beta} -\end{equation} - -At most the quotient approaches $2\beta$, however, in practice this will not occur since that would imply the previous quotient digit was too small. - -\subsection{Radix-$\beta$ Division with Remainder} -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_div}. \\ -\textbf{Input}. mp\_int $a, b$ \\ -\textbf{Output}. $c = \lfloor a/b \rfloor$, $d = a - bc$ \\ -\hline \\ -1. If $b = 0$ return(\textit{MP\_VAL}). \\ -2. If $\vert a \vert < \vert b \vert$ then do \\ -\hspace{3mm}2.1 $d \leftarrow a$ \\ -\hspace{3mm}2.2 $c \leftarrow 0$ \\ -\hspace{3mm}2.3 Return(\textit{MP\_OKAY}). \\ -\\ -Setup the quotient to receive the digits. \\ -3. Grow $q$ to $a.used + 2$ digits. \\ -4. $q \leftarrow 0$ \\ -5. $x \leftarrow \vert a \vert , y \leftarrow \vert b \vert$ \\ -6. $sign \leftarrow \left \lbrace \begin{array}{ll} - MP\_ZPOS & \mbox{if }a.sign = b.sign \\ - MP\_NEG & \mbox{otherwise} \\ - \end{array} \right .$ \\ -\\ -Normalize the inputs such that the leading digit of $y$ is greater than or equal to $\beta / 2$. \\ -7. $norm \leftarrow (lg(\beta) - 1) - (\lceil lg(y) \rceil \mbox{ (mod }lg(\beta)\mbox{)})$ \\ -8. $x \leftarrow x \cdot 2^{norm}, y \leftarrow y \cdot 2^{norm}$ \\ -\\ -Find the leading digit of the quotient. \\ -9. $n \leftarrow x.used - 1, t \leftarrow y.used - 1$ \\ -10. $y \leftarrow y \cdot \beta^{n - t}$ \\ -11. While ($x \ge y$) do \\ -\hspace{3mm}11.1 $q_{n - t} \leftarrow q_{n - t} + 1$ \\ -\hspace{3mm}11.2 $x \leftarrow x - y$ \\ -12. $y \leftarrow \lfloor y / \beta^{n-t} \rfloor$ \\ -\\ -Continued on the next page. \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_div} -\end{figure} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_div} (continued). \\ -\textbf{Input}. mp\_int $a, b$ \\ -\textbf{Output}. $c = \lfloor a/b \rfloor$, $d = a - bc$ \\ -\hline \\ -Now find the remainder fo the digits. \\ -13. for $i$ from $n$ down to $(t + 1)$ do \\ -\hspace{3mm}13.1 If $i > x.used$ then jump to the next iteration of this loop. \\ -\hspace{3mm}13.2 If $x_{i} = y_{t}$ then \\ -\hspace{6mm}13.2.1 $q_{i - t - 1} \leftarrow \beta - 1$ \\ -\hspace{3mm}13.3 else \\ -\hspace{6mm}13.3.1 $\hat r \leftarrow x_{i} \cdot \beta + x_{i - 1}$ \\ -\hspace{6mm}13.3.2 $\hat r \leftarrow \lfloor \hat r / y_{t} \rfloor$ \\ -\hspace{6mm}13.3.3 $q_{i - t - 1} \leftarrow \hat r$ \\ -\hspace{3mm}13.4 $q_{i - t - 1} \leftarrow q_{i - t - 1} + 1$ \\ -\\ -Fixup quotient estimation. \\ -\hspace{3mm}13.5 Loop \\ -\hspace{6mm}13.5.1 $q_{i - t - 1} \leftarrow q_{i - t - 1} - 1$ \\ -\hspace{6mm}13.5.2 t$1 \leftarrow 0$ \\ -\hspace{6mm}13.5.3 t$1_0 \leftarrow y_{t - 1}, $ t$1_1 \leftarrow y_t,$ t$1.used \leftarrow 2$ \\ -\hspace{6mm}13.5.4 $t1 \leftarrow t1 \cdot q_{i - t - 1}$ \\ -\hspace{6mm}13.5.5 t$2_0 \leftarrow x_{i - 2}, $ t$2_1 \leftarrow x_{i - 1}, $ t$2_2 \leftarrow x_i, $ t$2.used \leftarrow 3$ \\ -\hspace{6mm}13.5.6 If $\vert t1 \vert > \vert t2 \vert$ then goto step 13.5. \\ -\hspace{3mm}13.6 t$1 \leftarrow y \cdot q_{i - t - 1}$ \\ -\hspace{3mm}13.7 t$1 \leftarrow $ t$1 \cdot \beta^{i - t - 1}$ \\ -\hspace{3mm}13.8 $x \leftarrow x - $ t$1$ \\ -\hspace{3mm}13.9 If $x.sign = MP\_NEG$ then \\ -\hspace{6mm}13.10 t$1 \leftarrow y$ \\ -\hspace{6mm}13.11 t$1 \leftarrow $ t$1 \cdot \beta^{i - t - 1}$ \\ -\hspace{6mm}13.12 $x \leftarrow x + $ t$1$ \\ -\hspace{6mm}13.13 $q_{i - t - 1} \leftarrow q_{i - t - 1} - 1$ \\ -\\ -Finalize the result. \\ -14. Clamp excess digits of $q$ \\ -15. $c \leftarrow q, c.sign \leftarrow sign$ \\ -16. $x.sign \leftarrow a.sign$ \\ -17. $d \leftarrow \lfloor x / 2^{norm} \rfloor$ \\ -18. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_div (continued)} -\end{figure} -\textbf{Algorithm mp\_div.} -This algorithm will calculate quotient and remainder from an integer division given a dividend and divisor. The algorithm is a signed -division and will produce a fully qualified quotient and remainder. - -First the divisor $b$ must be non-zero which is enforced in step one. If the divisor is larger than the dividend than the quotient is implicitly -zero and the remainder is the dividend. - -After the first two trivial cases of inputs are handled the variable $q$ is setup to receive the digits of the quotient. Two unsigned copies of the -divisor $y$ and dividend $x$ are made as well. The core of the division algorithm is an unsigned division and will only work if the values are -positive. Now the two values $x$ and $y$ must be normalized such that the leading digit of $y$ is greater than or equal to $\beta / 2$. -This is performed by shifting both to the left by enough bits to get the desired normalization. - -At this point the division algorithm can begin producing digits of the quotient. Recall that maximum value of the estimation used is -$2\beta - {2 \over \beta}$ which means that a digit of the quotient must be first produced by another means. In this case $y$ is shifted -to the left (\textit{step ten}) so that it has the same number of digits as $x$. The loop on step eleven will subtract multiples of the -shifted copy of $y$ until $x$ is smaller. Since the leading digit of $y$ is greater than or equal to $\beta/2$ this loop will iterate at most two -times to produce the desired leading digit of the quotient. - -Now the remainder of the digits can be produced. The equation $\hat q = \lfloor {{x_i \beta + x_{i-1}}\over y_t} \rfloor$ is used to fairly -accurately approximate the true quotient digit. The estimation can in theory produce an estimation as high as $2\beta - {2 \over \beta}$ but by -induction the upper quotient digit is correct (\textit{as established on step eleven}) and the estimate must be less than $\beta$. - -Recall from section~\ref{sec:divest} that the estimation is never too low but may be too high. The next step of the estimation process is -to refine the estimation. The loop on step 13.5 uses $x_i\beta^2 + x_{i-1}\beta + x_{i-2}$ and $q_{i - t - 1}(y_t\beta + y_{t-1})$ as a higher -order approximation to adjust the quotient digit. - -After both phases of estimation the quotient digit may still be off by a value of one\footnote{This is similar to the error introduced -by optimizing Barrett reduction.}. Steps 13.6 and 13.7 subtract the multiple of the divisor from the dividend (\textit{Similar to step 3.3 of -algorithm~\ref{fig:raddiv}} and then subsequently add a multiple of the divisor if the quotient was too large. - -Now that the quotient has been determine finializing the result is a matter of clamping the quotient, fixing the sizes and de-normalizing the -remainder. An important aspect of this algorithm seemingly overlooked in other descriptions such as that of Algorithm 14.20 HAC \cite[pp. 598]{HAC} -is that when the estimations are being made (\textit{inside the loop on step 13.5}) that the digits $y_{t-1}$, $x_{i-2}$ and $x_{i-1}$ may lie -outside their respective boundaries. For example, if $t = 0$ or $i \le 1$ then the digits would be undefined. In those cases the digits should -respectively be replaced with a zero. - -EXAM,bn_mp_div.c - -The implementation of this algorithm differs slightly from the pseudo code presented previously. In this algorithm either of the quotient $c$ or -remainder $d$ may be passed as a \textbf{NULL} pointer which indicates their value is not desired. For example, the C code to call the division -algorithm with only the quotient is - -\begin{verbatim} -mp_div(&a, &b, &c, NULL); /* c = [a/b] */ -\end{verbatim} - -Lines @108,if@ and @113,if@ handle the two trivial cases of inputs which are division by zero and dividend smaller than the divisor -respectively. After the two trivial cases all of the temporary variables are initialized. Line @147,neg@ determines the sign of -the quotient and line @148,sign@ ensures that both $x$ and $y$ are positive. - -The number of bits in the leading digit is calculated on line @151,norm@. Implictly an mp\_int with $r$ digits will require $lg(\beta)(r-1) + k$ bits -of precision which when reduced modulo $lg(\beta)$ produces the value of $k$. In this case $k$ is the number of bits in the leading digit which is -exactly what is required. For the algorithm to operate $k$ must equal $lg(\beta) - 1$ and when it does not the inputs must be normalized by shifting -them to the left by $lg(\beta) - 1 - k$ bits. - -Throughout the variables $n$ and $t$ will represent the highest digit of $x$ and $y$ respectively. These are first used to produce the -leading digit of the quotient. The loop beginning on line @184,for@ will produce the remainder of the quotient digits. - -The conditional ``continue'' on line @186,continue@ is used to prevent the algorithm from reading past the leading edge of $x$ which can occur when the -algorithm eliminates multiple non-zero digits in a single iteration. This ensures that $x_i$ is always non-zero since by definition the digits -above the $i$'th position $x$ must be zero in order for the quotient to be precise\footnote{Precise as far as integer division is concerned.}. - -Lines @214,t1@, @216,t1@ and @222,t2@ through @225,t2@ manually construct the high accuracy estimations by setting the digits of the two mp\_int -variables directly. - -\section{Single Digit Helpers} - -This section briefly describes a series of single digit helper algorithms which come in handy when working with small constants. All of -the helper functions assume the single digit input is positive and will treat them as such. - -\subsection{Single Digit Addition and Subtraction} - -Both addition and subtraction are performed by ``cheating'' and using mp\_set followed by the higher level addition or subtraction -algorithms. As a result these algorithms are subtantially simpler with a slight cost in performance. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_add\_d}. \\ -\textbf{Input}. mp\_int $a$ and a mp\_digit $b$ \\ -\textbf{Output}. $c = a + b$ \\ -\hline \\ -1. $t \leftarrow b$ (\textit{mp\_set}) \\ -2. $c \leftarrow a + t$ \\ -3. Return(\textit{MP\_OKAY}) \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_add\_d} -\end{figure} - -\textbf{Algorithm mp\_add\_d.} -This algorithm initiates a temporary mp\_int with the value of the single digit and uses algorithm mp\_add to add the two values together. - -EXAM,bn_mp_add_d.c - -Clever use of the letter 't'. - -\subsubsection{Subtraction} -The single digit subtraction algorithm mp\_sub\_d is essentially the same except it uses mp\_sub to subtract the digit from the mp\_int. - -\subsection{Single Digit Multiplication} -Single digit multiplication arises enough in division and radix conversion that it ought to be implement as a special case of the baseline -multiplication algorithm. Essentially this algorithm is a modified version of algorithm s\_mp\_mul\_digs where one of the multiplicands -only has one digit. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_mul\_d}. \\ -\textbf{Input}. mp\_int $a$ and a mp\_digit $b$ \\ -\textbf{Output}. $c = ab$ \\ -\hline \\ -1. $pa \leftarrow a.used$ \\ -2. Grow $c$ to at least $pa + 1$ digits. \\ -3. $oldused \leftarrow c.used$ \\ -4. $c.used \leftarrow pa + 1$ \\ -5. $c.sign \leftarrow a.sign$ \\ -6. $\mu \leftarrow 0$ \\ -7. for $ix$ from $0$ to $pa - 1$ do \\ -\hspace{3mm}7.1 $\hat r \leftarrow \mu + a_{ix}b$ \\ -\hspace{3mm}7.2 $c_{ix} \leftarrow \hat r \mbox{ (mod }\beta\mbox{)}$ \\ -\hspace{3mm}7.3 $\mu \leftarrow \lfloor \hat r / \beta \rfloor$ \\ -8. $c_{pa} \leftarrow \mu$ \\ -9. for $ix$ from $pa + 1$ to $oldused$ do \\ -\hspace{3mm}9.1 $c_{ix} \leftarrow 0$ \\ -10. Clamp excess digits of $c$. \\ -11. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_mul\_d} -\end{figure} -\textbf{Algorithm mp\_mul\_d.} -This algorithm quickly multiplies an mp\_int by a small single digit value. It is specially tailored to the job and has a minimal of overhead. -Unlike the full multiplication algorithms this algorithm does not require any significnat temporary storage or memory allocations. - -EXAM,bn_mp_mul_d.c - -In this implementation the destination $c$ may point to the same mp\_int as the source $a$ since the result is written after the digit is -read from the source. This function uses pointer aliases $tmpa$ and $tmpc$ for the digits of $a$ and $c$ respectively. - -\subsection{Single Digit Division} -Like the single digit multiplication algorithm, single digit division is also a fairly common algorithm used in radix conversion. Since the -divisor is only a single digit a specialized variant of the division algorithm can be used to compute the quotient. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_div\_d}. \\ -\textbf{Input}. mp\_int $a$ and a mp\_digit $b$ \\ -\textbf{Output}. $c = \lfloor a / b \rfloor, d = a - cb$ \\ -\hline \\ -1. If $b = 0$ then return(\textit{MP\_VAL}).\\ -2. If $b = 3$ then use algorithm mp\_div\_3 instead. \\ -3. Init $q$ to $a.used$ digits. \\ -4. $q.used \leftarrow a.used$ \\ -5. $q.sign \leftarrow a.sign$ \\ -6. $\hat w \leftarrow 0$ \\ -7. for $ix$ from $a.used - 1$ down to $0$ do \\ -\hspace{3mm}7.1 $\hat w \leftarrow \hat w \beta + a_{ix}$ \\ -\hspace{3mm}7.2 If $\hat w \ge b$ then \\ -\hspace{6mm}7.2.1 $t \leftarrow \lfloor \hat w / b \rfloor$ \\ -\hspace{6mm}7.2.2 $\hat w \leftarrow \hat w \mbox{ (mod }b\mbox{)}$ \\ -\hspace{3mm}7.3 else\\ -\hspace{6mm}7.3.1 $t \leftarrow 0$ \\ -\hspace{3mm}7.4 $q_{ix} \leftarrow t$ \\ -8. $d \leftarrow \hat w$ \\ -9. Clamp excess digits of $q$. \\ -10. $c \leftarrow q$ \\ -11. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_div\_d} -\end{figure} -\textbf{Algorithm mp\_div\_d.} -This algorithm divides the mp\_int $a$ by the single mp\_digit $b$ using an optimized approach. Essentially in every iteration of the -algorithm another digit of the dividend is reduced and another digit of quotient produced. Provided $b < \beta$ the value of $\hat w$ -after step 7.1 will be limited such that $0 \le \lfloor \hat w / b \rfloor < \beta$. - -If the divisor $b$ is equal to three a variant of this algorithm is used which is called mp\_div\_3. It replaces the division by three with -a multiplication by $\lfloor \beta / 3 \rfloor$ and the appropriate shift and residual fixup. In essence it is much like the Barrett reduction -from chapter seven. - -EXAM,bn_mp_div_d.c - -Like the implementation of algorithm mp\_div this algorithm allows either of the quotient or remainder to be passed as a \textbf{NULL} pointer to -indicate the respective value is not required. This allows a trivial single digit modular reduction algorithm, mp\_mod\_d to be created. - -The division and remainder on lines @90,/@ and @91,-@ can be replaced often by a single division on most processors. For example, the 32-bit x86 based -processors can divide a 64-bit quantity by a 32-bit quantity and produce the quotient and remainder simultaneously. Unfortunately the GCC -compiler does not recognize that optimization and will actually produce two function calls to find the quotient and remainder respectively. - -\subsection{Single Digit Root Extraction} - -Finding the $n$'th root of an integer is fairly easy as far as numerical analysis is concerned. Algorithms such as the Newton-Raphson approximation -(\ref{eqn:newton}) series will converge very quickly to a root for any continuous function $f(x)$. - -\begin{equation} -x_{i+1} = x_i - {f(x_i) \over f'(x_i)} -\label{eqn:newton} -\end{equation} - -In this case the $n$'th root is desired and $f(x) = x^n - a$ where $a$ is the integer of which the root is desired. The derivative of $f(x)$ is -simply $f'(x) = nx^{n - 1}$. Of particular importance is that this algorithm will be used over the integers not over the a more continuous domain -such as the real numbers. As a result the root found can be above the true root by few and must be manually adjusted. Ideally at the end of the -algorithm the $n$'th root $b$ of an integer $a$ is desired such that $b^n \le a$. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_n\_root}. \\ -\textbf{Input}. mp\_int $a$ and a mp\_digit $b$ \\ -\textbf{Output}. $c^b \le a$ \\ -\hline \\ -1. If $b$ is even and $a.sign = MP\_NEG$ return(\textit{MP\_VAL}). \\ -2. $sign \leftarrow a.sign$ \\ -3. $a.sign \leftarrow MP\_ZPOS$ \\ -4. t$2 \leftarrow 2$ \\ -5. Loop \\ -\hspace{3mm}5.1 t$1 \leftarrow $ t$2$ \\ -\hspace{3mm}5.2 t$3 \leftarrow $ t$1^{b - 1}$ \\ -\hspace{3mm}5.3 t$2 \leftarrow $ t$3 $ $\cdot$ t$1$ \\ -\hspace{3mm}5.4 t$2 \leftarrow $ t$2 - a$ \\ -\hspace{3mm}5.5 t$3 \leftarrow $ t$3 \cdot b$ \\ -\hspace{3mm}5.6 t$3 \leftarrow \lfloor $t$2 / $t$3 \rfloor$ \\ -\hspace{3mm}5.7 t$2 \leftarrow $ t$1 - $ t$3$ \\ -\hspace{3mm}5.8 If t$1 \ne $ t$2$ then goto step 5. \\ -6. Loop \\ -\hspace{3mm}6.1 t$2 \leftarrow $ t$1^b$ \\ -\hspace{3mm}6.2 If t$2 > a$ then \\ -\hspace{6mm}6.2.1 t$1 \leftarrow $ t$1 - 1$ \\ -\hspace{6mm}6.2.2 Goto step 6. \\ -7. $a.sign \leftarrow sign$ \\ -8. $c \leftarrow $ t$1$ \\ -9. $c.sign \leftarrow sign$ \\ -10. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_n\_root} -\end{figure} -\textbf{Algorithm mp\_n\_root.} -This algorithm finds the integer $n$'th root of an input using the Newton-Raphson approach. It is partially optimized based on the observation -that the numerator of ${f(x) \over f'(x)}$ can be derived from a partial denominator. That is at first the denominator is calculated by finding -$x^{b - 1}$. This value can then be multiplied by $x$ and have $a$ subtracted from it to find the numerator. This saves a total of $b - 1$ -multiplications by t$1$ inside the loop. - -The initial value of the approximation is t$2 = 2$ which allows the algorithm to start with very small values and quickly converge on the -root. Ideally this algorithm is meant to find the $n$'th root of an input where $n$ is bounded by $2 \le n \le 5$. - -EXAM,bn_mp_n_root.c - -\section{Random Number Generation} - -Random numbers come up in a variety of activities from public key cryptography to simple simulations and various randomized algorithms. Pollard-Rho -factoring for example, can make use of random values as starting points to find factors of a composite integer. In this case the algorithm presented -is solely for simulations and not intended for cryptographic use. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_rand}. \\ -\textbf{Input}. An integer $b$ \\ -\textbf{Output}. A pseudo-random number of $b$ digits \\ -\hline \\ -1. $a \leftarrow 0$ \\ -2. If $b \le 0$ return(\textit{MP\_OKAY}) \\ -3. Pick a non-zero random digit $d$. \\ -4. $a \leftarrow a + d$ \\ -5. for $ix$ from 1 to $d - 1$ do \\ -\hspace{3mm}5.1 $a \leftarrow a \cdot \beta$ \\ -\hspace{3mm}5.2 Pick a random digit $d$. \\ -\hspace{3mm}5.3 $a \leftarrow a + d$ \\ -6. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_rand} -\end{figure} -\textbf{Algorithm mp\_rand.} -This algorithm produces a pseudo-random integer of $b$ digits. By ensuring that the first digit is non-zero the algorithm also guarantees that the -final result has at least $b$ digits. It relies heavily on a third-part random number generator which should ideally generate uniformly all of -the integers from $0$ to $\beta - 1$. - -EXAM,bn_mp_rand.c - -\section{Formatted Representations} -The ability to emit a radix-$n$ textual representation of an integer is useful for interacting with human parties. For example, the ability to -be given a string of characters such as ``114585'' and turn it into the radix-$\beta$ equivalent would make it easier to enter numbers -into a program. - -\subsection{Reading Radix-n Input} -For the purposes of this text we will assume that a simple lower ASCII map (\ref{fig:ASC}) is used for the values of from $0$ to $63$ to -printable characters. For example, when the character ``N'' is read it represents the integer $23$. The first $16$ characters of the -map are for the common representations up to hexadecimal. After that they match the ``base64'' encoding scheme which are suitable chosen -such that they are printable. While outputting as base64 may not be too helpful for human operators it does allow communication via non binary -mediums. - -\newpage\begin{figure}[h] -\begin{center} -\begin{tabular}{cc|cc|cc|cc} -\hline \textbf{Value} & \textbf{Char} & \textbf{Value} & \textbf{Char} & \textbf{Value} & \textbf{Char} & \textbf{Value} & \textbf{Char} \\ -\hline -0 & 0 & 1 & 1 & 2 & 2 & 3 & 3 \\ -4 & 4 & 5 & 5 & 6 & 6 & 7 & 7 \\ -8 & 8 & 9 & 9 & 10 & A & 11 & B \\ -12 & C & 13 & D & 14 & E & 15 & F \\ -16 & G & 17 & H & 18 & I & 19 & J \\ -20 & K & 21 & L & 22 & M & 23 & N \\ -24 & O & 25 & P & 26 & Q & 27 & R \\ -28 & S & 29 & T & 30 & U & 31 & V \\ -32 & W & 33 & X & 34 & Y & 35 & Z \\ -36 & a & 37 & b & 38 & c & 39 & d \\ -40 & e & 41 & f & 42 & g & 43 & h \\ -44 & i & 45 & j & 46 & k & 47 & l \\ -48 & m & 49 & n & 50 & o & 51 & p \\ -52 & q & 53 & r & 54 & s & 55 & t \\ -56 & u & 57 & v & 58 & w & 59 & x \\ -60 & y & 61 & z & 62 & $+$ & 63 & $/$ \\ -\hline -\end{tabular} -\end{center} -\caption{Lower ASCII Map} -\label{fig:ASC} -\end{figure} - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_read\_radix}. \\ -\textbf{Input}. A string $str$ of length $sn$ and radix $r$. \\ -\textbf{Output}. The radix-$\beta$ equivalent mp\_int. \\ -\hline \\ -1. If $r < 2$ or $r > 64$ return(\textit{MP\_VAL}). \\ -2. $ix \leftarrow 0$ \\ -3. If $str_0 =$ ``-'' then do \\ -\hspace{3mm}3.1 $ix \leftarrow ix + 1$ \\ -\hspace{3mm}3.2 $sign \leftarrow MP\_NEG$ \\ -4. else \\ -\hspace{3mm}4.1 $sign \leftarrow MP\_ZPOS$ \\ -5. $a \leftarrow 0$ \\ -6. for $iy$ from $ix$ to $sn - 1$ do \\ -\hspace{3mm}6.1 Let $y$ denote the position in the map of $str_{iy}$. \\ -\hspace{3mm}6.2 If $str_{iy}$ is not in the map or $y \ge r$ then goto step 7. \\ -\hspace{3mm}6.3 $a \leftarrow a \cdot r$ \\ -\hspace{3mm}6.4 $a \leftarrow a + y$ \\ -7. If $a \ne 0$ then $a.sign \leftarrow sign$ \\ -8. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_read\_radix} -\end{figure} -\textbf{Algorithm mp\_read\_radix.} -This algorithm will read an ASCII string and produce the radix-$\beta$ mp\_int representation of the same integer. A minus symbol ``-'' may precede the -string to indicate the value is negative, otherwise it is assumed to be positive. The algorithm will read up to $sn$ characters from the input -and will stop when it reads a character it cannot map the algorithm stops reading characters from the string. This allows numbers to be embedded -as part of larger input without any significant problem. - -EXAM,bn_mp_read_radix.c - -\subsection{Generating Radix-$n$ Output} -Generating radix-$n$ output is fairly trivial with a division and remainder algorithm. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_toradix}. \\ -\textbf{Input}. A mp\_int $a$ and an integer $r$\\ -\textbf{Output}. The radix-$r$ representation of $a$ \\ -\hline \\ -1. If $r < 2$ or $r > 64$ return(\textit{MP\_VAL}). \\ -2. If $a = 0$ then $str = $ ``$0$'' and return(\textit{MP\_OKAY}). \\ -3. $t \leftarrow a$ \\ -4. $str \leftarrow$ ``'' \\ -5. if $t.sign = MP\_NEG$ then \\ -\hspace{3mm}5.1 $str \leftarrow str + $ ``-'' \\ -\hspace{3mm}5.2 $t.sign = MP\_ZPOS$ \\ -6. While ($t \ne 0$) do \\ -\hspace{3mm}6.1 $d \leftarrow t \mbox{ (mod }r\mbox{)}$ \\ -\hspace{3mm}6.2 $t \leftarrow \lfloor t / r \rfloor$ \\ -\hspace{3mm}6.3 Look up $d$ in the map and store the equivalent character in $y$. \\ -\hspace{3mm}6.4 $str \leftarrow str + y$ \\ -7. If $str_0 = $``$-$'' then \\ -\hspace{3mm}7.1 Reverse the digits $str_1, str_2, \ldots str_n$. \\ -8. Otherwise \\ -\hspace{3mm}8.1 Reverse the digits $str_0, str_1, \ldots str_n$. \\ -9. Return(\textit{MP\_OKAY}).\\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_toradix} -\end{figure} -\textbf{Algorithm mp\_toradix.} -This algorithm computes the radix-$r$ representation of an mp\_int $a$. The ``digits'' of the representation are extracted by reducing -successive powers of $\lfloor a / r^k \rfloor$ the input modulo $r$ until $r^k > a$. Note that instead of actually dividing by $r^k$ in -each iteration the quotient $\lfloor a / r \rfloor$ is saved for the next iteration. As a result a series of trivial $n \times 1$ divisions -are required instead of a series of $n \times k$ divisions. One design flaw of this approach is that the digits are produced in the reverse order -(see~\ref{fig:mpradix}). To remedy this flaw the digits must be swapped or simply ``reversed''. - -\begin{figure} -\begin{center} -\begin{tabular}{|c|c|c|} -\hline \textbf{Value of $a$} & \textbf{Value of $d$} & \textbf{Value of $str$} \\ -\hline $1234$ & -- & -- \\ -\hline $123$ & $4$ & ``4'' \\ -\hline $12$ & $3$ & ``43'' \\ -\hline $1$ & $2$ & ``432'' \\ -\hline $0$ & $1$ & ``4321'' \\ -\hline -\end{tabular} -\end{center} -\caption{Example of Algorithm mp\_toradix.} -\label{fig:mpradix} -\end{figure} - -EXAM,bn_mp_toradix.c - -\chapter{Number Theoretic Algorithms} -This chapter discusses several fundamental number theoretic algorithms such as the greatest common divisor, least common multiple and Jacobi -symbol computation. These algorithms arise as essential components in several key cryptographic algorithms such as the RSA public key algorithm and -various Sieve based factoring algorithms. - -\section{Greatest Common Divisor} -The greatest common divisor of two integers $a$ and $b$, often denoted as $(a, b)$ is the largest integer $k$ that is a proper divisor of -both $a$ and $b$. That is, $k$ is the largest integer such that $0 \equiv a \mbox{ (mod }k\mbox{)}$ and $0 \equiv b \mbox{ (mod }k\mbox{)}$ occur -simultaneously. - -The most common approach (cite) is to reduce one input modulo another. That is if $a$ and $b$ are divisible by some integer $k$ and if $qa + r = b$ then -$r$ is also divisible by $k$. The reduction pattern follows $\left < a , b \right > \rightarrow \left < b, a \mbox{ mod } b \right >$. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Greatest Common Divisor (I)}. \\ -\textbf{Input}. Two positive integers $a$ and $b$ greater than zero. \\ -\textbf{Output}. The greatest common divisor $(a, b)$. \\ -\hline \\ -1. While ($b > 0$) do \\ -\hspace{3mm}1.1 $r \leftarrow a \mbox{ (mod }b\mbox{)}$ \\ -\hspace{3mm}1.2 $a \leftarrow b$ \\ -\hspace{3mm}1.3 $b \leftarrow r$ \\ -2. Return($a$). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Greatest Common Divisor (I)} -\label{fig:gcd1} -\end{figure} - -This algorithm will quickly converge on the greatest common divisor since the residue $r$ tends diminish rapidly. However, divisions are -relatively expensive operations to perform and should ideally be avoided. There is another approach based on a similar relationship of -greatest common divisors. The faster approach is based on the observation that if $k$ divides both $a$ and $b$ it will also divide $a - b$. -In particular, we would like $a - b$ to decrease in magnitude which implies that $b \ge a$. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Greatest Common Divisor (II)}. \\ -\textbf{Input}. Two positive integers $a$ and $b$ greater than zero. \\ -\textbf{Output}. The greatest common divisor $(a, b)$. \\ -\hline \\ -1. While ($b > 0$) do \\ -\hspace{3mm}1.1 Swap $a$ and $b$ such that $a$ is the smallest of the two. \\ -\hspace{3mm}1.2 $b \leftarrow b - a$ \\ -2. Return($a$). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Greatest Common Divisor (II)} -\label{fig:gcd2} -\end{figure} - -\textbf{Proof} \textit{Algorithm~\ref{fig:gcd2} will return the greatest common divisor of $a$ and $b$.} -The algorithm in figure~\ref{fig:gcd2} will eventually terminate since $b \ge a$ the subtraction in step 1.2 will be a value less than $b$. In other -words in every iteration that tuple $\left < a, b \right >$ decrease in magnitude until eventually $a = b$. Since both $a$ and $b$ are always -divisible by the greatest common divisor (\textit{until the last iteration}) and in the last iteration of the algorithm $b = 0$, therefore, in the -second to last iteration of the algorithm $b = a$ and clearly $(a, a) = a$ which concludes the proof. \textbf{QED}. - -As a matter of practicality algorithm \ref{fig:gcd1} decreases far too slowly to be useful. Specially if $b$ is much larger than $a$ such that -$b - a$ is still very much larger than $a$. A simple addition to the algorithm is to divide $b - a$ by a power of some integer $p$ which does -not divide the greatest common divisor but will divide $b - a$. In this case ${b - a} \over p$ is also an integer and still divisible by -the greatest common divisor. - -However, instead of factoring $b - a$ to find a suitable value of $p$ the powers of $p$ can be removed from $a$ and $b$ that are in common first. -Then inside the loop whenever $b - a$ is divisible by some power of $p$ it can be safely removed. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{Greatest Common Divisor (III)}. \\ -\textbf{Input}. Two positive integers $a$ and $b$ greater than zero. \\ -\textbf{Output}. The greatest common divisor $(a, b)$. \\ -\hline \\ -1. $k \leftarrow 0$ \\ -2. While $a$ and $b$ are both divisible by $p$ do \\ -\hspace{3mm}2.1 $a \leftarrow \lfloor a / p \rfloor$ \\ -\hspace{3mm}2.2 $b \leftarrow \lfloor b / p \rfloor$ \\ -\hspace{3mm}2.3 $k \leftarrow k + 1$ \\ -3. While $a$ is divisible by $p$ do \\ -\hspace{3mm}3.1 $a \leftarrow \lfloor a / p \rfloor$ \\ -4. While $b$ is divisible by $p$ do \\ -\hspace{3mm}4.1 $b \leftarrow \lfloor b / p \rfloor$ \\ -5. While ($b > 0$) do \\ -\hspace{3mm}5.1 Swap $a$ and $b$ such that $a$ is the smallest of the two. \\ -\hspace{3mm}5.2 $b \leftarrow b - a$ \\ -\hspace{3mm}5.3 While $b$ is divisible by $p$ do \\ -\hspace{6mm}5.3.1 $b \leftarrow \lfloor b / p \rfloor$ \\ -6. Return($a \cdot p^k$). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm Greatest Common Divisor (III)} -\label{fig:gcd3} -\end{figure} - -This algorithm is based on the first except it removes powers of $p$ first and inside the main loop to ensure the tuple $\left < a, b \right >$ -decreases more rapidly. The first loop on step two removes powers of $p$ that are in common. A count, $k$, is kept which will present a common -divisor of $p^k$. After step two the remaining common divisor of $a$ and $b$ cannot be divisible by $p$. This means that $p$ can be safely -divided out of the difference $b - a$ so long as the division leaves no remainder. - -In particular the value of $p$ should be chosen such that the division on step 5.3.1 occur often. It also helps that division by $p$ be easy -to compute. The ideal choice of $p$ is two since division by two amounts to a right logical shift. Another important observation is that by -step five both $a$ and $b$ are odd. Therefore, the diffrence $b - a$ must be even which means that each iteration removes one bit from the -largest of the pair. - -\subsection{Complete Greatest Common Divisor} -The algorithms presented so far cannot handle inputs which are zero or negative. The following algorithm can handle all input cases properly -and will produce the greatest common divisor. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_gcd}. \\ -\textbf{Input}. mp\_int $a$ and $b$ \\ -\textbf{Output}. The greatest common divisor $c = (a, b)$. \\ -\hline \\ -1. If $a = 0$ then \\ -\hspace{3mm}1.1 $c \leftarrow \vert b \vert $ \\ -\hspace{3mm}1.2 Return(\textit{MP\_OKAY}). \\ -2. If $b = 0$ then \\ -\hspace{3mm}2.1 $c \leftarrow \vert a \vert $ \\ -\hspace{3mm}2.2 Return(\textit{MP\_OKAY}). \\ -3. $u \leftarrow \vert a \vert, v \leftarrow \vert b \vert$ \\ -4. $k \leftarrow 0$ \\ -5. While $u.used > 0$ and $v.used > 0$ and $u_0 \equiv v_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}5.1 $k \leftarrow k + 1$ \\ -\hspace{3mm}5.2 $u \leftarrow \lfloor u / 2 \rfloor$ \\ -\hspace{3mm}5.3 $v \leftarrow \lfloor v / 2 \rfloor$ \\ -6. While $u.used > 0$ and $u_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}6.1 $u \leftarrow \lfloor u / 2 \rfloor$ \\ -7. While $v.used > 0$ and $v_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}7.1 $v \leftarrow \lfloor v / 2 \rfloor$ \\ -8. While $v.used > 0$ \\ -\hspace{3mm}8.1 If $\vert u \vert > \vert v \vert$ then \\ -\hspace{6mm}8.1.1 Swap $u$ and $v$. \\ -\hspace{3mm}8.2 $v \leftarrow \vert v \vert - \vert u \vert$ \\ -\hspace{3mm}8.3 While $v.used > 0$ and $v_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{6mm}8.3.1 $v \leftarrow \lfloor v / 2 \rfloor$ \\ -9. $c \leftarrow u \cdot 2^k$ \\ -10. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_gcd} -\end{figure} -\textbf{Algorithm mp\_gcd.} -This algorithm will produce the greatest common divisor of two mp\_ints $a$ and $b$. The algorithm was originally based on Algorithm B of -Knuth \cite[pp. 338]{TAOCPV2} but has been modified to be simpler to explain. In theory it achieves the same asymptotic working time as -Algorithm B and in practice this appears to be true. - -The first two steps handle the cases where either one of or both inputs are zero. If either input is zero the greatest common divisor is the -largest input or zero if they are both zero. If the inputs are not trivial than $u$ and $v$ are assigned the absolute values of -$a$ and $b$ respectively and the algorithm will proceed to reduce the pair. - -Step five will divide out any common factors of two and keep track of the count in the variable $k$. After this step, two is no longer a -factor of the remaining greatest common divisor between $u$ and $v$ and can be safely evenly divided out of either whenever they are even. Step -six and seven ensure that the $u$ and $v$ respectively have no more factors of two. At most only one of the while--loops will iterate since -they cannot both be even. - -By step eight both of $u$ and $v$ are odd which is required for the inner logic. First the pair are swapped such that $v$ is equal to -or greater than $u$. This ensures that the subtraction on step 8.2 will always produce a positive and even result. Step 8.3 removes any -factors of two from the difference $u$ to ensure that in the next iteration of the loop both are once again odd. - -After $v = 0$ occurs the variable $u$ has the greatest common divisor of the pair $\left < u, v \right >$ just after step six. The result -must be adjusted by multiplying by the common factors of two ($2^k$) removed earlier. - -EXAM,bn_mp_gcd.c - -This function makes use of the macros mp\_iszero and mp\_iseven. The former evaluates to $1$ if the input mp\_int is equivalent to the -integer zero otherwise it evaluates to $0$. The latter evaluates to $1$ if the input mp\_int represents a non-zero even integer otherwise -it evaluates to $0$. Note that just because mp\_iseven may evaluate to $0$ does not mean the input is odd, it could also be zero. The three -trivial cases of inputs are handled on lines @23,zero@ through @29,}@. After those lines the inputs are assumed to be non-zero. - -Lines @32,if@ and @36,if@ make local copies $u$ and $v$ of the inputs $a$ and $b$ respectively. At this point the common factors of two -must be divided out of the two inputs. The block starting at line @43,common@ removes common factors of two by first counting the number of trailing -zero bits in both. The local integer $k$ is used to keep track of how many factors of $2$ are pulled out of both values. It is assumed that -the number of factors will not exceed the maximum value of a C ``int'' data type\footnote{Strictly speaking no array in C may have more than -entries than are accessible by an ``int'' so this is not a limitation.}. - -At this point there are no more common factors of two in the two values. The divisions by a power of two on lines @60,div_2d@ and @67,div_2d@ remove -any independent factors of two such that both $u$ and $v$ are guaranteed to be an odd integer before hitting the main body of the algorithm. The while loop -on line @72, while@ performs the reduction of the pair until $v$ is equal to zero. The unsigned comparison and subtraction algorithms are used in -place of the full signed routines since both values are guaranteed to be positive and the result of the subtraction is guaranteed to be non-negative. - -\section{Least Common Multiple} -The least common multiple of a pair of integers is their product divided by their greatest common divisor. For two integers $a$ and $b$ the -least common multiple is normally denoted as $[ a, b ]$ and numerically equivalent to ${ab} \over {(a, b)}$. For example, if $a = 2 \cdot 2 \cdot 3 = 12$ -and $b = 2 \cdot 3 \cdot 3 \cdot 7 = 126$ the least common multiple is ${126 \over {(12, 126)}} = {126 \over 6} = 21$. - -The least common multiple arises often in coding theory as well as number theory. If two functions have periods of $a$ and $b$ respectively they will -collide, that is be in synchronous states, after only $[ a, b ]$ iterations. This is why, for example, random number generators based on -Linear Feedback Shift Registers (LFSR) tend to use registers with periods which are co-prime (\textit{e.g. the greatest common divisor is one.}). -Similarly in number theory if a composite $n$ has two prime factors $p$ and $q$ then maximal order of any unit of $\Z/n\Z$ will be $[ p - 1, q - 1] $. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_lcm}. \\ -\textbf{Input}. mp\_int $a$ and $b$ \\ -\textbf{Output}. The least common multiple $c = [a, b]$. \\ -\hline \\ -1. $c \leftarrow (a, b)$ \\ -2. $t \leftarrow a \cdot b$ \\ -3. $c \leftarrow \lfloor t / c \rfloor$ \\ -4. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_lcm} -\end{figure} -\textbf{Algorithm mp\_lcm.} -This algorithm computes the least common multiple of two mp\_int inputs $a$ and $b$. It computes the least common multiple directly by -dividing the product of the two inputs by their greatest common divisor. - -EXAM,bn_mp_lcm.c - -\section{Jacobi Symbol Computation} -To explain the Jacobi Symbol we shall first discuss the Legendre function\footnote{Arrg. What is the name of this?} off which the Jacobi symbol is -defined. The Legendre function computes whether or not an integer $a$ is a quadratic residue modulo an odd prime $p$. Numerically it is -equivalent to equation \ref{eqn:legendre}. - -\textit{-- Tom, don't be an ass, cite your source here...!} - -\begin{equation} -a^{(p-1)/2} \equiv \begin{array}{rl} - -1 & \mbox{if }a\mbox{ is a quadratic non-residue.} \\ - 0 & \mbox{if }a\mbox{ divides }p\mbox{.} \\ - 1 & \mbox{if }a\mbox{ is a quadratic residue}. - \end{array} \mbox{ (mod }p\mbox{)} -\label{eqn:legendre} -\end{equation} - -\textbf{Proof.} \textit{Equation \ref{eqn:legendre} correctly identifies the residue status of an integer $a$ modulo a prime $p$.} -An integer $a$ is a quadratic residue if the following equation has a solution. - -\begin{equation} -x^2 \equiv a \mbox{ (mod }p\mbox{)} -\label{eqn:root} -\end{equation} - -Consider the following equation. - -\begin{equation} -0 \equiv x^{p-1} - 1 \equiv \left \lbrace \left (x^2 \right )^{(p-1)/2} - a^{(p-1)/2} \right \rbrace + \left ( a^{(p-1)/2} - 1 \right ) \mbox{ (mod }p\mbox{)} -\label{eqn:rooti} -\end{equation} - -Whether equation \ref{eqn:root} has a solution or not equation \ref{eqn:rooti} is always true. If $a^{(p-1)/2} - 1 \equiv 0 \mbox{ (mod }p\mbox{)}$ -then the quantity in the braces must be zero. By reduction, - -\begin{eqnarray} -\left (x^2 \right )^{(p-1)/2} - a^{(p-1)/2} \equiv 0 \nonumber \\ -\left (x^2 \right )^{(p-1)/2} \equiv a^{(p-1)/2} \nonumber \\ -x^2 \equiv a \mbox{ (mod }p\mbox{)} -\end{eqnarray} - -As a result there must be a solution to the quadratic equation and in turn $a$ must be a quadratic residue. If $a$ does not divide $p$ and $a$ -is not a quadratic residue then the only other value $a^{(p-1)/2}$ may be congruent to is $-1$ since -\begin{equation} -0 \equiv a^{p - 1} - 1 \equiv (a^{(p-1)/2} + 1)(a^{(p-1)/2} - 1) \mbox{ (mod }p\mbox{)} -\end{equation} -One of the terms on the right hand side must be zero. \textbf{QED} - -\subsection{Jacobi Symbol} -The Jacobi symbol is a generalization of the Legendre function for any odd non prime moduli $p$ greater than 2. If $p = \prod_{i=0}^n p_i$ then -the Jacobi symbol $\left ( { a \over p } \right )$ is equal to the following equation. - -\begin{equation} -\left ( { a \over p } \right ) = \left ( { a \over p_0} \right ) \left ( { a \over p_1} \right ) \ldots \left ( { a \over p_n} \right ) -\end{equation} - -By inspection if $p$ is prime the Jacobi symbol is equivalent to the Legendre function. The following facts\footnote{See HAC \cite[pp. 72-74]{HAC} for -further details.} will be used to derive an efficient Jacobi symbol algorithm. Where $p$ is an odd integer greater than two and $a, b \in \Z$ the -following are true. - -\begin{enumerate} -\item $\left ( { a \over p} \right )$ equals $-1$, $0$ or $1$. -\item $\left ( { ab \over p} \right ) = \left ( { a \over p} \right )\left ( { b \over p} \right )$. -\item If $a \equiv b$ then $\left ( { a \over p} \right ) = \left ( { b \over p} \right )$. -\item $\left ( { 2 \over p} \right )$ equals $1$ if $p \equiv 1$ or $7 \mbox{ (mod }8\mbox{)}$. Otherwise, it equals $-1$. -\item $\left ( { a \over p} \right ) \equiv \left ( { p \over a} \right ) \cdot (-1)^{(p-1)(a-1)/4}$. More specifically -$\left ( { a \over p} \right ) = \left ( { p \over a} \right )$ if $p \equiv a \equiv 1 \mbox{ (mod }4\mbox{)}$. -\end{enumerate} - -Using these facts if $a = 2^k \cdot a'$ then - -\begin{eqnarray} -\left ( { a \over p } \right ) = \left ( {{2^k} \over p } \right ) \left ( {a' \over p} \right ) \nonumber \\ - = \left ( {2 \over p } \right )^k \left ( {a' \over p} \right ) -\label{eqn:jacobi} -\end{eqnarray} - -By fact five, - -\begin{equation} -\left ( { a \over p } \right ) = \left ( { p \over a } \right ) \cdot (-1)^{(p-1)(a-1)/4} -\end{equation} - -Subsequently by fact three since $p \equiv (p \mbox{ mod }a) \mbox{ (mod }a\mbox{)}$ then - -\begin{equation} -\left ( { a \over p } \right ) = \left ( { {p \mbox{ mod } a} \over a } \right ) \cdot (-1)^{(p-1)(a-1)/4} -\end{equation} - -By putting both observations into equation \ref{eqn:jacobi} the following simplified equation is formed. - -\begin{equation} -\left ( { a \over p } \right ) = \left ( {2 \over p } \right )^k \left ( {{p\mbox{ mod }a'} \over a'} \right ) \cdot (-1)^{(p-1)(a'-1)/4} -\end{equation} - -The value of $\left ( {{p \mbox{ mod }a'} \over a'} \right )$ can be found by using the same equation recursively. The value of -$\left ( {2 \over p } \right )^k$ equals $1$ if $k$ is even otherwise it equals $\left ( {2 \over p } \right )$. Using this approach the -factors of $p$ do not have to be known. Furthermore, if $(a, p) = 1$ then the algorithm will terminate when the recursion requests the -Jacobi symbol computation of $\left ( {1 \over a'} \right )$ which is simply $1$. - -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_jacobi}. \\ -\textbf{Input}. mp\_int $a$ and $p$, $a \ge 0$, $p \ge 3$, $p \equiv 1 \mbox{ (mod }2\mbox{)}$ \\ -\textbf{Output}. The Jacobi symbol $c = \left ( {a \over p } \right )$. \\ -\hline \\ -1. If $a = 0$ then \\ -\hspace{3mm}1.1 $c \leftarrow 0$ \\ -\hspace{3mm}1.2 Return(\textit{MP\_OKAY}). \\ -2. If $a = 1$ then \\ -\hspace{3mm}2.1 $c \leftarrow 1$ \\ -\hspace{3mm}2.2 Return(\textit{MP\_OKAY}). \\ -3. $a' \leftarrow a$ \\ -4. $k \leftarrow 0$ \\ -5. While $a'.used > 0$ and $a'_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}5.1 $k \leftarrow k + 1$ \\ -\hspace{3mm}5.2 $a' \leftarrow \lfloor a' / 2 \rfloor$ \\ -6. If $k \equiv 0 \mbox{ (mod }2\mbox{)}$ then \\ -\hspace{3mm}6.1 $s \leftarrow 1$ \\ -7. else \\ -\hspace{3mm}7.1 $r \leftarrow p_0 \mbox{ (mod }8\mbox{)}$ \\ -\hspace{3mm}7.2 If $r = 1$ or $r = 7$ then \\ -\hspace{6mm}7.2.1 $s \leftarrow 1$ \\ -\hspace{3mm}7.3 else \\ -\hspace{6mm}7.3.1 $s \leftarrow -1$ \\ -8. If $p_0 \equiv a'_0 \equiv 3 \mbox{ (mod }4\mbox{)}$ then \\ -\hspace{3mm}8.1 $s \leftarrow -s$ \\ -9. If $a' \ne 1$ then \\ -\hspace{3mm}9.1 $p' \leftarrow p \mbox{ (mod }a'\mbox{)}$ \\ -\hspace{3mm}9.2 $s \leftarrow s \cdot \mbox{mp\_jacobi}(p', a')$ \\ -10. $c \leftarrow s$ \\ -11. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_jacobi} -\end{figure} -\textbf{Algorithm mp\_jacobi.} -This algorithm computes the Jacobi symbol for an arbitrary positive integer $a$ with respect to an odd integer $p$ greater than three. The algorithm -is based on algorithm 2.149 of HAC \cite[pp. 73]{HAC}. - -Step numbers one and two handle the trivial cases of $a = 0$ and $a = 1$ respectively. Step five determines the number of two factors in the -input $a$. If $k$ is even than the term $\left ( { 2 \over p } \right )^k$ must always evaluate to one. If $k$ is odd than the term evaluates to one -if $p_0$ is congruent to one or seven modulo eight, otherwise it evaluates to $-1$. After the the $\left ( { 2 \over p } \right )^k$ term is handled -the $(-1)^{(p-1)(a'-1)/4}$ is computed and multiplied against the current product $s$. The latter term evaluates to one if both $p$ and $a'$ -are congruent to one modulo four, otherwise it evaluates to negative one. - -By step nine if $a'$ does not equal one a recursion is required. Step 9.1 computes $p' \equiv p \mbox{ (mod }a'\mbox{)}$ and will recurse to compute -$\left ( {p' \over a'} \right )$ which is multiplied against the current Jacobi product. - -EXAM,bn_mp_jacobi.c - -As a matter of practicality the variable $a'$ as per the pseudo-code is reprensented by the variable $a1$ since the $'$ symbol is not valid for a C -variable name character. - -The two simple cases of $a = 0$ and $a = 1$ are handled at the very beginning to simplify the algorithm. If the input is non-trivial the algorithm -has to proceed compute the Jacobi. The variable $s$ is used to hold the current Jacobi product. Note that $s$ is merely a C ``int'' data type since -the values it may obtain are merely $-1$, $0$ and $1$. - -After a local copy of $a$ is made all of the factors of two are divided out and the total stored in $k$. Technically only the least significant -bit of $k$ is required, however, it makes the algorithm simpler to follow to perform an addition. In practice an exclusive-or and addition have the same -processor requirements and neither is faster than the other. - -Line @59, if@ through @70, }@ determines the value of $\left ( { 2 \over p } \right )^k$. If the least significant bit of $k$ is zero than -$k$ is even and the value is one. Otherwise, the value of $s$ depends on which residue class $p$ belongs to modulo eight. The value of -$(-1)^{(p-1)(a'-1)/4}$ is compute and multiplied against $s$ on lines @73, if@ through @75, }@. - -Finally, if $a1$ does not equal one the algorithm must recurse and compute $\left ( {p' \over a'} \right )$. - -\textit{-- Comment about default $s$ and such...} - -\section{Modular Inverse} -\label{sec:modinv} -The modular inverse of a number actually refers to the modular multiplicative inverse. Essentially for any integer $a$ such that $(a, p) = 1$ there -exist another integer $b$ such that $ab \equiv 1 \mbox{ (mod }p\mbox{)}$. The integer $b$ is called the multiplicative inverse of $a$ which is -denoted as $b = a^{-1}$. Technically speaking modular inversion is a well defined operation for any finite ring or field not just for rings and -fields of integers. However, the former will be the matter of discussion. - -The simplest approach is to compute the algebraic inverse of the input. That is to compute $b \equiv a^{\Phi(p) - 1}$. If $\Phi(p)$ is the -order of the multiplicative subgroup modulo $p$ then $b$ must be the multiplicative inverse of $a$. The proof of which is trivial. - -\begin{equation} -ab \equiv a \left (a^{\Phi(p) - 1} \right ) \equiv a^{\Phi(p)} \equiv a^0 \equiv 1 \mbox{ (mod }p\mbox{)} -\end{equation} - -However, as simple as this approach may be it has two serious flaws. It requires that the value of $\Phi(p)$ be known which if $p$ is composite -requires all of the prime factors. This approach also is very slow as the size of $p$ grows. - -A simpler approach is based on the observation that solving for the multiplicative inverse is equivalent to solving the linear -Diophantine\footnote{See LeVeque \cite[pp. 40-43]{LeVeque} for more information.} equation. - -\begin{equation} -ab + pq = 1 -\end{equation} - -Where $a$, $b$, $p$ and $q$ are all integers. If such a pair of integers $ \left < b, q \right >$ exist than $b$ is the multiplicative inverse of -$a$ modulo $p$. The extended Euclidean algorithm (Knuth \cite[pp. 342]{TAOCPV2}) can be used to solve such equations provided $(a, p) = 1$. -However, instead of using that algorithm directly a variant known as the binary Extended Euclidean algorithm will be used in its place. The -binary approach is very similar to the binary greatest common divisor algorithm except it will produce a full solution to the Diophantine -equation. - -\subsection{General Case} -\newpage\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_invmod}. \\ -\textbf{Input}. mp\_int $a$ and $b$, $(a, b) = 1$, $p \ge 2$, $0 < a < p$. \\ -\textbf{Output}. The modular inverse $c \equiv a^{-1} \mbox{ (mod }b\mbox{)}$. \\ -\hline \\ -1. If $b \le 0$ then return(\textit{MP\_VAL}). \\ -2. If $b_0 \equiv 1 \mbox{ (mod }2\mbox{)}$ then use algorithm fast\_mp\_invmod. \\ -3. $x \leftarrow \vert a \vert, y \leftarrow b$ \\ -4. If $x_0 \equiv y_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ then return(\textit{MP\_VAL}). \\ -5. $B \leftarrow 0, C \leftarrow 0, A \leftarrow 1, D \leftarrow 1$ \\ -6. While $u.used > 0$ and $u_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}6.1 $u \leftarrow \lfloor u / 2 \rfloor$ \\ -\hspace{3mm}6.2 If ($A.used > 0$ and $A_0 \equiv 1 \mbox{ (mod }2\mbox{)}$) or ($B.used > 0$ and $B_0 \equiv 1 \mbox{ (mod }2\mbox{)}$) then \\ -\hspace{6mm}6.2.1 $A \leftarrow A + y$ \\ -\hspace{6mm}6.2.2 $B \leftarrow B - x$ \\ -\hspace{3mm}6.3 $A \leftarrow \lfloor A / 2 \rfloor$ \\ -\hspace{3mm}6.4 $B \leftarrow \lfloor B / 2 \rfloor$ \\ -7. While $v.used > 0$ and $v_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}7.1 $v \leftarrow \lfloor v / 2 \rfloor$ \\ -\hspace{3mm}7.2 If ($C.used > 0$ and $C_0 \equiv 1 \mbox{ (mod }2\mbox{)}$) or ($D.used > 0$ and $D_0 \equiv 1 \mbox{ (mod }2\mbox{)}$) then \\ -\hspace{6mm}7.2.1 $C \leftarrow C + y$ \\ -\hspace{6mm}7.2.2 $D \leftarrow D - x$ \\ -\hspace{3mm}7.3 $C \leftarrow \lfloor C / 2 \rfloor$ \\ -\hspace{3mm}7.4 $D \leftarrow \lfloor D / 2 \rfloor$ \\ -8. If $u \ge v$ then \\ -\hspace{3mm}8.1 $u \leftarrow u - v$ \\ -\hspace{3mm}8.2 $A \leftarrow A - C$ \\ -\hspace{3mm}8.3 $B \leftarrow B - D$ \\ -9. else \\ -\hspace{3mm}9.1 $v \leftarrow v - u$ \\ -\hspace{3mm}9.2 $C \leftarrow C - A$ \\ -\hspace{3mm}9.3 $D \leftarrow D - B$ \\ -10. If $u \ne 0$ goto step 6. \\ -11. If $v \ne 1$ return(\textit{MP\_VAL}). \\ -12. While $C \le 0$ do \\ -\hspace{3mm}12.1 $C \leftarrow C + b$ \\ -13. While $C \ge b$ do \\ -\hspace{3mm}13.1 $C \leftarrow C - b$ \\ -14. $c \leftarrow C$ \\ -15. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\end{figure} -\textbf{Algorithm mp\_invmod.} -This algorithm computes the modular multiplicative inverse of an integer $a$ modulo an integer $b$. This algorithm is a variation of the -extended binary Euclidean algorithm from HAC \cite[pp. 608]{HAC}. It has been modified to only compute the modular inverse and not a complete -Diophantine solution. - -If $b \le 0$ than the modulus is invalid and MP\_VAL is returned. Similarly if both $a$ and $b$ are even then there cannot be a multiplicative -inverse for $a$ and the error is reported. - -The astute reader will observe that steps seven through nine are very similar to the binary greatest common divisor algorithm mp\_gcd. In this case -the other variables to the Diophantine equation are solved. The algorithm terminates when $u = 0$ in which case the solution is - -\begin{equation} -Ca + Db = v -\end{equation} - -If $v$, the greatest common divisor of $a$ and $b$ is not equal to one then the algorithm will report an error as no inverse exists. Otherwise, $C$ -is the modular inverse of $a$. The actual value of $C$ is congruent to, but not necessarily equal to, the ideal modular inverse which should lie -within $1 \le a^{-1} < b$. Step numbers twelve and thirteen adjust the inverse until it is in range. If the original input $a$ is within $0 < a < p$ -then only a couple of additions or subtractions will be required to adjust the inverse. - -EXAM,bn_mp_invmod.c - -\subsubsection{Odd Moduli} - -When the modulus $b$ is odd the variables $A$ and $C$ are fixed and are not required to compute the inverse. In particular by attempting to solve -the Diophantine $Cb + Da = 1$ only $B$ and $D$ are required to find the inverse of $a$. - -The algorithm fast\_mp\_invmod is a direct adaptation of algorithm mp\_invmod with all all steps involving either $A$ or $C$ removed. This -optimization will halve the time required to compute the modular inverse. - -\section{Primality Tests} - -A non-zero integer $a$ is said to be prime if it is not divisible by any other integer excluding one and itself. For example, $a = 7$ is prime -since the integers $2 \ldots 6$ do not evenly divide $a$. By contrast, $a = 6$ is not prime since $a = 6 = 2 \cdot 3$. - -Prime numbers arise in cryptography considerably as they allow finite fields to be formed. The ability to determine whether an integer is prime or -not quickly has been a viable subject in cryptography and number theory for considerable time. The algorithms that will be presented are all -probablistic algorithms in that when they report an integer is composite it must be composite. However, when the algorithms report an integer is -prime the algorithm may be incorrect. - -As will be discussed it is possible to limit the probability of error so well that for practical purposes the probablity of error might as -well be zero. For the purposes of these discussions let $n$ represent the candidate integer of which the primality is in question. - -\subsection{Trial Division} - -Trial division means to attempt to evenly divide a candidate integer by small prime integers. If the candidate can be evenly divided it obviously -cannot be prime. By dividing by all primes $1 < p \le \sqrt{n}$ this test can actually prove whether an integer is prime. However, such a test -would require a prohibitive amount of time as $n$ grows. - -Instead of dividing by every prime, a smaller, more mangeable set of primes may be used instead. By performing trial division with only a subset -of the primes less than $\sqrt{n} + 1$ the algorithm cannot prove if a candidate is prime. However, often it can prove a candidate is not prime. - -The benefit of this test is that trial division by small values is fairly efficient. Specially compared to the other algorithms that will be -discussed shortly. The probability that this approach correctly identifies a composite candidate when tested with all primes upto $q$ is given by -$1 - {1.12 \over ln(q)}$. The graph (\ref{pic:primality}) demonstrates the probability of success for the range $3 \le q \le 100$. - -FIGU,primality,Probability of successful trial division to detect non-primes - -At approximately $q = 30$ the gain of performing further tests diminishes fairly quickly. At $q = 90$ further testing is generally not going to -be of any practical use. In the case of LibTomMath the default limit $q = 256$ was chosen since it is not too high and will eliminate -approximately $80\%$ of all candidate integers. The constant \textbf{PRIME\_SIZE} is equal to the number of primes in the test base. The -array \_\_prime\_tab is an array of the first \textbf{PRIME\_SIZE} prime numbers. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_prime\_is\_divisible}. \\ -\textbf{Input}. mp\_int $a$ \\ -\textbf{Output}. $c = 1$ if $n$ is divisible by a small prime, otherwise $c = 0$. \\ -\hline \\ -1. for $ix$ from $0$ to $PRIME\_SIZE$ do \\ -\hspace{3mm}1.1 $d \leftarrow n \mbox{ (mod }\_\_prime\_tab_{ix}\mbox{)}$ \\ -\hspace{3mm}1.2 If $d = 0$ then \\ -\hspace{6mm}1.2.1 $c \leftarrow 1$ \\ -\hspace{6mm}1.2.2 Return(\textit{MP\_OKAY}). \\ -2. $c \leftarrow 0$ \\ -3. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_prime\_is\_divisible} -\end{figure} -\textbf{Algorithm mp\_prime\_is\_divisible.} -This algorithm attempts to determine if a candidate integer $n$ is composite by performing trial divisions. - -EXAM,bn_mp_prime_is_divisible.c - -The algorithm defaults to a return of $0$ in case an error occurs. The values in the prime table are all specified to be in the range of a -mp\_digit. The table \_\_prime\_tab is defined in the following file. - -EXAM,bn_prime_tab.c - -Note that there are two possible tables. When an mp\_digit is 7-bits long only the primes upto $127$ may be included, otherwise the primes -upto $1619$ are used. Note that the value of \textbf{PRIME\_SIZE} is a constant dependent on the size of a mp\_digit. - -\subsection{The Fermat Test} -The Fermat test is probably one the oldest tests to have a non-trivial probability of success. It is based on the fact that if $n$ is in -fact prime then $a^{n} \equiv a \mbox{ (mod }n\mbox{)}$ for all $0 < a < n$. The reason being that if $n$ is prime than the order of -the multiplicative sub group is $n - 1$. Any base $a$ must have an order which divides $n - 1$ and as such $a^n$ is equivalent to -$a^1 = a$. - -If $n$ is composite then any given base $a$ does not have to have a period which divides $n - 1$. In which case -it is possible that $a^n \nequiv a \mbox{ (mod }n\mbox{)}$. However, this test is not absolute as it is possible that the order -of a base will divide $n - 1$ which would then be reported as prime. Such a base yields what is known as a Fermat pseudo-prime. Several -integers known as Carmichael numbers will be a pseudo-prime to all valid bases. Fortunately such numbers are extremely rare as $n$ grows -in size. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_prime\_fermat}. \\ -\textbf{Input}. mp\_int $a$ and $b$, $a \ge 2$, $0 < b < a$. \\ -\textbf{Output}. $c = 1$ if $b^a \equiv b \mbox{ (mod }a\mbox{)}$, otherwise $c = 0$. \\ -\hline \\ -1. $t \leftarrow b^a \mbox{ (mod }a\mbox{)}$ \\ -2. If $t = b$ then \\ -\hspace{3mm}2.1 $c = 1$ \\ -3. else \\ -\hspace{3mm}3.1 $c = 0$ \\ -4. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_prime\_fermat} -\end{figure} -\textbf{Algorithm mp\_prime\_fermat.} -This algorithm determines whether an mp\_int $a$ is a Fermat prime to the base $b$ or not. It uses a single modular exponentiation to -determine the result. - -EXAM,bn_mp_prime_fermat.c - -\subsection{The Miller-Rabin Test} -The Miller-Rabin (citation) test is another primality test which has tighter error bounds than the Fermat test specifically with sequentially chosen -candidate integers. The algorithm is based on the observation that if $n - 1 = 2^kr$ and if $b^r \nequiv \pm 1$ then after upto $k - 1$ squarings the -value must be equal to $-1$. The squarings are stopped as soon as $-1$ is observed. If the value of $1$ is observed first it means that -some value not congruent to $\pm 1$ when squared equals one which cannot occur if $n$ is prime. - -\begin{figure}[!h] -\begin{small} -\begin{center} -\begin{tabular}{l} -\hline Algorithm \textbf{mp\_prime\_miller\_rabin}. \\ -\textbf{Input}. mp\_int $a$ and $b$, $a \ge 2$, $0 < b < a$. \\ -\textbf{Output}. $c = 1$ if $a$ is a Miller-Rabin prime to the base $a$, otherwise $c = 0$. \\ -\hline -1. $a' \leftarrow a - 1$ \\ -2. $r \leftarrow n1$ \\ -3. $c \leftarrow 0, s \leftarrow 0$ \\ -4. While $r.used > 0$ and $r_0 \equiv 0 \mbox{ (mod }2\mbox{)}$ \\ -\hspace{3mm}4.1 $s \leftarrow s + 1$ \\ -\hspace{3mm}4.2 $r \leftarrow \lfloor r / 2 \rfloor$ \\ -5. $y \leftarrow b^r \mbox{ (mod }a\mbox{)}$ \\ -6. If $y \nequiv \pm 1$ then \\ -\hspace{3mm}6.1 $j \leftarrow 1$ \\ -\hspace{3mm}6.2 While $j \le (s - 1)$ and $y \nequiv a'$ \\ -\hspace{6mm}6.2.1 $y \leftarrow y^2 \mbox{ (mod }a\mbox{)}$ \\ -\hspace{6mm}6.2.2 If $y = 1$ then goto step 8. \\ -\hspace{6mm}6.2.3 $j \leftarrow j + 1$ \\ -\hspace{3mm}6.3 If $y \nequiv a'$ goto step 8. \\ -7. $c \leftarrow 1$\\ -8. Return(\textit{MP\_OKAY}). \\ -\hline -\end{tabular} -\end{center} -\end{small} -\caption{Algorithm mp\_prime\_miller\_rabin} -\end{figure} -\textbf{Algorithm mp\_prime\_miller\_rabin.} -This algorithm performs one trial round of the Miller-Rabin algorithm to the base $b$. It will set $c = 1$ if the algorithm cannot determine -if $b$ is composite or $c = 0$ if $b$ is provably composite. The values of $s$ and $r$ are computed such that $a' = a - 1 = 2^sr$. - -If the value $y \equiv b^r$ is congruent to $\pm 1$ then the algorithm cannot prove if $a$ is composite or not. Otherwise, the algorithm will -square $y$ upto $s - 1$ times stopping only when $y \equiv -1$. If $y^2 \equiv 1$ and $y \nequiv \pm 1$ then the algorithm can report that $a$ -is provably composite. If the algorithm performs $s - 1$ squarings and $y \nequiv -1$ then $a$ is provably composite. If $a$ is not provably -composite then it is \textit{probably} prime. - -EXAM,bn_mp_prime_miller_rabin.c - - - - -\backmatter -\appendix -\begin{thebibliography}{ABCDEF} -\bibitem[1]{TAOCPV2} -Donald Knuth, \textit{The Art of Computer Programming}, Third Edition, Volume Two, Seminumerical Algorithms, Addison-Wesley, 1998 - -\bibitem[2]{HAC} -A. Menezes, P. van Oorschot, S. Vanstone, \textit{Handbook of Applied Cryptography}, CRC Press, 1996 - -\bibitem[3]{ROSE} -Michael Rosing, \textit{Implementing Elliptic Curve Cryptography}, Manning Publications, 1999 - -\bibitem[4]{COMBA} -Paul G. Comba, \textit{Exponentiation Cryptosystems on the IBM PC}. IBM Systems Journal 29(4): 526-538 (1990) - -\bibitem[5]{KARA} -A. Karatsuba, Doklay Akad. Nauk SSSR 145 (1962), pp.293-294 - -\bibitem[6]{KARAP} -Andre Weimerskirch and Christof Paar, \textit{Generalizations of the Karatsuba Algorithm for Polynomial Multiplication}, Submitted to Design, Codes and Cryptography, March 2002 - -\bibitem[7]{BARRETT} -Paul Barrett, \textit{Implementing the Rivest Shamir and Adleman Public Key Encryption Algorithm on a Standard Digital Signal Processor}, Advances in Cryptology, Crypto '86, Springer-Verlag. - -\bibitem[8]{MONT} -P.L.Montgomery. \textit{Modular multiplication without trial division}. Mathematics of Computation, 44(170):519-521, April 1985. - -\bibitem[9]{DRMET} -Chae Hoon Lim and Pil Joong Lee, \textit{Generating Efficient Primes for Discrete Log Cryptosystems}, POSTECH Information Research Laboratories - -\bibitem[10]{MMB} -J. Daemen and R. Govaerts and J. Vandewalle, \textit{Block ciphers based on Modular Arithmetic}, State and {P}rogress in the {R}esearch of {C}ryptography, 1993, pp. 80-89 - -\bibitem[11]{RSAREF} -R.L. Rivest, A. Shamir, L. Adleman, \textit{A Method for Obtaining Digital Signatures and Public-Key Cryptosystems} - -\bibitem[12]{DHREF} -Whitfield Diffie, Martin E. Hellman, \textit{New Directions in Cryptography}, IEEE Transactions on Information Theory, 1976 - -\bibitem[13]{IEEE} -IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985) - -\bibitem[14]{GMP} -GNU Multiple Precision (GMP), \url{http://www.swox.com/gmp/} - -\bibitem[15]{MPI} -Multiple Precision Integer Library (MPI), Michael Fromberger, \url{http://thayer.dartmouth.edu/~sting/mpi/} - -\bibitem[16]{OPENSSL} -OpenSSL Cryptographic Toolkit, \url{http://openssl.org} - -\bibitem[17]{LIP} -Large Integer Package, \url{http://home.hetnet.nl/~ecstr/LIP.zip} - -\bibitem[18]{ISOC} -JTC1/SC22/WG14, ISO/IEC 9899:1999, ``A draft rationale for the C99 standard.'' - -\bibitem[19]{JAVA} -The Sun Java Website, \url{http://java.sun.com/} - -\bibitem[20]{LeVeque} -William LeVeque, \textit{Fundamentals of Number Theory}, Dover Publications, 2014 - -\bibitem[21]{ELGAMALREF} -T. Elgamal, \textit{A public key cryptosystem and a signature scheme based on discrete logarithms}, {IEEE} Transactions on Information Theory, 1985, pp. 469-472 - -\bibitem[22]{TOOM} -D. Knuth, \textit{The Art of Computer Programming; Volume 2. Third Edition}, Addison-Wesley, 1997, pg. 294 - -\bibitem[23]{POSIX1} -The Open Group, \url{http://www.opengroup.org/austin/papers/posix_faq.html}, 2017 - -\end{thebibliography} - -\input{tommath.ind} - -\end{document} diff --git a/makefile b/makefile index df296de..aa104c6 100644 --- a/makefile +++ b/makefile @@ -123,7 +123,7 @@ tune: $(LIBNAME) coveralls: lcov coveralls-lcov -docdvi poster docs mandvi manual: +poster docs manual: $(MAKE) -C doc/ $@ V=$(V) .PHONY: pre_gen @@ -133,7 +133,7 @@ pre_gen: sed -e 's/[[:blank:]]*$$//' mpi.c > pre_gen/mpi.c rm mpi.c -zipup: clean astyle new_file manual poster +zipup: clean astyle new_file docs @# Update the index, so diff-index won't fail in case the pdf has been created. @# As the pdf creation modifies the tex files, git sometimes detects the @# modified files, but misses that it's put back to its original version. From c917f3c39121100dac22a182d7587f12d7ebc05c Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sun, 20 Oct 2019 18:27:56 +0200 Subject: [PATCH 16/20] also remove poster --- doc/makefile | 20 ++------------------ doc/pics/design_process.sxd | Bin 6950 -> 0 bytes doc/pics/design_process.tif | Bin 79042 -> 0 bytes doc/pics/expt_state.sxd | Bin 6869 -> 0 bytes doc/pics/expt_state.tif | Bin 87542 -> 0 bytes doc/pics/makefile | 35 ----------------------------------- doc/pics/primality.tif | Bin 85514 -> 0 bytes doc/pics/radix.sxd | Bin 6181 -> 0 bytes doc/pics/sliding_window.sxd | Bin 6787 -> 0 bytes doc/pics/sliding_window.tif | Bin 53880 -> 0 bytes doc/poster.tex | 35 ----------------------------------- makefile | 2 +- 12 files changed, 3 insertions(+), 89 deletions(-) delete mode 100644 doc/pics/design_process.sxd delete mode 100644 doc/pics/design_process.tif delete mode 100644 doc/pics/expt_state.sxd delete mode 100644 doc/pics/expt_state.tif delete mode 100644 doc/pics/makefile delete mode 100644 doc/pics/primality.tif delete mode 100644 doc/pics/radix.sxd delete mode 100644 doc/pics/sliding_window.sxd delete mode 100644 doc/pics/sliding_window.tif delete mode 100644 doc/poster.tex diff --git a/doc/makefile b/doc/makefile index 7eeb1f9..2c7978f 100644 --- a/doc/makefile +++ b/doc/makefile @@ -9,26 +9,10 @@ ifeq ($(PLATFORM), Darwin) err: $(error Docs can't be built on Mac) -poster docs mandvi manual: err +docs mandvi manual: err endif -docs: poster manual - -# poster, makes the single page PDF poster -poster: poster.tex - cp poster.tex poster.bak - touch --reference=poster.tex poster.bak - (printf "%s" "\def\fixedpdfdate{"; date +'D:%Y%m%d%H%M%S%:z' -d @$$(stat --format=%Y poster.tex) | sed "s/:\([0-9][0-9]\)$$/'\1'}/g") > poster-deterministic.tex - printf "%s\n" "\pdfinfo{" >> poster-deterministic.tex - printf "%s\n" " /CreationDate (\fixedpdfdate)" >> poster-deterministic.tex - printf "%s\n}\n" " /ModDate (\fixedpdfdate)" >> poster-deterministic.tex - cat poster.tex >> poster-deterministic.tex - mv poster-deterministic.tex poster.tex - touch --reference=poster.bak poster.tex - pdflatex poster - sed -b -i 's,^/ID \[.*\]$$,/ID [<0> <0>],g' poster.pdf - mv poster.bak poster.tex - rm -f poster.aux poster.log poster.out +docs: manual #LTM user manual mandvi: bn.tex diff --git a/doc/pics/design_process.sxd b/doc/pics/design_process.sxd deleted file mode 100644 index 7414dbb27696fe716fe8c73a5c2b21d8c3e0c23c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6950 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 diff --git a/doc/pics/design_process.tif b/doc/pics/design_process.tif deleted file mode 100644 index 4a0c012d565ecd12a43186f132b3bccdefb9a23e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 79042 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 diff --git a/doc/pics/expt_state.sxd b/doc/pics/expt_state.sxd deleted file mode 100644 index 6518404d5fa6eca01b4457a813f85cda074c0915..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6869 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 YjJ7)dxd~WU_~#EhHWpUWwTse!03-Pj!~g&Q diff --git a/doc/pics/expt_state.tif b/doc/pics/expt_state.tif deleted file mode 100644 index cb06e8edf17017dec815be222c845f1b0a938e07..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 87542 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≦RYV{r={iMn(Ta_rSwB@dOoKkT7uoB zm>DX9w4o@~>(T4B6{=OK>K|NB_%L#N5_JJ$;s!Q}qJxUPIv=G3bmrL^6**GGA-Da^ zCB;W@?#|o}7gXp1E%T~qJTaVw0a<51tcNsB*noTLp+>XomZ1Ci_CA7uD{ibGLLbrc zT5N_{Zw1xom9I4Oe+VzQ2k5ll zA-%4~x&F@$@1$Lx7H*QE4ps;-706f=e)ER!+<0`&_7;vu*;d5e1Hdmg$Ck3Xz9$sC zT>ES{8$3`HsFZJ6Uks3y*oEzf$AQ*8vU5r+r>OaZO5$V<)eAq!DSxli{Vj1eh?-@R zM7k^F;Y|5aSD@rah|h1E#LmpZ{%oA72Ak^saDSUZe9flmts$QgjZS-A>rwtj1TI?h zJ^0)V-fJB_dBC+fRKDKg8^@9qC

Gz?-?J@iV6)5~XACr^a8KN7>Cj@YUK!?WXXd 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 design_process.ps - -sliding_window.ps: sliding_window.tif - tiff2ps -s -e sliding_window.tif > sliding_window.ps - -expt_state.ps: expt_state.tif - tiff2ps -s -e expt_state.tif > expt_state.ps - -primality.ps: primality.tif - tiff2ps -s -e primality.tif > primality.ps - -design_process.pdf: design_process.ps - epstopdf design_process.ps - -sliding_window.pdf: sliding_window.ps - epstopdf sliding_window.ps - -expt_state.pdf: expt_state.ps - epstopdf expt_state.ps - -primality.pdf: primality.ps - epstopdf primality.ps - - -pses: sliding_window.ps expt_state.ps primality.ps design_process.ps -pdfes: sliding_window.pdf expt_state.pdf primality.pdf design_process.pdf - -clean: - rm -rf *.ps *.pdf .xvpics - \ No newline at end of file diff --git a/doc/pics/primality.tif b/doc/pics/primality.tif deleted file mode 100644 index 76d6be3fac2cc8b07a401e008fbe45f02758cef7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 85514 zcmeFZRah0;+CK^^U801v0@5WZEg=Zf-7x8x(%m5-QX<{m-3)Yg(G-|bNcFfXxtH3FJq^Y}jV#6*b(^zI+roeq3Tz;vagq(XCO?@>S931?x zFyM1H5$uO{{|{2*$@~93_xtlz_y7O;{~0$((cpa`q?%a#gKC9UO-=LfKDKXeni`zZ zneh;>*+^!Oc=x}5|NcS)qGT@(HsR?zQqqnny~i`Wb@HPf%1%4!u{MyHY{SmZPE&8H zs;sQM#_7|NqGMC2WX2wUVH`R46pYeYWQD$J9l1K*7|{-}mAx*Sn5%an;dgJSu8tls zELWXU?7ci(d5=T0es%>H4<dAQIWb81 z3bykM?6?wLi;j+ty!%g_Z=#D8|K4KE;F`sJgVW8W9hc96qeh8`kS}6vbckS*H|?y@%s#_% ztzw6;ceqm${cA_wOIur8{ofm1&dT1_q1)Kll$SkU*aGy{`n5q?rXnLFy)^_TWmF%7 z;hvvOCdFeVD0ULc%ga~3_wVtq$rg~jA zJ~lSC5MW+SVCZdNg3WZ`NBuZtg=GcY}VjDJU z75_~jD!k89g2UcC5qT1?OVq%xyZ41NJGV)Q2yG2bP3}qM&CS}XU-lY3?)XSP*x0b3 zV6TpkE454w8%OwxuN@T^78WYvJOW!x(FH6oDlXP;bUra7r3(oS4Gjs=YI1doKn%3d z8jq984o|SJzfmV8L}j@)yI4X%KnU!?Zg9I|@5MGOpXyt4K3#p(@v8Gq0NN0;hbtyT;90HBuY`_)xr?g&=3I0(PPP9Z^1)K6!x>}V9EDq|)$GU~s& z?%5>ip@>ab=jGM&)#cxwHQ$|l(Ow0gz2>`HX*@#L>vJn7Cno~~gIZK{czF2bH6U<) zx65Pj^+|xR)Z@VR<%zrVrO=WdI3;CeyV{>i2Q_pPH&k)Wn;VR3P>3>8-IPaQKeGdsJJqqV_&gOHGr(ZR^%goFxFh`PG^ zl?=SEcWAqAaZiK$4ZgdfVOEDj`BVWzI+r7@gnOQfqwW_l6q_FSul8c9H zV0(KTY~83gC^&fR+&ooA25!{X?ci7Y5%cD^6Jzc7V%Z~QUu|kNbi|(iMa+xD?_FJ8 zH7U)_{M&?6DA?@Mql%LZ3=DvbCjlQ1&s_yP7iiGLZ`kpJr_)Pb@LyeBxl}J(bJ`}X z(>FFYRyHRMt{I4t@HpL7tVBWoTryH&>s1y}xfc z$ytU=15L`wFCii#a>ErS4O5|Gw?b(ua&M}wMbf5;+?Jh`%N?Df&(6-K4u`Uql?dB8+O` z!JIK`-nhDaZ*fa#aBy&xEP?=f5QFc|^0M$Md6%YSA!&SnURU1Z^rbB>uf1tgq%hsm zoO*&c2oY%5N!7D0OZf1w%DPh?)#{2v}?z(BU9OU^vHR)RKW*z0E0cYRxQhJKtX%P8U5g7=_)v8>^4%k(QL~#?a8x zQp+z%OiH4#;N;^I;s258*;%8!RA0li;UE~9{0ixCwI#D8Q;s?|T!jutMXEq>2b%AV z66!~jZ=kD7x{Yd2bm6My|1cpTp~e~QP6wCA$jC?xR)hr)b3j6fGP<{W3+va)CY!>f zH-cU?VUM4`zkzVg6YKq-Qi>sZHNN4P0i8<_qmnJENO7^JeG&#T-m~aIR7~7oFk5)u zihM+ofWr`>!NZhLw|$+Jo&B4%wBqg0MuSPRe@Oc!>WfxrW@@@wt=`eunYkRojduYn zfl#10d3tsR5U#qaDx&k|n@X(q1q-X%up%D4Ex-Gi1=%@0(r( zIvu5wm9ul64~jM&jzQ&q4>nJ&hLniDg@v@pqa=?}^dujjhj?Wg9tx;z$mlF-f-;@rw&wxW}jpPK3g@U?x>?;%2V-F-Z6m#ifTDsa0m^(%k6 zODmz6pWbub%FT_Q?C|2qNVzz*6^92vRG2^u6O~V^5x*dU!_P~ahfVG`c~^m4KLK4w z8zYocW&n;2gm>ra?}ZcsBs?WKFgR$y;dF6maBo+@5`z%YLF`9Xk2Dd3oMf@k)cpw+ z9lht%en9R|PHyh-xku%k6DPd)G6SJq^xQHqGlfZaOaSaPM|kYM&f=0cs-`9;Vono* z*L>Jj5)?Kz@3|5gZ~_mjV?y(Js2cceqNk~iQKdfl%d@$j&z=zF_%12pENJ6somHyrnrj>g= zEY7!;gKR-_N~Ykk*-^mMoPVbN0H#Kxf#L}MYw9Y$)YjDi?z1OjeS?EbhH^WOX$@Nf z%*n_EyK(m56u0_SFk!2K$2gAjjX&{MV)hb4u7y zf&Z+*stP6Hztu7X#1lzKNCY8kI9ve^^!H0jPytFMcTzkZEm zOXFGq%VcYEcXqC${>FA@5UX6Q)iNo36a(+G}_WFD_jy$|u z1Ca^W@o>4jwY4>z*)H3H9v~ZV$iqWS`n9I-_1kq1T7@Iu;nKe=^hBOX{9C-%e{0TP zYW0_d(C$Nm3)kB&atpb7KC7bz#%BZs^^`Gjae0Z(@3E`G!=I`$NZc9Jes0$d-V-6k z)Xeenf<1Sks3h4jV^Emf1seL-R8e3mAnbb``%6RbHNjT~V)hJZKNU_O$i1SYqkDYX zm}`<{5h^2d4h{~ks&&fPd3kx++5Jdp_?emIxKE;JpfP*BX+$I>TY|9HB^?gw!#Olz z42cX8hyU9}-`HWp`3l0GMI~FbSn(wnAK1-0H8C8mC400E4i28(2b24D2038Gx8Wct zQY2NZ&}RlR10GM1`ci^4>{E8%x!3=klNgzDNJqcM#uVwx#*`*4^Dor)_ZNkvyFoz5k}`bI{c=2<%zJ6 zeesi%F85tV#ysR!SPv_VYwg#0C04bpME6%o5{kI(;_Cg10g;$ub9s6R_ppdg-5GIVsDl(z<2LxUZeu;s*QXYJ-*OzB`{ zV?!1g)o*C#T2o!EOo4VyzVnm@>hNz6WB-4}q2%RW5K7s}T(yBP{l*||n5to-)>Hg# z_R8nP!SH&Zre(&Na=9J;WMQAg6|#3JO_F6G^hG2U-OSMDNMfe7XUg6oB+S;xo7I3P^>H8-RaH@NYWeW%WG<$-TO>XhrsY= z)NWe0q{=CQ8=RhwL+x2!&Isz--i87XY7dOSz?13iS6D%e&7B=I5X2*NFgRJo#>NgW zdL}0&p>z9ag7j`^5hhnbTua0K?&hq7Wzufhx)y_?SgY}?-o$+f?6l1VibDFrAam6h zUR_%QLGFZ=yE_9}8Ib8X`Mvl3?H~Ul&%E{(fu^>$a+3^I1Jw}-P|guBi0=~tvheP8 zOPC6EBJ`E?VdML0tE#H>Iq*nGqA_FR;*hz0<_7xvgEtvz-hlcH7uTjIvid&M+`LEY zX=tZGacn{YD%fvlcXvQg*U3p`5F*I{67iqd&dN#_T|-Dn2(nhXH90dg!lCneeQz&% z?jyzm{NTz;CSeWJhcL{=diK;ezJIGuLSo_$(&zSHZR&t3&Uf(A4AJ43oIE_P#;s>_ z-Utr1%v5A#WXz;XOZS2DOt(HW^BWK)7HK^V5N;jNoA3hBnE@0kA@b-B?S5zN?Y=>X z&cQ*5nLa;Th$fP{K^klz1K9Ta$G!eR?^y98F&C5Jy(tr=dOsy3CDj$}ftd+XTmP0g zsGbZC3|O|vHG$%fq-6V&)e1GyBk5F`FPLJPa$JNxMFBnbF}~~;dIT5Nf4ka2h1(Z;{*#NdfL%yv%(k<`8R~vb zk!X*B`_&6J9i4kM7h9rIAJ+$>6Y-*4NndC{Q&M)7aD3KZVK`J@t>{$8ri~)w>EBWh zek|zy&?aqZDM|mwD?%N3UY4cF7Alr&C%{SYrNL4*fxEAW`QPQ zu?lM$TH6q1 zy-gC)j~@xI9q*43oROVPAYC^GHOFrQHhiGItf55KGlsW(Bx2^p>tX(}Z#ugi8O~wA z3YXqyeinhE*)5;qk&w%mHaLfHa&nbFG4~G$@CF~h{Cr35e0!9f)O=^pvwdD;FE%o14^)2ZvRGS zgJoA}L2S3%wQnLn1p5;*Fy@v_NwJ#=@2__` zvg9iqo}dy)6%C>`H(T&Tcq6&Q(?HwPj~)i#SeJD_z-&*;!aR zQ1VRM^TNVDpB=Hzg+BLYZtAL)$lslR6d&JVY2^yVB0Q=bkeQUBFN-QFnuYzaU^Kb9 z8pOdtNs%|~e^#54u!UE3V3iJ$mc%n*tA;!kbO)&amtO^%X!0V4J}E&#lCdCTHMEux zxX#)dCej#jycsy%`As7t_KEIco{BtApLZFW*j3PRDrIJq2s4L?=+;%Pi;djUJ^i^x z;jpObuW}!1U%y&>r#Kx~@2tqR)1}LmzrM#@Sf{RBGY)xA9^~DrOO#fUs9W%nenBp{|AeRvU!AI&@+Ar1 zpAdilNVkRKEPs&tA%uO!>@!SsdbN7KUvgljJ>&Lk`Lge|C0nSMm%ZYoxp|(i_ri?L z-pfr<_l1n3lx6)~E>miH|fjo~cS^)0$9gpTQ|sM&}gO z-MFP!qGC9FYW1V)8u!+Eo*wYChhBchm{B$cYQhvD$j+Y37+iPyq_K(p$LIE-iW)kC z7xaGr&0qJM&B^JwB@FaD48w0sP8lF$jXBxcZ?Pmf--nDbEhrBLQypF2#&OkF3AY*( z$9Pufw%S|C(qrZAUOA*|aBwtXRrU6ozSgjO_uWw~BOlyQX+7CV+C`q!BmkvEV_FQF4pB@2s5&Re8s zgc{Ndsa8E5?A+?Xe0}-P_a5B5%kmu-%JQxIYH~5V8uM5Vl{_6r-2$7iDZIf z4DpQ5@JHz-x#3&RLb&0WPDfb-6V+ADe6Bh8X{Qs~ynFMU#N)GQ>cDu;N!LKEJWJv+ zdQn%vdcL<1T)ya^m|6nl1bcJZk4Qy_&*mK4zpj((GngFQ!Oo%l!Q}ORZD^s?dnZ&1 z=EBq$=@7jP(vKBS{)3LvIKdXjy@w9NhbOUhX1GS>k&JmhO?*pm)sGh{TiQoYE`vxE zYHf!L)H01cnvLwnrk=_;T`S|_3CQj_$wJDJ=gcB@b~sT6ET9TJf~T8`gT2w%dq-i} zJ0H@W$e)bO=gl9P%KOqs=0&{2MzitYeB5#+J85aHsmJu_oya34g731s@^}HyxW;~^ zC0o~P3-I#UPY0RvY*d7e84WfhUSBzot${*<#z2>;Me&uSIv%sDinn+;$!T3uOkL52 zy}P@)ZE0JZDK_<1CSf3bEjI^V0sk4PURoGP*62UI+otHbLj zr}HQtg(mb?7#cOs@jMpf5&UFWLPjJ{st_*F{qhCf9KL+p*AK zPR28nBd5WHchCBl_DkYeQF$vQv8(cFvtP#?=3DP>Rb_uvO;ErI}eGUPMsfaeebA{z5Fpm*80Lp^4${8Z+6Q%RjQ4Xr-(1iq^(B zAg-5TVun9z8~P&4kdKof@Ceg4ovhQ+Q|t>J+ol&N84wb_P8~*}dLeRiGf+<3qgVGC z-meIu&1+D~*4>;HBeH_MuX9EL()R9U?+X4W83}%5-~*)c2SORL+EUR?N926_E4yY+ z>@rt!I#{?&^~bh8=GP(<SbYI1a>C6XP}}DuKA?I zSZ%Gs&Ma_ny)B(ALMAXg&TGlHhU^xjz|BnVXO=7ixMs2i_1U^OqxabC$_Rso!5u8T zAC_%wM`ya@^GiNh5Co&e4hvDaS`^DZu8hh#zh*;j*JZG${+?aUso3o zmKu*9@J(on9u0jE;+>=pm&%?|gtX0-K~JC6=-2YO9cGr)N`-JKU=9o9N&=2dup@WH zn{yh!4JA=#$?bdEuQ)kA5nK=wjHisi3cXM#r?=WUOXa)UA`kEAKG0TuZ@gCb+5Kfo zrL?;%bh&(&*=?Z-Pn!hqRg;!Owi<4o*?oa^Fgbsft9GK=PqPO8Y2~9FDcWe3ABT1D z&tGH^|DA4P>ax{{DTPzB<=53PWo6n`r?sI~U0;qy9Gukc^;U#H$776jI(Gb33b+KW zj-=Nxj>o^gdxqJvU95@4-Z#x8>hr>WKc?jZwtTfkz$mGR?z<$1`|^?~nFz>QMEH_f za{G7975TlIo6MDc``i12WsA=C+^C@pmPSSKnPt<2gbKu&@_tp>{^*XygQp+}+jMd1 z7;!dUb2j$obsn{(CW^~1xj70Q9uO4?DmXnOfU5!OG@qXB@C@(SG><6Z+s^*Qxs{GU-ulu#L)5TyUw&Nr@c2)9UNgQHnoRs3E zr8YfBsL$EMRljEi$4w^e&38YVkO@`=*484~x)(KRlU?9m#3$Gi^L_M(WSL+nOvXup z;-v1dacs$SPCufQG%XzQ_>Mk!mcht*tFhy|$1};?dO7(onU!K0JK=-^3vM_WWX+zD`l<`C)j3Kd_Tu zqN&YYc<}SvE5aHjzBA;kY8#sYTIHUJIc$!1AW~1fuXrYH8Rnv!J`H$1KBLb0jD$l3 zqd32xGJGs!v3$xfY4+`Ja=U2iGV;?jBE+TObv9wNhv)E`nwyn=0B-JP6b zkY@(}m3XR1W`oUaWXMTbRh&IEw23*_p~<+OR0+49dN2+AOVI62wW*z5&~#tlYwvI6 zM%d-zSedQkwrY7LE7l^tAUim63VLE}!SwM7ae5jtuMQd6yxhXnE4jU$!UUxY#|AD2 zHcM+sqEp_7{>s3a?-cYC%v1NiL6dzppU(yG5&RH z>`G%`N(8}Z=ys*o)WNU#X5Ik^PA=Ek%4;!=`lza z$m$jr22U~?D=X?-{gA?#C+5AihLPjr)|}^3i!(ub$^}qwG%3LO_zgXz75(ZkGc9d& z^%$~kLIXQ271SB=ZTW=aBXt#~rucq*Sl>oBvqu%D zBhElv8XB64qVz#J3r(C8l9RpBkq@th+oh&vHP~FK_!#0O!8yQ#lY+M$rqEDwoNS)eCi)F zQoD)D!RH@)lV>ItyG1?1E;l)Jx{MOQ%`Jr+WpAx3yg%Q#S@Xzj_emJgpiO#NHvxg5 zX{=?9`3_5gT5SRPtdq-Y*QGic4#FM6YQiS z=p49m5U|;Q*8skoaw&rJJi)gi;sf+tbJWasRMm*U?*+!276l*dD>nG>gem-uQkFC~-@I^HXp$?DZY=_H?;>WM!p2GV(1j0;_)*0T2bm z`}Cq*uPc>nUx;q}Xfu+9QU3JW=`W>I_^viZ2x#gq-66Q9`~PFE;E2#AZ&Q%h<&)BV$a zkblSk7gr*^-aE0jTPzT&YZnvpILUqB*98*abe3DMq0G2tRKmIis(2vK`q&td))VfsA$OKT#hi4 zk=2=1ceG!BW6HV0MSbY_G(L^iyQ?-Nk?T$M53wa3Xx}^hn^ugXj`CWQj1V=sev!&# ze+;+GmCc_nE+VgFEvIC*kcX4bOXF>kKnnd*9&&{}y$&e9KMuFq6b&Wr<~*?gN8$r_ zuwf&00e`NyO^f4piavID+gLNE^g*+3p5g4u!_P%s{X;Rq?t{EyUxlpLgnn?ds5XM%%;cZdKB!*uvaYJ2_#riI02hJ)XO0?)R$dT99=i zXg$M&(9%Nf#!A}TL8J;t9X-+gbG?4eG=e!UY|2*N@ll$*2ADU((b05!cI}BF#6z3*wWQdnH+LiC>g0Vr zPH?aZ{o!`(oI@^SE}Ho10l3qY`l7yA9wiU=&Q^`P-O#W=voyO?byy)!ao)7-qDy}! zz&;^~JuMJbI9=`d-FG)*Z|}UswQG$no~ST0(;oQ(K>=EdvAk*JTy*M>sAt!;*(x|a z20N^&M>hd)cvW}a+qT1_ZKM&f`@3G9N+!xTJ01uo%HJJylI#rVtR0eIu|K9uDS;gt zexwLVCpZj$+7=R8d)E5%dGgxV;Q}un$ssNrDrh2xWW;Ea7>jM30m|0alHemdrnpFy zbWX>oCb_L5EDH)ftaULt$ET(%hp(rqhZ>R9Gt(6D@ignZ#9uCXZi+Xa4^`&aJrV(M zRXBFil?9LFj~A&N=Yp|G6CW< znMs&+WAD6@;o$X^m(3WIjOY!h#jGr8X z5IP;CnnH=ZWG6qr-N7PD?v2e>N!76xoFZtXf=0v{a}T>xQmP$=1q?Ail$SR&J|up5 zoK9AF_pwcF{lKbx?aP$1n$Q!Z^60PGMfs`=+&EsWbU0DubdY!{&{9gL* z+t6DMD7shcDn1qTxy~EN!<2NSyjBq(YDrh)q?i3DsgIk7iJmbP)MD(i;R10D&Lxg> znursJ#*38ythSJhk2f=12NBxnnfonka1lL?Equ3Nqf4h&^C?!Z;2HP>p0M3;r2=7t zYwpx~j?>Bu6#sapt81=$@qNYeY zrDx$p`hN;+U|@2hI7?IeD4;J}dUic!F(`i5Zmf9ZeEtRU%!rpcL6<4p((~9+wdG&l zZnsc;$#r8j;j`o)KHx@f8}^GSeO4C5!Irhb%2VrU{it0l*8;oH8TCS!f}%KC4cpN0 zr;<-nFKT**zGOMeZZtgqOcrQwlRmb1S*OIn9A}ivyO0EqQsW{<5&|!;J?K^FOz8zr znbr!03WW|8W`Awyaz4vllDnNzo%~G5i1J}~1e30ww0_>evkrZ3OPqLdtHKopX zKA54Ho0|@=t@hO{>%FSqJ$UTI5a32Jb^R=BW zfE-4IQ$Fbbnv>imjz07-^c$Saq{c&Ev`45^P#9ZQT-@yikBhyZtw!Y?@wCJjx1Swn z&(q#Pobi$47lss$S34^7<;;d8{1|c6)LE_%nF)x;Q7aOc^a{Jz`DAzzva>2qt@Em} z0@co5^Rhh*%Wm#z5^y&W3tTylW#-2Qa;C*Sv8mKxg~j##ni(iknKo7YsGJIF8(E&Q z`stl8$_G^$fwkfW_s3TJj^BrP<=beNK&V(7G={=5EIPJTWwKhDUdsZBHw z5s?X8YC&G98qMve0cu*#NK;5bh&NY&T6cK(&cI`1%6~9~l{;m|(BxS9BBE1IX@c^} z^u*d~O38&JL+6_9+L~W=1)`*c@sqP(z7Sgp`I21f5j{NhnN%hD`0ZUOmq}A-5Jxza zFN3M*yfq|5Z2XXpCKyb5xaE(uBaPLD<8pH%)FOfrFsjWPb> zxJCtzKgN02NpsO{Y*UhSmt96Acv>@Uqr^S$HYU;UzQa>X&!3Kg1f>-@W=g{Q_~$Hf%VU z%PFptp3WHFw{S;8+idOmjeLUJFV^j?k?GzI!7v5!E#iQW#csY$i|Z36wJ zCBx@sV~R$l*9w!yWzy|oE1x?nxyTvC$=_F(r75Q0OcMu!d+wQIUq}3n+I?J@E8eQ6 zQGDrtAt8b(pziFqyJt4$Xq9S*(NW<&axB?s%i7?vMd(|oHr5k47_XP`I%PK%r(dhH zreSn|I**l$HdBOy-{M1yuIyHVZGe)r<>u#Kwoiw%vv&kXPBhRYDZX==gnh!9bAOd2 z|NZh6-unh=tq#+TrM|YdEJQKI8(S^W@rB}(%%~z`I3f%z_6gu#U>_nAz-W3BIvejk z&tlPTwwC7D50Oh@0a!CgNcc>WVte`fxyOmUAcI2sj9o2B8WRFd|7Jozmfv-br0xzA0FuYA*2%5dTemljB zD)-aWfPV<16#tM4O6=JR{{S9~9i|ScmU($idiU&%z*XxuM=}Z3Z1P&P0P=L_t-ZVX z+2XtJDvU4CkkzxpB=9AvgQQ+nHm+mYd>;lUf-9MG{s;(_DpJ{{xe+*l&RIR*Jj1qU zs?DENf9W?Z#n;MRHx%+Sukn-Ag7R(O8{m+Z9LY z8!4^0WnFrRyuAGaeRO5mry#DNOS`MJN3_^B3Z(V*S8l(4e8*=uL7OO19iTp`kBHz! zK$xCbaeC3`Zif@u`}L@aFG(FDB;?hY6u44Z#OMR_=m8b9$m`!k9@vw`JwUXGCF3U# zf2CzcruD$*tmFbiu^!5JXpP-tv9Ysa6YdK)vJ`zF<)bF^VMtEQj1hMa?5I3i=JKj? z_u!ZBQbN8m#%65P_c8C+lCuvqb4RV&8sz#1&4zbgVr54QxO8+@4n>`nRN~UasRb)o z68QO5c(X-1@_FP3Rcx40LEVMIb%*s^qs8q>b~hFSVU3?q@~*Sy2&^EzOIjV( zeabtmFLm~n7N>GomSM*2HP(+h|B-&!+`ZgVI_u!h@AR)5e!IIy)$?Ot(m3jS8>H~zWMIPR&RDr;1Abh?&C(ZT<>_za z3sTf6xlwVim@8daB@(1a+4PR3r)q5XV@zd*!Ep6ZQ+-FKm@QRC-~*`0CC(#SBTqono5Em6AEt9o_*bZ^^m zTvhx-HU)Ox>xVFC3&&KOUhI2W;2&O;FY+Q! z5WS~N7KS;8`wt|X6Rzx0PQnVDUH^8Q`a;Pg^m0DQBs|>Jr?%RnmU1hH108g$8so4+ zFxx&7GIALqhxeO4lqVhDMXd~~WYep_ZYv6;SAvDneDIG+bH67S*ETFC_1!kE7u?nn z#Pxm|rtAheY39q3{W2^V7)0{1yjK$Mwi2lO<`Q2qA=Nj2aPU*>X!T}awI5~ag7M6H z;M>n8Gx_El0J1k60xV%8^0(vokSJVXesaQ9#&-e2HI(r&KZ|waV_&(-B&)!}cv4Db zwss=gHLMc~zR-L3L}W=pCN_>4L4z4T5Ecd&?myLzG+K|F8|o78QkI?$pPUWrW+Nc z9I~~Q#g@QYSWt4d7ku{Z%doHr-LuEUj6V=yJl|M5basB)Tj)PXv&mvAjd?{LuxJ8F zox?N5v#!7Lktnr`e9R)L9RcXskC&sRW1A(i%U8FRG&-G^#6xtW9@c`zHgIxZ> zgr+!c^i1N5YMIsQYP6Z@UroPfW@n;jsNxoaf%%F3pZFNyIzQ=3PrP<}UemIs-JoNO zgW_`Wgi#Ch1#Bm9|3j&< zkm1+j<7~fmTEKQYlA=XaXYES;;ItB>xLWx;#7do12a=PsyMdblsd|=WoVuUQ?jNS(Id%rV z2)-^rlW1%NQ8x^X<9{f{eG_Dp97DOdZ~W`^g!-*5v(qiytBaBS14l4JR1@FnT5_D- zs81RY7N{%yI~NDTe$q}%#EqHm3=Hu)IM7A@D%O5_dssGyXZ@bMRY_^`keR~@#uqeu zs{x1n?-&G(yY|`53>RzC3_Kn)tv|BGSP5p9&$oJtpeb&_=yKXuQOgPPBbXts|5}a2 zmXRpbYa?jVO6xZ z{}$sLT$sP@9E{@O{QR~_Gpiz>Ry#dfT;mrRBN(&mZ21LL-dESq_*q7FQGtNhAN+$n zPfAg~L3H$W3Qw1^au)6M(BRTxS@U1du@2el(A?ah);}tYEB+sL35~kBHc{i*)m~2` zK0SP?uEy*}{!81|Mes#a&fYI2agB_;jXEt2|O&oF~@? zw|jASeFeIJwG8$DlNmdyD$DAqv$K}zKGsvsLs$prlNAa*%|n3ip;Bd)Y)dIN<0XJD zn1TNY>A}}&A@*Jd22^hTHSc%}1)2gGrl4P!cy-zSjgBoiI5oKAGh5oW;CCrg|FzzW zNL^9U?fsz=je+K&#zv^|rQx< z#oDvlnisgvj*}|<6ysm}`_6IWWZHSll8Cj_@4Ja5|7kkL7~I_8?%U}gzh7eV6|S?j z+>E)-hyLcFAiS?}n}9OUqCW$iGAsvocIch1E`x+geUL%NXwyphi+0`86q!P$#*8c+ z8)M^~&dz$td)0^W6e~4uN(t(lIiL4b`0NLzRPRMyG}W9uJzYur+cra^oBv*DiAz*e z^w&4{4P{n*w<0D^&JA@Xg0Jt$L$Hx;!?(TGxG+ho3;kPxD}jjt<=!Q|k=E$u&@}zL@=01Hq$GeR7(Vn z9EatJ#}Bt|Z=2}g!Uosw`4zr@5x*z!6k6_TTJ$K+zkfKPxxNx~NrZu8#I6 zAYM&^S`IZ2ffe4A{847DoH5gdP1l=CMZ!sb4NeY@Gtl=x2wn-uD=#Ve2`D+-nqaJ? zn}UwN2W~IG%gf6Ui0UtH1*6r;uAZLIp3S=pn0@Pw-X7$a3~X0>)+;EDf#S=0Pl+e( zZ`Fz?Gp(G~Ow=uX2kyIX@9gaC?uuJ9`vuqi0=*}o|J*k@F_GxmGjJOnx2chU1oTE< zgDdezNoJH5lv!HjTf&Yfk1{|?17=KOsKobRFIQo0sOCuIGW1Ah)SH=O11~GQVb!q; zYjiPEqijUGUm7O#Pvp#*CYP(BscFC*oA0vzI=&xSdUDT}iHYfPun4%O?n_BQLGh8Y zqoc!>wo6D#O6u3aIbiL6wNw&mu2Q}-*B@Ga#CIZsL=jxU}ttrX9cD^#Mj z0~g-GD+28N{EXM5qY)NxPVcx9rD$e3ot|3PYAEIV@_@t*fR3l%=!iTxDLfZ$omgLF z@({&~eO=Nhd(iX!(So^-VMj@7DozJL8<;m{ecot;;SxzK0K<0A*x zKr<*!DsodNt78%Ka}w1-*8*V{k&R@Og1qUKVed zjQ>!ULq!8v+GHEdqpGg$aSu^24u7ylbasB;{q7c6u;zJxf4{>Sc%&ez;ii7{Yd5*u z+os(hxvTSorDTs=>g&zTJV4|p4OL2XLc1Vvd3{Tm5ai-uF4RM((;IGe?KKgE`1mFf zZS|4)V0NC_R+ZE*rCL&Sv2FJEzj}lF$J-NHxwzz?R`|<(eGAD~pvmM~u~y}QTrPEj zerL2rYPORt@DPTHa&3ZK{@AGX-0UoLuDr2P@)kUQaev$cE+;HhHwfG>{1dy5nd}t|OPAiN>Z$Q4h>MG4&&pCtec;*Nls|@_Mec9I_1ygv=yA4!JDs4_$NtS@^%wVj z5!4DakqnBHJu79ivjT(}Ti}@XvyU>DyLmYBy|edJHf7V(hN%_sjK0dWj?Em|KK$xZ zmY=_BaEwXEz>I&DfrfsGPjt`Fxj%7%%}06Poz2Zn3Cgf{h|(VgQ^D+?+tbu?0s~PF z?sU@;4uL-1Kc-=~o>E;s@h?guLChvS;}qqT_kB_8FIPt-2k{+A6CcJAKQRn$<2 z^n0m&17{r|UtUGbMph>co1B}&rX64Ryp2_SMo73V=S!bF82BV04Lr4RBTI=Bh(t1m zba74r#(<#>a=H6PoZa>gXnSuVfx_qZ4{f<=u9x+Xm@g4UL{(W$<3gLA?$<~m_~X4o zEb~f;2nnxc-cf}AYBy*VO&e#vg9=7=V!1 z{hFyz%`SO*=<$O2&l59q+meRah9ExgcOMDnk`ecgknddhqCc=>CBi!P<~lbvdYz0cNTef_q?Xd%ru?tbNztBAaW z!l%S`N#I2n*JdN2{16B%@(dXu{1dn~oU2gR)HJYSJz@7_!&ZFp@KEkH0KIOVdbqxx zyHX=oLWEwKFIihvRaHwXswr5t64Xw0tujNpCbzc>qQB>M11J&^746(SuN9@a4~E2F z+Pn4BM=#x;jyDfg;=j*iJ+f|QecffOub~A1-6YrK;{H()n4G=R9I46Pm9pqj(0}K`NO+&R?@tA zMojdS=#dFlH2Nnqs;d`-(}!bSKo_#8h)7)I2e6Woxw#6nN!*~irBZ&JQ)+Yaa2Hko zj0NxgE?{teY*dWm84qaD;WTF4@4|VoySp2}d`b!L6DnwkaZZV>$Na)V=)zNE-;OQN zb^9f|IPeZP8KCW4T8XBnX6{OlK69CjDQu?2zxEL?DhV|;1wG0eE4(}O)WFjxK%?51 zY*p8i=wgo*OT8ZqySkPPJxFxTPi;FXWD)~YP;K7vso_oZm-C&)WUFJsrLdpGlpV8K$ z_&|oz39?vnHF_USO2#!&Ke^wQrzjATLarCZww4@iq_~6K=XTPI%1SmW=)Kz_Bc_2S zZ-N(5WC_17S(P?Y+yuDN;mGsLkEtNaN78FC(?l0-z3fMgNL3^@)-K|n-Agds=CISx78n!&|=zxV!k@40u*+1<1HJWqF5 zS65f~Rh5x%Tzr006U*50$<;ORF&7utSKj(C-in{hq#`*5Mac}(+&rYZs%kB?2R1C@ z*wEG1hNG~F;E{K8+jWlH+;qmPe3I*Z{rxfkp=10!W&@jOP|yuUlN4E*1>+K#eI%IP zMVLWxm;Oy|n3!Vl6#t_~k4BT=BICSqV`+zhwY;GnYH=CAmaP94GcnPZ+7=I2NmoC; z+#}WGAMZ7VpIN@Dv9r&FD_m8?hw7!n7 z8RoCjqe|Pb6!7=o`Dv%`&O94wH`PdW*xRqxt?y9I)KctYRX8oL_UG1snS#V*#bfGE z^$Qb%6MRz-N=aUw+mQ*~9%-O>Do|ckwFha!dzH*I1C=hkdW)ltVQ;z@7jv!Wrl!)D z#(czvn`3xA0C5nb0phLF-9zT`<;&$Ia0c}`!Xbhpm2pE;GMT2P}K z`D&SbYwOeJ=h|}dY4a=ng99M=vp!F(q#hfy>25TRk~ZwTy?51|6cPV9=-!5idvLB= zYiMpI)Gu;1gIr&YH}UbZv`myFBgeXtYmN`_g)pGxMX9wELNQZmWE&Ku`t{SteNb){ zGVCP1u+uv=i2l$MuuZbZD2{mr?swQ+_~-9Z`!1rPzak^`p4@TWNyB7u=+FgH2L;$+ z)J8@S^keiJuB_i_&pg!9IFG;VDU`}Ip`rn#(K=-+XY!qe0!?jij(z?5H8{8bBuNZ& zH49R>01A?1Wo3O{;72!%=@1|D^YfFXEM^qpjtDdh^h?}r`=McW*44#DqpBRM(bJ2p zxZ2&e%n|38!K@p$P`7b+ZzMpDW_~G;5PQA^~pJEkm*OXOoRe8h4g?Tsf^50E2 z(_$wk=mWtT@Dy;`UPCWgPESplP!= z6@$7&F$6U)X4uQ@uAh0?_k+BC+TMWO%c!6mpEA7bhHm;uYbm+b*!V!oYw$894^i%I zchXW!XljX}<2yx47Z*JborU}NU)`fUd-BAIpPROov0C1wFpKi@x&?vW&7nF8wLGRg z+}zC7yM}N$EPa|O0Vnk{^<$9@5XEL4%%8Pctd9vj zL9uD{!kdhUEe$J1_TmC2fpR0r;*eamWwV-; zG1u)4JTCF2~F{4JeQs9CPqQxL72^Gay0m8%6 z;@2W0yv@zc=gQOs8F&XWrXoGe&fJpjf`S_u6DwzD6U`WDmcaWrZ`{zGLW9{wOHAP- z)`N38w|S@C=@E~GXr&wzlIZcr=D_GTk8KOoWQEUo*G_B8&ed?LQMZVrkNhE&6UKe( z3d3SLFrUKnNQtx1w`7BbzHK@f^t~c0cS=_HE>wz`vO_sI@VH4KR-xLAGu&63-{c@~I9$@e z#KZ&=f@k1vm|L%^s~iBXmnPtvoNXJem=>&6#0bmu+TWrcJ_2eO+{(zD83=djd0 zI)h4xNDdB;6D6b11{V^zC!KUIlk{o@=l-!+)%HkfuzKbMHe)w&+TPmv>hZsndY(}Y z=e~(E?`TVXbq@~khf1I(o>NVWqMHrnWMvBx;Z0*-*v%7nJKGl4{lpR zg0FWo4<(P(G;S+dH1Xjretv#ILFB4Bx?_9{a{p~?Y#@=jt3ld;|9t!-@JyTEBXyl?fxojXuBg(OC)NFA-6V^*n- z&PJo5QchLtHS_(ikgN=z3c!Q?*!ucadXT+(Fo(Txko#Y{I4+FdPcS?ku;zFCSlx1d zhDy%rUw%}_H+IG1zZDKlRp8}_-@(i;!^|-s{U{hMdImB$g@yNOhSKYZ+gaA|&^Zja|h|Q`we#_7yWLO*Be6)zc@I znT!AOGOd?GYgZ}8T@`?RWw=4f(<{*x8>~|~rvcS})GZTo17E&;-!@gIVe`=xSp=q4 zSEQYro4KX{Q2&gY1FaYDfX{5Ju_EpL8OS@2xHoeFSh+eu;X!O%I=_g@?sP`&nhocZ zBDdS3#7{ln#86Gy6@=lPV1jxC9^$)DjcPEQOQ@v=W1S3&8723R+3<~2eHjm+?xS~w z%Y-~sGP$tz7%?$>V8Nr#Y3e?W&>_svj_xZWx#75nQxwc{eKS8 zuA7@Y2-mb)77=w7KK=dd3HWHx8Il-tCgkE7pyhg^w#v#$Mb_r|PgCh#eWx@uQ1lEA zU3+6v+_=;Z12WQEJp%B`BGrFh86Lkky3%}8ZXT(Ycg2QpX}4UP{(e~Xmvh`AIpat1 zHcsDdJj>Dw`g)UnaJv!?kzmy0=-GT5K1bimkq6FtV(%3)%uYP@6mY>yx}^L6dAby% zU`yq?o6$KCpVWHs`N9T#(hQ0TcsxLuHSVz(zwiV7KP)2y+O#{nSY$HEp&vphTu{I<|Dk-C!gtWs*wT&0d;=C#Z z56|k}SU{3nU{JuAff7`A+nUWvBIu3f1cB()08+;4eqNd(U1{lemolXKwf(5(7b8z9 z6XN-MIu~;{R$2^`6$o;MXcn&GKyNaJJ0LjdH!EIzJ7@1~qJFIlbBS+sa zs4YcY$jSQztJ)zXxBFhrv7ieeA73Gr_ry;2_M${Yc+q5ke)=AqAufh{WlL4ad;Klq ziCO#5+y6bUhP^6OeRLKDqhiaLv>7pR-A;w}GELKJVUineJ>a3l7&5=<_@8umrGcpH z?jfz6#HVqFSksz*PIZ<`9Ubk8iTO=m3}xWb{4~?qjN0pK)&lWEBqa8qHzb*HPF(2h zZ1Lou<3mP9KNlZjTSKOOo|%}lvBV2eoj8FqTEmw;bvkm$FGD9AC+ZsgGmy%-88cqu z>N5Edt+FghP}Nc(i2o+qv}2<*rW`*vlsAFbok&S&7oW$*KJV{099yvG7l8MH!tkX109xXL|?YwP|Q9=D}ax{7(iXbPg5Z*_7drLx%HA z9koHZ?PsIVhUyxK%r3NQ`$|a+Ew7^xKdYhPr`5s%=O5?(k5?Q&b1IH(6-wX3MUV)2 ziSFJo4tYMkyK6Bo#GrCPBWV-?&lBYk1QCJNocsjum|MI+vtx@g6s2ijzIu^-rUu*e2 zH$mgh&Y!D=YLSuj#T=)ku{R@)Z(cPtQc7;i;5>_ec8K&pLo`j)eSF$AsKQJmD<^>1@oI# zzCWR%`8g{cn=n&pu-2lNS0>qkRVq((6~4in${N=}bL43@13|ie{w)Gfvm2^(3_O{d zJZS9vOuNPOtdmZvrhqU);VQPsCt`vS;jub>NUygI4vsPFPrnSux7ruuqH@Trm~;=Q^6q z@9xD!NedPirXQ6@@!bCSH?ck#OicXTby*tr8mM-i%H8dYby|~VV@nG?(VAw09^`l? zs`S(oPFcTz6@EbF-vhE`VilD#Ge*TKE!17y5gnZ|MV0-!g>`rHD%ke6q{20yH2=A>T^pAwC-9Q`c>1|B-(7Tc4$he8 ze{Mg?%Ip@kw@NMo0(#~$IgSfpsi_MHvT0XSU%Qskq^>$SAdly?N%q4t)UzLKx6CyeR7xgy zl#w1Iu4{j--PWdu%yJw1?2z;3q zFJZUv0ngK`)Q1P=_NjoMBljzLcs_L~`^`1ff11tGo+`w!w|`zxIT@QJA&z^P_MdUK z8CynJ%oe0k5yI12Y ze5b~@Ax-sE6POGqeliMImvEWS?*+shI#DXEs-eG4=n-)1CUzzW5`lEzJh6|JDNK$~%iN zJ;@L7tmyRkaOQVBBvY|ZO)=kEls+3Ov8G?v)b4OezDP||S0h&0(&A|H1D+>h0EM_g zqU*a6{F4y+z}hKIcK@}OGJpSKS`%}Hw*4+w|It5g@HuNyQE5eU;U`55rqki1YVRz~ zX;c=MV0DqoV2ea6;8xS8!@~5ORI#5W-0%ZH)T?Iv3<>QPXgFJK-(Gcf1$)d*3q>KF zxag>Jw9`?W3OJ*dPeX56BQu5Z&wC1-Kco$XQeIkyVg^O@Kbs;5yK!$7 zOq>86V?n|yHArh`oHi^Ubl+R7^E9c0%{+djtz*AABsfE9X(|kVlWL9G)KZO)!%Yh8 z8cxSWpFD0uQlbHh>kR%P_Us5bWLj-`bjItiSt$j=mZ0xff-OA$q>GvcD%aLm}|a(|b)4A}agS8LMxn&fo(MM5P`~ z$X6k`i7mmoiDqz!mh!%|*|q4me?;bg8QYRK=g~ym;7l?_VT6YSAL3u2zkf(13=2c# z_Mm-u)5TK?ye!{O|J`LSaQ%F|pgcE^G9y?26#j9ddB*=NVAl=QC(Ly8{L!Og^OlBz zL4)~agE|}ua`t6>_=oL4RKse`GtQ0%$y3ZG2tKybI_q>R;cfF@(;u7r>or3d>D+h*$hu?~lyDlHyI4aK?zIp^FdBW!zPCl~9Kr3>#KRWfiZtZT!LPU2K1`|Dt z`o6m7jAA9Hz_N=QL~?U6DJy4Rqn!FtK~P<@2~x()Z)Yk_^8rg(zKS`AAp_~L%WU`V z-Q(xM@)#7T*#`bF7|}Y}Z&9N8ZDXUftk9zQQE=|?Uc2eVs8g3OcVb_sMM}O?J>?@- z*+jF^7yBkoiJ4d~-p*tIzW^&0!uAy1*;@riw+9IJa>aB-WIQ9e-^9cO4K=l$$8DE! zsHmm=R@($TGQ!hKPFXXdl^QFjn2@C+MbVfaJwc4H-B;z;x9b*j|2{S&L`S{MZK13Z zG>5lT@IG9Sz-am+b@Qf+=K>=nnPVovL6)s1EhA%(%rKW^3F`=FU|>*Z#BI8o1!B16 zL~DGvAE95M(Y~gV?Uzp85aFPvR&0E_(?<1on(bYK$T6J5|Cl^ql7~f+`rMsM+ur6V z)K*;Gvz;>*lVchTli>{X^lFi1B_&2~uLc)*bu82!$4!C!3#o&bGnJNx@7xJ*B9n93 z)BGH#19iLJWu{8ug}dj`1ERcF&K$ETa}`b~UruV(`bNnOVH@(ZN1l4lx>r|24RWPC zRj$aZ#EtqtFke#&#Bn!}nVFeeL_BZaq*%khfUEsxlwjq%h1{s7vDFWI6H`l0&!{2j2ek`5&Wt{` zvn#}p$sbpo%>^FPoX>UC0e5G@aQ0nU7;bYQ+F+WdatSduT>3>p!IqY|{g_SjI%Qm} z;$^>RoRx(EUf2GAJI8AwKd)wJ61G%Q{b)3-4djlnFY`Qg*X2C(&ak*SG`*D(mj0SKx@0W?YT&z{@ zz|Q66dWQF~v&hPFO|q8tZ7kWH=4B@g7eQoMJwF&8Dq?!D3484AKm|@-%YirjPqw4@ z8G@SJ?4LZjvo6iD5?KeWJsPNOGAk>EW+cb9!N%`<5B9cEtCW0VgJpWxTlwq8SUxOmqGx03MGO2PAlF85R zvQcmAb@lbV*4hiQUnwdovOr6nDdEYL#Z68cL#=2i|K2&YAu4L>r{Y{l z?#D7yrBlc8e8jFwI2+E8457QbbIBlwJFSF((=i#nS@*v`+J>|0#?i$F3ZMv)A6J0|U_Q=mp6q^iV- ziIvLwarkc&tT9M0>1L%kkeX%`^rg?Ls;^6l`3Btrert7#*jZa;f z=%B#u0^#ZPZ5JNhl}%SE-?1@+?%LtpW<0E5_#S=Cnv4vIhHwI}%7wcZLmaA{uAeDH z6hyW})WwaiKrwI7X=joxZ66{6!2iwO zS}yFA={nx#Hu=46c-OF}A;gqB(k>*ll&oN(EsG#Sr-OX~J z-nsbP;O(*uUEDte<{oHm`>g~-ix~Zr46EnKNdrESF@~AMd$W5?$&xoVuK~)cqhD&j#KrA+Ic3{f!mv)s{(ebTVW7roY7*5o}~ZPTjWMpFiKl| z<7A=H4U}uA^6Fd93gR&zXd;Pmjz|+O`?1F+U(zciES%lqjfLTbaw#U=bM^(L+GC|- zjQpX#`V5C15;^NAL%Yr#r%aNMfocE4#H2kvkzBrriArg3fwwiu17) z%(_$&0`wAVj{L!^Xu7X^g(2l$sh!<}Q@8i-0b>kXb#2j3$P!b0Sjq#Xer88_gLMUej+U&1cS)sv$B zv9JRz<{>2yaB*QFla8d+vF*nh>gad~cPAvoXjvLt%;Qi3#lb1wGF2t2mqD1p93X<# zp_4Yau&>ot@76s?16QKaeS0+-4>OoU*PGz-lG*&4VP6cpD&D;C%$7=RqXEujc9|Nt z{tF!pXBdzej*j*^nwm@pjLOA~1Ps|Kps&0b0H`Gd{2}K>=UuBiljJY{Gm!~!@|QT+ z0icR34$m3Ls3>XB&#G_U}w<=UOs1Oa&yt-Y0XRo7*C)E~!? zz81O4aq4)7edB;#09KY^28$Opq4qbMG|Q_N8mn2r_`wtxpQ9|+%pPuRYXe8UlI38= zH=j=Y<_TH=ISSoV;$vbi{W{8mQg%*GPM_WqgOjD>N!PQFZ|zrjsEVNz8!rT7P3`~z zgr`?FznVy(ebvErLA*@H9;Y1M*bXj#%ue(?Z%(bDkgp6NBM{Amn;Zq94X{tx%c62+ z&OtSOhObKxN)x0w^NH{8em&7wwq3O9LuNl-@08T z&3alM(V00#&q1f$fR19`$G1@cmtCEWjqPPn(2NV+;yvFxS zi*G1*qIPQwGY=R__kfgu#G)vut7qwP1783f!CNBC&&Ox-O+4CU>4gHG7}$)y@VZD2 z99*gYL_~P+R5l^5{bTG@)yqEm&4jvyU_LIE60Gx%P))>okm$S(R3zC^8*Ck#>n%YI z;ZWv0cs-}|Vzn4gOgQbHJ@n_Q+bg%UuuxwINR@#boTMJsl>vSnSbqiAuIbucsRMiQgGjpj!~2Vdkp0D_M{bq#noU%cZt; zfT?Z}W3Giz$qgyHB6J3csn~(os*C3Fzm`TC?CBXYVrW#Qs`fPk4m7h5`vhBGL&~&B z9T5qA$uIyJVx)$SH_$K7aK-ADpyf$_anM$SMaeBHRl8v`(XS<#vSy%GdSN%{ zgkO1Y(j>dI(KF7UCg~jsZSqI6E48LggDcrx8(Smh_77>H;H!^C_e7&Q+H=5khekxHa`z^ShQ31og(YmWg`*0CVclL`EevDUf}R1Y7FJ15Gs_yY z!Np5rTPXSmRdy#O`UTt7=>_kc#gE0n4|}vn9IQi?PVgQ-I;GNkY^WA-2b#o63twVt;^ZJH|mxc1hlcN7vb;f~F#o6vOQ zd=B(+tU%$WahDrW(4g@|i-_ZVU$`828r-+0QY|rk(2)QYzG{Ot#SJAv3n`gu*0RgxQ7aAU(nk`i9gV6h7I@KW|x7rGePFFsGODbh)d!d?fM+67WB0ugw z@-Pdse&_lMR{ymLjVcBMygiYa5G*h#=RtaB>e(CAgh2olhe5|J1 z6Pc>rO<2QkX=nrtz>&D!_C0qjMOWY*d^=Ds6c_1%zlwzzacgTV1(}&MG1*FJWeROG zN5}OuFboebFNHS1_}qpYp{XJ%u%#9kAt~W*|^!@npV@n=myjj1$%~FX+`$z`jSPB#q9Vkjduc5H`qW z>e7$g@V*)`r;Y2*twEfPeVQ9{C8+xPpD`VwOx62SVDx+Dr06!u)ZS|}?us5*bEt?@ zk4B>xyDQ05RB8igbZu_3sAXk+QZ~2ais7|5RcHcl+$1bGNuLWTV`wl3fX z4dN5ututF&dMK9yxV~;{pDXU;LcV_Ki=GnlU|dtp&s zVTlo5Mlb)s?-hRP%|&c1Ht1Z(&keQRK_ z%Z?89C3$gtVa@UJ&v?KS^ib?@jhljQ=NLrD<>Egv1xPaYRh+e*QI0igVL;iS(nRmy zkI;w5Kip{jcbPJ8l>@rF8^;TbboDMawWTg~n3h=j2{`6&(7_e*A?V$|n}1GgIl3U9 zQdwmtDnaD+%0w+kwSJkqko&1qu;Ywkhg*WFth~-k11%+syZQq?$`VFTyBJ@o3S*C( z$9tw1lMeU#UP(EvcE#UeVb&>AGbbj#8Js=yoL5`mO?LJ>M?h~{Dg5Wj0;;`@OXDpf z1$Cb#cDN?pzs35a)s2jJdV2`W|KUO6?`fi`83dn~d5CDd4D?xAdgHSGb9Rm$6#$!i z`L!=QFBvU!lCGKEInWP0?q)OPoi(bB4AU~`M94Gn8n?W8dhd-4{2 zfAd-z7L=Dy(!(&Z4-bbKZa39+7iMGAx3#`e;laqmJ7a5ng_NSR4Xd>J3QQr{D~Eh! z#lu@W(~0}~%{M;YYRk@z1!~E#h9g^B<^R`{8QAMLPVQ}8i{a4z#G9d2Mj3|qkzp=^ zM&DfkfZ&k#A-jfipmRWC{^=%9q4k-M;F6`ilI zUT9si)RM8+z`&N>Ho$H?|MMiTNJ7Px20_;|6EVEQC4)6_0yi4BiT>c*sk+ol?-^2xSHuk6+Tjr#e3uu=9^DQBW z6X21n4zQyemcOTAIq2)L=fAnVa4Qp=B`w8?7h}^?z`o@$-yPn6w_e#3L#s0Y6m<3Xy%690a2?tU7!X3as!))wxLjbp`j^K*52?2U81YPE0} zZ*v~fUIeaChgebm!ODOMKLophi6up23twZAnYA`X@nD*)zdx#~NxHvB%PBxRvAv#{ z%*+z<6*zE7kF6s#O8@cO0}?3xOM>2@>zq_9mupuhfcTai@&8~FY$wD#JibP8TCc61 zs?>s|RlWH4SZ$w#N5d}P2x4pi|E|SA*2K@c4PNlW_w)t~AmCA*yZ?$BHyQzf8%63o zI#r}pRKrtkZ}eN+sOJ098v^kLS9I9nClMVTHPfa-0Rh8vy>B)*Z*6bY;AVy+b@J8H z4~Abpq{CocZwX`?T<48!Mx#OQ_V**#*8LI_-$+INl-`59{M%HAXJxQ1Q)Rd=0L9P$ z)B4zhZ}CE0ZFe0VTYKTCoTvDAtJbunrM*S={`T05YJU23mNU^LRK&r)&d#BJ${0?* z=lJ`7`MN6Leo)Qs_V7n95b~QgXBa8g=j){8Y@EW=b%I4$&<&qDN+AGoJ{M@{gaL(K6fQjQ@MMb|@`B`VRVpwW@ z=^NATEFKKcE^#{q3s)xTF(tW(mJYq!^Nq~yNC!zh#sK@%csIGi=TSAYNFmi^au z#o}A`tg*scEgx?0=o=?fhOvd-$Fs2eA-A2Go%QzjU+mOT3&nl^p2&;FtuwOr;n@Li zZ~XU@>g)nMT+Ow9y2vc|Y|+rwCyCG%2Co6EwEcVCInT~BV48dC?>XUEH|6W25ZO8u zNlC*UXkeaxErRH}bvQJ8kUBdX!Z$e?$)cu1VPcABCvwFX9Yh4HJv5(l>yzjd8KK#acC17qMPZ|ht z0`hzn&9F{{e(C z&+Fa+6slR%Zsir~yNM6e^%Z7k6#?y$g*L(Mxg`^T)kGgo9DsXKq$C;|%g)v=nb>BT zlfqxr6)HA=?@YCil#-V5Z)`N> zb;k$mi6%`5m^1v8i^kTJXBPq(MG8Z`#Kk^WhmDM=^Rk}GxOy;gr#}ebAHqbX1QAv4 zr((m6bom@P=1aun97tD+VO-$S&nZ_!ouAe$V2>L4@b+AB629?;jk5FmeH} zhmDR-Letpv!U8X5RWJR>nVzfbPIpSrkIl_8OfZsX zM&HuLK1AY^W_rVj^RMswd*9;EXdh1etS^3DHU0K&Z!tZj^tH`Sg|(0nSvk-VAh7WV zVN?0!5s}dSxO(cPDCAcx?^xZcz+kqNFXJ;QTX?V$?hq(PFojFMOS+4HsA2)8Lh11!!trGx{L@fsy5t;5+zl<###R(n_ zgwE$NNC6?CU2u|A+uP*k=6+A5+LHO_rD!Uo6h>8x<_``Gfa=bFW7D{Z{swsmZ#WY06@oGBywEuVszh>OH-X zD;E3hj1_(Hw@ZYu6;UAp@g2hq`G6Z68>6G2CZTosJ-zYHM$r`xMTlr$dd^A7SJG?# z=fist6L2l|;mVNe8twb)-)Mm=P8})IM08Tgl%E7zLuv?qa_ScjQg6URsFeq4%tnQ}%k%rJ++1{Eyk=z01)K z5F#4pna%w?~y0pcb+`~TtvOlNzy61o{CGJvyjj4d@x7Iiw;yf z+g7l(i6I~O_!Q3Iuj7m+hylX~JTXcwg-{0oCmrU6@kT$q(l-VDk!Rt1gH>+50|Pvm zokYy$^t5Se2Q&DfZ=XLuv9dO&kpzxk-tJ=PDOg(C2Z6L3PQ@m?7j-i~Pt^6teI6@B z%={Fq;`%u$F_Ztk#Ih*VC~nr)mOh@HuyH32#`cHEaJZz_3?!*Q#>=V%uy;9x1f2v= zynq0uz6OL?)^6`%8uyTG7UDI^A<{3z#h?x)Gx2glx?=JVlM8a~65?!Z&}4gl)s8^* zI6_`U46`y-F@%C4cCdAxIsjTcXlrSm?VodSG_PTidkOJnt6Rv`@pVd^lVAZRD(dW$ z#e)$bjY?Loh+m)$C7hFNDx3h>AQS=qByoZ%+08mcm#$SRk0?5<{?*gRjjL>fx%eOw=;shc(zpnd_SOe$}_|1R&oAQCO5d1 zrbb3C{`1eBJL-|xR*p4-_{023kf{->GF{~40d+`}XuC6-?3PZfoJ?(SBG zRpLKwVG+IgVP{8>L?Z@HtVvXEKm7XocG~;7uDcuK!x5Ovx*%TiUh9P&zxhtz_s-5vArcJ`7!OBR zHrGnRjauE%CUubHYU|#SiO`i|3CppA5Nkef^;J`;q@*MpzVRQ>@t)DFCnyM?8AU{- z?U|W*jr%!>AK5hrXXkX^qf$~*faU^>^Lqn)D1Y4!e8>4Ng7LW*Bb(-gg5{vxNPk!^ zptIg1!X+EES;Kn-IKf+yhz_yWM+itK3GB3Y!=l^m z?Qw&@u5G73p!UkkziS>(y^{-6;OArv-d|zXH3R4zGdmSNmJW_iD(t!e3bBWq6P~l|ICCDs3^X-M zPm@>Y@bmH-Wqnrd9~~WiBD1}8Amu)s$So;JJ$4eB6w9tDXB6eMeS+eaMvV-E4o(B75@>?Kg;dqF^|_|$r%(;y}7-ep}gfZQ>| zjR6rkAYr6kJ+J~Z1JnX=o=*?zFqf@aJ9Vy_`5aVcA>-?IzD1`z_&qN#uOWKvk_1cL zoO$x7PWy~mh=lR!ATu{7RW^2$qKYj0Jy!gwye$W-*j;+;;UN+yE709*&R)gbBMdwR z>r78ihhh!s#P#>ze^s#uc6F5yhC>>fD^!GmQ0V7zS|;LUdh7g^kdTu&ddS5N;-0&2 zWqskDJX-GtnkJx!qFHD0p@g)IlBtb?-HH$)6ij3u&@j?!%mp`(JzQ$CYt(H~0;96T zbC6;3{)X-&5k~HtH*fOrtoe!UecC8n@)o}+TC>(Z4TzT#W}n&x`z^@gBXj#^U*uqQ z-hC%6q9xVsVKaa-+4VV1^~LS5UkT#UA-Qb|5CJhUv?Gs<2uEggKRvLe<}Blj0P%~z zco?Az`uzIzOEcF8kRpHW1*~J`0$*uq>3LljQ+pC9-l32a&MP9apg)0#lyYmJ*T&9; zn49}I%K#W!+2*=1LRmS3n}?-B8x4A@csR=JvPkQ% zVQ=W#cB*S>aa(d-b?Gnp8ybDbF(Jq2gvsm|v^+c@$5A?SSg!xu*uW^mSNbm=Jl(}H zR6Luk>0xT>>ZsxX}UrxJptgo6?|NJ%yg=Q*&d zv~(lY!r57E4Kp(>Al-#8L=q{@VgOYDrjvvd#4ZTfHHn@5ANy$ABfaBRrWh*Sb zp}F>d9VpSBfB*-@TkXf2+{z5@-N%N8_tr4_jk-0|K@A+IAYSdp_0QjFoFqPCU`0tV zwZ}CZ=9t)`_R%+1D*wwQQ&`?glJrec`+gD%XG1Lf#fCJ$S>R2TGE9>5;|^N4Ui9`Irx z$zl5@7qD*TS4YRElc3B}T;tcTFO!q8bAqRir@NTNcZU40MTIsScAf^)aQ9*6{2eoU zz`ynBkARfkOjA`;GjU%+_7dzU!v}~+Pyzc} z8$ZHnCjfF@J8u?^J1zng3si<3(K1c<-7RRo@uC$pmKes}2UNwiwRfJF5ccTZ=#d$V z7wV~stWg0ssf`g|CLwM0hkmTnRg##UW|`E?@W$uHim?eQkUy1`^}I8u2w~<_+Qvz^ zH0=a_sh6jYr@mNOvCZi;b7gNovx>uUcULH~HVTb0ewHz`Uw#>0xjFIa6V+v8o~pD~ zbZiEOtE9JIU&ERD?6sRJyc(IC_qQ23r5<$6FVtbfl_Mj=MG=?f9)`4lA~Q15)6n(R z6qQ4$yFvtaKbWWyuO*YA&Xo8?-8DP@ILYL%+K9*)pW)hq@)d%7kg)x7 zV0k`4E;<+P(KIQzsK(#D$81M*SeI%35m&}#D_{Ti-;pJmt?k}pm#htj)&m|t{PT!< z8|cvw6EmwX35TN}U~gbmOMwNTg@$N(QW8|nl}u)d33~Mk!Nw+j@nljp z3TOIo*ev|1ph-pI=$&17I3*EXK<)y`?Fpj)tg0n)=RY|Yn0hu%$Y-aKvB!L zHcpxo7CIIyik}@f+;9|LD-B8N0f^xiYcO09Z_x7T!C#kS?OJ231(3{CazO z6ev31)qBTZU`Y0o=~Za2!#_-Enk1iIJhXjhr%gi^Fx}A^eA}ikd*q zT)zHwD6XemO$d?$&yEVNZIM@i^s>V@bl%O4DTh$uiVZb z?C(zx0(-``C0{^rZe*zxQ>cHld$f@us6jBh73K^1+`lA-&;bQ5=u|qPK}BF`0c7Dh zl|Q{irTn%xS5mECgJRJ=Bg`>jHDM2!S4=jNr+2i`qQs>lBJ7TUcnze`;-{7ip=0=@ z-%SjX$BdxXqACG+16k9P?3U&aC+6p6g_Qdz#^~lNpr5x&5O$|GXLomZI?<0mdM-Hk zm%%c7V6Y_W6sZeW=X8uPG&O!hGt5l=ZyJ1mg5uG=772R3a#?H#=h-qvYpb{RNst$1 zIS4@64BW?$vMu2M2Zy!Cfkaz<6E6epFs$9Q(#6GgcCIR11q|<(#}=||Y|uzxCO_6q z=HU4wzq}`H1tc1X%d&EH-D=4VdNniXh=xlnEaJB`ukuCUUD2=~#|isEmw`plfbfS@V_ydR7jIszat-mA1usjbP+qa}BZi>Kh0bT( zYBt|nw`K58L!vcIU`^y&d|Nc$m!>6m+K9$;IQ4v9PoQF!q(Vs{PjrUNDM*3(a9qZ8 z&!?Z~l~IUn5)UE#Z@JL|WGXyyCGh3r6w& zt^lsctaD3vah6}c>+@Z_w(EJuhh19t(ph{VFe1HE#n*iT^$8X5p38UDoZ<wmpDG?VTG`#U7^t`^C1p=dGvkiS5JV|L^Y87|gQ{}1SCG2LX&Xnc zB0cuh2CCQ>28vvaQnS$EIGls~HoC98^ILzp{WW}5HP?ehM+y3vdsHKlb_JDM zbnR}gn!dF*Gs*(ZEB6_3Zg?kdk_=((EOOAFfjvhjGCUj;)7``BCCVEXW`M$QFYX2ze1+Y#wENDs zleKotBczK%wX!>X8!igzNRR!Y89k+$?5hvsUr`#*eom+^Ei_5RnS{I>c z7LFSkSssf_F01ZtCiQbm09*Ip$IOA%-LR>yLm$%p=s>M2_Ie*NhZ(_zdGE^d~;$m9lgCJ zx%rxk4$h4c9%ww+mj91wE$M^aoO0Q(iW_$}NM=KHsHtacZECclTVJ*Rvr_$B~nk*1#P7Z41>uGBP$$X(7B{v0w{~At6iPR>RlFd)FMg`?7TB z?AF%44D0gUGG0%X8tXvcq$}PoXxSoc;^^-W@7V6n7lnuOH`lhxpC$crIicNzAtgm} zr5o2GExSh8nP2pIsi3Q&jcAFt=e!|rF^DKAn5%NH+&kMl)@09XyQDWb0k%$XEP*}0 zUO8RN=sr0>*CQw`>j1Q_r^$giF76-f#Q!5s{u+fq5)#VBYYU*Z=wDxv?gQ$i~rdOf!&v`6|t; zlGEW46^mT23vi1E1>(cz!Kt-PInnz=K}~ZOYCO5F$T)B0#!XG#6dq{qQcXw&idpR) z@O|u5&DvZ^f6Sd2Av!$87*bNVD?l`R+RFV;5j@MmA#fLmzhB56^?Vtuw|;;A-Nm0L zf(#bRm zu^EQ9eo*?=b!&A>C%_m|ZfBrqCm=$19!Ej3Qo{*hkF}j`OY_aubY&wWAx04tgk0F) z-QekHt^(S@g*SoD%1Y~O2RPj{H%?@Kr)`dWK&KkgK{bB)3BTW|NrBoP5J(|-JBUDO z>4Cq7SONZhqW?Gk8ZDy|VOqpW`;B%T2kBPO0!KS%-GYC!)4%N=eW^*b-mU5Hm@eJ} zt%+zgIM?Kou9@GPO0mS?lFz;-(d50vN1g^7I60}dL$zIjndw1*K4ImdS~1^67h|p2 zUn(3CN}{U}0N!`L4&*U|Bg8 ze(6SU{k&ypNi+mL&Caz0O#X#BTA98WD!xJgSZ8%!K#&<}?Un;(Pe^|le8&v0=^oQ; z|5DC8L2rc0GjrEvRx%ABnSzJ3)~d@LvizYiWB6UJl+@IPtV|CTMC7CUZca`c8M5TL z0dBt>zPBkzVnDGgk#0K`#$r~au2uA$^C3?x!RJt752!V85A17G}Gt7RI zqE>k7_+Q<(;HP*?g!vq~A7f|p*RN2^@&fn>D+->L8l1T&A0nH|%fnOENl#B7lG`ul zT6X*|xx5XR2TX#*#PPMYGX|z#R+bIS)l}24#M|YrcpmW_xQ*wb=5W&@l-`5Xw)_YS zn|Qf|7T&i2k8U-#b9L41kYKVgI%+)w1>oqNz#&#bM@RP@I0`e4H+Qlx0NTjx<+9xacd(Tm0GmI>Aif8Aw zd5;mB-H5IfzsRuEY2sR;Tu1qLpVlCLHAEXn3EQF~nf!yd30&}LP#1V91`_gW8^BAk zehT2Wt@*jR=S>}TK2AYOO6F0>cdE|SghIEhJm+=G?qPP!4QcZ@UgE<8-ZgOzXs;8 z2b*J|LJ*5l?j$EAh0=WQG^^Zg({`7?mssWu(y{6=@ZWNBj3b=(w~$H>%$S`<5@Y{)zE zIQq7A<~0s*Rm0u4@jZ^?YiZ6zhNE^S_2x`q8Ub?IV5ak~rt*AU=or>4zx7})6J5zO zk>}x!c!}}OJEhX8De{XxYjrKQHJ(FC`KshU`q2-KR=KUT{@U2c$i0`KXdFEKAb~kM zjV?aOjmz8bX; z^@ux(*Cwby;pO8K2>J;9&#Oykcmw@~l=q4J^3xB~`$$a3ROW46U3oKkoFK)GIOr_d zdg3(Yom)`jIL^Jcwvupk7Zzs55PQrV9d~+p@!r8zz0!e)?~lUBt89b;?&c1$;D27~ zU5WFH7b*vFj5OTj1JpKta9|))YPH6}fQQ*~dl;Xx-r6O4_`VH`A~Cjz3Rb$dH+PbjhDx!=NE0$PVQi1TU)!Hfx-KCi9d)DBl!HP zW&I@qUE!WyROztaW$d5J1E(zf+}HrEVOm1>$+F(@!7n`K2R5&Hy^GiN^tX!+_M#g6 z-O9?!dX%x>d+t!c-3;?fZ8HC|!; zfT>~csJ*63XF*rj^Xj^PUazT1g|8R+O>w8p*YM_Su%8{8a+e;So=vtL_}J$$g_A&UT?YlI&iYp@HHSG zqNT}(75Y5P-i9_Xj5INk*P@P$&W9%c{KG#QOdG~w@@l5Je{+|(On0davU{~YC$Yw_ z_bPbCTxmb?xiW11^Iaq++FDyBkG!eh;_lp8ZS%Z?R)5X-D~Z5s2Rr)*W2;M4XF0); zvhawA(t{&^Tpd_`@Q|#M-f^hVb25^W4%@^XJ;@=L&$V=N%E1U~YNUH@I?u;gKi{a6 zamxW#r{S-QWkT%kr&m2lymOi?&M8>(E_k(9K|lYAClCJWYNU$->U&D`&#PGEwUoC! zyeqvsFJyx{*!v$MR^#2t!jx{nUQ3X5%Y~M_D+ybo7cnE&6`b{A{^h3{A8^FM?l(w& zefQdGjW50u2~0XN=YYasQC+_}WQMA1cjD?;>9sPzF*c8X{P9Ocjb$>(3b9v6ZK-|k zxS1VBq_${hC0yqI_&RI$m>fEEXelII$}I;8^EYqy8zaw9554!XKRgsB6b2m%^unXA zscu$NQ(Hftn3c8AQxNni);nq+BwoO9VY<{gYA-Inb-azA$LH(PvxAG*srHaH z{VAcrt*@(FO1^#T&227{F??7LrNM_aq9PvC>c~ew*6`i(dl(1zm|XB)_;6dMAWbHR zSD8y{EITOv*3{y>-RxfVWQc&he6HkkiF3B{KUKULme`Q-IPs2vW>{Bxdb;?)>aXi1 z35MI}5@I0#U7jx=;*{>ZgaN;S)J{=kK1VX=Op#J6SJEg5i$Dh%DM4uz`vk~xiN>#K zWU@3y+6FdkA*N#o&P{%vT30NyHG*;Pa>D&jtY-)#HPa^*RwZ5h7(aGuGMeXU<%qZz z+Qe$Q`dzpHEzLz1)c!$!wF&p;2@wcEP zFW+*DbkszXn|aU-3dnI3Aqe})VxlsnN%D2$H~P?W+-ViLi-dJb14#z0eT@ho(IVh? z)r9(3*Q_!Rc;s5avhYmU%$p2hX77fuO+LsktDO+whUdO&Z-mT8gJdHmWOl!Fez>(g z=NJRxw|KGYzg+{{zOIeUg;4X@M}%0xbL}#e;AKgT9=POP*g;J*Z_Rev zH{iXMFVq)yr19azj;n=f!J}mF&?DtCm$EpzVTf<>rue@2{nxgnD@caaV8Q71^-oN_`7Z|v zO?a4Ngayg>yyC@9*e^|;?Jb44MpkS8X4V}$e57~l*>rG(`6}ku0r8{X_}3RvC|GvB zIr3zVk`;W`g%K(g6xG(dtbsId+qw-kSk!u-{gXLyI27cV}rv9zqJZ6~Lt)#`0o z^Rvw$d@-^O&qYT?S>LJ&c9u+-+7l%IvXe2@%FFB};d@dZ?N{P5DlMB*&87!n%6i1j+`!aX0KbTQ2%K`OpB$VSIw0q-vt zcWi{(?8PzBW5>d>W0o%vLb6v>l<2cI-Q<%j;5#G5cqYbLi$iMac1cp8LBe}_`)z++ z030K0F&Cpv>w86Zz#ZXkvIP;gBQ>q&RjPlaznwK)_JSR+$8WpBcBMvX@={MQ3q@4K zcJ>d6#N%PQBMr@mr!B2joHkfr{cN{IKtOUSbI$p1&rw~dP(I!_J-=$pBCk0X0J;98 z`1tsxj&iL{UaC&I+io4zg%;emCH;g*Z5g;KBPJ&HIWC#;PEO(WS+)tmT7@59c-K?& z%9n2*)=a{TC}zxyG}_8DL2>h>EgDZ;V`|eyD<8jWHa^0% z>4%(PaXWiqz%_VnNCY!n7OXC-=yn% zuv_3eY&GaRfV=p6Jk{Vk6#R(tHPRthXZ1MC#zD(tVsggD*$qwd=B-hYk(Prd^bfN0 z(~(Gl0A{ib=ME0L-h|vL4!7rngO-3jCr9|RoiCNgsx_At7rW$$;gvTX`se5U{ZrEF z!^~ShJg>WI-Mf&r;B7kT=s5Z`?I5wnN?fMHy9Nh&VA9<;-fJl=QaahTQ$hZ@Va12k zrAL2_%U)5F(XvSC?y%{3=9!u4Q%diq4y>6f*RhyJy>%*<@14LriF zxjOS*pG3@u##8a{my790*vIc+Q2p<5|NnX4eGl_}pJw&6k{*MXJ%eA zjSJOr8;0-xCE*QjOMw%b5m>7ip{Xl$SprK(*<>zwB#h3Nf-dnrX5yk(# zZBsWXm!+nVT$&;iQ?|ntw}L`s2ScbXkAdY__z)o$y>OPu?;H_m%AcAvR@YI=U98ip zDF5KL#!)CaIY#x2QurUrCU-HZZqOK(hiUa0iXJ=PCGa_80_s~0MV}^X2yyjS6`6_2WwLLG!2_LWw@ z$x51-q6a`RkDo=#w!>e+2Fy3*eN-eOT(%6`h zp+Z7z_jX#+b>R(7yU^g3l0|}_pWg>w%L>o9TDdX=QyXcSq(K;E8i(;Pt*`b$C&Ewb&&hX2C6Hol@#XX97nOn9 z-8t`IeY4?}9}JhkMBrmR{01c=P=*UKT}dNVRn;#F`&bj|kEN<7+#US#QF*_;qSElo z)?tUyjv`_4c_&ALB(~!6MlfxVAQFO8lmHK{)2Da)ZM(?Hz~UD?gt|v&gFQX(J1Brn()mQMSKo(q_;@0f(8d_VorZ$`9`cXExxyHc5Dn0f3QSLNwqIm9SXJi}+ zu3BY2wDzYTel+gdy3b^OK0HCk&E%=i#k6{8!vWvm^x9%yS;nId$qSv-+A{rLN@yZtr}@5lz(#9QwxqIVq@+*d#=p(vnm z*cUh2Vp`lLcdTboz<1Xv<<}XdPF(2wF`{DY!;7t8gDuSfiKY@N?C#vd30NuyaOxV_>cIZ0rIx&|lOWHz4x6{5uMbd1UoTOn4TCmFZO z)T65pKjP`Htqr)A(9%{}=_k1{JL?ORUUj5PZomN&(;1;hyZQlOnUpbq)X(p;Hm9~Q z+X(u7J&UgMRgK+yYJIa=eTfN@AJ@tVR2GQH9ur^bd;{XiMs+2{#R2*l20Lc+t}?4N zy3iu7(pq4kz}-?4n5C9=mv>m>;zj%T%2jibF76~b$~$vu?Gn@(jBC){w@R|zPN zs2HRB+v@1AU|;*W7?pcU1G=A#QbRvJDl?e$HoPy0?)d(q!ttGq8O>%#w+rW#eL;33 z=Xu%07E(bd0ru!MJUw0+l~q45d21-7-)U|l=7nU0`QW*i84Dk-QO!yOtn zN!A^mZMbA_`)K)%@k?NJ>)!da^6Jqb1qQINp0YQ)8h<9%y7ADO5a-HXI z;}2~!!-klAH_;Zb6pfOP1T&7!W@Xh6Pgk@eb;Z8Ht4K%}rX{P$D$4m>s=Rz$8-Jk$ zn36a_{ot>g@<}Gw-8q&cVdZzrk$Si2zfnoS2Ve{3It3|3Hb>o(AX8;7Abi zJ=uy13MEd|L9+9V&L4?eybEc9ptnBlu@rSkXdTwUX+&MUDt048K6!thTgCD^h*3Dn z(&4b}aC%~sS*}^Cwn#`qidcH$S3c%8c0l)ItEP-n`}N5vkY^(7^FheO7a9X^ctqi# zqOPuv5jr{+YmDj?FHl&__19;WGiR8{n5_2pk4yA72o>s{gL|PP0)?lnE)U)eGq^H@ zTujeGwNqVVa=N-{l4f06H)tp!u|n9&mQ6eJ5F z#S?4Zx^Cs7EA66=1bZL{%9|}!dBjy--7JVp)p+^M1faTzgwvFXt82>(w-N299W-XW zy~uJU3TZq&`?$P2D!C!L;nlXEqNBgA83mmS3t2lY?D;COADIY;z~}KpwloJM1I)_# zD6g~0M~2fy7iI7a=TYYf+|Pv@NEhb{k}@+gGTyw|xHjk0e+c%ub}|i%Zi~^ z12Ie?>_&1&3mkzzm8IK`-GAt&vN;*1r z|MLaI;S0IVdSHoDzWP9=Tz{2}pq;@~7V9$t>2TuUuxT2VX4i_0Hx7>ptuw!_yP4Pa z_K^`L@A>Wk*h4i0mt`h*Qky1BP3#MY9j&bNEgyax$rBZQ?^oG+iB^D|+SAi>OJ*H2 zGqWs(9cHzUyjE+p<)|E-Ty|yrj3w%W7Y7H2_-P98h(=bI%XbL_&a8(J#cRX`aZNjB zkD1izJje3dl_M?GtUJlTWzw;Qm(KvsKP}c&YB-;cM1<7zO9~g)S4`I|H7RMATh!M@ zk=>O+L!QaEXmSqdbz3k&BiPMc6LCXozX7jm~ zCE_Pr?2Y}DtS-P+-wTM#Qm4*g$KSRv44%}~$sv@l?V6rHC8W!L(T|#YS1PYE;AAGu z>LZ{Kqr!M$K_4o@D_2e?01&M+q{XeqnZ32UPMT9j`DWjv^<0<-GRhejd@36$l*e&} zN59HZzqJoWZx%EZ(hJw04<8oztTYqHwRugM95|`3d>7+ZYb0I#Lj!?^jIyt}!oK&( z(?L1DLuo|SF8ut8!~_xKVLw4pHq}@ep1@N4<<%y4F!;R-3fiwDAmA&OZbjgSqCCd% zlaib_SD^GyW;8WIf!GqL9a0umn1pP>RXL7gmpeu-*IE<))&aMp2jr^E(w2?aCJ$PR z?eH$Z5rsapgSBzkDcV!l+TJr;wi@eL6C9ERf*IW{(@iX1UCgRfkrS|O%krn&NF3_10JRZ20ht5P^3I<%x*TsMx{7`b*e;v%q8M64e|Fuo=GB? z6bF>ldlkH3XKS8{iKd?Tid(rfBK#u+B?f|*$Pka1NYeb`x zQccCvh?L5!5}}&=6iIfL{?3wo)05T4l&+kg_C?#?{yJxb=))^?V+9D-;*yf(*WR_w z%{6w6;=E8HhzR-V`%ViqhcuHCiV(9a##g-JPd}Zm`KaPTLOl=rm+5(*@%|tGy9Qfk zUFz(_z;3W80m>U!-6yh>|8aaEf^2LO4wn9?!85BFC0OxpVDdw>?Y1FN>3PdaxC-l-^8I0g% zwb$}czK&!+F=|%SJRo9b_tLMb=Ra=|^PEld8=+^p7ut^eOZTn}{03((kGVJSZ>Ki~ zlpNu3-j#oOzw3EX`G@%DucQ2bdTB)_Y_DlTA$IO2byn9$^g==>ko3?C31^ojO6#EB zF&yYH^55L6_844fQs$*mj8Ze>w1;a;PFGYtgz--N`_3Q#}do+tN-$m>S!$ zzGK?y{d>m?VCWBL2iCzTCCbxt6<=N%8bqbtIWEz1 zruH3|E3eT`{s-ao+t~IKeUZ4%61|#Q_h^QpFge{pt+z*lw$SM?KNZi#$R06lHty)O z+*M}BiLp;_e15u>!*0VC_rgNr4~^Z2A8^qdocZy8MR)#x^d=iU9;v z_lfK?JTlGIYZ`odp*7|aEK3By7=N(e(v{R>EXX%7q&a!0nM`C1I@bM0nLoxgQfqu1m*w#9c7T1|Hy@A zXPcoGYxBloDeHBLwf&X(^z;wir2&W3GStXH!D3N_b4i<*G6A?U3S1-&SRV`t@q#OR zvyE}Algonro1mbWg()gWJzwtj>WldBNCBOUe23)~L{=ACvP82~RWpp^R9RSJY6iTF zr*wS#`pgVV>qkfRSP4O~>rpyHd)R#o**0^m>vVTtb%9Xk*h67)r#FfU7g&9UVvQSu zwKzG81ex*ih3oX3g6_&gCUL5u4;L6)BxUk)tHf&$F6q>d*;u}w=K?gD{aPW_QC<%a z##@GH0<>??y9A38N$C0h?X6mlC5es`55?gB|Tuz}}bW3>> zHvZ!GwHl*=Cz2=M`$)Np3Q|KQ9OSKV{kMt4<58!JC9|=cGaQ>WK*G0c323GAF;tsv z5IcPMaLTg{{o}nAg_RIs%bCU38qG>CR^GBLfA-gOArJexIGQ^FS{qZC&C~{}(v)rm zGLBTeRo32@P0%4*#N*x`hT!ZZd5(TZ`~RA@gHHMpEy)QG(!B<_6xbBuvV~78Lr_Y} zEymE%(edi39W@ZFOP(`B)%UI*AYo^8x~ta@hMxKk|83O+#vujw9`9KLbWPV1l-zF9 znwhpd8hn~>_=#tL`F3GCkd8BE>>M0?qQ2+<5>>2x=%NX-;h?R!4)7q3V~!Ie z?FFZfHAF4!Aoun4d4`t;@)-^ww+<>wwsu8*=VH5icKFg&7<%_J1jNBJd~d~lAD?cf z$>;%wfP~szOFu=^w^6z(Ko~`#$451Ah^8$bqz2Ne@(?z*I^hhMEHrPh6t{Ce?F3ub z3v^P4Ca9ojAxe|A(ox#8o!4~yN?&!tr2rBre@j897Z^&U)j z0%Uf`8yg$zGY`mpg#)t4+SehpbNmnlryRfUi1ONQ@sW{{aMBDlc6QF{YEX>!SDI)q z@N!lTHFkA%)z{a*>i*pl{3Akrgwt*#ZF!5~P-xM{HM$R6)6?s`c09H=1F#+@X8hEG z=+Zhh+whL75M~#qmxqcfkC_O|TEt_)pY-}50!#iAY|?+B_H4zF1mA5{ zP%$5HlMRy7ff>X6dN4d7AYk9mgSPX%2Tb4rygwYL^M%+y z7j_8KzrsjQBK^pck_h}VZflmy{M6(?y}2W1toowE8c5#MM@({uXH z_XCj{G~J2&1YmNE`=XXs^X$t86P#)yq7xBqE~w0o8l^VcSCshgOHS2J2$YEZ_Ps>f zKT6e&b`#sYw=!chN09~Z?lkGc`~ClvKR$o#S{;ohqGFW$LyAuOUVD{wtGl^I#D_`- z6D58eYG<(~PaE6jSXtUJ^uFr)=xV@+dEf~*>@4T$p=KxdtDvr9i|>JNuKBvB?c=kK z+1hE;K^CIEaO6=*Nmb(EZKgqg%?xif&t|hsDG-UT9{{G)BY4s&S!d_Q#~%|t5ii8# zavpXSU1{NQQcGREpPEs5-EC&)R^M|@Y;4(O3Q0;87d4+eh;;KU>Qt3C(Z(`{kn+4z z%c<~O-#v=`Qv1Q!WYv^_`dx=5nbXH@gtniPiL4lH^#nH|nFXGy3U6R{#Yw5Bw+h;w zLK1~S6s(waQ($sm{2spe9~Hx{ars{oDt-@z>N^=T@GgtHx9LMVuOc#)LT%UN{iD=# zd^YhMUsYeJe2=cpWc~}ST%G0?)ZjJu`0dH*a=Np`jpLJ!TDR6!fvR^j8+6B>@mWpY zeFMNeWhrI^D&ecx@1#FX%G~IvD_WDMtqqkYSuZD6lMwfJ*KH^}+t+vS02r}X4 zUC=1510t*pCHaUiVI+zNwNz4Aq+*s!VtkumF_d66T}7td)@Rk9RG?X&B6?&=x2< zk?v{O$w~)X(+GsO*kf>Hgg>MVSl=c0ygylrZ#S9<*QRzvObZj>#gU=|w`r;;gr{bm z`vp&~Z{B$7R~6qPfh0d*qK7SQ_?MP4C8M3PYfDR0OV1?toOlwNr0;(G9NQu%cr$<4 z<=)kK^kUTB`CHFCIJ))`(KAa63(lb}UB{xMti=@aZDIRBz9&z?xwQ2VI^6kf&Z{uR zQ(E)b3^8h47UwSPFp5!OeQmLGBY*S(Hr~#B;bg^!dr45V_H0|Zs?#pL<#uGfz`&!@ z$(BJ^H|2pvYN_}qg-6jD^jri#3A%)1Zc^gnY{@5rHkSZ?lUu&%IxZ9AMM7=3X0%zk zUN}U-X4(nFe}?n^a*+?k{Ny5!=P1t2MGBoU7D!ZX97lP52D* z`IsguQBq+CE9iI9NIs1nikfrhTANg7xt&Y+%W?N%Mi)oUAbIsAR{Mnb4ll1!clQBD z`7x2@y?6tF0H4_*PrYx@?|>tta4j)8uZcvEF0|uKchNI zgYIbxnM`Ki2J`Y)$U9dWADJeB+HpzXnBYB*zzPg85 znnp%(r@O*ORD+D7Tm=Z?w#Ym>mND&&!IYY>uhpV zbsud%x0)4rS1zEp*BS|}D>G15DRm2ti8)}ypR+_|I|WgbzbOB?XO%DJ?$0;}#Wo9V+$WPo@aYf1wm@-CmdL896 z)HY)?_mkD{xz)WT6kqrJjZ~4CnR)1C_xh|3C$kMF?iqFYS98l!zM?8_N9j5Z@{)t^SI$Q7VmmBB_ShbJ)aDUfn`xH_bDSgi<-)P}JlNsGXtU)`)9NKKt5>Uk4C z%bK#XM@UB_)mf<9cT3`i(GErJvTkAYf~Th^a_ijNbdx9}F8ibPc zX>NUP%5dv9NOM_xMF!?N&W7!=M)?H5J0G(&asBDD`!@^R9)A7;0{}PZCo8S}S?EY% zus)F@?RwEQ0?vJ0i*}ZMQdX8p9X1<{Okek}u;H=-&SaBUEXtdy$B~~jnDi_c9w||=0&l=S3L`<*{zj0RQ^&6g z&hgor)$2;NSkvFz+r?7^^V)QK$L9+N1E4}wS@-ntg2Jl2%h%1!c#%V4UE^uuqKP3Z zRce_H|E4ce+c!`Ln?g%3_u7^me(XN#nB6&H@YP-Lt6a|~ront>G&DGP?9dnO2Bbu4 zDqcT#py~ELJ+`2m<+rfdWHx;?yWwj}>8srC`oEGh-3z{9pL8J~+xBnR=klv;uJo*j$T-Fcfk^W_vuHWzt`&=Gv|G6}TYyWFITwpgzL*3FQGhVSb<8Gw3 zoy)@K#)foleLa++(icGOD`GUh1H5>HJ4>=|-uor4w9{9m5%~J3i=Z z_Dx`~aHVM}(fy=utfuqfS9-DdCGKU6_h$k^lc3Iwg{~eu z`ti0054+u!a0@ zLW-$#G&gs)skWPIpNDwty}?a7eM7WG{2i6TRD5Us$GF}D{jtVZVyu4q?Ly1lbmYEw zJm5sa*%AA2vNRzJwZ~S1azO0+Tv@k$wx9Y^T2URX(=$K41C<*QHgxYh_W6s%0KKYc zgFSZWsbiDCKJZ@z?w9yR7R1g{inr1a!5#ZeDmM#TE+ei-*JucO`h+gS6!-I)6-b~!?SlYi86q}Q(>vVR#I6iRnhQc?m`Hz|E|Kb)AzHNp^GiA-(VfY2wy)0z(g z8pG_j3Ez#E#!c+m=~Bkpl)1S%vnv2_7Hb|gMxji`7h$-kCbOYVpX9*Lu90+rW4k9$ zaDLtWk%<2L=?{c%GV)l@;2I6RCkMXZsery0r^( zbbyIIbmMkFH|FmKhDfj`tq3Km)jDvZC56ZG*TU?@**3)3*qHVKG&S+RUH0L~^;$-V zmHV8>4a?S2;qK*r0vrtJdUF1F<2-BmxVQh^s!7M}N2u6}Du6T0X;o-z)m z_BPF9=YS-#QRNxrSlZXn(jd`y1+ZM-zWvqy=KAd!$jSJJsKwTH zcX!K0z7G8iHLP!ue0R&EnkB>qT0}Xl?V_kT9z=Wrvv2kuN zt(CZW4PB^|oSmIbOt{1HBF_W{H#tL1kK7NDISQn-v@99YUjPdIg*VFF#}Sc@x^7js zrGrSP7l-TF@1OEztrokIHaL1anK3+@t`^MCHOrQ)KxC6Y3|4d{Rz@SXK;V32$jGLIr)-f@O zZIU#!lClhpl1pSOwqBQ9OMU-d#x{o3-N#%tE?zTW^S8^Wax>Fh zt{NG=)Z`ro$h$B9xMR+Z@k_|1s%I2ir$UkYDmTe*f~|`_nTna{Q{$oDS`7fkuDc}? zNzj)bKBoMu7%K2i3CzvUSD2#y3ZbNCBJiFAR$-Mabkbi^!z+umVM>y zg2Usj`S_w{7VYynJz+i*IB;$~BG!Er+hVy2=W#(xY4K^if>}^sKsK_d%zzKs-Q9f2 z=hKsNBn6Hh72xM*>uJ0E7*~bU7pO1UcEj3Ykg>VSWg>jIk;~YUXn2Acy5iI1tSrqK zl`0nC-Um(gJx@&SqQIPuS;r9Lv#FHQ&~QytP)KOYQcR+Y-KjNH0Boo`Dk?~+oh+@Z zlTH=e)Kga%Ho|sbbN+B&t`rD`^#x@iA_WHfHb8H%2DnGYg1#uc_OH1pCY!+<-l37Eq{LD6>?6yO3es`+eS23{f zUw$%bK65yMo%;~tBW`9xruLl@)34RAB&brB%{#jlTVL}TyOEr4@|KT;bXa~{Z>Mp3x}2Ho;kxwQavbAS7)$lm7&)y1Aji! zT4JoUv%k(g+e%c+c-w%Ig2^m{ZVbfDMV>z$J-j>tTA9gDo;(5S`h>posl{s|sdU;9 zB>bs00R7icTL-CDckb&q9o&5DVe)O)phDf&j*hD0;*MfjJ$5JF%J;)!^1Y0Nn~sU6 z-DmIi?7^z@VpOTXtA`8HrIm)HCdBlVh)~f*jY;i?x9uK*(#KbSdUpF_%0F~2*EWwV zO1Z~f)o|A1iDvb%^^4r}%YmUQQKyUSg?a2W2k%!{^)v~HogT{GwbVYm0*=sBMz_Wg zNRgT|r)_qJHs!jxEok9njoXG3P3FTFwMGrGIG;8|4`Wkj^}*Yd=|FBj!qJU(A-O@m zK9qL}X^_6)>Owvq9+&=~mxeF}8${BZ&061BbmCQrFpjq$8v9&1(^=Ga(Pgxw%!e&5 zL_~umuPE0&c4KRTYHVMiCANfn*t4Du5{PbB=Eoghi|T^E~6GJ$db1Qe22ZI^V*T@8;TS+wG7FFyH)0 z&cfIk&q1a06vghveA}rn4FW6}SURAOf|4p1DsIO+KY<)o&jAyNombs~q?rGfn`A>Q zYFTDq@wnh~|Gw*69~zCBJhHkXr)09Puc}@rV*B(^*u9GI0992vpZ6tx;kOO&$j7z32yjRk$zS))X3ZebthJqPD9ky*matOyeiypKm}i0;Cu0^u>skv zlD&Pb%v-k>*!NXM{;dT$9g@>X+i^!7_sl!jEqgu&wcpEW^@vDLMEV(ozgtT4M!I%( zB2G5&vrfCm58}{1EjWvTJk4^p3d?^NoyGNJ%-2 zbzQ5+9777TH3K~5wuXYNh6)EAQYOMLvZEH#!4-<)VdbQ!&1POn4JHO6IcaHuS`HL@ zB+XO~W*@Go5nWCypIUxiv?axarH!=E?!^(+A_NA1TOY#1K7}>sQFs7wT&)nYqxMt2 zmniCSbp!Vdk{hTt8{-YsB&DP{rX+*>4EsaB3uYC&QH0gXY8)_K$Q?X!r`>v2snYJT zv+pSsN+i;?^4n-5?sJFNQn8SgN@FG!wZs>c!1l(xAqFY!(mNA-{(g@Mxl41y_wecm z?L1elv!8=B#`9gF_tpZq93S(;OeL*TTUD`yHWBb9$3p~jOKOU|{k>wefZrxzSlhta z;LWFizuoBGEG-mY3{%{r7XkPr?v%0RBzuotDp2b@MHu2k1E(AMaZYe2EBq^fU2(7#IJje4BH^p^J$ z%Dpu@6tS@PVd95SkSxh!e(E&IY2rl+d5SvIaq_^csq(PaQ^W|qQ4v4{v!$F_P8BV+ zeby@_B%L?oa4>x80Ft`)FZ&?&sk($jYysk@*J{-qwep_u!!sbRo1Pw2{;&~+hDO?8 z5)?AcH?911)hZuP&j3$PnQV6CX<+fz7agH^|N2-dUu0tA#EW_*nZI2%o9!RZ_qk(R zKvv#lcQ)tSYs2a3$nb{jzlWoFLoC=5N;<+Wi=iSDsBTzd7B@WKJ%>%c+&0pFrC@&(Z{I*w)7`WY=TCy=9>b2Sz zAa8lwSrIBKAS!w(ww8+t>GbGe-t5X>%`epZArW_k~ua5v0BcPiN&VQtw*$f916Ji`=wSyu9 zGilG#NZm>o#OtrECTp`o`C9g6`<^h*$ZHLOGgkF!r{vxsvFIfvxNBdizz#+xm6hnj z$$@=E9UUbzwQBS(R6P@6-Hq#vTsuI33u~fsk*M`Ke=SnQXiw2;QfZ5*wZp7(0#Q+8 z=^$~)Vf%TRvqe7x%H%Ec5a{#x9RD)?i+=RjyiEDB_|I4V(_{brfSKYrWpkNn8Fpi8 zXn9ML{bltJKa_90By)RhOC?MCvsRkG+c(-GJ74_ycH5(!#&4%T9Xq=zZnITK>E(Wh zmjgPds+wy}D^xS=Ibn6q4F!qkq*UO{Ys0Z&x@30mg6!mr~dsU`9JG2ttr?+!k~d&ldKvmL?LKC zRgq`3Y|014a-;qNk=~0SHj;}RJG_Y*aqfCsL@(I*{2}g?c_YnzZ z`Mq%%H^>0i245fcK5HCy9N^4>7YkM4lHf z%J$+ES(JqKO7vMdv1S%jgOwQ_T|ho8R7*~-7C&q;TNl@&KagP?7ne4D6>;NLTe}FVCvgt=Ihw$)WwU{W zql%I*BMBKgr?m36w#)8%pbSR1T(h(sYsq%_)s7G9W*k!b9K%@ zeze3l3PgyXfJYJ{zFfChLv7DHKG>4I=rnCqV#_bt@-aQR!Q>Q*htEY|4~!SrR9%;VEUd2LQ!mjCUeETC_AbkT9p_?yU^k zj_u1dGt;K5bia>-?d=BT%{aW_h0R`s>`YsY$m?%HB|H_{BWG}4gObb2%Ry9ggqXz! zAlLyD!{>>9Mw%25P(e&ZDV4-OE^26qAB9!no3u2$vGW;kj(QGO_w;!A`9rUPMsPT4)nE5m6uojA_`5uij%o!h_pTR%1S_iMV*n%@2@8g!<)xh&M_`t=dVu-|(eiOh^3 zRuqf)azH}@h8jdaM-deJHB^=ZCeK;7lA(a-9tCX6U*K*Fpm*fY$mEOMQ94o$?H!xR z0o~n(v(A)ou5nY|`j6=d_kldkQ_XWD1)652GmOyuZGLfar!fPGkHFgv%E|MQp!OZ2 zca7Ku3LryRZ_=E&znrDDKLG)DAD?G44x9s0MteTu4WQTT|0t9EsLy^YsO%Ay8X`Ik zKJuaugUGZ-GaCQ%G^~`I;YC*_VJSB3+sa>hS7Xd#5t`UhQ)KD)*6mNT4=SIVlQ%ZCjO%4e&&J> zJsll^-Wgx^TXdEDI@0|Yy zXU4%n;7XR}yB9{~!ki`DNNcH6b*fjKv(6vfQ8qf--*#D`cL>Cd+|e_Eye?mF8ea<# zLkgiRbPy29xDEJT%cDfu6J=Fm&+fP0o3DHQdZLOUTqRtD!rC)G=QEQVmzJi&#Km)$ z90iA)8s@tL4a&nxyA_ATK5AM;grKKaC=gZ@n9qtHg*Z!ME{%2+((WH~TLS7XPZH;( z_Y1g0E!t>!##h?@&wTCxxyhnir)JRp2v3VG&6VoD>Xd*9@+YkUXz?vWHxa3rk04S3 zGT@gl)2~8;n+7bla;*E#i{UUpv-$!c2@t_#5#2!N6KJal(_@r9LGByr6~oe255}}l zm}3-uVY&Jbdgc&ssIIc|u(0r>sT6)RQ(eOx9>tGb$bc_BrSa#_%j-|{8V$TZw|-Or zilk`?22}L^mk&^pu9$nWvhM`!GOhkpx241 zsVLxM$$3e*<60vdobmPVyB!ED4Ws&e7k>G@R5?hjQ>CSSL^cJTg>6p^3PE>0m`q~x zhL40H|6`Pt>U;X^S!a{kGVysirCI}Nt3d}g0TO&ek==4dY=Xg^mz1t)W^Zr5$B);M z5wE##w|`0Kzg|^L9`c*#-q;X}?tpFMk)D;+)JFO3$q1@~wu&>?fl3roX23|YFtf8* zzT$rRt1x$jMl@Lrcf8(~ck>#%Tx$e0>*?JmO%EEKs{yq@It@}wFV-&iFst+?;C@J# zOiEu2tvKl#Lf==;;l!VTR>K5_d z=R;4iFNcfLB<}+zD$CLL|E<4o9zRl%*nDw)qDq)xaxWvEV(j@TXjjc9uFxL^fC zwt12LHoZ(f6T`SLrRofg`Q;Fhb2Aww3J%lC$F+vhK=u5Xrw-XxRAImjU=Xpz-9Jmw zUBgzmAW)H(-FpA9uLYWLOP%T!huB$5=Wn&6$V7Yx-w)odyo_CYi56-)-ci}x-^}{tr|B|3pN~6Wef#t6=^zP*e z2iU$E?)6Rn=}sJ{DM#PutyDyf)owS~UnAfrY9L3PVn)SCl*HX{pDi31OT?;|H1D}x0&MWp~oaw$E7k@j2WXFH^W%%7w%%DA3pVLjcNZD~uj77+?nBR!| z>e2g$jegq~?WDC?ahe%lSUdM(Z`{4$MDcB+OMNY==YP=Jyg@V1*uvFrEzyoFMT{t# zgCfQ?Wn~I7ek?PO_xZ`niX*dSyNdG^7emJG1{2#?=pLU~UOM+U8ev@7}!`J?V|oUh!x5&(!(}hbfBOW3}vSgBYaW-&-@N-+%4amwAxS zOjL01j;I(od;~cI;)NJ!I^L5-X`QV$=T@#q!GmSJAGKlhzxvG>uqZJffY`SmW6ZT z_5|nokXLLe1nu#%M}pR&oxm~!o8P;xCiv>z^x(0#{4(aNSM}i!4K;luqk}}xl$6|w zmqnqrq9h`RKs-82pyc(Ed`Ma*lDy6Pe?jfbsx9>Y3H985;wyN)GGQwE2&PD?cq7kl zd&KE2SM62+YI1IvIcT`A`E^DHEAh4hOZ)CZKc%WB4dafR`~1bU{wOIqt+hF->4`tf zn?pXamGjfXi=!RPGh)x$h#b6Q4Mxo8yCaq1ZEzUqCt1QF)oV5S6fktg?$<<0Xn>Tj zw(%!(D=TF+{mYksRrAOdUo{Nl9tNiLVB@2?Ud?&?casLTt!5*tfx}C;?m;381Ss2A zha9K>a_L0A0nE6ds$YpZdeDEPaz-2~c^k`8*6k(UO?zb=A|W@oJ9_Z$5oWwmjTZD^(9h24j2Z0=zg8+ zQ>7YvA$u3j*d)6Vjy)y{sCT&hxEA!sC4O1H(dE0wC?lH{w}_92hKFZ(;;7RxjbIlM z6o+4L5VQR4K~KV?lF!kSKKWTQl$d=$(r;m%C;8Y8pkdl#E?Y z=F{Z5)l?*}ZXN-D;i6imHEN=30ITa2PCmOId_+p?1Ds$I#b+4)y+;?p9XeHjv!e-u zkH&)Qks#-#h1tf&U}J@!mE+(t)X!6U|&pLKSfhn}XYqaA```6n+BAx`*#Lu9IVSu-e1vc^V-=(V_@;Xsu7PP zP`(KX?cHjj%sw0OR=6wnb;B#_uW6A-NYGG-vtN3!c-aUQqCfk`2?3gKrbA@hj)p4l$AS_A+}1g+Yz+?+k`UODikR zqAms-(65r&)5k2=#zjx#h%)Fm>ze}l)urbC{+BVG=@Xw!pHa1E4TVDjmNIRxUM>Ct zy~e*YIqM#wMs6b~pXjyjr!&zJu5$@RJSjQ*CB?)X2mDxKQY`Oe!%ETn6f^A6nJKrN z0oGblKMP|4R||k+PcjpHi2t3*rvdXP*T`&#@u>EvN7;P`TJ0iM!bUwF-Uvwd+H0uo z-#k&E(ClYrXIF1iWpk0s#PI~QpC1*W90^9jVfySB?xZg@#4pRM%krEj)=|@IA|!wB z&u4tMi#!jw=9}65xvuU}3Itgu`L@>9U9CGWIEE-j^KEI6|MzdXQGo)$k72_GeX>>C zX`(L7=|lBD7%&M3J?x8TcU&;_)8Q8U!HNcxa6naG64#5JRcO$%(;*Slv{zI5a zxS`6puyv#8-qVMYfBqlc8hmR)#DY8_H=--hv<8N@UKSw5s>ZrXdCF6s)0W8k$(R1U z7B4dFF+r~K71WJp;dm>}YOGNMItrAo_6z|aFi_Fd6KjW)rR7sMBToH_%O za$214ZB&=9;C{W6$@Q2#irW?-9)KC*0ErO}Q~W^@5r_f&I0GNy5?fNjZ=7bsKKmIO zT*t@Uyu1$+U7oSaQo24yN;w9V8Du(;f&ZkxM8%Kz9jvTXQj10ed(6fVAQ(*OP^d%G z$-<(YrlMXN!DxEjj){!ZbF>Wr0AL%4$+nM;RdZYf%j31k!m)x7tDE~0HbAh=Kl7~i5EeSAAdUO z7o&nWb9<0c|6P7)+);n3Qplc)+M(ni# zL-#bLOWEOM5Fr77r@81y!`7eLhPX^nN5jl)$nO;MZYQ5FW>*GU^*0my5#kfn zo$b53or7Z@5mXl2K6_xF@!R8h!Pv{#ZE1^T|C}0n^7k(5gtdFt63kp8z7&(?_#h)A zV|{XFMq@<3u`}>Qv9wBr=IsqP_X+T7ZMyV0C}{N1ZXWYX4B?@Y6ThD^(42c)7_su^ zzQA#`+EB%R2qWs;ABxeFzZ+lqzq)(Ns3_aEZFuPJP6-L=kWv(oQbJm37(xU_q!kN6 z7?4sr1q4w_7(h@EB!*7uK|vY}q!elV_Tlz<*1f*>|NG5Tv+SFfRT#a3a3VmnDBRCk{uHMfSdfahUX42haU{V~?vocJ~}OiSgNt(W9dlj5Rk$ zh$ucoa>m9LQk|J@na`dbmJh98Iw%*$V?*oY7`r#LzFj$Q_ zYgr$irmxp4$Xj;A2U(Z5n-c|-&wF1A`5hAd>#nF?)W{-0qfVlx3&|MqY{c>D5aY*g#3 z204Lm{(E1)cHSTU1c1te6PIj6nJ?mwZd86gWP9|+?twJE(INs7UyZ@!YC`WbhQKE) z-$TMcf(*pcPH=Ot;JcmH1t|tq_lnbOtSnP}KDbe-27Yy|ZQxIk(L7k5oXpw>o;*Kt z|LwD!oHg;vMC>Xam5V^!GL=goc~0hV6?XwPVVl#&+}s>ANv*aM7K6=l6ie~q#*Wj$ z0F&ZhrKuLcrwGKae};Avhi2b+DLyyCSJ;&%b%#dN|2qa?tI&%Z`KlZM?SpDPIa&CEJLl$oL+E(hvxMqPV#e3c3 zFE@D!+WbWDPSU>!2fG;hJE#R%vk+rD@mfJ$uMI%su=*YDaGrmD&)fT>VT*8EanR%i z&7b~Cw);Fv2ed-ROl1Uu0FJ;O7#1KFL~cTgVL7|HTEU&`yvrwO#o{?|ie{}ps$;&4 zu1tS=`}O}YD-jMCTEfz}S^ zHcsE;4TO%w+b*Czeb!6)9}l)E^(m%$@mJUlcX#)S%TN)0bwU)LNv*yo%#im8DwCje zI5@n{a|8gZI{Bf*wRf}s2yy@Ucyt)Pwg9vOHBm5&kc5XxDZ8;l+a$$Q17@Z1JCrcT zy~jsfDX$Qc%w7`t4!sNANqbu{4M4U`Y;#Yim`W z-GKtht;U8AaNFR~|M^@_3L6`|#N+!;d?Bq6@R-p4?CtFx*zCFmFhRGT-B)0ul0(A! z3Nm_b{PfTIx^d0;^dFRB$#nhO%F4XyT9F${___}Kc?Z1=KbeXpACzk_!9l(E=UEF~N=&d#we^jSbu9tea!|7S+jkRR(LKH; zc+OwOA?+ab?DGE2hQ!w?ecUEc=)yM|0(H##vj6^$KZ}E08ZUuVgu`9HdM>hp;}hKh zko>P~u0B4ptkDo+x2e8XL+<4`;#;0Q`#ah-2Cdi{W;dzIK9@mUZ13O@{LP1Is+9Bi zi_UoQBaefa;i`&?*-yT;lXKgksk{Sxo)hOPLF;9F>^qQox4wgD12%DgK;kEGIYcte zArgD__6N8rZPIkq)L(zjjpZHRkI(c!;oI_Y5VH-ZVrnuVM{BMCT(^82sxpng7l5SQ z+}}q>xaag3UoQaTgGSP@e1Hwerr%JpfJ4 z!H8_&r@Ave*0L#qbKuvw5Tu@tzCkyyyVlzWKhFm}g2mV1UTa&{CO!TBmQlI&C$B5V zv~7epr0xPV|JW;L_KkG;f>fcSqazC14Ey`{0_+|)_8pR4jRNjmU!+9==f`lEGO3*U5MUKI zy1!1ue)w>{!DFzm_&807SY`bu-G|8K`kx)4uJn&~ig@VtFTIFBO#NdIBM^1}bS4o9 z|M|ZJGaqLzLo(EE*Ji|WSet;voc^h+v7=*afPecoXtJHRXCr0tw{&sHd_Cdv;nxe^ z?<#h)4g6uN&lAt6O^STHRQ&$?SYW~=B!<*zXd^&aQknaIU*?NzK!bt%G>hEcSKqMix9IjfR~n;suL3Qwi96s+jgtPbqdtQ<#wBBhi_j! zv^CWC`0=K)av;lXaAQTTP%FDG=6Rx(yK4t|>a9`U#b>5hz~PSGCJ z?Rr@_3AWG3^5(7}Lgq0~Xt6cn0!f;KQ&}x9X3Rz4WI-y)iafz~7XPqUc=*PHf~YGz z89l;;Q{g4WKC>%MT&CbQKxox8^>Y`k7Dy+^5?Hdn)OB<-za>GXA(33V7p^5nvt~gf zY#VYyi+n97^T0lH)d=y3G;nD|F#U|h_N~Pc!AjFD<8eYa9Cw_6BLHK-7rt@BupJ@@ z=miIW{Vp8fh8GvWq~5s}vm=j@can&1x1>kYe0x~^rlEo7OJhk%G)r*tJf@Zp)%Cmbs;_)v)tjRJh)>l7`Y^_py|yId6g|iB;N+M%h<$gIo##Ew%pY zI*XM)d-=wK54+XY=R&lJRH~IEFsXVbcvWvV-Jz<=-H>5lT>(`70BduO)dvqAf(rfa z=lZ0H=JDMKriYS@AMz+)Ia;~fRX(U_Y#gw@ki+<8`ZsNnGLyNj1l5-1?O`ZNb>dea{Tn;P{cccHnp6QfD;2G;KY#Y!-c-4u z?8h%cYavk1R!svb7)yN!&EPrJ9`su4jW*`{yZHUx*$}K(W2EotPV@Ug?w3sNaDDab zS4YVL$w#RvDVA4u7(Kwfz6i9*_MIN-#uvxSYeSVRX8c8Q6dfJit~qo(m_6Lz+q1l4 z&t-91xHP5Jk+B_4D;GVgT#l5>9DH{6 zmgN}47-CjiRK!gEGmlemRuaRQp%_M-XAe#MD@ykoD(I~hnnQxwqW*fS2JQ5R#7v#Y zigaymYuN|jf0*lNwqO9dZ&s8L0zft0oy|q6cJPjYgQgmMWZND?!6TA7+`WsPG%+(v zj7o|9H2r?R98skE=A_{FsP!Xg4Pilqq;_ai6iw}s0Il=#*+cx|7hCV?DfYyeIZ{tw z1vg&s*&B8;Qc}~dJt!tkh|bs-IM{A_PC2Kyq~6N8fykpCmd%)gXIltO;^T{&yiBYLKBxMYY(0|43cJOZv3GwnLe}HCOfmXY>^K=mf zXov)VE%(O_3$3lhXWi3MQxe68e06IH>Ub5?zX=UqPh-ydz5r+pRD7$>XlM5iMq=1c zrN4lA>Z$hWI-8$0-$W9|p{Py_}i~v0U1UzR43VW@tV*=Rh9f0W3Cuu zKzI&gI0X*B*^34E>{lxIP@RHeVp8`AcwV_i=VF~sba|#`kTXZ1G-}2AZvR?}Z9Prl zg+v?H>)Z&V%%Vx!Q9db*7>FnyaIHnVp?o#$ijWv60vN-o4&C&^q^OEWwh-<=Ti?pWQ?vUta~ix%sEu9hi-o zW}?8v$;oD^ZOo~mFIaR&lrzK2vJ^L*40R^Oqe=wH`%62gOcrj{kXNehU-a^l)4J<9 zbS|dlLHtgV=+$CI19SZi$Iz+@y1XXm=rCy-^=0mNq-11FpUIkD}F;0z$Z=K<+v=5|t-Q zpFepq&=pMs){1g{87xS*DhKw-r>@T~#toh1x$-~HlhxexUD6}DuDM0W*H{wuu=UpC zZhdbpZJhdpHDUJiWM`)N`1*<@IIxuquP=#F*Oe&UCKulGVUs?0gXhTe@A_N<6Bgj}`%`$|XSZ`-td2VJA4 ze(7l!mr-^d?8(kNBUE^6Vy6FqkHki}*NPxJj5AG6{?%$116x7S2g)6JAZLZZUTfhi z#hwq9ot)?@!H$YT4x0O&Zxy9D852RtSGndeGYlz{iMeVT-+c^SOD-yD-G&7)p%c1u z-_9$IKQq%7BRa`Bd^W8ZXG_I;S%;tHUANx7)a&4a^&}jW`OOGR_q?3SK}?;95DuG^ zpytZq))`qfV!qq8YQ)m>4IxvS`r8<#QT9=4ShGSRTk@&RqpM~r*d^};M$vT$*n_p2 z+5z=sO&ml=RjJ8(JX76~a|9Y(8+z^Q1q7|!#7GxY9ylekwb;42ThlTVxWKasi_*6U zlig^?fL%Dms;?Vxm6Qzk$S}X^*Tw7$vp#*NaSnAJ=-Q%c181jPJY?EFlQp6 zJ2Z2=17!X$op@x8y;5A|siE&-jz4d=PVwib3pDpB^M!i-YRGk5nErh9e${0!*vA<> zu$~_nKx1HcdHXuAmHSd2%gU(P<5qBxT11{alBfFk`E$?n6=9{~qNZ|7lA#a!=2VIt z@vB7meO9sx1bT22$bxai|xq+H)&6%VXh35GG*5ppYlA#YXB%(OV$^DViZ@~ zaOskSMCtxHnKtJXOuNX-O;`$OgxT>PhyGIgg``OdDtL0W3PRlnZax<+Bz_1p4T4$T zDJ-#HUYAR-(9}KgOtL@GdJ#IczLLMSFLM=>7~*-c=?9sKOb-j=U7hNPJ`8`OeNx`3qjziy{41`kl03 zDj%09@=Jn^bP7J6sV!A4kYIf*!7Xm;VsMYCz;@Zxs?$M2T&a9PGr=`l-L6=G1G`8d z(fNzjRVGPZQBl}>Z)@D4@5n)%;FYry#eiQD@rtl0?I^c^tkRR%7lbWrCBLDZeb0#S zX%tfPu-#4bR_`xs||0dk01D>c=A%()V+;#ZOjit-IC&9@0EA8lj+&|iU) z{^hyB^2aKz0^XKK+3v%(JOpYf$>@)*we2UV{J4Ug@`0k)Dx$03=9O^!FkGHWhr30m zXnG4vlj|o{!Fcnh{Krtk1m&ng1eTN`<44HEgjK(jy7F1ROiZSuTg^pSG5fo}UR~N2 z%~K{3A!WMU{81%h`?idRoRd!^YDIXKj9|uWMHnU}>qp3>>I70?^xL;nMpLcT{mKcB zt+tCro=Gv4DXz#*Ri&-OAkNqA6}lJeI<>G&espzPL@+5U94RlNt2o=qB+NUTP-+_U zwBK4`JGq&`GDY=#`5dF+!``+kC@em44d)v53^_KEA-;2se-GDS&|J0T$=%e>>O#Q+ zzx~GLowX!G+W$aS>!x7XF87NOz&YH5Q&N){RS(qeC%~J4(ATxMZ`gwTTd5E;s#pMZ za;X|ft5tc%beNRh@FmEoDsIE6WKQ1>T;2#*kcKFfh`F9_LEqlm5&50u>m5sd#DEPd zOyBFpT?>YG)1p@EC~3FWu?`T@>C~ZE-Uey60Q#7(&vAR~(Onn~Nhf8KZ{T(0ap)>u zU)rSR5;Lk{5c9~Ud;G)fd4Urbs7h4C`ucSwA#u5W*%9n!vZ%DTZz-;E<`cT@J85N^ z=Q~m}$-%LmWknydTQWy|)x0^Dj8Hj(^B@A7K{4Y*sHimuKDf71ob%&}S!ZH}ZtyXU zvL`3M7nxjCGUf5|D2AaTV+T^OouX2l1sTI|*bU0YnW4Fbg|MlU^WDozWaPqNYarjX z!iF59QeYXd@&8dO#O?LxFTkTLxjzL5Ca$xL`quUqLBE!v7yFZ?;apG5Rc|ug>{n{Q z0)ndBTCUk8C@B4PV?#sVSa8bk@09OYxJX3Y@+TL5^n-qZtI$mp$~!jfiU1WBo#;mq zTN%OR|88Hi5cvzKb#qgf*rfCn4s7Z~D0p{*1l`^QviUUHvpe1vo>t!JVFRH#C9^OB4VrOvPU7v&)^*~C^Sclo9 zTmYt@(fJ@ngy`27@k`OgLVg6aDoM8>NlLcH9juW2<&`7|C%Q(zdGls{)_vM6*f}Jp zSB)t@LsPMZI`hMGqu()s_P+%MX_fY?v@s!f9zN^0EgRJ}CJ|lRx=Z-=G5Dz(?219= zx`;#Q=(R>{^*RHqFNQXBFci9GZDloEhG)(y?Uyi5G_lPXU(1-AoTOxQ!{JS^T z83-!X%w8d%jv?@?l9-v;rLxg}yTqtckCqHQ-N8T3e%k2f*Lg%-Y+IZ5A1cvwK^vV) zwrXOV7qbUjxp_9jOPzk|D+wqDM}Pk$y7FnI->zX4!WSn{8pKS2vcCe?U_}Nd0>pk@ zHJI%#2)L{XS1MDqeA`)vHS&1IF|-R>OmJ;{|BOzT@|tAZw>@(bF11ifzH%Qi zjgTAE8C+-@zs%|=IdrhQlSMBHiw^OL^OG_tcPhmiazzlYuC-k`A8b<1oxS7O*+{O1 zI$BEW;`XQ$cUXRwg4BF78zeQ5^_{}7EPmBUJ3mEc%Hj6xBxH$G!j;?4W?n3yqAzO2 z??UAymwUHq?2lHdGqLgde6_tsIP?X1nJj~y(~&{9fk(MxAW8qM%b;zTwVy6?c$ zCBlK?F-2W5?5i`f5jc|l0eXX>UK%VZQ?EH8T0Q=y4#nHQ7OuE33o|1tJ3E#&`lb)4 z_*>zy+gNFM@FZgWAzFe%W3Kav(<2_*^>Fz9&+zLtm*W!jFo7 zLv2%Qd#yZ#M5W5{&O$PBI9-})NLky{Q#_(NM%=T&3FoK*OV6-VTeBmA4W3$Nwn#i4 zh&8$rkwN{Vp+U?_l33xjVq+^PPGs3)s^n2V=E+FS{Q)mRs};dciGGY-WU(CTWlCCR zrgJ{~qc1LK8ruG8+xKd_?vavf9&H%+ZIL{ajtqbASZZKhrC&M+sT2v%>(?XcZoxU{ zZA%j=^YsLSwX0UyY{YcmXP4q`%<~k-K}4`@Opq(icx+QzyX@PKADS7f(NA$!@ZrPS zUx>w*pO%YJDb)AyV9^PgBD{P{A7$?;UAEv*v|5Nw<(TcNg8T(*&{cLcC^S784aJQ4 z(>~V>;v|AmHDC^Bs)#klu!JD@cQ*31WVSM7umIYB9{mO}`-*T_4pm_KSOh_RvW7mN zo0oSf8HuG^I1x8Sw3=H+AnBghtkX{7W-1H2c<;5p$*I7^iVE5D^%&~UPQ;@upEPMa z*^zQ(tOh1YDfsT}&Q|2MsHBt>RyW*Sp&0gMbp7K@1d1Ut5dHH4Jj}eXc8QZhHwY-T zu-0}_b9J9QS`r?41JbA^ELb#iZ(g5j2fGvwK2DT3hNPCgNt9*hEF`CBbrtzQB^IxO z!-Mqjpqz)~;`C?~603w9?8LlJmbohHi^YKRxiO%15UhUjUWBy;M-5&ok^Es)Tw}4s z@V3+~YOXqV`E6cvur!7+bj;c-!cg|Rwu#aH0!`?F4>4vHMbqo|I}^euJ+oi0*s-Zv zG!Q04+N~(;$e{%9m4wQm+C5v$7@8N{!(bR^XBYE)$IWVQ6i9Y1;f$`6id1Y_Oie%+Su7a zG`X;}HZeKb`=4cZ<3{Xwaa#@u?B6-utBw)vR5Q;jrUn8%vGh>%X7VehIeP|n#RG3R z0LxV%Wc)b#I0R!2gX?{%=KK)%-98{?{(`O0H(Nwr-C1cj#|fE8RBr1njiM*d0&AaylZuh_!5}=PQY~o{OEn2nsOc7Se35#_7cNev9LZe$6!`B zubjZ+Z41^Pjh#5 zBcp*Ie!1I9Yt5Hja54QpzACRH0gj5QJUV)CUR8}lC@i{-xe|%D_S5dSL=eyC8o7)nwiPf;-}D^T_!hX-Z0Sl zGj2=Qx|&Ao1`;Gyw@{}XFXYU4bjEjY zmk6l~K;XoZM>?__zAsdB-kNT(XqAEK2+4vo2RY<*1m(Noj`hOvNI;n{ zibmyj+gnMcPS{^l$>)|w?a;YJc+=kS@Zf~iEFR_>&Y{TNZ~u_qLypac_&v)nL$Wkn zDRB%<@+scIM^%?@f2-F*8#1LMws?CkRCP_asv0~KK^x|?J`mQioIP=2j>FRZ*6JjZ z4Xls+*$56r7pWTZA?_S*WNeAk$(QwVcwxFMLzn8_9xiReQ|dCc5ZXFVP$8J!#W1Cd zoXtYMe~NrWaa$NtQ&R3Nj;!b#-ri4X!n#{6jju(ws4oA&FYI@$BMEpho@Ts2VesE0 z$rgY?2oh#E9Wjf->M2eOR@l_P{TB@4Smxx-k6*q>3hZlNFXQq^4i9A1H|O zmHAnmtt@9A-SUBGw{~UyfJ-V$7Ux zRU;IS#7^L(Kc;W~R@dms@z77ci>7G~bB^z#CH*?4z3UN;DuoZU!qv zS$Wm*QF954c~V3!-%>cC*b<{BfJNVV;>@;0)C1JWMWdS*W#P%-?GCEvr=Uu&woK-G zeHjWsC@9~jv7HkdF{PJ+X8lHbe{#7%F2@rp3&ouu8LH88~c04WHh?w|b{pjMoJX!xe zc9TJ5R%>Ty(ABb6HG4 zK1whW$oef~1&?15kl-5STgHm_y`4A-4Do&V#tTkE$(vHpH=FHpG&q5FGix z$Jt~K#TUHb@7Q8>G=^JsG;;mGI6Ovb zt~Kdtx;0-8+v^)Kw_>k>^E8EI?bLg%rAgA65Yr4Iz}ixa&ZbeHyU;Y$B7DuaR&h6Gi--fKaw!U^Rh0J^Nt0+a_% zP`NqKQYsbluPzljtx)fmg&e*pbPf7$E*YcS6Aek3)@R8dwIOl-2_l>Fo#ULXE+gc^ zT*5W%Xc|SQXP{5vdo9GQz9>w#Fvwh_oH}!TDB}>C_g-rLsA{ybUc680gN|j1V|uXv zC$_E2lUaEyjXl#DZD@#qWLX6TBZp!j6B36r>^(vs&wDjgnP$CfJUR=L1JoO&~c9U@+!5BW(-oZ-}SXq-ll45K#fH~=aMi_ znDk>#v|)qJW!&e_p4MVgSk*QJ9YUU}Yp`pop?aP7}Z$d zQ2G1k*yrOqDWIrwS?LU4KJ`7FMTHsbD z^LSF_$Cs90!ovroj&%0StLPiIZe3+1O=Z|P@yWRQWV^k2Tj{9xunW85Z>@VMpbK>; z(=f;Go%)mX-X{yGnUS(}l})g9+TZ&uVH9P|=1ZcqOYOHm@RqyaX4qE9WkhX=3rK8; zmrvY6-?+zZFGxA~wfSt%-fT26duVbmX;k?MFZLQ}Uoxtu!|hbBGsZujIMCa>K8p{% zW1zrcl#Td$dO~3RR86Exy)vx0Bx(O_ktJgqr^@CIr_d{pd+K6KZ z3ZNeud$M_CF=R}%J4K?*SWK6lM`@rrn?%|B_nDHFP{xe_e;7;W#^k6q)#GtVm1v)Q zQ{g>@m}pg%`?AS)rS_*!pDg|L^{H%HC-2$7z-!Cl^%Q?L^{0)t=N5hOf2fHQ03hJX zlZOQ|QidnJqX@S9cmc2G*MbwF^*$GJKGUY_{oYRHMDfmd3{n%nDs6(&{ zhd~4by;^`K^8AGYq!Y@X1JHW0jTD7KS`>LHI|{~+{`?8F;G}oh#&$X-cNede2C?!e zMO|_U2hX^+lj=i!w`@l8Q`qtMPBsPWko)Mk*25`461z0Py(AdPdpz8Ie0M`AXhlnK z_K3SQicmb8&}sh$mQP-uNy)g$(~C&JP47&ujnnNC)>lG-W=bIle6 zP-97nrp}Sk>aI!OG8Bi&-dT7VAtr$hUIU!g&XcJ@agL12tVeS9X(?Qx z1lM;sBz(40@aK1u^;3aNC#k@?e11UHg5jSs(t1j$jzdTx=%th`3!;``kIL#)5Cf6m9$tCztJRmO84r#Dgz&)k{kMcK#R*-F+A!({h zG;;*7&XJDB9refsH;m1u}yX|1~+)5tA3C0V4zL*Cao2aP)niTUg54Ae2E3 zS#Lgja3F8!na%)bmE;gUyU=`{Qn6}ID~_WkC+xV)O@ChTz@r#6J2MVD#376GRD#Od zHTw7V_OFUc^UDMrc-t|ey(Z`=xUuNuq+4C2I-ak`%f&UHev?;DftsuSA)Rh`J88@H zYms5i8};(2%~p=Pu_nGd>oL@yp)zuprV`>R<4cUB9nl>a(6-!^R%mXWSzmuT&!|Hy zfs^qJqp|mb)hO5u-U(=w7swW zel4-u@*zNVjhgF1MEYG&F`TJodl1*8s{bB?X|fKz(g%kwNLQKpIYKQ&*2V=wfG5dR z9(V97LF=G2>`c;!w6y!hfGT*RKmrY6sBKea_4c!d)b=%~lOS;)cO1)BwV%>tzh%eT89`P_#LWk&3&?zECI71e%ntCeUy@(< zBRq@EMHwQXuFL#WRh%QPDFU2xI~gwWtp=tE4L_2Ebw6H!Fp>qBR&fs-k6;}R-f({bW($d=MmE>fJ=8@CbYm6MG zsy%Y>xUWee=CGr+1z?SUXu_@~K0Q|N=$z9+nn5*I{Ef$;8SUQ`@&lG#yHKn@{A(Bz z_k!2BO<)V7M<(WAm<->+r!$0BLB2;0W&a3DRuTEakRw7^qoNw8+Q;hjH6prLxr*m0p z&%fO7>BQXd^70K3dG@k9%BB?`-kT8N9Wr*noarn|2ol<{H7Cg)e?Vq>x=A#7oftA> z4jh`!wJL_(6B9E*(X#cwec%Z^+&bjPW%#+L zlImiWH3*eQu?g5?9xHw8q$OdOOb?~`mQ6GcNh%*E!6`WCknD=BvSY>dGQWcZf;l)8 zThGP$3U9SeugxEOMFij#LCDs4va_edMxfL8!@W{@l!7D9(W|Bt!l?-XcEcbCh{s;H zo}7jMFBM9fMu*6DLV8Tv()QLZC9by98n8|1Pkd}Sq0>ZK_hP+2F&UZ>I1A-Zy9seg zb;_VH(kH0sTvH$4HH7$!SSm0b;Ml3j_lWecahQFS&adWlz&XEp5N`|Bvq(#ytxiPjIrPg_PD(z z>+F96VpQbz+{*E--0l=JWMKa=1brrd|2TdXGNm%qT-Ss>w}6^ZYASzIUJfOy4X9EA z8#OPDV+*3NPB*)Mw-J42%bO4Y;U|h5?sLpG#P`L6E&R!ff)8S~ zpoAkio7yc_6m>i98km48XidQAdFselHYJ>buUyf%wfvo|w{Hpw(PL(9aFfh0+F&?J zU%z&zCj!ak3H6O|KN<)38Cn^`R+vK*T1t7fp-e&c+wOy4TnX4k&Gw1e5>eR*<0ZMf0s8D!*ef{GLM~nETux2PIT;47e zwPgL2wSHBh5~KG15;&{L$t-c&k&*@p&^djN(-kBGiq#0ApsFC1e%t1h4Y5g*o!pI% z`_BCS=iXD~^({W4@DPJAWQdV0@wTCYtZehQ53gQDxQ08dMHhBfdW+2`z;SZ)I7Ce$ z{yS(a1YZ%TaGdY0hO#Z|Rhg$GX@SBKjfj8RZIrqH0E*pi@v@VE*$pk#CT-Ft$7um|} zoVqez{5Y5fji-Z@{(AFf6!Q3^>gn@jaWr3XWoxDfpb&3&z<%-upBIF3blZGLc4Btctwn?zC36 zNU|jG^n_w7OW&|5c*z|d?cW?@a7Uy6OcH49~A+KV(09@hQtG zf-s4g4HgROkJg}^@onO%kd2`2ZK8Str#RKW1rPm?$iOwnRoy4vzN>oVsY|gsaq=LMQ|^05$aL*BHlI zUkIAii&RtfM7)|$kI9a#c3G`CbM~yf{V>$i=2}JwCd1A#*P>k)(Pyql@;;QKc&2H! zQ)^ckzAVYCU`dhKJj=!?qs?lqSo2_RN zQy64x-oNJ}&}|2ilIMQ5ma6Q0ej5`{Sr?F3{n<}n%EGVipIK(wlv`^Z;2E5q! z?_z(4-cWEVCUBpWN!5zi7~y7zhLbpf*~K}o{+mxd&ysmi92M6Fd9f)}C2<#v=L_v< z&v^G5WWR+FwzOb}MK(Tf?sq~Sd0Q$)rw3r~qnn6V1eJF8+$HhB;2_I3=QGBg(-J&w zyb*Hq3dq3#;@|V7LK~b{%-_Xmar9ct**mxJU2Y3)^~7Dm+CMs<ThAkqx?Sm(yO}>+9dyOHQ->4N5ds1-C z25b%9`TC-bR4fsEB#GLD&bOh&E|7n&d;+oKyVs24xp5$_itf8jLzvo69D})PS(os| zN${NuLp`aswC5$STuN@K)FTUhW9ueQ<9N<;D@#j9pNr=RtbBjHjshV<2k1#FOp;&V zB$;lbL7kDAX-KJPEq97Nmb&M{E3EAB={BErNlJDGZL2Hqbjt*xAn~Z9%`PF9adqXR zyRX0xh=HRQ(7)X&cklF<0!$*ewgPUL zV(`$n9K9Emg+h}OSy@?W2W2mqbl61?rhuDnb*3JzJ-u+20N~l?1skj7&lB!kn993B zqR7amBwyqf5RkmQ>sqH4D1Pnp9BFbyq{^0e26l}y*rHbBa$A7EKc56KR!o0OA0%iGM+hs=l&JwJv$_^B2qO-HEP_R{A*d?X|)RD}9J} zX)aki<>!84u#)q-af8IAtFq2xBXuxZ&(A$x0(?USbI$AF-p}LU7;fnRRK5>)A{UjP zyWpRU;bF6}q1(TGyP7HreXaC2AO2cwxaQ;(dhT>D4|LS2is-f;t9^4(vmj+5Ag8#% z`xhu9cU!mU5Pe&|pj`n2IM1#X(Fjn$3x*2=qSa7i6tiQ*Q#oY5(VSS&-e3Io?Z8T_ z$?U5Ac9At@l|Aq}go1u-EE1*G=h*$kOZz+xS8bEp)%`s-Z+oSUbg#~+8Dh=g?s&a+ zbdm=$I(Kfa7g}L)oWJr#wIt7VBBIWlDQN1Ilb>JJZ1AmMz+X%r+6kMcuRdAcZE3kM z({%RMD*Gdl>$g9@)$~~TBXs(TXk3PB{Y3a8GRxZfBLp0Rsp`dh_h?@vm=-bPICkyq zPaO$d_%vRfzmRg(oyypQG|I$E)h7bg3R=X#lGXvnwMISP^U5 zpy&!E3!`MqMrfx~73+cVUNuBy+{*v8{wxQa3lCbppW--25>_%Ul0coRrZJ;?eXd>) zKcJm^_V(^LE`#Dk26L8P%4A^PT#KZI=15`XyU9rb*N2KJh7SX?gKt|ne54>d{aB)Y zQX@E6%|`8DX+o8tIgEvc78o_EHyM7Kb!Ft_xG6ED%m)J{!7UmSq}}xC6Xz>Nzv*{c zVwX=?xqvTOxdrl(ykCM{T*9=+2Zx8h9_^%}-!}qY@RzC)R}nyUZ)ZoOF91Ra~o8l9SxPf>C6KRhP%QdQ+bdU?^#gNCJ}n-=c~zIzdtVaSwh6BijpHO>gR zMgi@%#ia^kq7hux^1I&Q)5u&Cp7UhpY?rqoeTrh3krTNZJz^pm&#)q>zT?H6GzlDo zpHA0BwQrvf>)EfVQ4CCMZIg|nc$1#kBet@Y(Jax4M-K7H;0_?DGvr<_5W? z60|7w`a`{9M(;iQrwwf2%`2&L|2Er0(ABkFTM) zAlp^hg5nkMFcRAA#%RzLGbPy|t51SJsHOs`bGUQ|e*I~;ygi+k*i$TlC#7i^SKfh!qWIBiUI;^T2 zFYJ{gpaFK!yJwBJ)_4b8enq8dHBkbGDAgUGsD7b5LSRj&sCPTI1InRs&hFDZj~~QJ zGQOlmB(DBCyrQLDYrEuNH~JRUL|`aDbt@2vJ#IhP7KYS`NSFpKc0xJHmvR=RUk>;u<_`?>+UxzYmBlLD$PWdB)eQ!SJg1cXy#ki^Pyelf&eowdJ?sFiI(Y=YjEL&D}Tzp_&a^2cMhBKUZ>LGlhkK~!13KGD$Ow=nVsAhg-YTaM?%#+RahoYFiD0|G$~lh5?!sHY9$(XrKc4hFG-nO z*tYI(unr8ilGrJi*#3!6mi#wQ85>W6_i6u^w|xAsR`{so|G~HYrHkn+usYVtB|yl~ z6FuKkdUj{WMuYS-FPOnrAig&u5Q81i77QdO zUQHtqzrG?6mwv;0cMynB8UjRsJ^_Lp?lld=WXOj=go7T-c^IZZXrE>PeFhw1)MM!p zh#T-aK!-pqlOYf#urkCc;om6`h%4|u378EU7P$901fmVT8$y{o5dKT>Kd=8E0rCqE diff --git a/doc/pics/radix.sxd b/doc/pics/radix.sxd deleted file mode 100644 index b9eb9a032d0b5229d4828911466490a95c126a2b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6181 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 D!-Jt8 diff --git a/doc/pics/sliding_window.sxd b/doc/pics/sliding_window.sxd deleted file mode 100644 index 91e7c0d9f43b612ff0a59d86a71c8928fbd695f3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6787 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 diff --git a/doc/pics/sliding_window.tif b/doc/pics/sliding_window.tif deleted file mode 100644 index bb4cb96ebff4e06478672dd3583bd26a51d85b5d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 53880 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 DSo1$6 diff --git a/doc/poster.tex b/doc/poster.tex deleted file mode 100644 index e7388f4..0000000 --- a/doc/poster.tex +++ /dev/null @@ -1,35 +0,0 @@ -\documentclass[landscape,11pt]{article} -\usepackage{amsmath, amssymb} -\usepackage{hyperref} -\begin{document} -\hspace*{-3in} -\begin{tabular}{llllll} -$c = a + b$ & {\tt mp\_add(\&a, \&b, \&c)} & $b = 2a$ & {\tt mp\_mul\_2(\&a, \&b)} & \\ -$c = a - b$ & {\tt mp\_sub(\&a, \&b, \&c)} & $b = a/2$ & {\tt mp\_div\_2(\&a, \&b)} & \\ -$c = ab $ & {\tt mp\_mul(\&a, \&b, \&c)} & $c = 2^ba$ & {\tt mp\_mul\_2d(\&a, b, \&c)} \\ -$b = a^2 $ & {\tt mp\_sqr(\&a, \&b)} & $c = a/2^b, d = a \mod 2^b$ & {\tt mp\_div\_2d(\&a, b, \&c, \&d)} \\ -$c = \lfloor a/b \rfloor, d = a \mod b$ & {\tt mp\_div(\&a, \&b, \&c, \&d)} & $c = a \mod 2^b $ & {\tt mp\_mod\_2d(\&a, b, \&c)} \\ - && \\ -$a = b $ & {\tt mp\_set\_int(\&a, b)} & $c = a \vee b$ & {\tt mp\_or(\&a, \&b, \&c)} \\ -$b = a $ & {\tt mp\_copy(\&a, \&b)} & $c = a \wedge b$ & {\tt mp\_and(\&a, \&b, \&c)} \\ - && $c = a \oplus b$ & {\tt mp\_xor(\&a, \&b, \&c)} \\ - & \\ -$b = -a $ & {\tt mp\_neg(\&a, \&b)} & $d = a + b \mod c$ & {\tt mp\_addmod(\&a, \&b, \&c, \&d)} \\ -$b = |a| $ & {\tt mp\_abs(\&a, \&b)} & $d = a - b \mod c$ & {\tt mp\_submod(\&a, \&b, \&c, \&d)} \\ - && $d = ab \mod c$ & {\tt mp\_mulmod(\&a, \&b, \&c, \&d)} \\ -Compare $a$ and $b$ & {\tt mp\_cmp(\&a, \&b)} & $c = a^2 \mod b$ & {\tt mp\_sqrmod(\&a, \&b, \&c)} \\ -Is Zero? & {\tt mp\_iszero(\&a)} & $c = a^{-1} \mod b$ & {\tt mp\_invmod(\&a, \&b, \&c)} \\ -Is Even? & {\tt mp\_iseven(\&a)} & $d = a^b \mod c$ & {\tt mp\_exptmod(\&a, \&b, \&c, \&d)} \\ -Is Odd ? & {\tt mp\_isodd(\&a)} \\ -&\\ -$\vert \vert a \vert \vert$ & {\tt mp\_unsigned\_bin\_size(\&a)} & $res$ = 1 if $a$ prime to $t$ rounds? & {\tt mp\_prime\_is\_prime(\&a, t, \&res)} \\ -$buf \leftarrow a$ & {\tt mp\_to\_unsigned\_bin(\&a, buf)} & Next prime after $a$ to $t$ rounds. & {\tt mp\_prime\_next\_prime(\&a, t, bbs\_style)} \\ -$a \leftarrow buf[0..len-1]$ & {\tt mp\_read\_unsigned\_bin(\&a, buf, len)} \\ -&\\ -$b = \sqrt{a}$ & {\tt mp\_sqrt(\&a, \&b)} & $c = \mbox{gcd}(a, b)$ & {\tt mp\_gcd(\&a, \&b, \&c)} \\ -$c = a^{1/b}$ & {\tt mp\_n\_root(\&a, b, \&c)} & $c = \mbox{lcm}(a, b)$ & {\tt mp\_lcm(\&a, \&b, \&c)} \\ -&\\ -Greater Than & MP\_GT & Equal To & MP\_EQ \\ -Less Than & MP\_LT & Bits per digit & DIGIT\_BIT \\ -\end{tabular} -\end{document} diff --git a/makefile b/makefile index aa104c6..82d278d 100644 --- a/makefile +++ b/makefile @@ -123,7 +123,7 @@ tune: $(LIBNAME) coveralls: lcov coveralls-lcov -poster docs manual: +docs manual: $(MAKE) -C doc/ $@ V=$(V) .PHONY: pre_gen From 35178bfdb4145c96b2f2fe94fc40157c8c3c2dda Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Sun, 20 Oct 2019 19:18:29 +0200 Subject: [PATCH 17/20] fixup c917f3c39121100dac22a182d7587f12d7ebc05c --- doc/makefile | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/makefile b/doc/makefile index 2c7978f..583becc 100644 --- a/doc/makefile +++ b/doc/makefile @@ -39,5 +39,4 @@ manual: mandvi rm -f bn.aux bn.dvi bn.log bn.idx bn.lof bn.out bn.toc clean: - ${MAKE} -C pics/ clean MAKE=${MAKE} rm -f *.idx *.toc *.log *.aux *.dvi *.lof *.ind *.ilg *.ps *.log tommath.tex From 2ef4c9bdd4c5fd1c81de4cfc5ef9a09cb1677891 Mon Sep 17 00:00:00 2001 From: Francois Perrad Date: Sun, 20 Oct 2019 16:37:46 +0200 Subject: [PATCH 18/20] handles MP_BUF in mp_error_to_string (cherry picked from commit a825e0a3601f81ddf1a6753c45e5b74d44c23d78) --- bn_mp_error_to_string.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/bn_mp_error_to_string.c b/bn_mp_error_to_string.c index e936ec1..2e2adb0 100644 --- a/bn_mp_error_to_string.c +++ b/bn_mp_error_to_string.c @@ -17,6 +17,8 @@ const char *mp_error_to_string(mp_err code) return "Value out of range"; case MP_ITER: return "Max. iterations reached"; + case MP_BUF: + return "Buffer overflow"; default: return "Invalid error code"; } From ddef44e7d3f1c4954ad3ce9492c7190aeee4d9b5 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Mon, 21 Oct 2019 10:49:10 +0200 Subject: [PATCH 19/20] update changes, bump version, fixup c917f3c [skip ci] --- changes.txt | 2 ++ makefile | 2 +- makefile_include.mk | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/changes.txt b/changes.txt index 6f44409..ebf7382 100644 --- a/changes.txt +++ b/changes.txt @@ -27,10 +27,12 @@ v1.2.0 -- The custom allocators which were formerly known as XMALLOC(), XFREE() etc. are now available as MP_MALLOC(), MP_REALLOC(), MP_CALLOC() and MP_FREE(). MP_REALLOC() and MP_FREE() now also provide the allocated size to ease the usage of simple allocators without tracking. + -- Building is now also possible with MSVC 2015, 2017 and 2019 (use makefile.msvc) -- Added mp_decr() and mp_incr() -- Added mp_log_u32() -- Improved prime-checking -- Improved Toom-Cook multiplication + -- Removed the LTM book (`make docs` now builds the user manual) Jan 28th, 2019 diff --git a/makefile b/makefile index 82d278d..be9fac6 100644 --- a/makefile +++ b/makefile @@ -145,7 +145,7 @@ zipup: clean astyle new_file docs @echo 'fixme check' -@(find libtommath-$(VERSION)/ -type f | xargs grep 'FIXM[E]') && echo '############## BEWARE: the "fixme" marker was found !!! ##############' || true mkdir -p libtommath-$(VERSION)/doc - cp doc/bn.pdf doc/poster.pdf libtommath-$(VERSION)/doc/ + cp doc/bn.pdf libtommath-$(VERSION)/doc/ $(MAKE) -C libtommath-$(VERSION)/ pre_gen tar -c libtommath-$(VERSION)/ | xz -6e -c - > ltm-$(VERSION).tar.xz zip -9rq ltm-$(VERSION).zip libtommath-$(VERSION) diff --git a/makefile_include.mk b/makefile_include.mk index 00ae204..70f448f 100644 --- a/makefile_include.mk +++ b/makefile_include.mk @@ -3,7 +3,7 @@ # #version of library -VERSION=1.2.0-rc2 +VERSION=1.2.0-rc3 VERSION_PC=1.2.0 VERSION_SO=3:0:2 From 6a02e94338821e35a29c46b1ef8a5c299098a759 Mon Sep 17 00:00:00 2001 From: Steffen Jaeckel Date: Tue, 22 Oct 2019 11:43:35 +0200 Subject: [PATCH 20/20] final bump --- makefile_include.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makefile_include.mk b/makefile_include.mk index 70f448f..7b025e8 100644 --- a/makefile_include.mk +++ b/makefile_include.mk @@ -3,7 +3,7 @@ # #version of library -VERSION=1.2.0-rc3 +VERSION=1.2.0 VERSION_PC=1.2.0 VERSION_SO=3:0:2