Simplify BN_rand_range
[openssl.git] / doc / crypto / bn.pod
index bc500ab..f7ce9df 100644 (file)
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
 
 =head1 NAME
 
-bn - Multiprecision integer arithmetics
+bn - multiprecision integer arithmetics
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 
@@ -21,19 +21,27 @@ bn - Multiprecision integer arithmetics
  BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);
  BIGNUM *BN_dup(const BIGNUM *a);
 
  BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b);
  BIGNUM *BN_dup(const BIGNUM *a);
 
+ BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b);
+
  int BN_num_bytes(const BIGNUM *a);
  int BN_num_bits(const BIGNUM *a);
  int BN_num_bits_word(BN_ULONG w);
 
  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_add(BIGNUM *r, const BIGNUM *a, const 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_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
  int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
+ int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx);
  int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
          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(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+ int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
+ int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+         BN_CTX *ctx);
+ int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
+         BN_CTX *ctx);
  int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
          BN_CTX *ctx);
  int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m,
          BN_CTX *ctx);
+ int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, 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_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);
@@ -43,7 +51,7 @@ bn - Multiprecision integer arithmetics
  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);
  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);
+ BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w);
 
  int BN_cmp(BIGNUM *a, BIGNUM *b);
  int BN_ucmp(BIGNUM *a, BIGNUM *b);
 
  int BN_cmp(BIGNUM *a, BIGNUM *b);
  int BN_ucmp(BIGNUM *a, BIGNUM *b);
@@ -58,12 +66,14 @@ bn - Multiprecision integer arithmetics
  int BN_set_word(BIGNUM *a, unsigned long w);
  unsigned long BN_get_word(BIGNUM *a);
 
  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);
+ int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
+ int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
+ int BN_rand_range(BIGNUM *rnd, BIGNUM *range);
 
 
- 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);
+ 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(const 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_set_bit(BIGNUM *a, int n);
  int BN_clear_bit(BIGNUM *a, int n);
@@ -81,7 +91,7 @@ bn - Multiprecision integer arithmetics
  int BN_hex2bn(BIGNUM **a, const char *str);
  int BN_dec2bn(BIGNUM **a, const char *str);
  int BN_print(BIO *fp, const BIGNUM *a);
  int BN_hex2bn(BIGNUM **a, const char *str);
  int BN_dec2bn(BIGNUM **a, const char *str);
  int BN_print(BIO *fp, const BIGNUM *a);
- int BN_print_fp(FILE *fp, BIGNUM *a);
+ int BN_print_fp(FILE *fp, const BIGNUM *a);
  int BN_bn2mpi(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);
  BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret);
 
@@ -125,51 +135,18 @@ should not be modified or accessed directly.
 
 The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>;
 L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations.
 
 The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>;
 L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations.
-Comparision is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)>
+Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)>
 describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of
 random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime
 numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion
 of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>.
 
 describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of
 random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime
 numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion
 of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|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
 
 =head1 SEE ALSO
 
+L<bn_internal(3)|bn_internal(3)>,
 L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
 L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
 L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
 L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
-L<BN_copy(3)|BN_copy(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>,
+L<BN_copy(3)|BN_copy(3)>, L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>,
 L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>,
 L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>,
 L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>,
 L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>,
 L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>,
 L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>,