new manual page EVP_PKEY_CTX_get_operation(3),

also documenting EVP_PKEY_CTX_get0_pkey(3)

4 files changed, 127 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_get_operation.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_get_operation.3
new file mode 100644
index 0000000000..b6e7275b5a
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_PKEY_CTX_get_operation.3
@@ -0,0 +1,118 @@
+.\" $OpenBSD: EVP_PKEY_CTX_get_operation.3,v 1.1 2023/09/09 14:39:09 schwarze Exp $
+.\"
+.\" 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.
+.\"
+.Dd $Mdocdate: September 9 2023 $
+.Dt EVP_PKEY_CTX_GET_OPERATION 3
+.Os
+.Sh NAME
+.Nm EVP_PKEY_CTX_get_operation ,
+.Nm EVP_PKEY_CTX_get0_pkey
+.Nd inspect EVP_PKEY_CTX objects
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft int
+.Fo EVP_PKEY_CTX_get_operation
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Ft EVP_PKEY *
+.Fo EVP_PKEY_CTX_get0_pkey
+.Fa "EVP_PKEY_CTX *ctx"
+.Fc
+.Sh DESCRIPTION
+.Fn EVP_PKEY_CTX_get_operation
+finds out which initialization function has been called on
+.Fa ctx ,
+if any:
+.Bl -column EVP_PKEY_OP_VERIFYRECO EVP_PKEY_verify_recover_init
+.It return value             Ta initialized with            Ta e.g. for
+.It Dv EVP_PKEY_OP_DECRYPT   Ta Xr EVP_PKEY_decrypt_init  3 Ta RSA, SM2
+.It Dv EVP_PKEY_OP_DERIVE    Ta Xr EVP_PKEY_derive_init   3 Ta HKDF
+.It Dv EVP_PKEY_OP_ENCRYPT   Ta Xr EVP_PKEY_encrypt_init  3 Ta RSA, SM2
+.It Dv EVP_PKEY_OP_KEYGEN    Ta Xr EVP_PKEY_keygen_init   3 Ta almost all
+.It Dv EVP_PKEY_OP_PARAMGEN  Ta Xr EVP_PKEY_paramgen_init 3 Ta DH, DSA, EC
+.It Dv EVP_PKEY_OP_SIGN      Ta Xr EVP_PKEY_sign_init     3 Ta DSA,EC,RSA,SM2
+.It Dv EVP_PKEY_OP_SIGN      Ta Xr EVP_DigestSignInit     3 Ta ED25519
+.It Dv EVP_PKEY_OP_SIGNCTX   Ta Xr EVP_DigestSignInit     3 Ta CMAC, HMAC
+.It Dv EVP_PKEY_OP_UNDEFINED Ta not initialized             Ta NONE
+.It Dv EVP_PKEY_OP_VERIFY    Ta Xr EVP_PKEY_verify_init   3 Ta DSA,EC,RSA,SM2
+.It Dv EVP_PKEY_OP_VERIFY    Ta Xr EVP_DigestVerifyInit   3 Ta ED25519
+.It Dv EVP_PKEY_OP_VERIFYCTX Ta Xr EVP_DigestVerifyInit   3 Ta no built-in
+.It Dv EVP_PKEY_OP_VERIFYRECOVER Ta Xr EVP_PKEY_verify_recover_init 3 Ta RSA
+.El
+.Pp
+The rightmost column of the above table shows examples of algoritms
+the return values can occur for.
+For example, if
+.Xr EVP_PKEY_base_id 3
+returns
+.Dv EVP_PKEY_HKDF ,
+then calling
+.Fn EVP_PKEY_CTX_get_operation
+on a
+.Vt EVP_PKEY_CTX
+using that key may return
+.Dv EVP_PKEY_OP_DERIVE .
+.Pp
+If the return value is
+.Dv EVP_PKEY_OP_SIGNCTX
+or
+.Dv EVP_PKEY_OP_VERIFYCTX ,
+the
+.Fa ctx
+supports
+.Xr EVP_DigestSignUpdate 3
+or
+.Xr EVP_DigestVerifyUpdate 3 ,
+respectively.
+If the return value is
+.Dv EVP_PKEY_OP_SIGN
+or
+.Dv EVP_PKEY_OP_VERIFY ,
+if does not, and only one-shot signing or verification is supported.
+.Pp
+The return value
+.Dv EVP_PKEY_OP_UNDEFINED
+can for example occur if the
+.Fa ctx
+was freshly returned from
+.Xr EVP_PKEY_CTX_new 3
+or
+.Xr EVP_PKEY_CTX_new_id 3
+and not yet initialized.
+.Sh RETURN VALUES
+.Fn EVP_PKEY_CTX_get_operation
+returns one of the
+.Dv EVP_PKEY_OP_*
+constants.
+.Pp
+.Fn EVP_PKEY_CTX_get0_pkey
+returns an internal pointer to the
+.Vt EVP_PKEY
+object used by
+.Fa ctx ,
+without incrementing its reference count.
+.Sh SEE ALSO
+.Xr evp 3 ,
+.Xr EVP_PKEY_base_id 3 ,
+.Xr EVP_PKEY_CTX_ctrl 3 ,
+.Xr EVP_PKEY_CTX_new 3 ,
+.Xr EVP_PKEY_new 3
+.Sh HISTORY
+.Fn EVP_PKEY_CTX_get_operation
+and
+.Fn EVP_PKEY_CTX_get0_pkey
+first appeared in OpenSSL 1.0.0 and have been available since
+.Ox 4.9 .
diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3
index 229f552246..7a72ac18fa 100644
--- a/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3
+++ b/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_CTX_new.3,v 1.12 2022/07/13 21:51:35 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_CTX_new.3,v 1.13 2023/09/09 14:39:09 schwarze Exp $
 .\" full merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
 .\" This file is a derived work.
