document BN_nist_mod_521(3) and their four siblings

3 files changed, 118 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/BN_new.3 b/src/lib/libcrypto/man/BN_new.3
index 1913b75ec5..7e3432770f 100644
--- a/src/lib/libcrypto/man/BN_new.3
+++ b/src/lib/libcrypto/man/BN_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BN_new.3,v 1.21 2022/11/18 01:21:40 schwarze Exp $
+.\" $OpenBSD: BN_new.3,v 1.22 2022/11/21 22:04:04 schwarze Exp $
 .\" full merge up to: OpenSSL man3/BN_new 2457c19d Mar 6 08:43:36 2004 +0000
 .\" selective merge up to: man3/BN_new 681acb31 Sep 29 13:10:34 2017 +0200
 .\" full merge up to: OpenSSL man7/bn 05ea606a May 20 20:52:46 2016 -0400
@@ -50,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 18 2022 $
+.Dd $Mdocdate: November 21 2022 $
 .Dt BN_NEW 3
 .Os
 .Sh NAME
@@ -161,6 +161,7 @@ and sets an error code that can be obtained by
 .Xr BN_mod_mul_montgomery 3 ,
 .Xr BN_mod_mul_reciprocal 3 ,
 .Xr BN_mod_sqrt 3 ,
+.Xr BN_nist_mod_521 3 ,
 .Xr BN_num_bytes 3 ,
 .Xr BN_rand 3 ,
 .Xr BN_security_bits 3 ,
diff --git a/src/lib/libcrypto/man/BN_nist_mod_521.3 b/src/lib/libcrypto/man/BN_nist_mod_521.3
new file mode 100644
index 0000000000..72dd4a7124
--- /dev/null
+++ b/src/lib/libcrypto/man/BN_nist_mod_521.3
@@ -0,0 +1,113 @@
+.\" $OpenBSD: BN_nist_mod_521.3,v 1.1 2022/11/21 22:04:04 schwarze Exp $
+.\"
+.\" 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.
+.\"
+.Dd $Mdocdate: November 21 2022 $
+.Dt BN_NIST_MOD_521 3
+.Os
+.Sh NAME
+.Nm BN_nist_mod_192 ,
+.Nm BN_nist_mod_224 ,
+.Nm BN_nist_mod_256 ,
+.Nm BN_nist_mod_384 ,
+.Nm BN_nist_mod_521
+.Nd reduction modulo NIST-recommended primes
+.Sh SYNOPSIS
+.In openssl/bn.h
+.Ft int
+.Fo BN_nist_mod_192
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_nist_mod_224
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_nist_mod_256
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_nist_mod_384
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_nist_mod_521
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Sh DESCRIPTION
+These functions are optimized versions of
+.Xr BN_nnmod 3
+using precomputed tables.
+They ignore their
+.Fa m
+argument and use the following moduli instead:
+.Pp
+.Bl -tag -width BN_nist_mod_521() -offset indent -compact
+.It Fn BN_nist_mod_192
+.Xr BN_get0_nist_prime_192 3
+.It Fn BN_nist_mod_224
+.Xr BN_get0_nist_prime_224 3
+.It Fn BN_nist_mod_256
+.Xr BN_get0_nist_prime_256 3
+.It Fn BN_nist_mod_384
+.Xr BN_get0_nist_prime_384 3
+.It Fn BN_nist_mod_521
+.Xr BN_get0_nist_prime_521 3
+.El
+.Pp
+They reduce
+.Fa a
+modulo the respective prime number and place the non-negative remainder in
+.Fa r .
+.Pp
+These functions are designed to save time when performing multiplications
+in prime fields of these specific orders.
+Consequently, if
+.Fa a
+is negative or larger than the square of the modulus being used, they call
+.Xr BN_nnmod 3
+instead of attempting any optimization.
+.Sh RETURN VALUES
+These functions return 1 on success or 0 on error.
+.Sh SEE ALSO
+.Xr BN_get0_nist_prime_521 3 ,
+.Xr BN_nnmod 3 ,
+.Xr EC_GFp_nist_method 3
+.Sh STANDARDS
+.Rs
+.%T Digital Signature Standard (DSS)
+.%I National Institute of Standards and Technology
+.%R FIPS PUB 186-4
+.%U https://doi.org/10.6028/NIST.FIPS.186-4
+.%Q Information Technology Laboratory
+.%C Gaithersburg, Maryland
+.%D July 2013
+.%O Appendix D.1.2 Curves over Prime Fields
+.Re
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 8c799cf564..88f1a05f7e 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.237 2022/11/18 01:21:40 schwarze Exp $
+# $OpenBSD: Makefile,v 1.238 2022/11/21 22:04:04 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -79,6 +79,7 @@ MAN=	\
         BN_mod_mul_reciprocal.3 \
         BN_mod_sqrt.3 \
         BN_new.3 \
+        BN_nist_mod_521.3 \
         BN_num_bytes.3 \
         BN_rand.3 \
         BN_set_bit.3 \