Document the BN library.
[openssl.git] / crypto / bn / bn_lib.c
index 994764c031d133e74d71a322373ced804ef0bd19..df79d6e3380d38259c0d3c91dfcffd18345740e0 100644 (file)
@@ -60,7 +60,7 @@
 #include "cryptlib.h"
 #include "bn_lcl.h"
 
-char *BN_version="Big Number" OPENSSL_VERSION_PTEXT;
+const char *BN_version="Big Number" OPENSSL_VERSION_PTEXT;
 
 /* For a 32 bit machine
  * 2 -   4 ==  128
@@ -71,17 +71,16 @@ char *BN_version="Big Number" OPENSSL_VERSION_PTEXT;
  * 7 - 128 == 4096
  * 8 - 256 == 8192
  */
-int bn_limit_bits=0;
-int bn_limit_num=8;        /* (1<<bn_limit_bits) */
-int bn_limit_bits_low=0;
-int bn_limit_num_low=8;    /* (1<<bn_limit_bits_low) */
-int bn_limit_bits_high=0;
-int bn_limit_num_high=8;   /* (1<<bn_limit_bits_high) */
-int bn_limit_bits_mont=0;
-int bn_limit_num_mont=8;   /* (1<<bn_limit_bits_mont) */
-
-void BN_set_params(mult,high,low,mont)
-int mult,high,low,mont;
+OPENSSL_GLOBAL int bn_limit_bits=0;
+OPENSSL_GLOBAL int bn_limit_num=8;        /* (1<<bn_limit_bits) */
+OPENSSL_GLOBAL int bn_limit_bits_low=0;
+OPENSSL_GLOBAL int bn_limit_num_low=8;    /* (1<<bn_limit_bits_low) */
+OPENSSL_GLOBAL int bn_limit_bits_high=0;
+OPENSSL_GLOBAL int bn_limit_num_high=8;   /* (1<<bn_limit_bits_high) */
+OPENSSL_GLOBAL int bn_limit_bits_mont=0;
+OPENSSL_GLOBAL int bn_limit_num_mont=8;   /* (1<<bn_limit_bits_mont) */
+
+void BN_set_params(int mult, int high, int low, int mont)
        {
        if (mult >= 0)
                {
@@ -113,8 +112,7 @@ int mult,high,low,mont;
                }
        }
 
-int BN_get_params(which)
-int which;
+int BN_get_params(int which)
        {
        if      (which == 0) return(bn_limit_bits);
        else if (which == 1) return(bn_limit_bits_high);
@@ -123,7 +121,7 @@ int which;
        else return(0);
        }
 
-BIGNUM *BN_value_one()
+BIGNUM *BN_value_one(void)
        {
        static BN_ULONG data_one=1L;
        static BIGNUM const_one={&data_one,1,1,0};
@@ -131,7 +129,7 @@ BIGNUM *BN_value_one()
        return(&const_one);
        }
 
-char *BN_options()
+char *BN_options(void)
        {
        static int init=0;
        static char data[16];
@@ -150,10 +148,9 @@ char *BN_options()
        return(data);
        }
 
