Document the BN library.

1 files changed, 152 insertions, 115 deletions

diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod
index fbd674dd5e..1a0e38b24c 100644
--- a/doc/crypto/bn.pod
+++ b/doc/crypto/bn.pod
@@ -8,131 +8,168 @@ bn - Multiprecision integer arithmetics
 
  #include <openssl/bn.h>
 
- #define BN_prime_checks(b)
- #define BN_num_bytes(a)
- #define BN_is_word(a,w)
- #define BN_is_zero(a)
- #define BN_is_one(a)
- #define BN_is_odd(a)
- #define BN_one(a)
- #define BN_zero(a)
- 
- #define bn_expand(n,b)
- #define bn_wexpand(n,b)
- 
- #define bn_fix_top(a)
- 
- BIGNUM *BN_value_one(void);
- char *	BN_options(void);
- BN_CTX *BN_CTX_new(void);
- void	BN_CTX_init(BN_CTX *c);
- void	BN_CTX_free(BN_CTX *c);
- int     BN_rand(BIGNUM *rnd, int bits, int top,int bottom);
- int	BN_num_bits(const BIGNUM *a);
- int	BN_num_bits_word(BN_ULONG);
  BIGNUM *BN_new(void);
- void	BN_init(BIGNUM *);
- void	BN_clear_free(BIGNUM *a);
+ void BN_free(BIGNUM *a);
+ void BN_init(BIGNUM *);
+ void BN_clear(BIGNUM *a);
+ void BN_clear_free(BIGNUM *a);
+
+ BN_CTX *BN_CTX_new(void);
+ void BN_CTX_init(BN_CTX *c);
+ void BN_CTX_free(BN_CTX *c);
+
  BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);
- BIGNUM *BN_bin2bn(const unsigned char *s,int len,BIGNUM *ret);
- int	BN_bn2bin(const BIGNUM *a, unsigned char *to);
- BIGNUM *BN_mpi2bn(unsigned char *s,int len,BIGNUM *ret);
- int	BN_bn2mpi(const BIGNUM *a, unsigned char *to);
- int	BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
- int	BN_usub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
- int	BN_uadd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
- int	BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
- int	BN_mod(BIGNUM *rem, const BIGNUM *m, const BIGNUM *d, BN_CTX *ctx);
- int	BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *m, const BIGNUM *d,
- 	       BN_CTX *ctx);
- int	BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b,BN_CTX *ctx);
- int	BN_sqr(BIGNUM *r, BIGNUM *a,BN_CTX *ctx);
- BN_ULONG BN_mod_word(BIGNUM *a, BN_ULONG w);
- BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
- int	BN_mul_word(BIGNUM *a, BN_ULONG w);
- int	BN_add_word(BIGNUM *a, BN_ULONG w);
- int	BN_sub_word(BIGNUM *a, BN_ULONG w);
- int	BN_set_word(BIGNUM *a, BN_ULONG w);
- BN_ULONG BN_get_word(BIGNUM *a);
- int	BN_cmp(const BIGNUM *a, const BIGNUM *b);
- void	BN_free(BIGNUM *a);
- int	BN_is_bit_set(const BIGNUM *a, int n);
- int	BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
- int	BN_lshift1(BIGNUM *r, BIGNUM *a);
- int	BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p,BN_CTX *ctx);
- int	BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
- 		   const BIGNUM *m,BN_CTX *ctx);
- int	BN_mod_exp_mont(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
- 			const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
- int	BN_mod_exp2_mont(BIGNUM *r, BIGNUM *a1, BIGNUM *p1,BIGNUM *a2,
- 		BIGNUM *p2,BIGNUM *m,BN_CTX *ctx,BN_MONT_CTX *m_ctx);
- int	BN_mod_exp_simple(BIGNUM *r, BIGNUM *a, BIGNUM *p,
- 	BIGNUM *m,BN_CTX *ctx);
- int	BN_mask_bits(BIGNUM *a,int n);
- int	BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, BN_CTX *ctx);
- int	BN_print_fp(FILE *fp, BIGNUM *a);
- int	BN_print(BIO *fp, const BIGNUM *a);
- int	BN_reciprocal(BIGNUM *r, BIGNUM *m, int len, BN_CTX *ctx);
- int	BN_rshift(BIGNUM *r, BIGNUM *a, int n);
- int	BN_rshift1(BIGNUM *r, BIGNUM *a);
- void	BN_clear(BIGNUM *a);
- BIGNUM *bn_expand2(BIGNUM *b, int bits);
  BIGNUM *BN_dup(const BIGNUM *a);
