| blob | f50680b756fe3246868d4c1fd14299bebd0b840c |
1 .\" $NetBSD: BN_BLINDING_new.3,v 1.14 2015/06/12 17:01:13 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "BN_BLINDING_new 3"
138 .TH BN_BLINDING_new 3 "2014-04-07" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
145 BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
146 BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_get_flags,
147 BN_BLINDING_set_flags, BN_BLINDING_create_param \- blinding related BIGNUM
148 functions.
149 .SH "LIBRARY"
150 libcrypto, -lcrypto
151 .SH "SYNOPSIS"
152 .IX Header "SYNOPSIS"
153 .Vb 1
154 \& #include <openssl/bn.h>
155 \&
156 \& BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
157 \& BIGNUM *mod);
158 \& void BN_BLINDING_free(BN_BLINDING *b);
159 \& int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
160 \& int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
161 \& int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
162 \& int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
163 \& BN_CTX *ctx);
164 \& int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
165 \& BN_CTX *ctx);
166 \& #ifndef OPENSSL_NO_DEPRECATED
167 \& unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
168 \& void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
169 \& #endif
170 \& CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
171 \& unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
172 \& void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
173 \& BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
174 \& const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
175 \& int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
176 \& const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
177 \& BN_MONT_CTX *m_ctx);
178 .Ve
179 .SH "DESCRIPTION"
180 .IX Header "DESCRIPTION"
181 \&\fIBN_BLINDING_new()\fR allocates a new \fB\s-1BN_BLINDING\s0\fR structure and copies
182 the \fBA\fR and \fBAi\fR values into the newly created \fB\s-1BN_BLINDING\s0\fR object.
183 .PP
184 \&\fIBN_BLINDING_free()\fR frees the \fB\s-1BN_BLINDING\s0\fR structure.
185 .PP
186 \&\fIBN_BLINDING_update()\fR updates the \fB\s-1BN_BLINDING\s0\fR parameters by squaring
187 the \fBA\fR and \fBAi\fR or, after specific number of uses and if the
188 necessary parameters are set, by re-creating the blinding parameters.
189 .PP
190 \&\fIBN_BLINDING_convert_ex()\fR multiplies \fBn\fR with the blinding factor \fBA\fR.
191 If \fBr\fR is not \s-1NULL\s0 a copy the inverse blinding factor \fBAi\fR will be
192 returned in \fBr\fR (this is useful if a \fB\s-1RSA\s0\fR object is shared among
193 several threads). \fIBN_BLINDING_invert_ex()\fR multiplies \fBn\fR with the
194 inverse blinding factor \fBAi\fR. If \fBr\fR is not \s-1NULL\s0 it will be used as
195 the inverse blinding.
196 .PP
197 \&\fIBN_BLINDING_convert()\fR and \fIBN_BLINDING_invert()\fR are wrapper
198 functions for \fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR
199 with \fBr\fR set to \s-1NULL.\s0
200 .PP
201 \&\fIBN_BLINDING_thread_id()\fR provides access to the \fB\s-1CRYPTO_THREADID\s0\fR
202 object within the \fB\s-1BN_BLINDING\s0\fR structure. This is to help users
203 provide proper locking if needed for multi-threaded use. The \*(L"thread
204 id\*(R" object of a newly allocated \fB\s-1BN_BLINDING\s0\fR structure is
205 initialised to the thread id in which \fIBN_BLINDING_new()\fR was called.
206 .PP
207 \&\fIBN_BLINDING_get_flags()\fR returns the \s-1BN_BLINDING\s0 flags. Currently
208 there are two supported flags: \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR and
209 \&\fB\s-1BN_BLINDING_NO_RECREATE\s0\fR. \fB\s-1BN_BLINDING_NO_UPDATE\s0\fR inhibits the
210 automatic update of the \fB\s-1BN_BLINDING\s0\fR parameters after each use
211 and \fB\s-1BN_BLINDING_NO_RECREATE\s0\fR inhibits the automatic re-creation
212 of the \fB\s-1BN_BLINDING\s0\fR parameters after a fixed number of uses (currently
213 32). In newly allocated \fB\s-1BN_BLINDING\s0\fR objects no flags are set.
214 \&\fIBN_BLINDING_set_flags()\fR sets the \fB\s-1BN_BLINDING\s0\fR parameters flags.
215 .PP
216 \&\fIBN_BLINDING_create_param()\fR creates new \fB\s-1BN_BLINDING\s0\fR parameters
217 using the exponent \fBe\fR and the modulus \fBm\fR. \fBbn_mod_exp\fR and
218 \&\fBm_ctx\fR can be used to pass special functions for exponentiation
219 (normally \fIBN_mod_exp_mont()\fR and \fB\s-1BN_MONT_CTX\s0\fR).
220 .SH "RETURN VALUES"
221 .IX Header "RETURN VALUES"
222 \&\fIBN_BLINDING_new()\fR returns the newly allocated \fB\s-1BN_BLINDING\s0\fR structure
223 or \s-1NULL\s0 in case of an error.
224 .PP
225 \&\fIBN_BLINDING_update()\fR, \fIBN_BLINDING_convert()\fR, \fIBN_BLINDING_invert()\fR,
226 \&\fIBN_BLINDING_convert_ex()\fR and \fIBN_BLINDING_invert_ex()\fR return 1 on
227 success and 0 if an error occured.
228 .PP
229 \&\fIBN_BLINDING_thread_id()\fR returns a pointer to the thread id object
230 within a \fB\s-1BN_BLINDING\s0\fR object.
231 .PP
232 \&\fIBN_BLINDING_get_flags()\fR returns the currently set \fB\s-1BN_BLINDING\s0\fR flags
233 (a \fBunsigned long\fR value).
234 .PP
235 \&\fIBN_BLINDING_create_param()\fR returns the newly created \fB\s-1BN_BLINDING\s0\fR
236 parameters or \s-1NULL\s0 on error.
237 .SH "SEE ALSO"
238 .IX Header "SEE ALSO"
239 \&\fIopenssl_bn\fR\|(3)
240 .SH "HISTORY"
241 .IX Header "HISTORY"
242 BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it
243 deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id.
244 .PP
245 BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
246 BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
247 and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
248 .SH "AUTHOR"
249 .IX Header "AUTHOR"
250 Nils Larsch for the OpenSSL project (http://www.openssl.org).