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.

diff --git a/lib/libcrypto/man/EVP_PKEY_asn1_new.3 b/lib/libcrypto/man/EVP_PKEY_asn1_new.3
index aa6e016..82a109c 100644 (file)
--- 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 <levitte@openssl.org>
+.\" 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 Richard Levitte <levitte@openssl.org>
 .\" and Paul Yang <yang.yang@baishancloud.com>.
 .\" 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