-int BN_num_bits_word(l)
-BN_ULONG l;
+int BN_num_bits_word(BN_ULONG l)
        {
-       static char bits[256]={
+       static const char bits[256]={
                0,1,2,2,3,3,3,3,4,4,4,4,4,4,4,4,
                5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,
                6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,
@@ -238,8 +235,7 @@ BN_ULONG l;
                }
        }
 
-int BN_num_bits(a)
-BIGNUM *a;
+int BN_num_bits(const BIGNUM *a)
        {
        BN_ULONG l;
        int i;
@@ -259,8 +255,7 @@ BIGNUM *a;
        return(i+BN_num_bits_word(l));
        }
 
-void BN_clear_free(a)
-BIGNUM *a;
+void BN_clear_free(BIGNUM *a)
        {
        int i;
 
@@ -277,8 +272,7 @@ BIGNUM *a;
                Free(a);
        }
 
-void BN_free(a)
-BIGNUM *a;
+void BN_free(BIGNUM *a)
        {
        if (a == NULL) return;
        if ((a->d != NULL) && !(BN_get_flags(a,BN_FLG_STATIC_DATA)))
@@ -288,13 +282,12 @@ BIGNUM *a;
                Free(a);
        }
 
-void BN_init(a)
-BIGNUM *a;
+void BN_init(BIGNUM *a)
        {
        memset(a,0,sizeof(BIGNUM));
        }
 
-BIGNUM *BN_new()
+BIGNUM *BN_new(void)
        {
        BIGNUM *ret;
 
@@ -312,7 +305,7 @@ BIGNUM *BN_new()
        }
 
 
-BN_CTX *BN_CTX_new()
+BN_CTX *BN_CTX_new(void)
        {
        BN_CTX *ret;
 
@@ -328,16 +321,14 @@ BN_CTX *BN_CTX_new()
        return(ret);
        }
 
-void BN_CTX_init(ctx)
-BN_CTX *ctx;
+void BN_CTX_init(BN_CTX *ctx)
        {
        memset(ctx,0,sizeof(BN_CTX));
        ctx->tos=0;
        ctx->flags=0;
        }
 
-void BN_CTX_free(c)
-BN_CTX *c;
+void BN_CTX_free(BN_CTX *c)
        {
        int i;
 
@@ -350,12 +341,16 @@ BN_CTX *c;
                Free(c);
        }
 
-BIGNUM *bn_expand2(b, words)
-BIGNUM *b;
-int words;
+/* This is an internal function that should not be used in applications.
+ * It ensures that 'b' has enough room for a 'bits' bit number.  It is
+ * mostly used by the various BIGNUM routines.  If there is an error,
+ * NULL is returned. if not, 'b' is returned.
+ */
+BIGNUM *bn_expand2(BIGNUM *b, int words)
        {
-       BN_ULONG *A,*B,*a;
-       int i,j;
+       BN_ULONG *A,*a;
+       const BN_ULONG *B;
+       int i;
 
        bn_check_top(b);
 
@@ -373,11 +368,38 @@ int words;
                        BNerr(BN_F_BN_EXPAND2,ERR_R_MALLOC_FAILURE);
                        return(NULL);
                        }
-memset(A,0x5c,sizeof(BN_ULONG)*(words+1));
 #if 1
                B=b->d;
+               /* Check if the previous number needs to be copied */
                if (B != NULL)
                        {
+#if 0
+                       /* This lot is an unrolled loop to copy b->top 
+                        * BN_ULONGs from B to A
+                        */
+/*
+ * I have nothing against unrolling but it's usually done for
+ * several reasons, namely:
+ * - minimize percentage of decision making code, i.e. branches;
+ * - avoid cache trashing;
+ * - make it possible to schedule loads earlier;
+ * Now let's examine the code below. The cornerstone of C is
+ * "programmer is always right" and that's what we love it for:-)
+ * For this very reason C compilers have to be paranoid when it
+ * comes to data aliasing and assume the worst. Yeah, but what
+ * does it mean in real life? This means that loop body below will
+ * be compiled to sequence of loads immediately followed by stores
+ * as compiler assumes the worst, something in A==B+1 style. As a
+ * result CPU pipeline is going to starve for incoming data. Secondly
+ * if A and B happen to share same cache line such code is going to
+ * cause severe cache trashing. Both factors have severe impact on
+ * performance of modern CPUs and this is the reason why this
+ * particulare piece of code is #ifdefed away and replaced by more
+ * "friendly" version found in #else section below. This comment
+ * also applies to BN_copy function.
+ *
+ *                                     <appro@fy.chalmers.se>
+ */
                        for (i=b->top&(~7); i>0; i-=8)
                                {
                                A[0]=B[0]; A[1]=B[1]; A[2]=B[2]; A[3]=B[3];
@@ -414,39 +436,66 @@ memset(A,0x5c,sizeof(BN_ULONG)*(words+1));
                                 */
                                ;
                                }
-                       B= &(b->d[b->top]);
-                       j=b->max-8;
-                       for (i=b->top; i<j; i+=8)
+#else
+                       for (i=b->top>>2; i>0; i--,A+=4,B+=4)
                                {
-                               B[0]=0; B[1]=0; B[2]=0; B[3]=0;
-                               B[4]=0; B[5]=0; B[6]=0; B[7]=0;
-                               B+=8;
+                               /*
+                                * The fact that the loop is unrolled
+                                * 4-wise is a tribute to Intel. It's
+                                * the one that doesn't have enough
+                                * registers to accomodate more data.
+                                * I'd unroll it 8-wise otherwise:-)
+                                *
+                                *              <appro@fy.chalmers.se>
+                                */
+                               BN_ULONG a0,a1,a2,a3;
+                               a0=B[0]; a1=B[1]; a2=B[2]; a3=B[3];
+                               A[0]=a0; A[1]=a1; A[2]=a2; A[3]=a3;
                                }
-                       for (j+=8; i<j; i++)
+                       switch (b->top&3)
                                {
-                               B[0]=0;
-                               B++;
+                               case 3: A[2]=B[2];
+                               case 2: A[1]=B[1];
+                               case 1: A[0]=B[0];
+                               case 0: ; /* ultrix cc workaround, see above */
                                }
-#else
-                       memcpy(a->d,b->d,sizeof(b->d[0])*b->top);
 #endif
-               
-/*             memset(&(p[b->max]),0,((words+1)-b->max)*sizeof(BN_ULONG)); */
-/*     { int i; for (i=b->max; i<words+1; i++) p[i]=i;} */
                        Free(b->d);
                        }
 
                b->d=a;
                b->max=words;
+
+               /* Now need to zero any data between b->top and b->max */
+
+               A= &(b->d[b->top]);
+               for (i=(b->max - b->top)>>3; i>0; i--,A+=8)
+                       {
+                       A[0]=0; A[1]=0; A[2]=0; A[3]=0;
+                       A[4]=0; A[5]=0; A[6]=0; A[7]=0;
+                       }
+               for (i=(b->max - b->top)&7; i>0; i--,A++)
+                       A[0]=0;
+#else
+                       memset(A,0,sizeof(BN_ULONG)*(words+1));
+                       memcpy(A,b->d,sizeof(b->d[0])*b->top);
+                       b->d=a;
+                       b->max=words;
+#endif
+               
+/*             memset(&(p[b->max]),0,((words+1)-b->max)*sizeof(BN_ULONG)); */
+/*     { int i; for (i=b->max; i<words+1; i++) p[i]=i;} */
+
                }
        return(b);
        }
 
