xref: /openbsd-src/lib/libcrypto/man/BN_add.3 (revision 4301e57c79f8993ab3c659535f2265f6f16b919d) 
1.\"	$OpenBSD: BN_add.3,v 1.4 2016/11/20 15:57:50 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: November 20 2016 $
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 .
268.Pp
269.Fn BN_nnmod
270reduces
271.Fa a
272modulo
273.Fa m
274and places the non-negative remainder in
275.Fa r .
276.Pp
277.Fn BN_mod_add
278adds
279.Fa a
280to
281.Fa b
282modulo
283.Fa m
284and places the non-negative result in
285.Fa r .
286.Pp
287.Fn BN_mod_sub
288subtracts
289.Fa b
290from
291.Fa a
292modulo
293.Fa m
294and places the non-negative result in
295.Fa r .
296.Pp
297.Fn BN_mod_mul
298multiplies
299.Fa a
300by
301.Fa b
302and finds the non-negative remainder respective to modulus
303.Fa m
304.Pq Li r=(a*b)%m .
305.Fa r
306may be the same
307.Vt BIGNUM
308as
309.Fa a
310or
311.Fa b .
312For more efficient algorithms for repeated computations using the same
313modulus, see
314.Xr BN_mod_mul_montgomery 3
315and
316.Xr BN_mod_mul_reciprocal 3 .
317.Pp
318.Fn BN_mod_sqr
319takes the square of
320.Fa a
321modulo
322.Fa m
323and places the result in
324.Fa r .
325.Pp
326.Fn BN_exp
327raises
328.Fa a
329to the
330.Fa p Ns -th
331power and places the result in
332.Fa r
333.Pq Li r=a^p .
334This function is faster than repeated applications of
335.Fn BN_mul .
336.Pp
337.Fn BN_mod_exp
338computes
339.Fa a
340to the
341.Fa p Ns -th
342power modulo
343.Fa m
344.Pq Li r=(a^p)%m .
345This function uses less time and space than
346.Fn BN_exp .
347.Pp
348.Fn BN_gcd
349computes the greatest common divisor of
350.Fa a
351and
352.Fa b
353and places the result in
354.Fa r .
355.Fa r
356may be the same
357.Vt BIGNUM
358as
359.Fa a
360or
361.Fa b .
362.Pp
363For all functions,
364.Fa ctx
365is a previously allocated
366.Vt BN_CTX
367used for temporary variables; see
368.Xr BN_CTX_new 3 .
369.Pp
370Unless noted otherwise, the result
371.Vt BIGNUM
372must be different from the arguments.
373.Sh RETURN VALUES
374For all functions, 1 is returned for success, 0 on error.
375The return value should always be checked, for example:
376.Pp
377.Dl if (!BN_add(r,a,b)) goto err;
378.Pp
379The error codes can be obtained by
380.Xr ERR_get_error 3 .
381.Sh SEE ALSO
382.Xr bn 3 ,
383.Xr BN_add_word 3 ,
384.Xr BN_CTX_new 3 ,
385.Xr BN_set_bit 3 ,
386.Xr BN_set_negative 3 ,
387.Xr ERR_get_error 3
388.Sh HISTORY
389.Fn BN_add ,
390.Fn BN_sub ,
391.Fn BN_sqr ,
392.Fn BN_div ,
393.Fn BN_mod ,
394.Fn BN_mod_mul ,
395.Fn BN_mod_exp ,
396and
397.Fn BN_gcd
398are available in all versions of SSLeay and OpenSSL.
399The
400.Fa ctx
401argument to
402.Fn BN_mul
403was added in SSLeay 0.9.1b.
404.Fn BN_exp
405appeared in SSLeay 0.9.0.
406.Fn BN_nnmod ,
407.Fn BN_mod_add ,
408.Fn BN_mod_sub ,
409and
410.Fn BN_mod_sqr
411were added in OpenSSL 0.9.7.
412