From 17c708b1c97937aa29f92ecc6df4e37c96d7835a Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 14 Nov 2022 18:28:29 +0000 Subject: [PATCH] document BN_reciprocal(3) --- lib/libcrypto/man/BN_mod_mul_reciprocal.3 | 65 +++++++++++++++++++---- 1 file changed, 55 insertions(+), 10 deletions(-) diff --git a/lib/libcrypto/man/BN_mod_mul_reciprocal.3 b/lib/libcrypto/man/BN_mod_mul_reciprocal.3 index 77c2932739f..f28ade2a41b 100644 --- a/lib/libcrypto/man/BN_mod_mul_reciprocal.3 +++ b/lib/libcrypto/man/BN_mod_mul_reciprocal.3 @@ -1,7 +1,25 @@ -.\" $OpenBSD: BN_mod_mul_reciprocal.3,v 1.11 2021/11/30 18:34:35 tb Exp $ -.\" OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000 +.\" $OpenBSD: BN_mod_mul_reciprocal.3,v 1.12 2022/11/14 18:28:29 schwarze Exp $ +.\" full merge up to: OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000 +.\" selective merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 .\" -.\" This file was written by Ulf Moeller . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" 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. +.\" +.\" The original file was written by Ulf Moeller . .\" Copyright (c) 2000 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,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: November 30 2021 $ +.Dd $Mdocdate: November 14 2022 $ .Dt BN_MOD_MUL_RECIPROCAL 3 .Os .Sh NAME @@ -57,7 +75,8 @@ .Nm BN_RECP_CTX_init , .Nm BN_RECP_CTX_free , .Nm BN_RECP_CTX_set , -.Nm BN_div_recp +.Nm BN_div_recp , +.Nm BN_reciprocal .Nd modular multiplication using reciprocal .Sh SYNOPSIS .In openssl/bn.h @@ -95,6 +114,13 @@ .Fa "BN_RECP_CTX *recp" .Fa "BN_CTX *ctx" .Fc +.Ft int +.Fo BN_reciprocal +.Fa "BIGNUM *r" +.Fa "const BIGNUM *m" +.Fa "int len" +.Fa "BN_CTX *ctx" +.Fc .Sh DESCRIPTION .Fn BN_mod_mul_reciprocal can be used to perform an efficient @@ -160,6 +186,15 @@ It places the quotient in and the remainder in .Fa rem . .Pp +.Fn BN_reciprocal +divides the +.Fa len Ap th +power of two by +.Fa m +and places the quotient in +.Fa r , +rounding it towards zero to the closest integer. +.Pp The .Vt BN_RECP_CTX structure is defined as follows: @@ -182,7 +217,17 @@ or .Dv NULL on error. .Pp -For the other functions, 1 is returned for success or 0 on error. +.Fn BN_mod_mul_reciprocal , +.Fn BN_RECP_CTX_set , +and +.Fn BN_div_recp +return 1 for success or 0 on error. +.Pp +.Fn BN_reciprocal +returns +.Fa len +for success or \-1 on error. +.Pp The error codes can be obtained by .Xr ERR_get_error 3 . .Sh SEE ALSO @@ -191,14 +236,14 @@ The error codes can be obtained by .Xr BN_new 3 .Sh HISTORY .Fn BN_mod_mul_reciprocal -first appeared in SSLeay 0.5.1 and has been available since +and +.Fn BN_reciprocal +first appeared in SSLeay 0.5.1 and have been available since .Ox 2.4 . .Pp .Vt BN_RECP_CTX was added in SSLeay 0.9.0. -Before that, a function -.Fn BN_reciprocal -was used instead, and the +Before that, the .Fn BN_mod_mul_reciprocal arguments were different. .Pp -- 2.20.1