xref: /freebsd/crypto/openssl/doc/man3/BN_BLINDING_new.pod (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95)
1=pod
2
3=head1 NAME
4
5BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
6BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
7BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread,
8BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
9BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
10
11=head1 SYNOPSIS
12
13 #include <openssl/bn.h>
14
15 BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
16                              BIGNUM *mod);
17 void BN_BLINDING_free(BN_BLINDING *b);
18 int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
19 int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
20 int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
21 int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
22                            BN_CTX *ctx);
23 int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
24                           BN_CTX *ctx);
25 int BN_BLINDING_is_current_thread(BN_BLINDING *b);
26 void BN_BLINDING_set_current_thread(BN_BLINDING *b);
27 int BN_BLINDING_lock(BN_BLINDING *b);
28 int BN_BLINDING_unlock(BN_BLINDING *b);
29 unsigned long BN_BLINDING_get_flags(const BN_BLINDING *b);
30 void BN_BLINDING_set_flags(BN_BLINDING *b, unsigned long flags);
31 BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
32                                       const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
33                                       int (*bn_mod_exp)(BIGNUM *r,
34                                                         const BIGNUM *a,
35                                                         const BIGNUM *p,
36                                                         const BIGNUM *m,
37                                                         BN_CTX *ctx,
38                                                         BN_MONT_CTX *m_ctx),
39                                       BN_MONT_CTX *m_ctx);
40
41=head1 DESCRIPTION
42
43BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
44the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
45
46BN_BLINDING_free() frees the B<BN_BLINDING> structure.
47If B<b> is NULL, nothing is done.
48
49BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
50the B<A> and B<Ai> or, after specific number of uses and if the
51necessary parameters are set, by re-creating the blinding parameters.
52
53BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
54If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
55returned in B<r> (this is useful if a B<RSA> object is shared among
56several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
57inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
58the inverse blinding.
59
60BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
61functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
62with B<r> set to NULL.
63
64BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
65structure is owned by the current thread. This is to help users
66provide proper locking if needed for multi-threaded use.
67
68BN_BLINDING_set_current_thread() sets the current thread as the
69owner of the B<BN_BLINDING> structure.
70
71BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
72
73BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
74
75BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
76there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
77B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
78automatic update of the B<BN_BLINDING> parameters after each use
79and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
80of the B<BN_BLINDING> parameters after a fixed number of uses (currently
8132). In newly allocated B<BN_BLINDING> objects no flags are set.
82BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
83
84BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
85using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
86B<m_ctx> can be used to pass special functions for exponentiation
87(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
88
89=head1 RETURN VALUES
90
91BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
92or NULL in case of an error.
93
94BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
95BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
96success and 0 if an error occurred.
97
98BN_BLINDING_is_current_thread() returns 1 if the current thread owns
99the B<BN_BLINDING> object, 0 otherwise.
100
101BN_BLINDING_set_current_thread() doesn't return anything.
102
103BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
104succeeded or 0 on error.
105
106BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
107(a B<unsigned long> value).
108
109BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
110parameters or NULL on error.
111
112=head1 HISTORY
113
114BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
115deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
116
117=head1 COPYRIGHT
118
119Copyright 2005-2021 The OpenSSL Project Authors. All Rights Reserved.
120
121Licensed under the Apache License 2.0 (the "License").  You may not use
122this file except in compliance with the License.  You can obtain a copy
123in the file LICENSE in the source distribution or at
124L<https://www.openssl.org/source/license.html>.
125
126=cut
127