BN_add() -- SSLeay 0.9.0b -- January 1999

NAME

BN_add, BN_sub, BN_mul, BN_div, BN_mod, BN_reciprocal, BN_sqr, BN_exp,
BN_mod_exp, BN_mod_exp_simple, BN_mod_inverse, BN_mod_mul, BN_mod_exp_mont,
BN_mod_exp_recp, BN_mod_mul_reciprocal, BN_gcd -- BN arithmetic routines

SYNOPSIS

#include "bn.h"

int BN_add(r, a, b)
BIGNUM *r, *a, *b;

int BN_sub(r, a, b)
BIGNUM *r, *a, *b;

int BN_mul(r, a, b)
BIGNUM *r, *a, *b;

int BN_div(dv, rem, m, d, ctx)
BIGNUM *dv, *rem, *m, *d;
BN_CTX *ctx;

int BN_mod(rem, m, d, ctx)
BIGNUM *rem, *m, *d;
BN_CTX *ctx;

int BN_reciprocal(r, m, ctx)
BIGNUM *r, *m;
BN_CTX *ctx;

int BN_sqr(r, a, ctx)
BIGNUM *r, *a;
BN_CTX *ctx;

int BN_exp(r, a, p, ctx)
BIGNUM *r, *a, *p;
BN_CTX *ctx;

int BN_mod_exp(r, a, p, m, ctx)
BIGNUM *r, *a,*p, *m;
BN_CTX *ctx;

int BN_mod_exp_mont(r, a, p, m, ctx, m_ctx)
BIGNUM *r, *a,*p, *m;
BN_CTX *ctx;
BN_MONT_CTX *m_ctx;

int BN_mod_exp_recp(r, a, p, m, ctx)
BIGNUM *r, *a,*p, *m;
BN_CTX *ctx;

int BN_mod_exp_simple(r, a, p, m, ctx)
BIGNUM *r, *a,*p, *m;
BN_CTX *ctx;

int BN_mod_mul_reciprocal(r, x, y, m, i, nb, ctx)
BIGNUM *r, *x, *y, *m, *i;
int nb;
BN_CTX *ctx;

int BN_gcd(r, a, b, ctx)
BIGNUM *r, *a, *b;
BN_CTX *ctx;

int BN_mod_mul(ret, a, b, m, ctx)
BIGNUM *ret, *a, *b, *m;
BN_CTX *ctx;

BIGNUM *BN_mod_inverse(a, n, ctx)
BIGNUM *a, *n;
BN_CTX *ctx;

int BN_mod_mul_montgomery(r, a, b, mont, ctx)
BIGNUM *r, *a, *b;
BN_MONT_CTX *mont;
BN_CTX *ctx;

DESCRIPTION

BN_add adds the two BIGNUMs a and b and places the result in r. r may be expanded to contain the new value. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

BN_sub subtracts b from a and places the result in r. r may be expanded to contain the new value. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

BN_mul multiplies a and b and places the result in r. r may be expanded to contain the new value. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

Note that r must be different from a and b.

BN_div divides m by d, places the result in dv and the remainder in rem. If either dv or rem are NULL then the coresponding value will not be returned. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

BN_mod finds the remainder of m divided by d and places it in rem. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

This function is much faster than BN_div(NULL,rem,m,d,ctx) and should be used in preference to it when only the remainder is desired.

BN_reciprocal computes the reciprocal of m and places the result, left-shifted to make it an integer, in r. That is, r=(1/m)>>(BN_num_bits(m)+1). ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. This function handles negative BIGNUMs properly. The number of bits 1/m was leftshifted is returned, or -1 on error.

The number of bits shifted is required by BN_mod_mul_reciprocal().

BN_sqr squares a and places the result in r. r may be expanded to contain the new value. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

This function is much faster than BN_mul(r,a,a) and should be used in preference to it.

Note that r must be different from a.

BN_exp computes a to the p power and places the result in r. r may be expanded to contain the new value. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

This function is much faster than repeated applications of BN_mul, and should be used in preference to it.

BN_mod_exp_simple is generally not called; use BN_mod_exp instead, which will call the appropriate (faster) routine.

BN_mod_inverse computes the inverse of a in the field F^*_n. That is, the new value satisfies (a* new value)%n == 1. This new value is returned, or NULL on error. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated.

This function is used in the generation of RSA keys.

BN_mod_exp computes (a to the p power) mod m by calling either BN_mod_exp_mont or BN_mod_exp_recp, depending on whether m is odd or not. It retrieves the result and places it in r. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

BN_mod_mul performs a BN_mul (or if a and b point to the same structure, BN_sqr) of a and b, and then calls BN_mod on that result with m as the divisor. The final result is then placed in r. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. 0 is returned on success or 1 on error. This function handles negative BIGNUMs properly.

BN_mod_exp_mont is called by BN_mod_exp. You probably won't ever need to call it directly.

BN_mod_exp_recp is called by BN_mod_exp. You probably won't ever need to call it directly.

BN_mod_mul_reciprocal is used to perform an efficient BN_mod_mul() operation. If you want to use repeated applications of BN_mod_mul with the same modulus it is much faster to compute BN_inverse of the modulus and then call this function which uses BN_mul instead of BN_divide.

This function multiples x and y, and computes the remainder when divided by m. This result is returned or NULL on error. i must be the reciprocal of the modulus m. and returns nb must be the number of bits the reciprocal was shifted (see BN_reciprocal for this).

Normal usage is as follows:

  bn=BN_reciprocal(i,m);
  for (...)  { 
       BN_mod_mul_reciprocal(r,x,y,m,i,bn,ctx); 
  }

This function is used in BN_mod_exp() and BN_is_prime().

BN_gcd computes the greatest common divisor of a and b and places the result in r. The ctx, which holds the temporary BIGNUMs required by this function, must have been previously allocated. 0 is returned on success or 1 on error. I am not sure what this does if you pass it negative numbers.