Document the BN library.
[openssl.git] / crypto / bn / bn.h
index 2c14a1d58202c39a94d1b89b82ba1d7ea8e714fd..5d789ff96cafe5b33f21c952b0a74768b8b1a79d 100644 (file)
@@ -1,4 +1,4 @@
-/* crypto/bn/bn.org */
+/* crypto/bn/bn.h */
 /* Copyright (C) 1995-1997 Eric Young (eay@cryptsoft.com)
  * All rights reserved.
  *
  * [including the GNU Public Licence.]
  */
 
-/* WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING 
- *
- * Always modify bn.org since bn.h is automatically generated from
- * it during SSLeay configuration.
- *
- * WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
- */
-
 #ifndef HEADER_BN_H
 #define HEADER_BN_H
 
+#ifndef WIN16
+#include <stdio.h> /* FILE */
+#endif
+#include <openssl/opensslconf.h>
+
 #ifdef  __cplusplus
 extern "C" {
 #endif
 
-#undef BN_LLONG
-
-#ifdef WIN32
-#define BN_LLONG /* This comment stops Configure mutilating things */
+#ifdef VMS
+#undef BN_LLONG /* experimental, so far... */
 #endif
 
 #define BN_MUL_COMBA
 #define BN_SQR_COMBA
-#undef BN_RECURSION
+#define BN_RECURSION
 #define RECP_MUL_MOD
 #define MONT_MUL_MOD
 
@@ -98,17 +93,6 @@ extern "C" {
 #define BN_DIV2W
 #endif
 
-/* Only one for the following should be defined */
-/* The prime number generation stuff may not work when
- * EIGHT_BIT but I don't care since I've only used this mode
- * for debuging the bignum libraries */
-#undef SIXTY_FOUR_BIT_LONG
-#undef SIXTY_FOUR_BIT
-#define THIRTY_TWO_BIT
-#undef SIXTEEN_BIT
-#undef EIGHT_BIT
-
-
 /* assuming long is 64bit - this is the DEC Alpha
  * unsigned long long is only 64 bits :-(, don't define
  * BN_LLONG for the DEC Alpha */
@@ -135,11 +119,11 @@ extern "C" {
 /* This is where the long long data type is 64 bits, but long is 32.
  * For machines where there are 64bit registers, this is the mode to use.
  * IRIX, on R4000 and above should use this mode, along with the relevent
- * assember code :-).  Do NOT define BN_ULLONG.
+ * assember code :-).  Do NOT define BN_LLONG.
  */
 #ifdef SIXTY_FOUR_BIT
 #undef BN_LLONG
-/* #define BN_ULLONG   unsigned long long */
+#undef BN_ULLONG
 #define BN_ULONG       unsigned long long
 #define BN_LONG                long long
 #define BN_BITS                128
@@ -158,7 +142,7 @@ extern "C" {
 #endif
 
 #ifdef THIRTY_TWO_BIT
-#ifdef WIN32
+#if defined(WIN32) && !defined(__GNUC__)
 #define BN_ULLONG      unsigned _int64
 #else
 #define BN_ULLONG      unsigned long long
@@ -169,7 +153,12 @@ extern "C" {
 #define BN_BYTES       4
 #define BN_BITS2       32
 #define BN_BITS4       16
+#ifdef WIN32
+/* VC++ doesn't like the LL suffix */
+#define BN_MASK                (0xffffffffffffffffL)
+#else
 #define BN_MASK                (0xffffffffffffffffLL)
+#endif
 #define BN_MASK2       (0xffffffffL)
 #define BN_MASK2l      (0xffff)
 #define BN_MASK2h1     (0xffff8000L)
@@ -294,7 +283,8 @@ typedef struct bn_recp_ctx_st
 #define BN_to_montgomery(r,a,mont,ctx) BN_mod_mul_montgomery(\
        r,a,&((mont)->RR),(mont),ctx)
 
-#define BN_prime_checks                (5)
+#define BN_prime_checks 0 /* default: select number of iterations
+                            based on the size of the number */
 
 #define BN_num_bytes(a)        ((BN_num_bits(a)+7)/8)
 #define BN_is_word(a,w)        (((a)->top == 1) && ((a)->d[0] == (BN_ULONG)(w)))
@@ -321,30 +311,30 @@ typedef struct bn_recp_ctx_st
                } \
        }
 
-#ifndef NOPROTO
 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(BIGNUM *a);
+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);
-BIGNUM *BN_copy(BIGNUM *a, BIGNUM *b);
-BIGNUM *BN_bin2bn(unsigned char *s,int len,BIGNUM *ret);
-int    BN_bn2bin(BIGNUM *a, unsigned char *to);
+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(BIGNUM *a, unsigned char *to);
-int    BN_sub(BIGNUM *r, BIGNUM *a, BIGNUM *b);
-int    BN_usub(BIGNUM *r, BIGNUM *a, BIGNUM *b);
-int    BN_uadd(BIGNUM *r, BIGNUM *a, BIGNUM *b);
-int    BN_add(BIGNUM *r, BIGNUM *a, BIGNUM *b);
-int    BN_mod(BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
-int    BN_div(BIGNUM *dv, BIGNUM *rem, BIGNUM *m, BIGNUM *d, BN_CTX *ctx);
-int    BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b,BN_CTX *ctx);
+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, const BIGNUM *a, const 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);
@@ -353,49 +343,49 @@ 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(BIGNUM *a, BIGNUM *b);
+int    BN_cmp(const BIGNUM *a, const BIGNUM *b);
 void   BN_free(BIGNUM *a);
