.Dd $Mdocdate: February 23 2015 $
.Dt BN_MOD_MUL_RECIPROCAL 3
.Os
.Sh NAME
.Nm BN_mod_mul_reciprocal ,
.Nm BN_div_recp ,
.Nm BN_RECP_CTX_new ,
.Nm BN_RECP_CTX_init ,
.Nm BN_RECP_CTX_free ,
.Nm BN_RECP_CTX_set
.Nd modular multiplication using reciprocal
.Sh SYNOPSIS
.In openssl/bn.h
.Ft BN_RECP_CTX *
.Fo BN_RECP_CTX_new
.Fa void
.Fc
.Ft void
.Fo BN_RECP_CTX_init
.Fa "BN_RECP_CTX *recp"
.Fc
.Ft void
.Fo BN_RECP_CTX_free
.Fa "BN_RECP_CTX *recp"
.Fc
.Ft int
.Fo BN_RECP_CTX_set
.Fa "BN_RECP_CTX *recp"
.Fa "const BIGNUM *m"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo BN_div_recp
.Fa "BIGNUM *dv"
.Fa "BIGNUM *rem"
.Fa "BIGNUM *a"
.Fa "BN_RECP_CTX *recp"
.Fa "BN_CTX *ctx"
.Fc
.Ft int
.Fo BN_mod_mul_reciprocal
.Fa "BIGNUM *r"
.Fa "BIGNUM *a"
.Fa "BIGNUM *b"
.Fa "BN_RECP_CTX *recp"
.Fa "BN_CTX *ctx"
.Fc
.Sh DESCRIPTION
.Fn BN_mod_mul_reciprocal
can be used to perform an efficient
.Xr BN_mod_mul 3
operation when the operation will be performed repeatedly with the same
modulus.
It computes
.Fa r Ns =( Ns Fa a Ns * Ns Fa b Ns )% Ns Fa m
using
.Fa recp Ns =1/ Ns Fa m ,
which is set as described below.
.Fa ctx
is a previously allocated
.Vt BN_CTX
used for temporary variables.
.Pp
.Fn BN_RECP_CTX_new
allocates and initializes a
.Vt BN_RECP_CTX
structure.
.Fn BN_RECP_CTX_init
initializes an existing uninitialized
.Vt BN_RECP_CTX .
.Pp
.Fn BN_RECP_CTX_free
frees the components of the
.Vt BN_RECP_CTX ,
and, if it was created by
.Fn BN_RECP_CTX_new ,
also the structure itself.
.Pp
.Fn BN_RECP_CTX_set
stores
.Fa m
in
.Fa recp
and sets it up for computing
.Pf 1/ Fa m
and shifting it left by
.Fn BN_num_bits m Ns +1
to make it an integer.
The result and the number of bits it was shifted left will later be
stored in
.Fa recp .
.Pp
.Fn BN_div_recp
divides
.Fa a
by
.Fa m
using
.Fa recp .
It places the quotient in
.Fa dv
and the remainder in
.Fa rem .
.Pp
The
.Vt BN_RECP_CTX
structure is defined as follows:
.Bd -literal
typedef struct bn_recp_ctx_st {
	BIGNUM N;	/* the divisor */
	BIGNUM Nr;	/* the reciprocal */
	int num_bits;
	int shift;
	int flags;
} BN_RECP_CTX;
.Ed
.Pp
It cannot be shared between threads.
.Sh RETURN VALUES
.Fn BN_RECP_CTX_new
returns the newly allocated
.Vt BN_RECP_CTX ,
or
.Dv NULL
on error.
.Pp
.Fn BN_RECP_CTX_init
and
.Fn BN_RECP_CTX_free
return no values.
.Pp
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr bn 3 ,
.Xr BN_add 3 ,
.Xr BN_CTX_new 3 ,
.Xr ERR_get_error 3
.Sh HISTORY
.Vt BN_RECP_CTX
was added in SSLeay 0.9.0.
Before that, a function
.Fn BN_reciprocal
was used instead, and the
.Fn BN_mod_mul_reciprocal
arguments were different.