Commit e35af275 authored by Matt Caswell's avatar Matt Caswell
Browse files

Update documentation following BN opaquify 



Reviewed-by: default avatarTim Hudson <tjh@openssl.org>
parent 19391879

doc/crypto/BN_CTX_new.pod

+16 −10
Original line number Diff line number Diff line
@@ -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<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
@@ -33,16 +28,26 @@ If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>, 
L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX>

may be freed by BN_CTX_free().



BN_CTX_init() (deprecated) initializes an existing uninitialized B<BN_CTX>.

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<BN_CTX>. If the allocation fails,

it returns B<NULL> and sets an error code that can be obtained by

L<ERR_get_error(3)|ERR_get_error(3)>.



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<BN_CTX_start(3)|BN_CTX_start(3)> 
=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

doc/crypto/BN_generate_prime.pod

+41 −5
Original line number Diff line number Diff line
@@ -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<BN_GENCB> 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<gencb> is a B<BN_GENCB *>, B<callback> is of

type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
@@ -114,6 +125,9 @@ A callback is invoked through a call to B<BN_GENCB_call>. This will check 
the type of the callback and will invoke B<callback(a, b, gencb)> for new

style callbacks or B<callback(a, b, cb_arg)> 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<callback> parameter, and an argument to pass to it in
@@ -132,10 +146,31 @@ prime with an error probability of less than 0.25^B<nchecks>, and 


BN_generate_prime() returns the prime number on success, B<NULL> otherwise.



BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL>

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<ERR_get_error(3)|ERR_get_error(3)>.



=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<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>
@@ -145,6 +180,7 @@ L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)> 
The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime()

were added in SSLeay 0.9.0. The B<ret> 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

doc/crypto/BN_mod_mul_montgomery.pod

+22 −18
Original line number Diff line number Diff line
@@ -11,7 +11,6 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication 
 #include <openssl/bn.h>



 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<BN_MONT_CTX> structure.

BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>.



BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>

by precomputing its inverse and a value R.
@@ -55,27 +53,12 @@ Note that I<a> must be non-negative and smaller than the modulus. 
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for

temporary variables.



The B<BN_MONT_CTX> 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<BN_MONT_CTX>, 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<ERR_get_error(3)|ERR_get_error(3)>.
@@ -85,6 +68,26 @@ The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 
The inputs must be reduced modulo B<m>, 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<BN_MONT_CTX>. 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<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
@@ -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

doc/crypto/BN_mod_mul_reciprocal.pod

+22 −14
Original line number Diff line number Diff line
@@ -11,7 +11,6 @@ reciprocal 
 #include <openssl/bn.h>



 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<recp>. 
BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient

in B<dv> and the remainder in B<rem>.



The B<BN_RECP_CTX> 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<BN_RECP_CTX> 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<ERR_get_error(3)|ERR_get_error(3)>.



=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<BN_RECP_CTX>. 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<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
@@ -76,6 +84,6 @@ L<BN_CTX_new(3)|BN_CTX_new(3)> 


B<BN_RECP_CTX> 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

doc/crypto/BN_new.pod

+21 −7
Original line number Diff line number Diff line
@@ -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<BIGNUM> structure. BN_init()

initializes an existing uninitialized B<BIGNUM>.

BN_new() allocates and initializes a B<BIGNUM> 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<a> and sets it
@@ -37,8 +34,25 @@ BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails, 
it returns B<NULL> and sets an error code that can be obtained

by L<ERR_get_error(3)|ERR_get_error(3)>.



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<BIGNUM>. 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<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> 


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