From: schwarze <schwarze@openbsd.org>
Date: Sat, 9 Sep 2023 14:35:23 +0000 (+0000)
Subject: document EVP_PKEY_CTX_get_data(3) and EVP_PKEY_CTX_set_data(3)
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=4c9162e2246a4e225a421ffc272405595bad094b;p=openbsd

document EVP_PKEY_CTX_get_data(3) and EVP_PKEY_CTX_set_data(3)
---

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 <yang.yang@baishancloud.com>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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 <yang.yang@baishancloud.com>.
 .\" 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