From e7d941cd4fecb8ed1bf6eb25c016a77bb81b9c97 Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Fri, 21 Apr 2023 06:34:37 +0000
Subject: [PATCH] Remove some (soon to be) outdated documentation

The documentation of the BN_MOD_CTX has been out of sync with reality
for decades. The structure is now opaque, so its members should not be
documented this way. They internals aren't important for the rest of
the page.

BN_MOD_CTX_init() will soon be removed. It's useless unless you like
leaks.
---
 lib/libcrypto/man/BN_mod_mul_montgomery.3 | 51 ++---------------------
 1 file changed, 3 insertions(+), 48 deletions(-)

diff --git a/lib/libcrypto/man/BN_mod_mul_montgomery.3 b/lib/libcrypto/man/BN_mod_mul_montgomery.3
index 7b22efd7f59..0815eced493 100644
--- a/lib/libcrypto/man/BN_mod_mul_montgomery.3
+++ b/lib/libcrypto/man/BN_mod_mul_montgomery.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BN_mod_mul_montgomery.3,v 1.14 2021/12/21 11:14:07 schwarze Exp $
+.\" $OpenBSD: BN_mod_mul_montgomery.3,v 1.15 2023/04/21 06:34:37 tb Exp $
 .\" full merge up to: OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
@@ -66,12 +66,11 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 21 2021 $
+.Dd $Mdocdate: April 21 2023 $
 .Dt BN_MOD_MUL_MONTGOMERY 3
 .Os
 .Sh NAME
 .Nm BN_MONT_CTX_new ,
-.Nm BN_MONT_CTX_init ,
 .Nm BN_MONT_CTX_free ,
 .Nm BN_MONT_CTX_set ,
 .Nm BN_MONT_CTX_set_locked ,
@@ -87,10 +86,6 @@
 .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
@@ -146,12 +141,6 @@ allocates and initializes a
 .Vt BN_MONT_CTX
 structure.
 .Pp
-.Fn BN_MONT_CTX_init
-initializes an existing uninitialized
-.Vt BN_MONT_CTX .
-It is deprecated and dangerous: see
-.Sx CAVEATS .
-.Pp
 .Fn BN_MONT_CTX_set
 sets up the
 .Fa mont
@@ -237,21 +226,6 @@ 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
 .Sy Warning :
 The inputs must be reduced modulo
 .Fa m ,
@@ -288,29 +262,10 @@ and
 first appeared in SSLeay 0.6.1 and have been available since
 .Ox 2.4 .
 .Pp
-.Fn BN_MONT_CTX_init
-and
 .Fn BN_MONT_CTX_copy
-first appeared in SSLeay 0.9.1 and have been available since
+first appeared in SSLeay 0.9.1 and has been available since
 .Ox 2.6 .
 .Pp
 .Fn BN_MONT_CTX_set_locked
 first appeared in OpenSSL 0.9.8 and has been available since
 .Ox 4.0 .
-.Sh CAVEATS
-.Fn BN_MONT_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_MONT_CTX_new ,
-or the context itself will likely be leaked later.
-It can only be used on a static
-.Vt BN_MONT_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_MONT_CTX
-is made opaque.
-- 
2.20.1