BN_BLINDING_new.pod 4.5 KB
Newer Older
N
Nils Larsch 已提交
1 2 3 4 5 6
=pod

=head1 NAME

BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, 
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, 
M
Matt Caswell 已提交
7
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags,
N
Nils Larsch 已提交
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
functions.

=head1 SYNOPSIS

 #include <openssl/bn.h>

 BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
	BIGNUM *mod);
 void BN_BLINDING_free(BN_BLINDING *b);
 int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
 int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
 int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
 int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
	BN_CTX *ctx);
 int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
	BN_CTX *ctx);
25
 #ifndef OPENSSL_NO_DEPRECATED
26 27
 unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
 void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
28 29
 #endif
 CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
N
Nils Larsch 已提交
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
 unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
 void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
 BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
	const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
	int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
			  const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
	BN_MONT_CTX *m_ctx);

=head1 DESCRIPTION

BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.

BN_BLINDING_free() frees the B<BN_BLINDING> structure.

BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
the B<A> and B<Ai> or, after specific number of uses and if the
necessary parameters are set, by re-creating the blinding parameters.

BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
returned in B<r> (this is useful if a B<RSA> object is shared amoung
several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
the inverse blinding.

BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
with B<r> set to NULL.

60 61 62 63 64
BN_BLINDING_thread_id() provides access to the B<CRYPTO_THREADID>
object within the B<BN_BLINDING> structure. This is to help users
provide proper locking if needed for multi-threaded use. The "thread
id" object of a newly allocated B<BN_BLINDING> structure is
initialised to the thread id in which BN_BLINDING_new() was called.
N
Nils Larsch 已提交
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86

BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
automatic update of the B<BN_BLINDING> parameters after each use
and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
of the B<BN_BLINDING> parameters after a fixed number of uses (currently
32). In newly allocated B<BN_BLINDING> objects no flags are set.
BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.

BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
B<m_ctx> can be used to pass special functions for exponentiation
(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).

=head1 RETURN VALUES

BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
or NULL in case of an error.

BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
87
success and 0 if an error occurred.
N
Nils Larsch 已提交
88

89 90
BN_BLINDING_thread_id() returns a pointer to the thread id object
within a B<BN_BLINDING> object.
N
Nils Larsch 已提交
91 92 93 94 95 96 97 98 99 100 101 102 103

BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
(a B<unsigned long> value).

BN_BLINDING_create_param() returns the newly created B<BN_BLINDING> 
parameters or NULL on error.

=head1 SEE ALSO

L<bn(3)|bn(3)>

=head1 HISTORY

104
BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it
105 106
deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id.

N
Nils Larsch 已提交
107 108 109 110 111 112 113 114 115
BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8

=head1 AUTHOR

Nils Larsch for the OpenSSL project (http://www.openssl.org).

=cut