Update documentation following BN opaquify
Reviewed-by: Tim Hudson <tjh@openssl.org>
This commit is contained in:
Matt Caswell
parent
1939187922
commit
e35af275d5
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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);
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user