| blob | 8a11d7c08048d5ce85173e758a5e686582c75256 |
1 .\" $OpenBSD: BN_add.3,v 1.13 2018/04/29 15:58:21 schwarze Exp $
2 .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3 .\"
4 .\" This file was written by Ulf Moeller <ulf@openssl.org>
5 .\" and Bodo Moeller <bodo@openssl.org>.
6 .\" Copyright (c) 2000, 2001, 2015 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: April 29 2018 $
53 .Dt BN_ADD 3
54 .Os
55 .Sh NAME
56 .Nm BN_add ,
57 .Nm BN_sub ,
58 .Nm BN_mul ,
59 .Nm BN_sqr ,
60 .Nm BN_div ,
61 .Nm BN_mod ,
62 .Nm BN_nnmod ,
63 .Nm BN_mod_add ,
64 .Nm BN_mod_sub ,
65 .Nm BN_mod_mul ,
66 .Nm BN_mod_sqr ,
67 .Nm BN_exp ,
68 .Nm BN_mod_exp ,
69 .\" The following are public, but intentionally undocumented for now:
70 .\" .Nm BN_mod_exp_mont_consttime ,
71 .\" .Nm BN_mod_exp_mont ,
72 .\" .Nm BN_mod_exp_mont_word ,
73 .\" .Nm BN_mod_exp_recp ,
74 .\" .Nm BN_mod_exp_simple ,
75 .\" Maybe they should be deleted from <openssl/bn.h>.
76 .Nm BN_gcd
77 .Nd arithmetic operations on BIGNUMs
78 .Sh SYNOPSIS
79 .In openssl/bn.h
80 .Ft int
81 .Fo BN_add
82 .Fa "BIGNUM *r"
83 .Fa "const BIGNUM *a"
84 .Fa "const BIGNUM *b"
85 .Fc
86 .Ft int
87 .Fo BN_sub
88 .Fa "BIGNUM *r"
89 .Fa "const BIGNUM *a"
90 .Fa "const BIGNUM *b"
91 .Fc
92 .Ft int
93 .Fo BN_mul
94 .Fa "BIGNUM *r"
95 .Fa "BIGNUM *a"
96 .Fa "BIGNUM *b"
97 .Fa "BN_CTX *ctx"
98 .Fc
99 .Ft int
100 .Fo BN_sqr
101 .Fa "BIGNUM *r"
102 .Fa "BIGNUM *a"
103 .Fa "BN_CTX *ctx"
104 .Fc
105 .Ft int
106 .Fo BN_div
107 .Fa "BIGNUM *dv"
108 .Fa "BIGNUM *rem"
109 .Fa "const BIGNUM *a"
110 .Fa "const BIGNUM *d"
111 .Fa "BN_CTX *ctx"
112 .Fc
113 .Ft int
114 .Fo BN_mod
115 .Fa "BIGNUM *rem"
116 .Fa "const BIGNUM *a"
117 .Fa "const BIGNUM *m"
118 .Fa "BN_CTX *ctx"
119 .Fc
120 .Ft int
121 .Fo BN_nnmod
122 .Fa "BIGNUM *r"
123 .Fa "const BIGNUM *a"
124 .Fa "const BIGNUM *m"
125 .Fa "BN_CTX *ctx"
126 .Fc
127 .Ft int
128 .Fo BN_mod_add
129 .Fa "BIGNUM *r"
130 .Fa "BIGNUM *a"
131 .Fa "BIGNUM *b"
132 .Fa "const BIGNUM *m"
133 .Fa "BN_CTX *ctx"
134 .Fc
135 .Ft int
136 .Fo BN_mod_sub
137 .Fa "BIGNUM *r"
138 .Fa "BIGNUM *a"
139 .Fa "BIGNUM *b"
140 .Fa "const BIGNUM *m"
141 .Fa "BN_CTX *ctx"
142 .Fc
143 .Ft int
144 .Fo BN_mod_mul
145 .Fa "BIGNUM *r"
146 .Fa "BIGNUM *a"
147 .Fa "BIGNUM *b"
148 .Fa "const BIGNUM *m"
149 .Fa "BN_CTX *ctx"
150 .Fc
151 .Ft int
152 .Fo BN_mod_sqr
153 .Fa "BIGNUM *r"
154 .Fa "BIGNUM *a"
155 .Fa "const BIGNUM *m"
156 .Fa "BN_CTX *ctx"
157 .Fc
158 .Ft int
159 .Fo BN_exp
160 .Fa "BIGNUM *r"
161 .Fa "BIGNUM *a"
162 .Fa "BIGNUM *p"
163 .Fa "BN_CTX *ctx"
164 .Fc
165 .Ft int
166 .Fo BN_mod_exp
167 .Fa "BIGNUM *r"
168 .Fa "BIGNUM *a"
169 .Fa "const BIGNUM *p"
170 .Fa "const BIGNUM *m"
171 .Fa "BN_CTX *ctx"
172 .Fc
173 .Ft int
174 .Fo BN_gcd
175 .Fa "BIGNUM *r"
176 .Fa "BIGNUM *a"
177 .Fa "BIGNUM *b"
178 .Fa "BN_CTX *ctx"
179 .Fc
180 .Sh DESCRIPTION
181 .Fn BN_add
182 adds
183 .Fa a
184 and
185 .Fa b
186 and places the result in
187 .Fa r
188 .Pq Li r=a+b .
189 .Fa r
190 may be the same
191 .Vt BIGNUM
192 as
193 .Fa a
194 or
195 .Fa b .
196 .Pp
197 .Fn BN_sub
198 subtracts
199 .Fa b
200 from
201 .Fa a
202 and places the result in
203 .Fa r
204 .Pq Li r=a-b .
205 .Fa r
206 may be the same
207 .Vt BIGNUM
208 as
209 .Fa a
210 or
211 .Fa b .
212 .Pp
213 .Fn BN_mul
214 multiplies
215 .Fa a
216 and
217 .Fa b
218 and places the result in
219 .Fa r
220 .Pq Li r=a*b .
221 .Fa r
222 may be the same
223 .Vt BIGNUM
224 as
225 .Fa a
226 or
227 .Fa b .
228 For multiplication by powers of 2, use
229 .Xr BN_lshift 3 .
230 .Pp
231 .Fn BN_sqr
232 takes the square of
233 .Fa a
234 and places the result in
235 .Fa r
236 .Pq Li r=a^2 .
237 .Fa r
238 and
239 .Fa a
240 may be the same
241 .Vt BIGNUM .
242 This function is faster than
243 .Fn BN_mul r a a .
244 .Pp
245 .Fn BN_div
246 divides
247 .Fa a
248 by
249 .Fa d
250 and places the result in
251 .Fa dv
252 and the remainder in
253 .Fa rem
254 .Pq Li dv=a/d , rem=a%d .
255 If the flag
256 .Dv BN_FLG_CONSTTIME
257 is set on
258 .Fa a
259 or
260 .Fa d ,
261 it operates in constant time.
262 Either of
263 .Fa dv
264 and
265 .Fa rem
266 may be
267 .Dv NULL ,
268 in which case the respective value is not returned.
269 The result is rounded towards zero; thus if
270 .Fa a
271 is negative, the remainder will be zero or negative.
272 For division by powers of 2, use
273 .Fn BN_rshift 3 .
274 .Pp
275 .Fn BN_mod
276 corresponds to
277 .Fn BN_div
278 with
279 .Fa dv
280 set to
281 .Dv NULL .
282 It is implemented as a macro.
283 .Pp
284 .Fn BN_nnmod
285 reduces
286 .Fa a
287 modulo
288 .Fa m
289 and places the non-negative remainder in
290 .Fa r .
291 .Pp
292 .Fn BN_mod_add
293 adds
294 .Fa a
295 to
296 .Fa b
297 modulo
298 .Fa m
299 and places the non-negative result in
300 .Fa r .
301 .Pp
302 .Fn BN_mod_sub
303 subtracts
304 .Fa b
305 from
306 .Fa a
307 modulo
308 .Fa m
309 and places the non-negative result in
310 .Fa r .
311 .Pp
312 .Fn BN_mod_mul
313 multiplies
314 .Fa a
315 by
316 .Fa b
317 and finds the non-negative remainder respective to modulus
318 .Fa m
319 .Pq Li r=(a*b)%m .
320 .Fa r
321 may be the same
322 .Vt BIGNUM
323 as
324 .Fa a
325 or
326 .Fa b .
327 For more efficient algorithms for repeated computations using the same
328 modulus, see
329 .Xr BN_mod_mul_montgomery 3
330 and
331 .Xr BN_mod_mul_reciprocal 3 .
332 .Pp
333 .Fn BN_mod_sqr
334 takes the square of
335 .Fa a
336 modulo
337 .Fa m
338 and places the result in
339 .Fa r .
340 .Pp
341 .Fn BN_exp
342 raises
343 .Fa a
344 to the
345 .Fa p Ns -th
346 power and places the result in
347 .Fa r
348 .Pq Li r=a^p .
349 This function is faster than repeated applications of
350 .Fn BN_mul .
351 .Pp
352 .Fn BN_mod_exp
353 computes
354 .Fa a
355 to the
356 .Fa p Ns -th
357 power modulo
358 .Fa m
359 .Pq Li r=(a^p)%m .
360 If the flag
361 .Dv BN_FLG_CONSTTIME
362 is set on
363 .Fa p ,
364 it operates in constant time.
365 This function uses less time and space than
366 .Fn BN_exp .
367 .Pp
368 .Fn BN_gcd
369 computes the greatest common divisor of
370 .Fa a
371 and
372 .Fa b
373 and places the result in
374 .Fa r .
375 .Fa r
376 may be the same
377 .Vt BIGNUM
378 as
379 .Fa a
380 or
381 .Fa b .
382 .Pp
383 For all functions,
384 .Fa ctx
385 is a previously allocated
386 .Vt BN_CTX
387 used for temporary variables; see
388 .Xr BN_CTX_new 3 .
389 .Pp
390 Unless noted otherwise, the result
391 .Vt BIGNUM
392 must be different from the arguments.
393 .Sh RETURN VALUES
394 For all functions, 1 is returned for success, 0 on error.
395 The return value should always be checked, for example:
396 .Pp
397 .Dl if (!BN_add(r,a,b)) goto err;
398 .Pp
399 The error codes can be obtained by
400 .Xr ERR_get_error 3 .
401 .Sh SEE ALSO
402 .Xr BN_add_word 3 ,
403 .Xr BN_CTX_new 3 ,
404 .Xr BN_new 3 ,
405 .Xr BN_set_bit 3 ,
406 .Xr BN_set_flags 3 ,
407 .Xr BN_set_negative 3
408 .Sh HISTORY
409 .Fn BN_add ,
410 .Fn BN_sub ,
411 .Fn BN_mul ,
412 .Fn BN_sqr ,
413 .Fn BN_div ,
414 .Fn BN_mod ,
415 .Fn BN_mod_mul ,
416 .Fn BN_mod_exp ,
417 and
418 .Fn BN_gcd
419 first appeared in SSLeay 0.5.1.
420 .Fn BN_exp
421 first appeared in SSLeay 0.9.0.
422 All these functions have been available since
423 .Ox 2.4 .
424 .Pp
425 The
426 .Fa ctx
427 argument to
428 .Fn BN_mul
429 was added in SSLeay 0.9.1 and
430 .Ox 2.6 .
431 .Pp
432 .Fn BN_nnmod ,
433 .Fn BN_mod_add ,
434 .Fn BN_mod_sub ,
435 and
436 .Fn BN_mod_sqr
437 first appeared in OpenSSL 0.9.7 and have been available since
438 .Ox 3.2 .
439 .Sh BUGS
440 Even if the
441 .Dv BN_FLG_CONSTTIME
442 flag is set on
443 .Fa a
444 or
445 .Fa b ,
446 .Fn BN_gcd
447 neither fails nor operates in constant time, potentially allowing
448 timing side-channel attacks.
449 .Pp
450 Even if the
451 .Dv BN_FLG_CONSTTIME
452 flag is set on
453 .Fa p ,
454 if the modulus
455 .Fa m
456 is even,
457 .Fn BN_mod_exp
458 does not operate in constant time, potentially allowing
459 timing side-channel attacks.
460 .Pp
461 If
462 .Dv BN_FLG_CONSTTIME
463 is set on
464 .Fa p ,
465 .Fn BN_exp
466 fails instead of operating in constant time.