NAME
BN_add
, BN_uadd
,
BN_sub
, BN_usub
,
BN_mul
, BN_sqr
,
BN_div
, BN_mod
,
BN_nnmod
, BN_mod_add
,
BN_mod_add_quick
,
BN_mod_sub
,
BN_mod_sub_quick
,
BN_mod_mul
, BN_mod_sqr
,
BN_mod_lshift
,
BN_mod_lshift_quick
,
BN_mod_lshift1
,
BN_mod_lshift1_quick
,
BN_exp
, BN_mod_exp
,
BN_gcd
—
arithmetic operations on
BIGNUMs
SYNOPSIS
#include
<openssl/bn.h>
int
BN_add
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b);
int
BN_uadd
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b);
int
BN_sub
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b);
int
BN_usub
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b);
int
BN_mul
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, BN_CTX *ctx);
int
BN_sqr
(BIGNUM *r,
const BIGNUM *a, BN_CTX
*ctx);
int
BN_div
(BIGNUM *dv,
BIGNUM *rem, const BIGNUM *a,
const BIGNUM *d, BN_CTX
*ctx);
int
BN_mod
(BIGNUM *rem,
const BIGNUM *a, const BIGNUM
*m, BN_CTX *ctx);
int
BN_nnmod
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*m, BN_CTX *ctx);
int
BN_mod_add
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, const BIGNUM *m, BN_CTX
*ctx);
int
BN_mod_add_quick
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, const BIGNUM *m);
int
BN_mod_sub
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, const BIGNUM *m, BN_CTX
*ctx);
int
BN_mod_sub_quick
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, const BIGNUM *m);
int
BN_mod_mul
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, const BIGNUM *m, BN_CTX
*ctx);
int
BN_mod_sqr
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*m, BN_CTX *ctx);
int
BN_mod_lshift
(BIGNUM *r,
const BIGNUM *a, int n,
const BIGNUM *m, BN_CTX
*ctx);
int
BN_mod_lshift_quick
(BIGNUM *r,
const BIGNUM *a, int n,
const BIGNUM *m);
int
BN_mod_lshift1
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*m, BN_CTX *ctx);
int
BN_mod_lshift1_quick
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*m);
int
BN_exp
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*p, BN_CTX *ctx);
int
BN_mod_exp
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*p, const BIGNUM *m, BN_CTX
*ctx);
int
BN_gcd
(BIGNUM *r,
const BIGNUM *a, const BIGNUM
*b, BN_CTX *ctx);
DESCRIPTION
BN_add
()
adds a and b and places the
result in r (r=a+b
).
r may be the same BIGNUM as
a or b.
BN_uadd
()
adds the absolute values of a and
b and places the result in r
(r=|a|+|b|
). r may be the same
BIGNUM as a or
b.
BN_sub
()
subtracts b from a and places
the result in r (r=a-b
).
r may be the same BIGNUM as
a or b.
BN_usub
()
subtracts the absolute value of b from the absolute
value of a and places the result in
r (r=|a|-|b|
). It requires the
absolute value of a to be greater than the absolute
value of b; otherwise it will fail.
r may be the same BIGNUM as
a or b.
BN_mul
()
multiplies a and b and places
the result in r (r=a*b
).
r may be the same BIGNUM as
a or b. For multiplication by
powers of 2, use
BN_lshift(3).
BN_sqr
()
takes the square of a and places the result in
r (r=a^2
).
r and a may be the same
BIGNUM. This function is faster than
BN_mul
(r,
a, a).
BN_div
()
divides a by d and places the
result in dv and the remainder in
rem (dv=a/d
,
rem=a%d
). If the flag
BN_FLG_CONSTTIME
is set on a
or d, it operates in constant time. Either of
dv and rem may be
NULL
, in which case the respective value is not
returned. The result is rounded towards zero; thus if
a is negative, the remainder will be zero or negative.
For division by powers of 2, use
BN_rshift
(3).
BN_mod
()
corresponds to BN_div
() with
dv set to NULL
. It is
implemented as a macro.
BN_nnmod
()
reduces a modulo m and places
the non-negative remainder in r.
BN_mod_add
()
adds a to b modulo
m and places the non-negative result in
r.
BN_mod_add_quick
()
is a variant of BN_mod_add
() that requires
a and b to both be non-negative
and smaller than m. If any of these constraints are
violated, it silently produces wrong results.
BN_mod_sub
()
subtracts b from a modulo
m and places the non-negative result in
r.
BN_mod_sub_quick
()
is a variant of BN_mod_sub
() that requires
a and b to both be non-negative
and smaller than m. If any of these constraints are
violated, it silently produces wrong results.
BN_mod_mul
()
multiplies a by b and finds the
non-negative remainder respective to modulus m
(r=(a*b)%m
). r may be the same
BIGNUM as a or
b. For more efficient algorithms for repeated
computations using the same modulus, see
BN_mod_mul_montgomery(3) and
BN_mod_mul_reciprocal(3).
BN_mod_sqr
()
takes the square of a modulo m
and places the result in r.
BN_mod_lshift
()
shifts a left by n bits, reduces
the result modulo m, and places the non-negative
remainder in r (r=a*2^n mod
m
).
BN_mod_lshift1
()
shifts a left by one bit, reduces the result modulo
m, and places the non-negative remainder in
r (r=a*2 mod m
).
BN_mod_lshift_quick
()
and
BN_mod_lshift1_quick
()
are variants of BN_mod_lshift
() and
BN_mod_lshift1
(), respectively, that require
a to be non-negative and less than
m. If either of these constraints is violated, they
sometimes fail and sometimes silently produce wrong results.
BN_exp
()
raises a to the p-th power and
places the result in r
(r=a^p
). This function is faster than repeated
applications of BN_mul
().
BN_mod_exp
()
computes a to the p-th power
modulo m (r=(a^p)%m
). If the
flag BN_FLG_CONSTTIME
is set on
p, it operates in constant time. This function uses
less time and space than BN_exp
().
BN_gcd
()
computes the greatest common divisor of a and
b and places the result in r.
r may be the same BIGNUM as
a or b.
For all functions, ctx is a previously allocated BN_CTX used for temporary variables; see BN_CTX_new(3).
Unless noted otherwise, the result BIGNUM must be different from the arguments.
RETURN VALUES
For all functions, 1 is returned for success, 0 on error. The return value should always be checked, for example:
if (!BN_add(r,a,b)) goto
err;
The error codes can be obtained by ERR_get_error(3).
SEE ALSO
BN_add_word(3), BN_CTX_new(3), BN_new(3), BN_set_bit(3), BN_set_flags(3), BN_set_negative(3)
HISTORY
BN_add
(),
BN_sub
(), BN_mul
(),
BN_sqr
(), BN_div
(),
BN_mod
(), BN_mod_mul
(),
BN_mod_exp
(), and BN_gcd
()
first appeared in SSLeay 0.5.1. BN_exp
() first
appeared in SSLeay 0.9.0. All these functions have been available since
OpenBSD 2.4.
BN_uadd
(),
BN_usub
(), and the ctx
argument to BN_mul
() first appeared in SSLeay 0.9.1
and have been available since OpenBSD 2.6.
BN_nnmod
(),
BN_mod_add
(),
BN_mod_add_quick
(),
BN_mod_sub
(),
BN_mod_sub_quick
(),
BN_mod_sqr
(),
BN_mod_lshift
(),
BN_mod_lshift_quick
(),
BN_mod_lshift1
(), and
BN_mod_lshift1_quick
() first appeared in OpenSSL
0.9.7 and have been available since OpenBSD 3.2.
BUGS
Even if the BN_FLG_CONSTTIME
flag is set
on a or b,
BN_gcd
() neither fails nor operates in constant
time, potentially allowing timing side-channel attacks.
Even if the BN_FLG_CONSTTIME
flag is set
on p, if the modulus m is even,
BN_mod_exp
() does not operate in constant time,
potentially allowing timing side-channel attacks.
If BN_FLG_CONSTTIME
is set on
p, BN_exp
() fails instead of
operating in constant time.