PR: 2078

[openssl.git] / doc / crypto / bn_internal.pod

diff --git a/doc/crypto/bn_internal.pod b/doc/crypto/bn_internal.pod
index 8da244aed47ce3ba08cb4814b9e1b7c93213cafb..91840b0f0d63cec7fb409c975c375ccf521e3b53 100644 (file)
--- a/doc/crypto/bn_internal.pod
+++ b/doc/crypto/bn_internal.pod
@@ -13,6 +13,8 @@ library internal functions
 
 =head1 SYNOPSIS
 
+ #include <openssl/bn.h>
+
  BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w);
  BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num,
    BN_ULONG w);
@@ -34,9 +36,9 @@ library internal functions
    int nb);
  void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n);
  void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2,
-   BN_ULONG *tmp);
+   int dna,int dnb,BN_ULONG *tmp);
  void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
-   int tn, int n, BN_ULONG *tmp);
+   int n, int tna,int tnb, BN_ULONG *tmp);
  void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b,
    int n2, BN_ULONG *tmp);
  void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l,
@@ -70,24 +72,34 @@ applications.
 
 =head2 The BIGNUM structure
 
- typedef struct bignum_st
+ typedef struct bignum_st BIGNUM;
+
+ struct bignum_st
         {
-        int top;      /* index of last used d (most significant word) */
-        BN_ULONG *d;  /* pointer to an array of 'BITS2' bit chunks */
-        int max;      /* size of the d array */
-        int neg;      /* sign */
-        } BIGNUM;
-
-The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s,
-least significant first. A B<BN_ULONG> can be either 16, 32 or 64 bits
-in size (B<BITS2>), depending on the 'number of bits' specified in
+        BN_ULONG *d;    /* Pointer to an array of 'BN_BITS2' bit chunks. */
+        int top;        /* Index of last used d +1. */
+        /* The next are internal book keeping for bn_expand. */
+        int dmax;       /* Size of the d array. */
+        int neg;        /* one if the number is negative */
+        int flags;
+        };
+
+
+The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>),
+least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits
+in size, depending on the 'number of bits' (B<BITS2>) specified in
 C<openssl/bn.h>.
 
-B<max> is the size of the B<d> array that has been allocated.  B<top>
-is the 'last' entry being used, so for a value of 4, bn.d[0]=4 and
+B<dmax> is the size of the B<d> array that has been allocated.  B<top>
+is the number of words being used, so for a value of 4, bn.d[0]=4 and
 bn.top=1.  B<neg> is 1 if the number is negative.  When a B<BIGNUM> is
 B<0>, the B<d> field can be B<NULL> and B<top> == B<0>.
 
+B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The 
+flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and 
+BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM>
+structure B<b>.
+
 Various routines in this library require the use of temporary
 B<BIGNUM> variables during their execution.  Since dynamic memory
 allocation to create B<BIGNUM>s is rather expensive when used in
@@ -152,14 +164,15 @@ bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word
 arrays B<r>, B<a> and B<b>.  It computes the B<n> low words of
 B<a>*B<b> and places the result in B<r>.
 
-bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<t>) operates on the B<n2>
-word arrays B<a> and B<b> and the 2*B<n2> word arrays B<r> and B<t>.
-B<n2> must be a power of 2.  It computes B<a>*B<b> and places the
-result in B<r>.
+bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates
+on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb>
+(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2>
+word arrays B<r> and B<t>.  B<n2> must be a power of 2.  It computes
+B<a>*B<b> and places the result in B<r>.
 
-bn_mul_part_recursive(B<r>, B<a>, B<b>, B<tn>, B<n>, B<tmp>) operates
-on the B<n>+B<tn> word arrays B<a> and B<b> and the 4*B<n> word arrays
-B<r> and B<tmp>.
+bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>)
+operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and
+B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>.
 
 bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the
 B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a>
@@ -201,17 +214,17 @@ call bn_expand2(), which allocates a new B<d> array and copies the
 data.  They return B<NULL> on error, B<b> otherwise.
 
 The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most
-significant non-zero word when B<a> has shrunk.
+significant non-zero word plus one when B<a> has shrunk.
 
 =head2 Debugging
 
 bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top
-E<lt>= (a)-E<gt>max)>.  A violation will cause the program to abort.
+E<lt>= (a)-E<gt>dmax)>.  A violation will cause the program to abort.
 
 bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d>
 (in reverse order, i.e. most significant word first) to stderr.
 
-bn_set_max() makes B<a> a static number with a B<max> of its current size.
+bn_set_max() makes B<a> a static number with a B<dmax> of its current size.
 This is used by bn_set_low() and bn_set_high() to make B<r> a read-only
 B<BIGNUM> that contains the B<n> low or high words of B<a>.