1 files changed, 181 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BN_mod_mul_montgomery.3 b/src/lib/libcrypto/man/BN_mod_mul_montgomery.3
new file mode 100644
index 0000000000..ac120f3c02
--- /dev/null
+++ b/src/lib/libcrypto/man/BN_mod_mul_montgomery.3
@@ -0,0 +1,181 @@
+.Dd $Mdocdate: February 23 2015 $
+.Dt BN_MOD_MUL_MONTGOMERY 3
+.Os
+.Sh NAME
+.Nm BN_mod_mul_montgomery ,
+.Nm BN_MONT_CTX_new ,
+.Nm BN_MONT_CTX_init ,
+.Nm BN_MONT_CTX_free ,
+.Nm BN_MONT_CTX_set ,
+.Nm BN_MONT_CTX_copy ,
+.Nm BN_from_montgomery ,
+.Nm BN_to_montgomery
+.Nd Montgomery multiplication
+.Sh SYNOPSIS
+.In openssl/bn.h
+.Ft BN_MONT_CTX *
+.Fo BN_MONT_CTX_new
+.Fa void
+.Fc
+.Ft void
+.Fo BN_MONT_CTX_init
+.Fa "BN_MONT_CTX *ctx"
+.Fc
+.Ft void
+.Fo BN_MONT_CTX_free
+.Fa "BN_MONT_CTX *mont"
+.Fc
+.Ft int
+.Fo BN_MONT_CTX_set
+.Fa "BN_MONT_CTX *mont"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft BN_MONT_CTX *
+.Fo BN_MONT_CTX_copy
+.Fa "BN_MONT_CTX *to"
+.Fa "BN_MONT_CTX *from"
+.Fc
+.Ft int
+.Fo BN_mod_mul_montgomery
+.Fa "BIGNUM *r"
+.Fa "BIGNUM *a"
+.Fa "BIGNUM *b"
+.Fa "BN_MONT_CTX *mont"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_from_montgomery
+.Fa "BIGNUM *r"
+.Fa "BIGNUM *a"
+.Fa "BN_MONT_CTX *mont"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_to_montgomery
+.Fa "BIGNUM *r"
+.Fa "BIGNUM *a"
+.Fa "BN_MONT_CTX *mont"
+.Fa "BN_CTX *ctx"
+.Fc
+.Sh DESCRIPTION
+These functions implement Montgomery multiplication.
+They are used automatically when
+.Xr BN_mod_exp 3
+is called with suitable input, but they may be useful when several
+operations are to be performed using the same modulus.
+.Pp
+.Fn BN_MONT_CTX_new
+allocates and initializes a
+.Vt BN_MONT_CTX
+structure.
+.Fn BN_MONT_CTX_init
+initializes an existing uninitialized
+.Vt BN_MONT_CTX .
+.Pp
+.Fn BN_MONT_CTX_set
+sets up the
+.Fa mont
+structure from the modulus
+.Fa m
+by precomputing its inverse and a value R.
+.Pp
+.Fn BN_MONT_CTX_copy
+copies the
+.Vt BN_MONT_CTX
+.Fa from
+to
+.Fa to .
+.Pp
+.Fn BN_MONT_CTX_free
+frees the components of the
+.Vt BN_MONT_CTX ,
+and, if it was created by
+.Fn BN_MONT_CTX_new ,
+also the structure itself.
+.Pp
+.Fn BN_mod_mul_montgomery
+computes
+.Pp
+.D1 Mont Ns Po Fa a , Fa b Pc := Fa a No * Fa b No * R^-1
+.Pp
+and places the result in
+.Fa r .
+.Pp
+.Fn BN_from_montgomery
+performs the Montgomery reduction
+.Pp
+.D1 Fa r No = Fa a No * R^-1.
+.Pp
+.Fn BN_to_montgomery
+computes
+.Pp
+.D1 Mont Ns Po Fa a , No R^2 Pc = Fa a No * R .
+.Pp
+Note that
+.Fa a
+must be non-negative and smaller than the modulus.
+.Pp
+For all functions,
+.Fa ctx
+is a previously allocated
+.Vt BN_CTX
+used for temporary variables.
+.Pp
+The
+.Vt BN_MONT_CTX
+structure is defined as follows:
+.Bd -literal
+typedef struct bn_mont_ctx_st {
+        int ri;         /* number of bits in R */
+        BIGNUM RR;      /* R^2 (used to convert to Montgomery form) */
+        BIGNUM N;       /* The modulus */
+        BIGNUM Ni;      /* R*(1/R mod N) - N*Ni = 1
+                         * (Ni is only stored for bignum algorithm) */
+        BN_ULONG n0;    /* least significant word of Ni */
+        int flags;
+} BN_MONT_CTX;
+.Ed
+.Pp
+.Fn BN_to_montgomery
+is a macro.
+.Pp
+.Sy Warning:
+The inputs must be reduced modulo
+.Fa m ,
+otherwise the result will be outside the expected range.
+.Sh RETURN VALUES
+.Fn BN_MONT_CTX_new
+returns the newly allocated
+.Vt BN_MONT_CTX ,
+and
+.Dv NULL
+on error.
+.Pp
+.Fn BN_MONT_CTX_init
+and
+.Fn BN_MONT_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
+.Fn BN_MONT_CTX_new ,
+.Fn BN_MONT_CTX_free ,
+.Fn BN_MONT_CTX_set ,
+.Fn BN_mod_mul_montgomery ,
+.Fn BN_from_montgomery
+and
+.Fn BN_to_montgomery
+are available in all versions of SSLeay and OpenSSL.
+.Pp
+.Fn BN_MONT_CTX_init
+and
+.Fn BN_MONT_CTX_copy
+were added in SSLeay 0.9.1b.