- int	BN_ucmp(const BIGNUM *a, const BIGNUM *b);
- int	BN_set_bit(BIGNUM *a, int n);
- int	BN_clear_bit(BIGNUM *a, int n);
- char *	BN_bn2hex(const BIGNUM *a);
- char *	BN_bn2dec(const BIGNUM *a);
- int 	BN_hex2bn(BIGNUM **a, const char *str);
- int 	BN_dec2bn(BIGNUM **a, const char *str);
- int	BN_gcd(BIGNUM *r,BIGNUM *in_a,BIGNUM *in_b,BN_CTX *ctx);
- BIGNUM *BN_mod_inverse(BIGNUM *ret,BIGNUM *a, const BIGNUM *n,BN_CTX *ctx);
+
+ int BN_num_bytes(const BIGNUM *a);
+ int BN_num_bits(const BIGNUM *a);
+ int BN_num_bits_word(BN_ULONG w);
+
+ int BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
+ int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
+ int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+ int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
+         BN_CTX *ctx);
+ int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
+ int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+ int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+         BN_CTX *ctx);
+ int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx);
+ int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+         const BIGNUM *m, BN_CTX *ctx);
+ int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+
+ int BN_add_word(BIGNUM *a, BN_ULONG w);
+ int BN_sub_word(BIGNUM *a, BN_ULONG w);
+ int BN_mul_word(BIGNUM *a, BN_ULONG w);
+ BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w);
+ BN_ULONG BN_mod_word(BIGNUM *a, BN_ULONG w);
+
+ int BN_cmp(BIGNUM *a, BIGNUM *b);
+ int BN_ucmp(BIGNUM *a, BIGNUM *b);
+ int BN_is_zero(BIGNUM *a);
+ int BN_is_one(BIGNUM *a);
+ int BN_is_word(BIGNUM *a, BN_ULONG w);
+ int BN_is_odd(BIGNUM *a);
+
+ int BN_zero(BIGNUM *a);
+ int BN_one(BIGNUM *a);
+ BIGNUM *BN_value_one(void);
+ int BN_set_word(BIGNUM *a, unsigned long w);
+ unsigned long BN_get_word(BIGNUM *a);
+
+ int BN_rand(BIGNUM *rnd, int bits, int top,int bottom);
+
  BIGNUM *BN_generate_prime(BIGNUM *ret,int bits,int safe,BIGNUM *add,
- 		BIGNUM *rem,void (*callback)(int,int,void *),void *cb_arg);
- int	BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int,void *),
- 		BN_CTX *ctx,void *cb_arg);
- void	ERR_load_BN_strings(void );
- 
- BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w);
- BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w);
- void     bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num);
- BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d);
- BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,int num);
- BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,int num);
- 
- BN_MONT_CTX *BN_MONT_CTX_new(void );
+         BIGNUM *rem,void (*callback)(int,int,void *),void *cb_arg);
+ int BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int,void *),
+         BN_CTX *ctx,void *cb_arg);
+
+ int BN_set_bit(BIGNUM *a, int n);
+ int BN_clear_bit(BIGNUM *a, int n);
+ int BN_is_bit_set(const BIGNUM *a, int n);
+ int BN_mask_bits(BIGNUM *a, int n);
+ int BN_lshift(BIGNUM *r, const BIGNUM *a, int n);
+ int BN_lshift1(BIGNUM *r, BIGNUM *a);
+ int BN_rshift(BIGNUM *r, BIGNUM *a, int n);
+ int BN_rshift1(BIGNUM *r, BIGNUM *a);
+
+ int BN_bn2bin(const BIGNUM *a, unsigned char *to);
+ BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
+ char *BN_bn2hex(const BIGNUM *a);
+ char *BN_bn2dec(const BIGNUM *a);
+ int BN_hex2bn(BIGNUM **a, const char *str);
+ int BN_dec2bn(BIGNUM **a, const char *str);
+ int BN_print_fp(FILE *fp, BIGNUM *a);
+ int BN_print(BIO *fp, const BIGNUM *a);
+ int BN_bn2mpi(const BIGNUM *a, unsigned char *to);
+ BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
+
+ BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n,
+     BN_CTX *ctx);
+
+ BN_RECP_CTX *BN_RECP_CTX_new(void);
+ void BN_RECP_CTX_init(BN_RECP_CTX *recp);
+ void BN_RECP_CTX_free(BN_RECP_CTX *recp);
+ int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
+ int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+        BN_RECP_CTX *recp, BN_CTX *ctx);
+
+ BN_MONT_CTX *BN_MONT_CTX_new(void);
  void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
