summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/man/BN_mod_mul_reciprocal.3274
-rw-r--r--src/lib/libcrypto/man/Makefile3
2 files changed, 1 insertions, 276 deletions
diff --git a/src/lib/libcrypto/man/BN_mod_mul_reciprocal.3 b/src/lib/libcrypto/man/BN_mod_mul_reciprocal.3
deleted file mode 100644
index f28ade2a41..0000000000
--- a/src/lib/libcrypto/man/BN_mod_mul_reciprocal.3
+++ /dev/null
@@ -1,274 +0,0 @@
1.\" $OpenBSD: BN_mod_mul_reciprocal.3,v 1.12 2022/11/14 18:28:29 schwarze Exp $
2.\" full merge up to: OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000
3.\" selective merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
9.\"
10.\" Permission to use, copy, modify, and distribute this software for any
11.\" purpose with or without fee is hereby granted, provided that the above
12.\" copyright notice and this permission notice appear in all copies.
13.\"
14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21.\"
22.\" The original file was written by Ulf Moeller <ulf@openssl.org>.
23.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: November 14 2022 $
70.Dt BN_MOD_MUL_RECIPROCAL 3
71.Os
72.Sh NAME
73.Nm BN_mod_mul_reciprocal ,
74.Nm BN_RECP_CTX_new ,
75.Nm BN_RECP_CTX_init ,
76.Nm BN_RECP_CTX_free ,
77.Nm BN_RECP_CTX_set ,
78.Nm BN_div_recp ,
79.Nm BN_reciprocal
80.Nd modular multiplication using reciprocal
81.Sh SYNOPSIS
82.In openssl/bn.h
83.Ft int
84.Fo BN_mod_mul_reciprocal
85.Fa "BIGNUM *r"
86.Fa "const BIGNUM *a"
87.Fa "const BIGNUM *b"
88.Fa "BN_RECP_CTX *recp"
89.Fa "BN_CTX *ctx"
90.Fc
91.Ft BN_RECP_CTX *
92.Fo BN_RECP_CTX_new
93.Fa void
94.Fc
95.Ft void
96.Fo BN_RECP_CTX_init
97.Fa "BN_RECP_CTX *recp"
98.Fc
99.Ft void
100.Fo BN_RECP_CTX_free
101.Fa "BN_RECP_CTX *recp"
102.Fc
103.Ft int
104.Fo BN_RECP_CTX_set
105.Fa "BN_RECP_CTX *recp"
106.Fa "const BIGNUM *m"
107.Fa "BN_CTX *ctx"
108.Fc
109.Ft int
110.Fo BN_div_recp
111.Fa "BIGNUM *dv"
112.Fa "BIGNUM *rem"
113.Fa "const BIGNUM *a"
114.Fa "BN_RECP_CTX *recp"
115.Fa "BN_CTX *ctx"
116.Fc
117.Ft int
118.Fo BN_reciprocal
119.Fa "BIGNUM *r"
120.Fa "const BIGNUM *m"
121.Fa "int len"
122.Fa "BN_CTX *ctx"
123.Fc
124.Sh DESCRIPTION
125.Fn BN_mod_mul_reciprocal
126can be used to perform an efficient
127.Xr BN_mod_mul 3
128operation when the operation will be performed repeatedly with the same
129modulus.
130It computes
131.Fa r Ns =( Ns Fa a Ns * Ns Fa b Ns )% Ns Fa m
132using
133.Fa recp Ns =1/ Ns Fa m ,
134which is set as described below.
135.Fa ctx
136is a previously allocated
137.Vt BN_CTX
138used for temporary variables.
139.Pp
140.Fn BN_RECP_CTX_new
141allocates and initializes a
142.Vt BN_RECP_CTX
143structure.
144.Pp
145.Fn BN_RECP_CTX_init
146initializes an existing uninitialized
147.Vt BN_RECP_CTX .
148It is deprecated and dangerous: see
149.Sx CAVEATS .
150.Pp
151.Fn BN_RECP_CTX_free
152frees the components of the
153.Vt BN_RECP_CTX ,
154and, if it was created by
155.Fn BN_RECP_CTX_new ,
156also the structure itself.
157If
158.Fa recp
159is a
160.Dv NULL
161pointer, no action occurs.
162.Pp
163.Fn BN_RECP_CTX_set
164stores
165.Fa m
166in
167.Fa recp
168and sets it up for computing
169.Pf 1/ Fa m
170and shifting it left by
171.Fn BN_num_bits m Ns +1
172to make it an integer.
173The result and the number of bits it was shifted left will later be
174stored in
175.Fa recp .
176.Pp
177.Fn BN_div_recp
178divides
179.Fa a
180by
181.Fa m
182using
183.Fa recp .
184It places the quotient in
185.Fa dv
186and the remainder in
187.Fa rem .
188.Pp
189.Fn BN_reciprocal
190divides the
191.Fa len Ap th
192power of two by
193.Fa m
194and places the quotient in
195.Fa r ,
196rounding it towards zero to the closest integer.
197.Pp
198The
199.Vt BN_RECP_CTX
200structure is defined as follows:
201.Bd -literal
202typedef struct bn_recp_ctx_st {
203 BIGNUM N; /* the divisor */
204 BIGNUM Nr; /* the reciprocal */
205 int num_bits;
206 int shift;
207 int flags;
208} BN_RECP_CTX;
209.Ed
210.Pp
211It cannot be shared between threads.
212.Sh RETURN VALUES
213.Fn BN_RECP_CTX_new
214returns the newly allocated
215.Vt BN_RECP_CTX
216or
217.Dv NULL
218on error.
219.Pp
220.Fn BN_mod_mul_reciprocal ,
221.Fn BN_RECP_CTX_set ,
222and
223.Fn BN_div_recp
224return 1 for success or 0 on error.
225.Pp
226.Fn BN_reciprocal
227returns
228.Fa len
229for success or \-1 on error.
230.Pp
231The error codes can be obtained by
232.Xr ERR_get_error 3 .
233.Sh SEE ALSO
234.Xr BN_add 3 ,
235.Xr BN_CTX_new 3 ,
236.Xr BN_new 3
237.Sh HISTORY
238.Fn BN_mod_mul_reciprocal
239and
240.Fn BN_reciprocal
241first appeared in SSLeay 0.5.1 and have been available since
242.Ox 2.4 .
243.Pp
244.Vt BN_RECP_CTX
245was added in SSLeay 0.9.0.
246Before that, the
247.Fn BN_mod_mul_reciprocal
248arguments were different.
249.Pp
250.Fn BN_RECP_CTX_new ,
251.Fn BN_RECP_CTX_init ,
252.Fn BN_RECP_CTX_free ,
253.Fn BN_RECP_CTX_set ,
254and
255.Fn BN_div_recp
256first appeared in SSLeay 0.9.1 and have been available since
257.Ox 2.6 .
258.Sh CAVEATS
259.Fn BN_RECP_CTX_init
260must not be called on a context that was used previously, or
261memory used by the embedded
262.Vt BIGNUM
263structures is leaked immediately.
264Besides, it must not be called on a context created with
265.Fn BN_RECP_CTX_new ,
266or the context itself will likely be leaked later.
267It can only be used on a static
268.Vt BN_RECP_CTX
269structure, on one located on the stack, or on one
270.Xr malloc 3 Ap ed
271manually, but all these options are discouraged because they
272will no longer work once
273.Vt BN_RECP_CTX
274is made opaque.
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index d20c8d8ed5..3616c157d3 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1# $OpenBSD: Makefile,v 1.247 2023/04/27 09:08:08 tb Exp $ 1# $OpenBSD: Makefile,v 1.248 2023/04/27 09:43:55 tb Exp $
2 2
3.include <bsd.own.mk> 3.include <bsd.own.mk>
4 4
@@ -78,7 +78,6 @@ MAN= \
78 BN_kronecker.3 \ 78 BN_kronecker.3 \
79 BN_mod_inverse.3 \ 79 BN_mod_inverse.3 \
80 BN_mod_mul_montgomery.3 \ 80 BN_mod_mul_montgomery.3 \
81 BN_mod_mul_reciprocal.3 \
82 BN_mod_sqrt.3 \ 81 BN_mod_sqrt.3 \
83 BN_new.3 \ 82 BN_new.3 \
84 BN_num_bytes.3 \ 83 BN_num_bytes.3 \
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-11-01 16:02:37 +0000