From 181e2e3812899f324e70a5ac90cbbde921abecaa Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 21 Nov 2022 22:04:04 +0000 Subject: [PATCH] document BN_nist_mod_521(3) and their four siblings --- lib/libcrypto/man/BN_new.3 | 5 +- lib/libcrypto/man/BN_nist_mod_521.3 | 113 ++++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- 3 files changed, 118 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/BN_nist_mod_521.3 diff --git a/lib/libcrypto/man/BN_new.3 b/lib/libcrypto/man/BN_new.3 index 1913b75ec5a..7e3432770ff 100644 --- a/lib/libcrypto/man/BN_new.3 +++ b/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/lib/libcrypto/man/BN_nist_mod_521.3 b/lib/libcrypto/man/BN_nist_mod_521.3 new file mode 100644 index 00000000000..72dd4a71248 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 8c799cf5649..88f1a05f7e2 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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 \ -- 2.20.1