From dcc61ddd189d354a2d2c43ffd6b6778884ca08cd Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 13 Sep 2023 14:18:21 +0000 Subject: [PATCH] Various improvements: * Document the ASN1_PKEY_CTRL_DEFAULT_MD_NID control operation. * Mention that EVP_PKEY_asn1_new(3) sets ASN1_PKEY_DYNAMIC. * Fix the description of EVP_PKEY_asn1_copy(3), which was totally wrong. * Warn about the crazy ASN1_PKEY_DYNAMIC handling in EVP_PKEY_asn1_free(3). * Be more precise about EVP_PKEY_asn1_new(3) RETURN VALUES. --- lib/libcrypto/man/EVP_PKEY_asn1_new.3 | 78 +++++++++++++++++++++------ 1 file changed, 63 insertions(+), 15 deletions(-) diff --git a/lib/libcrypto/man/EVP_PKEY_asn1_new.3 b/lib/libcrypto/man/EVP_PKEY_asn1_new.3 index aa6e016dfdf..82a109c57d1 100644 --- a/lib/libcrypto/man/EVP_PKEY_asn1_new.3 +++ b/lib/libcrypto/man/EVP_PKEY_asn1_new.3 @@ -1,8 +1,25 @@ -.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.9 2023/08/27 13:15:29 schwarze Exp $ +.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.10 2023/09/13 14:18:21 schwarze Exp $ .\" selective merge up to: .\" OpenSSL man3/EVP_PKEY_ASN1_METHOD b0004708 Nov 1 00:45:24 2017 +0800 .\" -.\" This file was written by Richard Levitte +.\" 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 Richard Levitte .\" and Paul Yang . .\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. .\" @@ -50,7 +67,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 27 2023 $ +.Dd $Mdocdate: September 13 2023 $ .Dt EVP_PKEY_ASN1_NEW 3 .Os .Sh NAME @@ -345,11 +362,34 @@ and .Ed .Pp Add extra algorithm specific control. -This method is called by -.Xr EVP_PKEY_get_default_digest_nid 3 , +.Pp +If the +.Fa op +argument is +.Dv ASN1_PKEY_CTRL_DEFAULT_MD_NID , +the +.Fa pkey_ctrl +method is supposed to write the message digest NID +for public key signature operations with the given +.Fa pkey +to +.Pf * Fa arg2 +as documented in the +.Xr EVP_PKEY_get_default_digest_nid 3 +manual page. +.Pp +The +.Fa pkey_ctrl +method is also called by .Fn PKCS7_SIGNER_INFO_set , .Fn PKCS7_RECIP_INFO_set , and other functions. +.\" TODO: +.\" ASN1_PKEY_CTRL_CMS_ENVELOPE in cms_env.c rsa_ameth.c +.\" ASN1_PKEY_CTRL_CMS_RI_TYPE in cms_env.c dsa_ameth.c ec_ameth.c rsa_ameth.c +.\" ASN1_PKEY_CTRL_CMS_SIGN in cms_sd.c dsa_ameth.c ec_ameth.c rsa_ameth.c +.\" ASN1_PKEY_CTRL_PKCS7_ENCRYPT in pk7_lib.c rsa_ameth.c +.\" ASN1_PKEY_CTRL_PKCS7_SIGN in pk7_lib.c dsa_ameth.c ec_ameth.c rsa_ameth.c .Bd -unfilled .Ft int Fn (*pkey_check) "const EVP_PKEY *pk" .Ft int Fn (*pkey_public_check) "const EVP_PKEY *pk" @@ -378,7 +418,7 @@ It is called by .Fn EVP_PKEY_asn1_new creates and returns a new .Vt EVP_PKEY_ASN1_METHOD -object, and associates the given +object, marks it as dynamically allocated, and associates the given .Fa id , .Fa flags , .Fa pem_str @@ -404,20 +444,28 @@ See for more information. .Pp .Fn EVP_PKEY_asn1_copy -copies an -.Vt EVP_PKEY_ASN1_METHOD -object from +copies all function pointers from .Fa src to .Fa dst . +The data in +.Fa dst +that can be set with +.Fn EVP_PKEY_asn1_new +\(em NIDs, flags, and strings \(em +remains unchanged. This function is not thread safe, it is recommended to only use this when initializing the application. .Pp .Fn EVP_PKEY_asn1_free -frees an existing -.Vt EVP_PKEY_ASN1_METHOD -pointed by -.Fa ameth . +frees the dynamically allocated +.Fa ameth +including all memory it refers to. +If +.Fa ameth +is +.Dv NULL +of not marked as dynamically allocated, no action occurs. .Pp .Fn EVP_PKEY_asn1_add0 adds @@ -456,11 +504,11 @@ set the diverse methods of the given object. .Sh RETURN VALUES .Fn EVP_PKEY_asn1_new -returns a pointer to an +returns a pointer to the new .Vt EVP_PKEY_ASN1_METHOD object or .Dv NULL -on error. +if memory allocation fails. .Pp .Fn EVP_PKEY_asn1_add0 and -- 2.20.1