From 4c9162e2246a4e225a421ffc272405595bad094b Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 9 Sep 2023 14:35:23 +0000 Subject: [PATCH] document EVP_PKEY_CTX_get_data(3) and EVP_PKEY_CTX_set_data(3) --- lib/libcrypto/man/EVP_PKEY_meth_new.3 | 64 ++++++++++++++++++++++++--- 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/lib/libcrypto/man/EVP_PKEY_meth_new.3 b/lib/libcrypto/man/EVP_PKEY_meth_new.3 index 3d9d1ba5be4..5ec0b12105c 100644 --- a/lib/libcrypto/man/EVP_PKEY_meth_new.3 +++ b/lib/libcrypto/man/EVP_PKEY_meth_new.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: EVP_PKEY_meth_new.3,v 1.5 2022/07/13 19:10:40 schwarze Exp $ -.\" selective merge up to: OpenSSL 335a587b May 7 11:59:11 2019 +0200 +.\" $OpenBSD: EVP_PKEY_meth_new.3,v 1.6 2023/09/09 14:35:23 schwarze Exp $ +.\" selective merge up to: OpenSSL 35fd9953 May 28 14:49:38 2019 +0200 .\" -.\" This file was written by Paul Yang +.\" 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 Paul Yang . .\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,7 +65,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: July 13 2022 $ +.Dd $Mdocdate: September 9 2023 $ .Dt EVP_PKEY_METH_NEW 3 .Os .Sh NAME @@ -73,7 +90,9 @@ .Nm EVP_PKEY_meth_set_ctrl , .Nm EVP_PKEY_meth_set_check , .Nm EVP_PKEY_meth_set_public_check , -.Nm EVP_PKEY_meth_set_param_check +.Nm EVP_PKEY_meth_set_param_check , +.Nm EVP_PKEY_CTX_get_data , +.Nm EVP_PKEY_CTX_set_data .Nd manipulate an EVP_PKEY_METHOD structure .Sh SYNOPSIS .In openssl/evp.h @@ -202,6 +221,15 @@ .Fa "EVP_PKEY_METHOD *pmeth" .Fa "int (*param_check)(EVP_PKEY *pkey)" .Fc +.Ft void * +.Fo EVP_PKEY_CTX_get_data +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set_data +.Fa "EVP_PKEY_CTX *ctx" +.Fa "void *data" +.Fc .Sh DESCRIPTION The .Vt EVP_PKEY_METHOD @@ -539,6 +567,24 @@ The functions set the corresponding fields of .Fa pmeth to the arguments passed. +.Pp +.Fn EVP_PKEY_CTX_get_data +retrieves algorithm- and implementation-specific private key data from +.Fa ctx . +Public key algorithm implementations typically allocate and initialize +this data automatically in their +.Fn init +function. +.Pp +.Fn EVP_PKEY_CTX_set_data +transfers ownership of the given +.Fa data +to +.Fa ctx , +replacing the existing algorithm- and implementation-specific +private key data. +It is the responsibility of the caller to free the existing data +before calling this function. .Sh RETURN VALUES .Fn EVP_PKEY_meth_new returns a pointer to a new @@ -556,6 +602,10 @@ if no matching object is found. .Pp .Fn EVP_PKEY_meth_add0 returns 1 if the method is added successfully or 0 if an error occurred. +.Pp +.Fn EVP_PKEY_CTX_get_data +returns an internal pointer owned by +.Fa ctx . .Sh SEE ALSO .Xr EVP_DigestInit 3 , .Xr EVP_PKEY_meth_get0_info 3 , @@ -578,8 +628,10 @@ returns 1 if the method is added successfully or 0 if an error occurred. .Fn EVP_PKEY_meth_set_encrypt , .Fn EVP_PKEY_meth_set_decrypt , .Fn EVP_PKEY_meth_set_derive , +.Fn EVP_PKEY_meth_set_ctrl , +.Fn EVP_PKEY_CTX_get_data , and -.Fn EVP_PKEY_meth_set_ctrl +.Fn EVP_PKEY_CTX_set_data first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . .Pp -- 2.20.1