-BIGNUM *BN_dup(a)
-BIGNUM *a;
+BIGNUM *BN_dup(const BIGNUM *a)
        {
        BIGNUM *r;
 
+       if (a == NULL) return NULL;
+
        bn_check_top(a);
 
        r=BN_new();
@@ -454,12 +503,11 @@ BIGNUM *a;
        return((BIGNUM *)BN_copy(r,a));
        }
 
-BIGNUM *BN_copy(a, b)
-BIGNUM *a;
-BIGNUM *b;
+BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b)
        {
        int i;
-       BN_ULONG *A,*B;
+       BN_ULONG *A;
+       const BN_ULONG *B;
 
        bn_check_top(b);
 
@@ -469,47 +517,18 @@ BIGNUM *b;
 #if 1
        A=a->d;
        B=b->d;
-       for (i=b->top&(~7); i>0; i-=8)
+       for (i=b->top>>2; i>0; i--,A+=4,B+=4)
                {
-               A[0]=B[0];
-               A[1]=B[1];
-               A[2]=B[2];
-               A[3]=B[3];
-               A[4]=B[4];
-               A[5]=B[5];
-               A[6]=B[6];
-               A[7]=B[7];
-               A+=8;
-               B+=8;
+               BN_ULONG a0,a1,a2,a3;
+               a0=B[0]; a1=B[1]; a2=B[2]; a3=B[3];
+               A[0]=a0; A[1]=a1; A[2]=a2; A[3]=a3;
                }
-       switch (b->top&7)
+       switch (b->top&3)
                {
-       case 7:
-               A[6]=B[6];
-       case 6:
-               A[5]=B[5];
-       case 5:
-               A[4]=B[4];
-       case 4:
-               A[3]=B[3];
-       case 3:
-               A[2]=B[2];
-       case 2:
-               A[1]=B[1];
-       case 1:
-               A[0]=B[0];
-        case 0:
-               /* I need the 'case 0' entry for utrix cc.
-                * If the optimiser is turned on, it does the
-                * switch table by doing
-                * a=top&7
-                * a--;
-                * goto jump_table[a];
-                * If top is 0, this makes us jump to 0xffffffc which is
-                * rather bad :-(.
-                * eric 23-Apr-1998
-                */
-               ;
+               case 3: A[2]=B[2];
+               case 2: A[1]=B[1];
+               case 1: A[0]=B[0];
+               case 0: ; /* ultrix cc workaround, see comments in bn_expand2 */
                }
 #else
        memcpy(a->d,b->d,sizeof(b->d[0])*b->top);
@@ -523,8 +542,7 @@ BIGNUM *b;
        return(a);
        }
 
