Update documentation following BN opaquify

Reviewed-by: NTim Hudson <tjh@openssl.org>

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

@@ -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

@@ -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

@@ -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

@@ -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

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);