xref: /openbsd-src/lib/libcrypto/man/BN_add.3 (revision 0c85fcf7a3654521c5dbc57501c5d0b858c3c1f9) 
1.\"	$OpenBSD: BN_add.3,v 1.8 2018/03/20 20:26:23 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: March 20 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.Nm BN_gcd
70.Nd arithmetic operations on BIGNUMs
71.Sh SYNOPSIS
72.In openssl/bn.h
73.Ft int
74.Fo BN_add
75.Fa "BIGNUM *r"
76.Fa "const BIGNUM *a"
77.Fa "const BIGNUM *b"
78.Fc
79.Ft int
80.Fo BN_sub
81.Fa "BIGNUM *r"
82.Fa "const BIGNUM *a"
83.Fa "const BIGNUM *b"
84.Fc
85.Ft int
86.Fo BN_mul
87.Fa "BIGNUM *r"
88.Fa "BIGNUM *a"
89.Fa "BIGNUM *b"
90.Fa "BN_CTX *ctx"
91.Fc
92.Ft int
93.Fo BN_sqr
94.Fa "BIGNUM *r"
95.Fa "BIGNUM *a"
96.Fa "BN_CTX *ctx"
97.Fc
98.Ft int
99.Fo BN_div
100.Fa "BIGNUM *dv"
101.Fa "BIGNUM *rem"
102.Fa "const BIGNUM *a"
103.Fa "const BIGNUM *d"
104.Fa "BN_CTX *ctx"
105.Fc
106.Ft int
107.Fo BN_mod
108.Fa "BIGNUM *rem"
109.Fa "const BIGNUM *a"
110.Fa "const BIGNUM *m"
111.Fa "BN_CTX *ctx"
112.Fc
113.Ft int
114.Fo BN_nnmod
115.Fa "BIGNUM *r"
116.Fa "const BIGNUM *a"
117.Fa "const BIGNUM *m"
118.Fa "BN_CTX *ctx"
119.Fc
120.Ft int
121.Fo BN_mod_add
122.Fa "BIGNUM *r"
123.Fa "BIGNUM *a"
124.Fa "BIGNUM *b"
125.Fa "const BIGNUM *m"
126.Fa "BN_CTX *ctx"
127.Fc
128.Ft int
129.Fo BN_mod_sub
130.Fa "BIGNUM *r"
131.Fa "BIGNUM *a"
132.Fa "BIGNUM *b"
133.Fa "const BIGNUM *m"
134.Fa "BN_CTX *ctx"
135.Fc
136.Ft int
137.Fo BN_mod_mul
138.Fa "BIGNUM *r"
139.Fa "BIGNUM *a"
140.Fa "BIGNUM *b"
141.Fa "const BIGNUM *m"
142.Fa "BN_CTX *ctx"
143.Fc
144.Ft int
145.Fo BN_mod_sqr
146.Fa "BIGNUM *r"
147.Fa "BIGNUM *a"
148.Fa "const BIGNUM *m"
149.Fa "BN_CTX *ctx"
150.Fc
151.Ft int
152.Fo BN_exp
153.Fa "BIGNUM *r"
154.Fa "BIGNUM *a"
155.Fa "BIGNUM *p"
156.Fa "BN_CTX *ctx"
157.Fc
158.Ft int
159.Fo BN_mod_exp
160.Fa "BIGNUM *r"
161.Fa "BIGNUM *a"
162.Fa "const BIGNUM *p"
163.Fa "const BIGNUM *m"
164.Fa "BN_CTX *ctx"
165.Fc
166.Ft int
167.Fo BN_gcd
168.Fa "BIGNUM *r"
169.Fa "BIGNUM *a"
170.Fa "BIGNUM *b"
171.Fa "BN_CTX *ctx"
172.Fc
173.Sh DESCRIPTION
174.Fn BN_add
175adds
176.Fa a
177and
178.Fa b
179and places the result in
180.Fa r
181.Pq Li r=a+b .
182.Fa r
183may be the same
184.Vt BIGNUM
185as
186.Fa a
187or
188.Fa b .
189.Pp
190.Fn BN_sub
191subtracts
192.Fa b
193from
194.Fa a
195and places the result in
196.Fa r
197.Pq Li r=a-b .
198.Fa r
199may be the same
200.Vt BIGNUM
201as
202.Fa a
203or
204.Fa b .
205.Pp
206.Fn BN_mul
207multiplies
208.Fa a
209and
210.Fa b
211and places the result in
212.Fa r
213.Pq Li r=a*b .
214.Fa r
215may be the same
216.Vt BIGNUM
217as
218.Fa a
219or
220.Fa b .
221For multiplication by powers of 2, use
222.Xr BN_lshift 3 .
223.Pp
224.Fn BN_sqr
225takes the square of
226.Fa a
227and places the result in
228.Fa r
229.Pq Li r=a^2 .
230.Fa r
231and
232.Fa a
233may be the same
234.Vt BIGNUM .
235This function is faster than
236.Fn BN_mul r a a .
237.Pp
238.Fn BN_div
239divides
240.Fa a
241by
242.Fa d
243and places the result in
244.Fa dv
245and the remainder in
246.Fa rem
247.Pq Li dv=a/d , rem=a%d .
248Either of
249.Fa dv
250and
251.Fa rem
252may be
253.Dv NULL ,
254in which case the respective value is not returned.
255The result is rounded towards zero; thus if
256.Fa a
257is negative, the remainder will be zero or negative.
258For division by powers of 2, use
259.Fn BN_rshift 3 .
260.Pp
261.Fn BN_mod
262corresponds to
263.Fn BN_div
264with
265.Fa dv
266set to
267.Dv NULL .
268It is implemented as a macro.
269.Pp
270.Fn BN_nnmod
271reduces
272.Fa a
273modulo
274.Fa m
275and places the non-negative remainder in
276.Fa r .
277.Pp
278.Fn BN_mod_add
279adds
280.Fa a
281to
282.Fa b
283modulo
284.Fa m
285and places the non-negative result in
286.Fa r .
287.Pp
288.Fn BN_mod_sub
289subtracts
290.Fa b
291from
292.Fa a
293modulo
294.Fa m
295and places the non-negative result in
296.Fa r .
297.Pp
298.Fn BN_mod_mul
299multiplies
300.Fa a
301by
302.Fa b
303and finds the non-negative remainder respective to modulus
304.Fa m
305.Pq Li r=(a*b)%m .
306.Fa r
307may be the same
308.Vt BIGNUM
309as
310.Fa a
311or
312.Fa b .
313For more efficient algorithms for repeated computations using the same
314modulus, see
315.Xr BN_mod_mul_montgomery 3
316and
317.Xr BN_mod_mul_reciprocal 3 .
318.Pp
319.Fn BN_mod_sqr
320takes the square of
321.Fa a
322modulo
323.Fa m
324and places the result in
325.Fa r .
326.Pp
327.Fn BN_exp
328raises
329.Fa a
330to the
331.Fa p Ns -th
332power and places the result in
333.Fa r
334.Pq Li r=a^p .
335This function is faster than repeated applications of
336.Fn BN_mul .
337.Pp
338.Fn BN_mod_exp
339computes
340.Fa a
341to the
342.Fa p Ns -th
343power modulo
344.Fa m
345.Pq Li r=(a^p)%m .
346This function uses less time and space than
347.Fn BN_exp .
348.Pp
349.Fn BN_gcd
350computes the greatest common divisor of
351.Fa a
352and
353.Fa b
354and places the result in
355.Fa r .
356.Fa r
357may be the same
358.Vt BIGNUM
359as
360.Fa a
361or
362.Fa b .
363.Pp
364For all functions,
365.Fa ctx
366is a previously allocated
367.Vt BN_CTX
368used for temporary variables; see
369.Xr BN_CTX_new 3 .
370.Pp
371Unless noted otherwise, the result
372.Vt BIGNUM
373must be different from the arguments.
374.Sh RETURN VALUES
375For all functions, 1 is returned for success, 0 on error.
376The return value should always be checked, for example:
377.Pp
378.Dl if (!BN_add(r,a,b)) goto err;
379.Pp
380The error codes can be obtained by
381.Xr ERR_get_error 3 .
382.Sh SEE ALSO
383.Xr BN_add_word 3 ,
384.Xr BN_CTX_new 3 ,
385.Xr BN_new 3 ,
386.Xr BN_set_bit 3 ,
387.Xr BN_set_flags 3 ,
388.Xr BN_set_negative 3
389.Sh HISTORY
390.Fn BN_add ,
391.Fn BN_sub ,
392.Fn BN_mul ,
393.Fn BN_sqr ,
394.Fn BN_div ,
395.Fn BN_mod ,
396.Fn BN_mod_mul ,
397.Fn BN_mod_exp ,
398and
399.Fn BN_gcd
400appeared before SSLeay 0.8 and have been available since
401.Ox 2.4 .
402.Pp
403The
404.Fa ctx
405argument to
406.Fn BN_mul
407was added in SSLeay 0.9.1b.
408.Fn BN_exp
409appeared in SSLeay 0.9.0.
410.Fn BN_nnmod ,
411.Fn BN_mod_add ,
412.Fn BN_mod_sub ,
413and
414.Fn BN_mod_sqr
415were added in OpenSSL 0.9.7.
416