-int    BN_is_bit_set(BIGNUM *a, int n);
-int    BN_lshift(BIGNUM *r, BIGNUM *a, int n);
+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, BIGNUM *p, BIGNUM *m,BN_CTX *ctx);
-int    BN_mod_exp_mont(BIGNUM *r, BIGNUM *a, BIGNUM *p, BIGNUM *m,BN_CTX *ctx,
-               BN_MONT_CTX *m_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, BIGNUM *m,
-       BN_CTX *ctx);
+int    BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, BN_CTX *ctx);
 #ifndef WIN16
 int    BN_print_fp(FILE *fp, BIGNUM *a);
 #endif
 #ifdef HEADER_BIO_H
-int    BN_print(BIO *fp, BIGNUM *a);
+int    BN_print(BIO *fp, const BIGNUM *a);
 #else
-int    BN_print(char *fp, BIGNUM *a);
+int    BN_print(char *fp, const BIGNUM *a);
 #endif
 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(BIGNUM *a);
-int    BN_ucmp(BIGNUM *a, BIGNUM *b);
+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(BIGNUM *a);
-char * BN_bn2dec(BIGNUM *a);
-int    BN_hex2bn(BIGNUM **a,char *str);
-int    BN_dec2bn(BIGNUM **a,char *str);
+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, BIGNUM *n,BN_CTX *ctx);
-BIGNUM *BN_generate_prime(BIGNUM *ret,int bits,int strong,BIGNUM *add,
-               BIGNUM *rem,void (*callback)(int,int,char *),char *cb_arg);
-int    BN_is_prime(BIGNUM *p,int nchecks,void (*callback)(int,int,char *),
-               BN_CTX *ctx,char *cb_arg);
+BIGNUM *BN_mod_inverse(BIGNUM *ret,BIGNUM *a, const BIGNUM *n,BN_CTX *ctx);
+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);
@@ -408,10 +398,10 @@ BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp,int num);
 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);
+                         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,BIGNUM *modulus,BN_CTX *ctx);
+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);
@@ -423,142 +413,23 @@ 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); /* 0, mul, 1 high, 2 low, 3 mont */
 
-void bn_mul_normal(BN_ULONG *r,BN_ULONG *a,int na,BN_ULONG *b,int nb);
-void bn_mul_comba8(BN_ULONG *r,BN_ULONG *a,BN_ULONG *b);
-void bn_mul_comba4(BN_ULONG *r,BN_ULONG *a,BN_ULONG *b);
-void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp);
-void bn_sqr_comba8(BN_ULONG *r,BN_ULONG *a);
-void bn_sqr_comba4(BN_ULONG *r,BN_ULONG *a);
-int bn_cmp_words(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 *t);
-void bn_mul_part_recursive(BN_ULONG *r,BN_ULONG *a,BN_ULONG *b,
-       int tn, int n,BN_ULONG *t);
-void bn_sqr_recursive(BN_ULONG *r,BN_ULONG *a, int n2, BN_ULONG *t);
-void bn_mul_low_normal(BN_ULONG *r,BN_ULONG *a,BN_ULONG *b, int n);
-
 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,BIGNUM *rdiv,BN_CTX *ctx);