-void BN_clear(a)
-BIGNUM *a;
+void BN_clear(BIGNUM *a)
        {
        if (a->d != NULL)
                memset(a->d,0,a->max*sizeof(a->d[0]));
@@ -532,8 +550,7 @@ BIGNUM *a;
        a->neg=0;
        }
 
-BN_ULONG BN_get_word(a)
-BIGNUM *a;
+BN_ULONG BN_get_word(BIGNUM *a)
        {
        int i,n;
        BN_ULONG ret=0;
@@ -546,15 +563,15 @@ BIGNUM *a;
 #ifndef SIXTY_FOUR_BIT /* the data item > unsigned long */
                ret<<=BN_BITS4; /* stops the compiler complaining */
                ret<<=BN_BITS4;
+#else
+               ret=0;
 #endif
                ret|=a->d[i];
                }
        return(ret);
        }
 
-int BN_set_word(a,w)
-BIGNUM *a;
-BN_ULONG w;
+int BN_set_word(BIGNUM *a, BN_ULONG w)
        {
        int i,n;
        if (bn_expand(a,sizeof(BN_ULONG)*8) == NULL) return(0);
@@ -572,6 +589,8 @@ BN_ULONG w;
 #ifndef SIXTY_FOUR_BIT /* the data item > unsigned long */
                w>>=BN_BITS4;
                w>>=BN_BITS4;
+#else
+               w=0;
 #endif
                a->d[i]=(BN_ULONG)w&BN_MASK2;
                if (a->d[i] != 0) a->top=i+1;
@@ -580,10 +599,7 @@ BN_ULONG w;
        }
 
 /* ignore negative */
-BIGNUM *BN_bin2bn(s, len, ret)
-unsigned char *s;
-int len;
-BIGNUM *ret;
+BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret)
        {
        unsigned int i,m;
        unsigned int n;
@@ -620,9 +636,7 @@ BIGNUM *ret;
        }
 
 /* ignore negative */
-int BN_bn2bin(a, to)
-BIGNUM *a;
-unsigned char *to;
+int BN_bn2bin(const BIGNUM *a, unsigned char *to)
        {
        int n,i;
        BN_ULONG l;
@@ -636,9 +650,7 @@ unsigned char *to;
        return(n);
        }
 
-int BN_ucmp(a, b)
-BIGNUM *a;
-BIGNUM *b;
+int BN_ucmp(const BIGNUM *a, const BIGNUM *b)
        {
        int i;
        BN_ULONG t1,t2,*ap,*bp;
@@ -660,9 +672,7 @@ BIGNUM *b;
        return(0);
        }
 
-int BN_cmp(a, b)
-BIGNUM *a;
-BIGNUM *b;
+int BN_cmp(const BIGNUM *a, const BIGNUM *b)
        {
        int i;
        int gt,lt;
@@ -703,9 +713,7 @@ BIGNUM *b;
        return(0);
        }
 
-int BN_set_bit(a, n)
-BIGNUM *a;
-int n;
+int BN_set_bit(BIGNUM *a, int n)
        {
        int i,j,k;
 
@@ -719,13 +727,11 @@ int n;
                a->top=i+1;
                }
 
-       a->d[i]|=(1L<<j);
+       a->d[i]|=(((BN_ULONG)1)<<j);
        return(1);
        }
 
-int BN_clear_bit(a, n)
-BIGNUM *a;
-int n;
+int BN_clear_bit(BIGNUM *a, int n)
        {
        int i,j;
 
@@ -733,14 +739,12 @@ int n;
        j=n%BN_BITS2;
        if (a->top <= i) return(0);
 
-       a->d[i]&=(~(1L<<j));
+       a->d[i]&=(~(((BN_ULONG)1)<<j));
        bn_fix_top(a);
        return(1);
        }
 
-int BN_is_bit_set(a, n)
-BIGNUM *a;
-int n;
+int BN_is_bit_set(const BIGNUM *a, int n)
        {
        int i,j;
 
@@ -751,9 +755,7 @@ int n;
        return((a->d[i]&(((BN_ULONG)1)<<j))?1:0);
        }
 
-int BN_mask_bits(a,n)
-BIGNUM *a;
-int n;
+int BN_mask_bits(BIGNUM *a, int n)
        {
        int b,w;
 
@@ -771,9 +773,7 @@ int n;
        return(1);
        }
 
-int bn_cmp_words(a,b,n)
-BN_ULONG *a,*b;
-int n;
+int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n)
        {
        int i;
        BN_ULONG aa,bb;