Debian Codegraph @

upstream/debian-unstable/man3/BN_add.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BN_ADD 3SSL"
58 .TH BN_ADD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
65 BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_mod_sqrt, BN_exp, BN_mod_exp, BN_gcd \-
66 arithmetic operations on BIGNUMs
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/bn.h>
71 \&
72 \& int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
73 \&
74 \& int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
75 \&
76 \& int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
77 \&
78 \& int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx);
79 \&
80 \& int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
81 \& BN_CTX *ctx);
82 \&
83 \& int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
84 \&
85 \& int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
86 \&
87 \& int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
88 \& BN_CTX *ctx);
89 \&
90 \& int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
91 \& BN_CTX *ctx);
92 \&
93 \& int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
94 \& BN_CTX *ctx);
95 \&
96 \& int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
97 \&
98 \& BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);
99 \&
100 \& int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);
101 \&
102 \& int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
103 \& const BIGNUM *m, BN_CTX *ctx);
104 \&
105 \& int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
106 .Ve
107 .SH DESCRIPTION
108 .IX Header "DESCRIPTION"
109 \&\fBBN_add()\fR adds \fIa\fR and \fIb\fR and places the result in \fIr\fR (\f(CW\*(C`r=a+b\*(C'\fR).
110 \&\fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR.
111 .PP
112 \&\fBBN_sub()\fR subtracts \fIb\fR from \fIa\fR and places the result in \fIr\fR (\f(CW\*(C`r=a\-b\*(C'\fR).
113 \&\fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR.
114 .PP
115 \&\fBBN_mul()\fR multiplies \fIa\fR and \fIb\fR and places the result in \fIr\fR (\f(CW\*(C`r=a*b\*(C'\fR).
116 \&\fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR.
117 For multiplication by powers of 2, use \fBBN_lshift\fR\|(3).
118 .PP
119 \&\fBBN_sqr()\fR takes the square of \fIa\fR and places the result in \fIr\fR
120 (\f(CW\*(C`r=a^2\*(C'\fR). \fIr\fR and \fIa\fR may be the same \fBBIGNUM\fR.
121 This function is faster than BN_mul(r,a,a).
122 .PP
123 \&\fBBN_div()\fR divides \fIa\fR by \fId\fR and places the result in \fIdv\fR and the
124 remainder in \fIrem\fR (\f(CW\*(C`dv=a/d, rem=a%d\*(C'\fR). Either of \fIdv\fR and \fIrem\fR may
125 be \fBNULL\fR, in which case the respective value is not returned.
126 The result is rounded towards zero; thus if \fIa\fR is negative, the
127 remainder will be zero or negative.
128 For division by powers of 2, use \fBBN_rshift\fR\|(3).
129 .PP
130 \&\fBBN_mod()\fR corresponds to \fBBN_div()\fR with \fIdv\fR set to \fBNULL\fR.
131 .PP
132 \&\fBBN_nnmod()\fR reduces \fIa\fR modulo \fIm\fR and places the nonnegative
133 remainder in \fIr\fR.
134 .PP
135 \&\fBBN_mod_add()\fR adds \fIa\fR to \fIb\fR modulo \fIm\fR and places the nonnegative
136 result in \fIr\fR.
137 .PP
138 \&\fBBN_mod_sub()\fR subtracts \fIb\fR from \fIa\fR modulo \fIm\fR and places the
139 nonnegative result in \fIr\fR.
140 .PP
141 \&\fBBN_mod_mul()\fR multiplies \fIa\fR by \fIb\fR and finds the nonnegative
142 remainder respective to modulus \fIm\fR (\f(CW\*(C`r=(a*b) mod m\*(C'\fR). \fIr\fR may be
143 the same \fBBIGNUM\fR as \fIa\fR or \fIb\fR. For more efficient algorithms for
144 repeated computations using the same modulus, see
145 \&\fBBN_mod_mul_montgomery\fR\|(3) and
146 \&\fBBN_mod_mul_reciprocal\fR\|(3).
147 .PP
148 \&\fBBN_mod_sqr()\fR takes the square of \fIa\fR modulo \fBm\fR and places the
149 result in \fIr\fR.
150 .PP
151 \&\fBBN_mod_sqrt()\fR returns the modular square root of \fIa\fR such that
152 \&\f(CW\*(C`in^2 = a (mod p)\*(C'\fR. The modulus \fIp\fR must be a
153 prime, otherwise an error or an incorrect "result" will be returned.
154 The result is stored into \fIin\fR which can be NULL. The result will be
155 newly allocated in that case.
156 .PP
157 \&\fBBN_exp()\fR raises \fIa\fR to the \fIp\fR\-th power and places the result in \fIr\fR
158 (\f(CW\*(C`r=a^p\*(C'\fR). This function is faster than repeated applications of
159 \&\fBBN_mul()\fR.
160 .PP
161 \&\fBBN_mod_exp()\fR computes \fIa\fR to the \fIp\fR\-th power modulo \fIm\fR (\f(CW\*(C`r=a^p %
162 m\*(C'\fR). This function uses less time and space than \fBBN_exp()\fR. Do not call this
163 function when \fBm\fR is even and any of the parameters have the
164 \&\fBBN_FLG_CONSTTIME\fR flag set.
165 .PP
166 \&\fBBN_gcd()\fR computes the greatest common divisor of \fIa\fR and \fIb\fR and
167 places the result in \fIr\fR. \fIr\fR may be the same \fBBIGNUM\fR as \fIa\fR or
168 \&\fIb\fR.
169 .PP
170 For all functions, \fIctx\fR is a previously allocated \fBBN_CTX\fR used for
171 temporary variables; see \fBBN_CTX_new\fR\|(3).
172 .PP
173 Unless noted otherwise, the result \fBBIGNUM\fR must be different from
174 the arguments.
175 .SH NOTES
176 .IX Header "NOTES"
177 For modular operations such as \fBBN_nnmod()\fR or \fBBN_mod_exp()\fR it is an error
178 to use the same \fBBIGNUM\fR object for the modulus as for the output.
179 .SH "RETURN VALUES"
180 .IX Header "RETURN VALUES"
181 The \fBBN_mod_sqrt()\fR returns the result (possibly incorrect if \fIp\fR is
182 not a prime), or NULL.
183 .PP
184 For all remaining functions, 1 is returned for success, 0 on error. The return
185 value should always be checked (e.g., \f(CW\*(C`if (!BN_add(r,a,b)) goto err;\*(C'\fR).
186 The error codes can be obtained by \fBERR_get_error\fR\|(3).
187 .SH "SEE ALSO"
188 .IX Header "SEE ALSO"
189 \&\fBERR_get_error\fR\|(3), \fBBN_CTX_new\fR\|(3),
190 \&\fBBN_add_word\fR\|(3), \fBBN_set_bit\fR\|(3)
191 .SH COPYRIGHT
192 .IX Header "COPYRIGHT"
193 Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
194 .PP
195 Licensed under the Apache License 2.0 (the "License"). You may not use
196 this file except in compliance with the License. You can obtain a copy
197 in the file LICENSE in the source distribution or at
198 <https://www.openssl.org/source/license.html>.