+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, BIGNUM *a, BIGNUM *p, BIGNUM *m,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);
 
 
-#else
-
-BIGNUM *BN_value_one();
-char * BN_options();
-BN_CTX *BN_CTX_new();
-void   BN_CTX_init();
-void   BN_CTX_free();
-int     BN_rand();
-int    BN_num_bits();
-int    BN_num_bits_word();
-BIGNUM *BN_new();
-void   BN_init();
-void   BN_clear_free();
-BIGNUM *BN_copy();
-BIGNUM *BN_bin2bn();
-int    BN_bn2bin();
-BIGNUM *BN_mpi2bn();
-int    BN_bn2mpi();
-int    BN_sub();
-int    BN_usub();
-int    BN_uadd();
-int    BN_add();
-int    BN_mod();
-int    BN_div();
-int    BN_mul();
-int    BN_sqr();
-BN_ULONG BN_mod_word();
-BN_ULONG BN_div_word();
-int    BN_add_word();
-int    BN_sub_word();
-int    BN_mul_word();
-int    BN_set_word();
-unsigned long BN_get_word();
-int    BN_cmp();
-void   BN_free();
-int    BN_is_bit_set();
-int    BN_lshift();
-int    BN_lshift1();
-int    BN_exp();
-int    BN_mod_exp();
-int    BN_mod_exp_mont();
-int    BN_mod_exp_recp();
-int    BN_mod_exp_simple();
-int    BN_mask_bits();
-int    BN_mod_mul_reciprocal();
-int    BN_mod_mul();
-#ifndef WIN16
-int    BN_print_fp();
-#endif
-int    BN_print();
-int    BN_reciprocal();
-int    BN_rshift();
-int    BN_rshift1();
-void   BN_clear();
-BIGNUM *bn_expand2();
-BIGNUM *BN_dup();
-int    BN_ucmp();
-int    BN_set_bit();
-int    BN_clear_bit();
-char * BN_bn2hex();
-char * BN_bn2dec();
-int    BN_hex2bn();
-int    BN_dec2bn();
-int    BN_gcd();
-BIGNUM *BN_mod_inverse();
-BIGNUM *BN_generate_prime();
-int    BN_is_prime();
-void   ERR_load_BN_strings();
-
-BN_ULONG bn_mul_add_words();
-BN_ULONG bn_mul_words();
-void     bn_sqr_words();
-BN_ULONG bn_div_words();
-BN_ULONG bn_add_words();
-BN_ULONG bn_sub_words();
-
-int BN_mod_mul_montgomery();
-int BN_from_montgomery();
-BN_MONT_CTX *BN_MONT_CTX_new();
-void BN_MONT_CTX_init();
-void BN_MONT_CTX_free();
-int BN_MONT_CTX_set();
-
-BN_BLINDING *BN_BLINDING_new();
-void BN_BLINDING_free();
-int BN_BLINDING_update();
-int BN_BLINDING_convert();
-int BN_BLINDING_invert();
-
-void bn_mul_normal();
-void bn_mul_comba8();
-void bn_mul_comba4();
-void bn_sqr_normal();
-void bn_sqr_comba8();
-void bn_sqr_comba4();
-int bn_cmp_words();
-void bn_mul_recursive();
-void bn_mul_part_recursive();
-void bn_sqr_recursive();
-void bn_mul_low_normal();
-
-void   BN_RECP_CTX_init();
-BN_RECP_CTX *BN_RECP_CTX_new();
-void   BN_RECP_CTX_free();
-int    BN_RECP_CTX_set();
-int    BN_mod_mul_reciprocal();
-int    BN_mod_exp_recp();
-int    BN_div_recp();
-
-#endif
-
 /* BEGIN ERROR CODES */
+/* The following lines are auto generated by the script mkerr.pl. Any changes
+ * made after this point may be overwritten when the script is next run.
+ */
+
 /* Error codes for the BN functions. */
 
 /* Function codes. */
@@ -587,9 +458,9 @@ int BN_div_recp();
 #define BN_R_ENCODING_ERROR                             104
 #define BN_R_EXPAND_ON_STATIC_BIGNUM_DATA               105
 #define BN_R_INVALID_LENGTH                             106
-#define BN_R_NOT_INITALISED                             107
+#define BN_R_NOT_INITIALIZED                            107
 #define BN_R_NO_INVERSE                                         108
+
 #ifdef  __cplusplus
 }
 #endif