xref: /openbsd-src/lib/libcrypto/man/BN_add.3 (revision 99fd087599a8791921855f21bd7e36130f39aadc) 
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
182adds
183.Fa a
184and
185.Fa b
186and places the result in
187.Fa r
188.Pq Li r=a+b .
189.Fa r
190may be the same
191.Vt BIGNUM
192as
193.Fa a
194or
195.Fa b .
196.Pp
197.Fn BN_sub
198subtracts
199.Fa b
200from
201.Fa a
202and places the result in
203.Fa r
204.Pq Li r=a-b .
205.Fa r
206may be the same
207.Vt BIGNUM
208as
209.Fa a
210or
211.Fa b .
212.Pp
213.Fn BN_mul
214multiplies
215.Fa a
216and
217.Fa b
218and places the result in
219.Fa r
220.Pq Li r=a*b .
221.Fa r
222may be the same
223.Vt BIGNUM
224as
225.Fa a
226or
227.Fa b .
228For multiplication by powers of 2, use
229.Xr BN_lshift 3 .
230.Pp
231.Fn BN_sqr
232takes the square of
233.Fa a
234and places the result in
235.Fa r
236.Pq Li r=a^2 .
237.Fa r
238and
239.Fa a
240may be the same
241.Vt BIGNUM .
242This function is faster than
243.Fn BN_mul r a a .
244.Pp
245.Fn BN_div
246divides
247.Fa a
248by
249.Fa d
250and places the result in
251.Fa dv
252and the remainder in
253.Fa rem
254.Pq Li dv=a/d , rem=a%d .
255If the flag
256.Dv BN_FLG_CONSTTIME
257is set on
258.Fa a
259or
260.Fa d ,
261it operates in constant time.
262Either of
263.Fa dv
264and
265.Fa rem
266may be
267.Dv NULL ,
268in which case the respective value is not returned.
269The result is rounded towards zero; thus if
270.Fa a
271is negative, the remainder will be zero or negative.
272For division by powers of 2, use
273.Fn BN_rshift 3 .
274.Pp
275.Fn BN_mod
276corresponds to
277.Fn BN_div
278with
279.Fa dv
280set to
281.Dv NULL .
282It is implemented as a macro.
283.Pp
284.Fn BN_nnmod
285reduces
286.Fa a
287modulo
288.Fa m
289and places the non-negative remainder in
290.Fa r .
291.Pp
292.Fn BN_mod_add
293adds
294.Fa a
295to
296.Fa b
297modulo
298.Fa m
299and places the non-negative result in
300.Fa r .
301.Pp
302.Fn BN_mod_sub
303subtracts
304.Fa b
305from
306.Fa a
307modulo
308.Fa m
309and places the non-negative result in
310.Fa r .
311.Pp
312.Fn BN_mod_mul
313multiplies
314.Fa a
315by
316.Fa b
317and finds the non-negative remainder respective to modulus
318.Fa m
319.Pq Li r=(a*b)%m .
320.Fa r
321may be the same
322.Vt BIGNUM
323as
324.Fa a
325or
326.Fa b .
327For more efficient algorithms for repeated computations using the same
328modulus, see
329.Xr BN_mod_mul_montgomery 3
330and
331.Xr BN_mod_mul_reciprocal 3 .
332.Pp
333.Fn BN_mod_sqr
334takes the square of
335.Fa a
336modulo
337.Fa m
338and places the result in
339.Fa r .
340.Pp
341.Fn BN_exp
342raises
343.Fa a
344to the
345.Fa p Ns -th
346power and places the result in
347.Fa r
348.Pq Li r=a^p .
349This function is faster than repeated applications of
350.Fn BN_mul .
351.Pp
352.Fn BN_mod_exp
353computes
354.Fa a
355to the
356.Fa p Ns -th
357power modulo
358.Fa m
359.Pq Li r=(a^p)%m .
360If the flag
361.Dv BN_FLG_CONSTTIME
362is set on
363.Fa p ,
364it operates in constant time.
365This function uses less time and space than
366.Fn BN_exp .
367.Pp
368.Fn BN_gcd
369computes the greatest common divisor of
370.Fa a
371and
372.Fa b
373and places the result in
374.Fa r .
375.Fa r
376may be the same
377.Vt BIGNUM
378as
379.Fa a
380or
381.Fa b .
382.Pp
383For all functions,
384.Fa ctx
385is a previously allocated
386.Vt BN_CTX
387used for temporary variables; see
388.Xr BN_CTX_new 3 .
389.Pp
390Unless noted otherwise, the result
391.Vt BIGNUM
392must be different from the arguments.
393.Sh RETURN VALUES
394For all functions, 1 is returned for success, 0 on error.
395The return value should always be checked, for example:
396.Pp
397.Dl if (!BN_add(r,a,b)) goto err;
398.Pp
399The 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 ,
417and
418.Fn BN_gcd
419first appeared in SSLeay 0.5.1.
420.Fn BN_exp
421first appeared in SSLeay 0.9.0.
422All these functions have been available since
423.Ox 2.4 .
424.Pp
425The
426.Fa ctx
427argument to
428.Fn BN_mul
429was 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 ,
435and
436.Fn BN_mod_sqr
437first appeared in OpenSSL 0.9.7 and have been available since
438.Ox 3.2 .
439.Sh BUGS
440Even if the
441.Dv BN_FLG_CONSTTIME
442flag is set on
443.Fa a
444or
445.Fa b ,
446.Fn BN_gcd
447neither fails nor operates in constant time, potentially allowing
448timing side-channel attacks.
449.Pp
450Even if the
451.Dv BN_FLG_CONSTTIME
452flag is set on
453.Fa p ,
454if the modulus
455.Fa m
456is even,
457.Fn BN_mod_exp
458does not operate in constant time, potentially allowing
459timing side-channel attacks.
460.Pp
461If
462.Dv BN_FLG_CONSTTIME
463is set on
464.Fa p ,
465.Fn BN_exp
466fails instead of operating in constant time.
467