@@ -65,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_CTX_NEW 3
 .Os
 .Sh NAME
@@ -159,6 +159,8 @@ if an error occurred.
 .Xr EVP_PKEY_base_id 3 ,
 .Xr EVP_PKEY_check 3 ,
 .Xr EVP_PKEY_CTX_ctrl 3 ,
+.Xr EVP_PKEY_CTX_get_operation 3 ,
+.Xr EVP_PKEY_CTX_hkdf_mode 3 ,
 .Xr EVP_PKEY_decrypt 3 ,
 .Xr EVP_PKEY_derive 3 ,
 .Xr EVP_PKEY_encrypt 3 ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index c7a79fa7b6..ec8d3fe191 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.267 2023/09/07 14:22:11 schwarze Exp $
+# $OpenBSD: Makefile,v 1.268 2023/09/09 14:39:09 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -181,6 +181,7 @@ MAN=	\
         EVP_OpenInit.3 \
         EVP_PKCS82PKEY.3 \
         EVP_PKEY_CTX_ctrl.3 \
+        EVP_PKEY_CTX_get_operation.3 \
         EVP_PKEY_CTX_new.3 \
         EVP_PKEY_CTX_set_hkdf_md.3 \
         EVP_PKEY_add1_attr.3 \
diff --git a/src/lib/libcrypto/man/evp.3 b/src/lib/libcrypto/man/evp.3
index 2f2d07c7a7..b29f76480f 100644
--- a/src/lib/libcrypto/man/evp.3
+++ b/src/lib/libcrypto/man/evp.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: evp.3,v 1.23 2023/09/07 14:22:11 schwarze Exp $
+.\" $OpenBSD: evp.3,v 1.24 2023/09/09 14:39:09 schwarze Exp $
 .\" full merge up to: OpenSSL man7/evp 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>,
@@ -51,7 +51,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 7 2023 $
+.Dd $Mdocdate: September 9 2023 $
 .Dt EVP 3
 .Os
 .Sh NAME
@@ -222,6 +222,7 @@ operations are more efficient using the high-level interfaces.
 .Xr EVP_PKEY_check 3 ,
 .Xr EVP_PKEY_cmp 3 ,
 .Xr EVP_PKEY_CTX_ctrl 3 ,
+.Xr EVP_PKEY_CTX_get_operation 3 ,
 .Xr EVP_PKEY_CTX_new 3 ,
 .Xr EVP_PKEY_CTX_set_hkdf_md 3 ,
 .Xr EVP_PKEY_decrypt 3 ,