+++ /dev/null
-.\" $OpenBSD: BN_mod_mul_reciprocal.3,v 1.12 2022/11/14 18:28:29 schwarze Exp $
-.\" full merge up to: OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000
-.\" selective merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
-.\"
-.\" This file is a derived work.
-.\" The changes are covered by the following Copyright and license:
-.\"
-.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
-.\"
-.\" Permission to use, copy, modify, and distribute this software for any
-.\" purpose with or without fee is hereby granted, provided that the above
-.\" copyright notice and this permission notice appear in all copies.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-.\"
-.\" The original file was written by Ulf Moeller <ulf@openssl.org>.
-.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\"
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in
-.\" the documentation and/or other materials provided with the
-.\" distribution.
-.\"
-.\" 3. All advertising materials mentioning features or use of this
-.\" software must display the following acknowledgment:
-.\" "This product includes software developed by the OpenSSL Project
-.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
-.\"
-.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
-.\" endorse or promote products derived from this software without
-.\" prior written permission. For written permission, please contact
-.\" openssl-core@openssl.org.
-.\"
-.\" 5. Products derived from this software may not be called "OpenSSL"
-.\" nor may "OpenSSL" appear in their names without prior written
-.\" permission of the OpenSSL Project.
-.\"
-.\" 6. Redistributions of any form whatsoever must retain the following
-.\" acknowledgment:
-.\" "This product includes software developed by the OpenSSL Project
-.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
-.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
-.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-.\" OF THE POSSIBILITY OF SUCH DAMAGE.
-.\"
-.Dd $Mdocdate: November 14 2022 $
-.Dt BN_MOD_MUL_RECIPROCAL 3
-.Os
-.Sh NAME
-.Nm BN_mod_mul_reciprocal ,
-.Nm BN_RECP_CTX_new ,
-.Nm BN_RECP_CTX_init ,
-.Nm BN_RECP_CTX_free ,
-.Nm BN_RECP_CTX_set ,
-.Nm BN_div_recp ,
-.Nm BN_reciprocal
-.Nd modular multiplication using reciprocal
-.Sh SYNOPSIS
-.In openssl/bn.h
-.Ft int
-.Fo BN_mod_mul_reciprocal
-.Fa "BIGNUM *r"
-.Fa "const BIGNUM *a"
-.Fa "const BIGNUM *b"
-.Fa "BN_RECP_CTX *recp"
-.Fa "BN_CTX *ctx"
-.Fc
-.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 "const BIGNUM *a"
-.Fa "BN_RECP_CTX *recp"
-.Fa "BN_CTX *ctx"
-.Fc
-.Ft int
-.Fo BN_reciprocal
-.Fa "BIGNUM *r"
-.Fa "const BIGNUM *m"
-.Fa "int len"
-.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.
-.Pp
-.Fn BN_RECP_CTX_init
-initializes an existing uninitialized
-.Vt BN_RECP_CTX .
-It is deprecated and dangerous: see
-.Sx CAVEATS .
-.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.
-If
-.Fa recp
-is a
-.Dv NULL
-pointer, no action occurs.
-.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
-.Fn BN_reciprocal
-divides the
-.Fa len Ap th
-power of two by
-.Fa m
-and places the quotient in
-.Fa r ,
-rounding it towards zero to the closest integer.
-.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_mod_mul_reciprocal ,
-.Fn BN_RECP_CTX_set ,
-and
-.Fn BN_div_recp
-return 1 for success or 0 on error.
-.Pp
-.Fn BN_reciprocal
-returns
-.Fa len
-for success or \-1 on error.
-.Pp
-The error codes can be obtained by
-.Xr ERR_get_error 3 .
-.Sh SEE ALSO
-.Xr BN_add 3 ,
-.Xr BN_CTX_new 3 ,
-.Xr BN_new 3
-.Sh HISTORY
-.Fn BN_mod_mul_reciprocal
-and
-.Fn BN_reciprocal
-first appeared in SSLeay 0.5.1 and have been available since
-.Ox 2.4 .
-.Pp
-.Vt BN_RECP_CTX
-was added in SSLeay 0.9.0.
-Before that, the
-.Fn BN_mod_mul_reciprocal
-arguments were different.
-.Pp
-.Fn BN_RECP_CTX_new ,
-.Fn BN_RECP_CTX_init ,
-.Fn BN_RECP_CTX_free ,
-.Fn BN_RECP_CTX_set ,
-and
-.Fn BN_div_recp
-first appeared in SSLeay 0.9.1 and have been available since
-.Ox 2.6 .
-.Sh CAVEATS
-.Fn BN_RECP_CTX_init
-must not be called on a context that was used previously, or
-memory used by the embedded
-.Vt BIGNUM
-structures is leaked immediately.
-Besides, it must not be called on a context created with
-.Fn BN_RECP_CTX_new ,
-or the context itself will likely be leaked later.
-It can only be used on a static
-.Vt BN_RECP_CTX
-structure, on one located on the stack, or on one
-.Xr malloc 3 Ap ed
-manually, but all these options are discouraged because they
-will no longer work once
-.Vt BN_RECP_CTX
-is made opaque.
projects / openbsd / commitdiff