- int BN_mod_mul_montgomery(BIGNUM *r,BIGNUM *a,BIGNUM *b,BN_MONT_CTX *mont,
- 			  BN_CTX *ctx);
- int BN_from_montgomery(BIGNUM *r,BIGNUM *a,BN_MONT_CTX *mont,BN_CTX *ctx);
  void BN_MONT_CTX_free(BN_MONT_CTX *mont);
- int BN_MONT_CTX_set(BN_MONT_CTX *mont,const BIGNUM *modulus,BN_CTX *ctx);
- BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to,BN_MONT_CTX *from);
- 
- BN_BLINDING *BN_BLINDING_new(BIGNUM *A,BIGNUM *Ai,BIGNUM *mod);
- void BN_BLINDING_free(BN_BLINDING *b);
- int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
- int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *r, BN_CTX *ctx);
- int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
- 
- void BN_set_params(int mul,int high,int low,int mont);
- int BN_get_params(int which);
- 
- void	BN_RECP_CTX_init(BN_RECP_CTX *recp);
- BN_RECP_CTX *BN_RECP_CTX_new(void);
- void	BN_RECP_CTX_free(BN_RECP_CTX *recp);
- int	BN_RECP_CTX_set(BN_RECP_CTX *recp,const BIGNUM *rdiv,BN_CTX *ctx);
- int	BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *x, BIGNUM *y,
- 		BN_RECP_CTX *recp,BN_CTX *ctx);
- int	BN_mod_exp_recp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
- 			const BIGNUM *m, BN_CTX *ctx);
- int	BN_div_recp(BIGNUM *dv, BIGNUM *rem, BIGNUM *m,
- 		BN_RECP_CTX *recp, BN_CTX *ctx);
+ int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
+ BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from);
+ int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b,
+         BN_MONT_CTX *mont, BN_CTX *ctx);
+ int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
+         BN_CTX *ctx);
+ int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont,
+         BN_CTX *ctx);
+
 
 =head1 DESCRIPTION
 
+This library performs arithmetic operations on integers of arbitrary
+size. It was written for use in public key cryptography, such as RSA
+and Diffie-Hellman.
+
+It uses dynamic memory allocation for storing its data structures.
+That means that there is no limit on the size of the numbers
+manipulated by these functions, but return values must always be
+checked in case a memory allocation error has occurred.
+
+The basic object in this library is a B<BIGNUM>. It is used to hold a
+single large integer. This type should be considered opaque and fields
+should not be modified or accessed directly.
+
+The creation of B<BIGNUM> objects is described in L<BN_new(3)>;
+L<BN_add(3)> describes most of the arithmetic operations.
+Comparision is described in L<BN_cmp(3)>; L<BN_zero(3)> describes
+certain assignments, L<BN_rand(3)> the generation of random numbers,
+L<BN_generate_prime(3)> deals with prime numbers and L<BN_set_bit(3)>
+with bit operations. The conversion of B<BIGNUM>s to external
+formats is described in L<BN_bn2bin(3)>.
+
+=head1 INTERNALS
+
+The following description is based on the SSLeay documentation:
+
+ typedef struct bignum_st
+        {
+        int top;        /* Index of last used d. */
+        BN_ULONG *d;    /* Pointer to an array of 'BITS2' bit chunks. */
+        int max;        /* Size of the d array. */
+        int neg;
+        } BIGNUM;
+
+The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s.
+A B<BN_ULONG> can be either 16, 32 or 64 bits in size, depending on
+the 'number of bits' specified in 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
+bn.top=1. B<neg> is 1 if the number is negative.  When a BIGNUM is
+'0', the B<d> field can be NULL and B<top> == 0.  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 conjunction with repeated subroutine
+calls, the B<BN_CTX> structure is used.  This structure contains
+B<BN_CTX_NUM> B<BIGNUM>s.  B<BN_CTX_NUM> is the maximum number of
+temporary B<BIGNUM>s any publicly exported function will use.
+
+ #define BN_CTX_NUM  12
+ typedef struct bignum_ctx
+        {
+        int tos;                    /* top of stack */
+        BIGNUM *bn[BN_CTX_NUM];     /* The variables */
+        } BN_CTX;
+
 =head1 SEE ALSO
 
-err(3), rand(3)
+dh(3), err(3), rand(3), rsa(3), BN_new(3), BN_CTX_new(3), BN_copy(3),
+BN_num_bytes(3), BN_add(3), BN_add_word(3), BN_cmp(3), BN_zero(3),
+BN_rand(3), BN_generate_prime(3), BN_set_bit(3), BN_bn2bin(3),
+BN_mod_inverse(3), BN_mod_mul_reciprocal(3), BN_mod_mul_montgomery(3)
 
 =cut