From e35af275d592188cb0adf3a4cc6641e302acd9a7 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Sun, 2 Nov 2014 19:45:04 +0000 Subject: [PATCH] Update documentation following BN opaquify Reviewed-by: Tim Hudson --- doc/crypto/BN_CTX_new.pod | 26 ++++++++++------ doc/crypto/BN_generate_prime.pod | 46 +++++++++++++++++++++++++--- doc/crypto/BN_mod_mul_montgomery.pod | 40 +++++++++++++----------- doc/crypto/BN_mod_mul_reciprocal.pod | 36 +++++++++++++--------- doc/crypto/BN_new.pod | 28 ++++++++++++----- doc/crypto/bn.pod | 22 ++++++++----- 6 files changed, 136 insertions(+), 62 deletions(-) diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod index bbedbb1778..e86a72ad3c 100644 --- a/doc/crypto/BN_CTX_new.pod +++ b/doc/crypto/BN_CTX_new.pod @@ -12,11 +12,6 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures void BN_CTX_free(BN_CTX *c); -Deprecated: - - void BN_CTX_init(BN_CTX *c); - - =head1 DESCRIPTION A B is a structure that holds B temporary variables used by @@ -33,16 +28,26 @@ If L has been used on the B, L must be called before the B may be freed by BN_CTX_free(). -BN_CTX_init() (deprecated) initializes an existing uninitialized B. -This should not be used for new programs. Use BN_CTX_new() instead. - =head1 RETURN VALUES BN_CTX_new() returns a pointer to the B. If the allocation fails, it returns B and sets an error code that can be obtained by L. -BN_CTX_init() and BN_CTX_free() have no return values. +BN_CTX_free() has no return values. + +=head1 REMOVED FUNCTIONALITY + + void BN_CTX_init(BN_CTX *c); + +BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should +replace use of BN_CTX_init with BN_CTX_new instead: + + BN_CTX *ctx; + ctx = BN_CTX_new(); + if(!ctx) /* Handle error */ + ... + BN_CTX_free(ctx); =head1 SEE ALSO @@ -52,6 +57,7 @@ L =head1 HISTORY BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay -and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b. +and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b and removed in OpenSSL +1.1.0. =cut diff --git a/doc/crypto/BN_generate_prime.pod b/doc/crypto/BN_generate_prime.pod index 4522fa9bdb..f5b05e8328 100644 --- a/doc/crypto/BN_generate_prime.pod +++ b/doc/crypto/BN_generate_prime.pod @@ -3,8 +3,9 @@ =head1 NAME BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, -BN_GENCB_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime, -BN_is_prime_fasttest - generate primes and test for primality +BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, +BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test +for primality =head1 SYNOPSIS @@ -20,10 +21,17 @@ BN_is_prime_fasttest - generate primes and test for primality int BN_GENCB_call(BN_GENCB *cb, int a, int b); - #define BN_GENCB_set_old(gencb, callback, cb_arg) ... + BN_GENCB *BN_GENCB_new(void); - #define BN_GENCB_set(gencb, callback, cb_arg) ... + void BN_GENCB_free(BN_GENCB *cb); + void BN_GENCB_set_old(BN_GENCB *gencb, + void (*callback)(int, int, void *), void *cb_arg); + + void BN_GENCB_set(BN_GENCB *gencb, + int (*callback)(int, int, BN_GENCB *), void *cb_arg); + + void *BN_GENCB_get_arg(BN_GENCB *cb); Deprecated: @@ -103,6 +111,9 @@ B structure that are supported: "new" style and "old" style. New programs should prefer the "new" style, whilst the "old" style is provided for backwards compatibility purposes. +A BN_GENCB structure should be created through a call to BN_GENCB_new, and freed +through a call to BN_GENCB_free. + For "new" style callbacks a BN_GENCB structure should be initialised with a call to BN_GENCB_set(), where B is a B, B is of type B and B is a B. @@ -114,6 +125,9 @@ A callback is invoked through a call to B. This will check the type of the callback and will invoke B for new style callbacks or B for old style. +It is possible to obtained the argument associated with a BN_GENCB structure +(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. + BN_generate_prime (deprecated) works in the same way as BN_generate_prime_ex but expects an old style callback function directly in the B parameter, and an argument to pass to it in @@ -132,10 +146,31 @@ prime with an error probability of less than 0.25^B, and BN_generate_prime() returns the prime number on success, B otherwise. +BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B +otherwise. + +BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB +structure. + Callback functions should return 1 on success or 0 on error. The error codes can be obtained by L. +=head1 REMOVED FUNCTIONALITY + +As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure +directly, as in: + + BN_GENCB callback; + +Instead applications should create a BN_GENCB structure using BN_GENCB_new: + + BN_GENCB *callback; + callback = BN_GENCB_new(); + if(!callback) /* handle error */ + ... + BN_GENCB_free(callback); + =head1 SEE ALSO L, L, L @@ -145,6 +180,7 @@ L, L, L The B arguments to BN_generate_prime() and to BN_is_prime() were added in SSLeay 0.9.0. The B argument to BN_generate_prime() was added in SSLeay 0.9.1. -BN_is_prime_fasttest() was added in OpenSSL 0.9.5. +BN_is_prime_fasttest() was added in OpenSSL 0.9.5. BN_GENCB_new, BN_GENCB_free +and BN_GENCB_get_arg were added in OpenSSL 1.1.0 =cut diff --git a/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod index 6b16351b92..51687488ce 100644 --- a/doc/crypto/BN_mod_mul_montgomery.pod +++ b/doc/crypto/BN_mod_mul_montgomery.pod @@ -11,7 +11,6 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication #include BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_init(BN_MONT_CTX *ctx); void BN_MONT_CTX_free(BN_MONT_CTX *mont); int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); @@ -34,7 +33,6 @@ but they may be useful when several operations are to be performed using the same modulus. BN_MONT_CTX_new() allocates and initializes a B structure. -BN_MONT_CTX_init() initializes an existing uninitialized B. BN_MONT_CTX_set() sets up the I structure from the modulus I by precomputing its inverse and a value R. @@ -55,27 +53,12 @@ Note that I must be non-negative and smaller than the modulus. For all functions, I is a previously allocated B used for temporary variables. -The B structure is defined as follows: - - typedef struct bn_mont_ctx_st - { - int ri; /* number of bits in R */ - BIGNUM RR; /* R^2 (used to convert to Montgomery form) */ - BIGNUM N; /* The modulus */ - BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1 - * (Ni is only stored for bignum algorithm) */ - BN_ULONG n0; /* least significant word of Ni */ - int flags; - } BN_MONT_CTX; - -BN_to_montgomery() is a macro. - =head1 RETURN VALUES BN_MONT_CTX_new() returns the newly allocated B, and NULL on error. -BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values. +BN_MONT_CTX_free() has no return value. For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by L. @@ -85,6 +68,26 @@ The error codes can be obtained by L. The inputs must be reduced modulo B, otherwise the result will be outside the expected range. +=head1 REMOVED FUNCTIONALITY + + void BN_MONT_CTX_init(BN_MONT_CTX *c); + +BN_MONT_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to +initialize an existing uninitialized B. Typically this would be +done as follows: + + BN_MONT_CTX ctx; + BN_MONT_CTX_init(&ctx); + +Instead applications should create a BN_MONT_CTX structure using +BN_MONT_CTX_new: + + BN_MONT_CTX *ctx; + ctx = BN_MONT_CTX_new(); + if(!ctx) /* handle error */ + ... + BN_MONT_CTX_free(ctx); + =head1 SEE ALSO L, L, L, @@ -97,5 +100,6 @@ BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() are available in all versions of SSLeay and OpenSSL. BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b. +BN_MONT_CTX_init was removed in OpenSSL 1.1.0 =cut diff --git a/doc/crypto/BN_mod_mul_reciprocal.pod b/doc/crypto/BN_mod_mul_reciprocal.pod index 74a216ddc2..cd4b728f47 100644 --- a/doc/crypto/BN_mod_mul_reciprocal.pod +++ b/doc/crypto/BN_mod_mul_reciprocal.pod @@ -11,7 +11,6 @@ reciprocal #include 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); @@ -44,18 +43,7 @@ later be stored in B. BN_div_recp() divides B by B using B. It places the quotient in B and the remainder in B. -The B structure is defined as follows: - - typedef struct bn_recp_ctx_st - { - BIGNUM N; /* the divisor */ - BIGNUM Nr; /* the reciprocal */ - int num_bits; - int shift; - int flags; - } BN_RECP_CTX; - -It cannot be shared between threads. +The B structure cannot be shared between threads. =head1 RETURN VALUES @@ -67,6 +55,26 @@ BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values. For the other functions, 1 is returned for success, 0 on error. The error codes can be obtained by L. +=head1 REMOVED FUNCTIONALITY + + void BN_RECP_CTX_init(BN_RECP_CTX *recp); + +BN_RECP_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to +initialize an existing uninitialized B. Typically this would be +done as follows: + + BN_RECP_CTX ctx; + BN_RECP_CTX_init(&ctx); + +Applications should replace use of BN_RECP_CTX_init with BN_RECP_CTX_new +instead: + + BN_RECP_CTX *ctx; + ctx = BN_RECP_CTX_new(); + if(!ctx) /* Handle error */ + ... + BN_RECP_CTX_free(ctx); + =head1 SEE ALSO L, L, L, @@ -76,6 +84,6 @@ L B was added in SSLeay 0.9.0. Before that, the function BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal() -arguments were different. +arguments were different. BN_RECP_CTX_init was removed in OpenSSL 1.1.0 =cut diff --git a/doc/crypto/BN_new.pod b/doc/crypto/BN_new.pod index ab7a105e3a..61743e37fe 100644 --- a/doc/crypto/BN_new.pod +++ b/doc/crypto/BN_new.pod @@ -10,8 +10,6 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs BIGNUM *BN_new(void); - void BN_init(BIGNUM *); - void BN_clear(BIGNUM *a); void BN_free(BIGNUM *a); @@ -20,8 +18,7 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs =head1 DESCRIPTION -BN_new() allocates and initializes a B structure. BN_init() -initializes an existing uninitialized B. +BN_new() allocates and initializes a B structure. BN_clear() is used to destroy sensitive data such as keys when they are no longer needed. It erases the memory used by B and sets it @@ -37,8 +34,25 @@ BN_new() returns a pointer to the B. If the allocation fails, it returns B and sets an error code that can be obtained by L. -BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return -values. +BN_clear(), BN_free() and BN_clear_free() have no return values. + +=head1 REMOVED FUNCTIONALITY + + void BN_init(BIGNUM *); + +BN_init() is no longer available as of OpenSSL 1.1.0. It was used to initialize +an existing uninitialized B. Typically this would be done as follows: + + BIGNUM a; + BN_init(&a); + +Applications should replace use of BN_init with BN_new instead: + + BIGNUM *a; + a = BN_new(); + if(!a) /* Handle error */ + ... + BN_free(a); =head1 SEE ALSO @@ -48,6 +62,6 @@ L, L BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay -0.9.1b. +0.9.1b and removed in OpenSSL 1.1.0. =cut diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod index cd2f8e50c6..b52916bada 100644 --- a/doc/crypto/bn.pod +++ b/doc/crypto/bn.pod @@ -10,12 +10,10 @@ bn - multiprecision integer arithmetics BIGNUM *BN_new(void); 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); @@ -74,10 +72,20 @@ bn - multiprecision integer arithmetics int BN_rand_range(BIGNUM *rnd, BIGNUM *range); int BN_pseudo_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(const BIGNUM *p, int nchecks, - void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); + int BN_generate_prime_ex(BIGNUM *ret,int bits,int safe, const BIGNUM *add, + const BIGNUM *rem, BN_GENCB *cb); + + int BN_is_prime_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, BN_GENCB *cb); + + int BN_is_prime_fasttest_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, + int do_trial_division, BN_GENCB *cb); + + int BN_GENCB_call(BN_GENCB *cb, int a, int b); + BN_GENCB *BN_GENCB_new(void); + void BN_GENCB_free(BN_GENCB *cb); + void BN_GENCB_set_old(BN_GENCB *gencb, void (*callback)(int, int, void *), void *cb_arg); + void BN_GENCB_set(BN_GENCB *gencb, int (*callback)(int, int, BN_GENCB *), void *cb_arg); + void *BN_GENCB_get_arg(BN_GENCB *cb); int BN_set_bit(BIGNUM *a, int n); int BN_clear_bit(BIGNUM *a, int n); @@ -103,14 +111,12 @@ bn - multiprecision integer arithmetics 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); void BN_MONT_CTX_free(BN_MONT_CTX *mont); 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); -- 2.34.1