From dc05e4a388389ad4ad019ebaff6e46cad27ba1d2 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 9 Sep 2023 14:31:38 +0000 Subject: [PATCH] Document EVP_PKEY_CTX_set0_keygen_info(3). While here, also add the missing RETURN VALUES entries for EVP_PKEY_gen_cb(3), EVP_PKEY_CTX_get_cb(3), and EVP_PKEY_CTX_get_keygen_info(3). --- lib/libcrypto/man/EVP_PKEY_keygen.3 | 69 ++++++++++++++++++++++++----- 1 file changed, 59 insertions(+), 10 deletions(-) diff --git a/lib/libcrypto/man/EVP_PKEY_keygen.3 b/lib/libcrypto/man/EVP_PKEY_keygen.3 index aae994541fb..7641dba5a2e 100644 --- a/lib/libcrypto/man/EVP_PKEY_keygen.3 +++ b/lib/libcrypto/man/EVP_PKEY_keygen.3 @@ -1,8 +1,24 @@ -.\" $OpenBSD: EVP_PKEY_keygen.3,v 1.11 2023/04/25 16:50:33 tb Exp $ -.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 -.\" selective merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 +.\" $OpenBSD: EVP_PKEY_keygen.3,v 1.12 2023/09/09 14:31:38 schwarze Exp $ +.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 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 Dr. Stephen Henson . .\" Copyright (c) 2006, 2009, 2013, 2015, 2016, 2018 The OpenSSL Project. .\" All rights reserved. .\" @@ -50,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: April 25 2023 $ +.Dd $Mdocdate: September 9 2023 $ .Dt EVP_PKEY_KEYGEN 3 .Os .Sh NAME @@ -61,6 +77,7 @@ .Nm EVP_PKEY_gen_cb , .Nm EVP_PKEY_CTX_set_cb , .Nm EVP_PKEY_CTX_get_cb , +.Nm EVP_PKEY_CTX_set0_keygen_info , .Nm EVP_PKEY_CTX_get_keygen_info , .Nm EVP_PKEY_CTX_set_app_data , .Nm EVP_PKEY_CTX_get_app_data @@ -98,6 +115,12 @@ .Fo EVP_PKEY_CTX_get_cb .Fa "EVP_PKEY_CTX *ctx" .Fc +.Ft void +.Fo EVP_PKEY_CTX_set0_keygen_info +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int *dat" +.Fa "int datlen" +.Fc .Ft int .Fo EVP_PKEY_CTX_get_keygen_info .Fa "EVP_PKEY_CTX *ctx" @@ -131,13 +154,22 @@ and .Fn EVP_PKEY_paramgen are similar except parameters are generated. .Pp -The function +The functions .Fn EVP_PKEY_CTX_set_cb -sets the key or parameter generation callback to -.Fa cb . -The function +and .Fn EVP_PKEY_CTX_get_cb -returns the key or parameter generation callback. +set and retrieve the key or parameter generation callback, respectively. +.Pp +The function +.Fn EVP_PKEY_CTX_set0_keygen_info +sets the parameters associated with the generation operation to the array +.Fa dat +containing +.Ft datlen +integer parameters. +The caller retains ownership of the +.Fa dat +array; it will never be freed by the library. .Pp The function .Fn EVP_PKEY_CTX_get_keygen_info @@ -209,6 +241,23 @@ and return 1 for success and 0 or a negative value for failure. In particular, a return value of -2 indicates the operation is not supported by the public key algorithm. +.Pp +Callback functions of the type +.Fn EVP_PKEY_gen_cb +are supposed to return 1 on success or 0 on error. +.Pp +.Fn EVP_PKEY_CTX_get_cb +returns a function pointer to the currently installed callback function or +.Dv NULL +if no callback function is installed. +.Pp +.Fn EVP_PKEY_CTX_get_keygen_info +retuns the number of available parameters if +.Fa idx +is \-1, one of these parameters if +.Fa idx +is greater than or equal to zero but less than the number +of available parameters, or 0 otherwise. .Sh EXAMPLES Generate a 2048-bit RSA key: .Bd -literal -offset indent -- 2.20.1