From 027215cf0916a4a23f00c35286ea0487e53a5981 Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 9 Sep 2023 14:39:09 +0000 Subject: [PATCH] new manual page EVP_PKEY_CTX_get_operation(3), also documenting EVP_PKEY_CTX_get0_pkey(3) --- .../man/EVP_PKEY_CTX_get_operation.3 | 118 ++++++++++++++++++ lib/libcrypto/man/EVP_PKEY_CTX_new.3 | 6 +- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/evp.3 | 5 +- 4 files changed, 127 insertions(+), 5 deletions(-) create mode 100644 lib/libcrypto/man/EVP_PKEY_CTX_get_operation.3 diff --git a/lib/libcrypto/man/EVP_PKEY_CTX_get_operation.3 b/lib/libcrypto/man/EVP_PKEY_CTX_get_operation.3 new file mode 100644 index 00000000000..b6e7275b5a4 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/EVP_PKEY_CTX_new.3 b/lib/libcrypto/man/EVP_PKEY_CTX_new.3 index 229f5522465..7a72ac18fac 100644 --- a/lib/libcrypto/man/EVP_PKEY_CTX_new.3 +++ b/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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index c7a79fa7b6f..ec8d3fe191f 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/evp.3 b/lib/libcrypto/man/evp.3 index 2f2d07c7a7e..b29f76480fe 100644 --- a/lib/libcrypto/man/evp.3 +++ b/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 , @@ -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 , -- 2.20.1