xref: /openssl/doc/man3/BN_add.pod (revision 7ed6de99) 
1=pod
2
3=head1 NAME
4
5BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
6BN_mod_sub, BN_mod_mul, BN_mod_sqr, BN_mod_sqrt, BN_exp, BN_mod_exp, BN_gcd -
7arithmetic operations on BIGNUMs
8
9=head1 SYNOPSIS
10
11 #include <openssl/bn.h>
12
13 int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
14
15 int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);
16
17 int BN_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
18
19 int BN_sqr(BIGNUM *r, const BIGNUM *a, BN_CTX *ctx);
20
21 int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d,
22            BN_CTX *ctx);
23
24 int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
25
26 int BN_nnmod(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
27
28 int BN_mod_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
29                BN_CTX *ctx);
30
31 int BN_mod_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
32                BN_CTX *ctx);
33
34 int BN_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *m,
35                BN_CTX *ctx);
36
37 int BN_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx);
38
39 BIGNUM *BN_mod_sqrt(BIGNUM *in, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);
40
41 int BN_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);
42
43 int BN_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
44                const BIGNUM *m, BN_CTX *ctx);
45
46 int BN_gcd(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
47
48=head1 DESCRIPTION
49
50BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
51I<r> may be the same B<BIGNUM> as I<a> or I<b>.
52
53BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
54I<r> may be the same B<BIGNUM> as I<a> or I<b>.
55
56BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
57I<r> may be the same B<BIGNUM> as I<a> or I<b>.
58For multiplication by powers of 2, use L<BN_lshift(3)>.
59
60BN_sqr() takes the square of I<a> and places the result in I<r>
61(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
62This function is faster than BN_mul(r,a,a).
63
64BN_div() divides I<a> by I<d> and places the result in I<dv> and the
65remainder in I<rem> (C<dv=a/d, rem=a%d>). Either of I<dv> and I<rem> may
66be B<NULL>, in which case the respective value is not returned.
67The result is rounded towards zero; thus if I<a> is negative, the
68remainder will be zero or negative.
69For division by powers of 2, use BN_rshift(3).
70
71BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>.
72
73BN_nnmod() reduces I<a> modulo I<m> and places the nonnegative
74remainder in I<r>.
75
76BN_mod_add() adds I<a> to I<b> modulo I<m> and places the nonnegative
77result in I<r>.
78
79BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the
80nonnegative result in I<r>.
81
82BN_mod_mul() multiplies I<a> by I<b> and finds the nonnegative
83remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
84the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
85repeated computations using the same modulus, see
86L<BN_mod_mul_montgomery(3)> and
87L<BN_mod_mul_reciprocal(3)>.
88
89BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
90result in I<r>.
91
92BN_mod_sqrt() returns the modular square root of I<a> such that
93C<in^2 = a (mod p)>. The modulus I<p> must be a
94prime, otherwise an error or an incorrect "result" will be returned.
95The result is stored into I<in> which can be NULL. The result will be
96newly allocated in that case.
97
98BN_exp() raises I<a> to the I<p>-th power and places the result in I<r>
99(C<r=a^p>). This function is faster than repeated applications of
100BN_mul().
101
102BN_mod_exp() computes I<a> to the I<p>-th power modulo I<m> (C<r=a^p %
103m>). This function uses less time and space than BN_exp(). Do not call this
104function when B<m> is even and any of the parameters have the
105B<BN_FLG_CONSTTIME> flag set.
106
107BN_gcd() computes the greatest common divisor of I<a> and I<b> and
108places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
109I<b>.
110
111For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
112temporary variables; see L<BN_CTX_new(3)>.
113
114Unless noted otherwise, the result B<BIGNUM> must be different from
115the arguments.
116
117=head1 NOTES
118
119For modular operations such as BN_nnmod() or BN_mod_exp() it is an error
120to use the same B<BIGNUM> object for the modulus as for the output.
121
122=head1 RETURN VALUES
123
124The BN_mod_sqrt() returns the result (possibly incorrect if I<p> is
125not a prime), or NULL.
126
127For all remaining functions, 1 is returned for success, 0 on error. The return
128value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
129The error codes can be obtained by L<ERR_get_error(3)>.
130
131=head1 SEE ALSO
132
133L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
134L<BN_add_word(3)>, L<BN_set_bit(3)>
135
136=head1 COPYRIGHT
137
138Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
139
140Licensed under the Apache License 2.0 (the "License").  You may not use
141this file except in compliance with the License.  You can obtain a copy
142in the file LICENSE in the source distribution or at
143L<https://www.openssl.org/source/license.html>.
144
145=cut
146