From: schwarze <schwarze@openbsd.org>
Date: Mon, 20 Dec 2021 15:02:13 +0000 (+0000)
Subject: document BN_mod_add_quick(3), BN_mod_sub_quick(3), BN_mod_lshift(3),
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=77ae073a6877a13755242b2d539d1fd26e8e04c3;p=openbsd

document BN_mod_add_quick(3), BN_mod_sub_quick(3), BN_mod_lshift(3),
BN_mod_lshift_quick(3), BN_mod_lshift1(3), and BN_mod_lshift1_quick(3)
---

diff --git a/lib/libcrypto/man/BN_add.3 b/lib/libcrypto/man/BN_add.3
index e2f1642aa75..ab2d3433218 100644
--- a/lib/libcrypto/man/BN_add.3
+++ b/lib/libcrypto/man/BN_add.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BN_add.3,v 1.15 2021/12/19 18:39:32 schwarze Exp $
+.\" $OpenBSD: BN_add.3,v 1.16 2021/12/20 15:02:13 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 19 2021 $
+.Dd $Mdocdate: December 20 2021 $
 .Dt BN_ADD 3
 .Os
 .Sh NAME
@@ -80,9 +80,15 @@
 .Nm BN_mod ,
 .Nm BN_nnmod ,
 .Nm BN_mod_add ,
+.Nm BN_mod_add_quick ,
 .Nm BN_mod_sub ,
+.Nm BN_mod_sub_quick ,
 .Nm BN_mod_mul ,
 .Nm BN_mod_sqr ,
+.Nm BN_mod_lshift ,
+.Nm BN_mod_lshift_quick ,
+.Nm BN_mod_lshift1 ,
+.Nm BN_mod_lshift1_quick ,
 .Nm BN_exp ,
 .Nm BN_mod_exp ,
 .\" The following are public, but intentionally undocumented for now:
@@ -164,6 +170,13 @@
 .Fa "BN_CTX *ctx"
 .Fc
 .Ft int
+.Fo BN_mod_add_quick
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *b"
+.Fa "const BIGNUM *m"
+.Fc
+.Ft int
 .Fo BN_mod_sub
 .Fa "BIGNUM *r"
 .Fa "const BIGNUM *a"
@@ -172,6 +185,13 @@
 .Fa "BN_CTX *ctx"
 .Fc
 .Ft int
+.Fo BN_mod_sub_quick
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *b"
+.Fa "const BIGNUM *m"
+.Fc
+.Ft int
 .Fo BN_mod_mul
 .Fa "BIGNUM *r"
 .Fa "const BIGNUM *a"
@@ -187,6 +207,34 @@
 .Fa "BN_CTX *ctx"
 .Fc
 .Ft int
+.Fo BN_mod_lshift
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "int n"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_mod_lshift_quick
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "int n"
+.Fa "const BIGNUM *m"
+.Fc
+.Ft int
+.Fo BN_mod_lshift1
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fa "BN_CTX *ctx"
+.Fc
+.Ft int
+.Fo BN_mod_lshift1_quick
+.Fa "BIGNUM *r"
+.Fa "const BIGNUM *a"
+.Fa "const BIGNUM *m"
+.Fc
+.Ft int
 .Fo BN_exp
 .Fa "BIGNUM *r"
 .Fa "const BIGNUM *a"
@@ -368,6 +416,18 @@ modulo
 and places the non-negative result in
 .Fa r .
 .Pp
+.Fn BN_mod_add_quick
+is a variant of
+.Fn BN_mod_add
+that requires
+.Fa a
+and
+.Fa b
+to both be non-negative and smaller than
+.Fa m .
+If any of these constraints are violated,
+it silently produces wrong results.
+.Pp
 .Fn BN_mod_sub
 subtracts
 .Fa b
@@ -378,6 +438,18 @@ modulo
 and places the non-negative result in
 .Fa r .
 .Pp
+.Fn BN_mod_sub_quick
+is a variant of
+.Fn BN_mod_sub
+that requires
+.Fa a
+and
+.Fa b
+to both be non-negative and smaller than
+.Fa m .
+If any of these constraints are violated,
+it silently produces wrong results.
+.Pp
 .Fn BN_mod_mul
 multiplies
 .Fa a
@@ -407,6 +479,40 @@ modulo
 and places the result in
 .Fa r .
 .Pp
+.Fn BN_mod_lshift
+shifts
+.Fa a
+left by
+.Fa n
+bits, reduces the result modulo
+.Fa m ,
+and places the non-negative remainder in
+.Fa r
+.Pq Li r=a*2^n mod m .
+.Pp
+.Fn BN_mod_lshift1
+shifts
+.Fa a
+left by one bit, reduces the result modulo
+.Fa m ,
+and places the non-negative remainder in
+.Fa r
+.Pq Li r=a*2 mod m .
+.Pp
+.Fn BN_mod_lshift_quick
+and
+.Fn BN_mod_lshift1_quick
+are variants of
+.Fn BN_mod_lshift
+and
+.Fn BN_mod_lshift1 ,
+respectively, that require
+.Fa a
+to be non-negative and less than
+.Fa m .
+If either of these constraints is violated, they sometimes fail
+and sometimes silently produce wrong results.
+.Pp
 .Fn BN_exp
 raises
 .Fa a
@@ -502,9 +608,15 @@ first appeared in SSLeay 0.9.1 and have been available since
 .Pp
 .Fn BN_nnmod ,
 .Fn BN_mod_add ,
+.Fn BN_mod_add_quick ,
 .Fn BN_mod_sub ,
+.Fn BN_mod_sub_quick ,
+.Fn BN_mod_sqr ,
+.Fn BN_mod_lshift ,
+.Fn BN_mod_lshift_quick ,
+.Fn BN_mod_lshift1 ,
 and
-.Fn BN_mod_sqr
+.Fn BN_mod_lshift1_quick
 first appeared in OpenSSL 0.9.7 and have been available since
 .Ox 3.2 .
 .Sh BUGS