From: schwarze <schwarze@openbsd.org>
Date: Wed, 13 Sep 2023 13:55:50 +0000 (+0000)
Subject: document the EVP_PKEY_ASN1_METHOD flags
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=be0ef251eed1e6835e6d4dba8d5439b1ecb55123;p=openbsd

document the EVP_PKEY_ASN1_METHOD flags
ASN1_PKEY_ALIAS, ASN1_PKEY_DYNAMIC, and ASN1_PKEY_SIGPARAM_NULL
---

diff --git a/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3 b/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3
index d5bc0ea8ea5..9f272a24268 100644
--- a/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3
+++ b/lib/libcrypto/man/EVP_PKEY_asn1_get_count.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_asn1_get_count.3,v 1.6 2023/08/27 13:23:12 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_asn1_get_count.3,v 1.7 2023/09/13 13:55:50 schwarze Exp $
 .\" full merge up to: OpenSSL 72a7a702 Feb 26 14:05:09 2019 +0000
 .\"
 .\" 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: August 27 2023 $
+.Dd $Mdocdate: September 13 2023 $
 .Dt EVP_PKEY_ASN1_GET_COUNT 3
 .Os
 .Sh NAME
@@ -169,9 +169,55 @@ retrieves the public key ID as returned by
 the base public key ID as returned by
 .Xr EVP_PKEY_base_id 3
 .Pq both NIDs ,
-any flags, the method description,
-and the PEM type string associated with
-.Fa ameth .
+any flags, and internal pointers owned by
+.Fa ameth
+pointing to its method description string and its PEM type string.
+.Pp
+The following flags bits can occur, OR'ed together in
+.Pf * Fa ppkey_flags :
+.Bl -tag -width Ds
+.It Dv ASN1_PKEY_ALIAS
+This
+.Fa ameth
+object serves as an alias for another
+.Vt EVP_PKEY_ASN1_METHOD
+object and will never be returned from
+.Fn EVP_PKEY_asn1_find
+or
+.Fn EVP_PKEY_asn1_find_str .
+It is either an alias built into the library, or it was created with
+.Xr EVP_PKEY_asn1_add_alias 3 .
+.It Dv ASN1_PKEY_DYNAMIC
+This
+.Fa ameth
+object is marked as dynamically allocated.
+If this flag is set,
+.Xr EVP_PKEY_asn1_free 3
+can free
+.Fa ameth ;
+otherwise,
+.Xr EVP_PKEY_asn1_free 3
+has no effect on it.
+.It Dv ASN1_PKEY_SIGPARAM_NULL
+If the signing
+.Fa ctx
+uses an
+.Vt EVP_PKEY
+private key associated with this
+.Fa ameth ,
+instruct
+.Xr ASN1_item_sign_ctx 3
+to use a parameter type of
+.Dv V_ASN1_NULL
+instead of the default
+.Dv V_ASN1_UNDEF
+when encoding the ASN.1
+.Vt AlgorithmIdentifier
+objects with
+.Xr X509_ALGOR_set0 3 .
+In particular, this is used for
+.Dv EVP_PKEY_RSA .
+.El
 .Pp
 .Fn EVP_PKEY_asn1_get_count ,
 .Fn EVP_PKEY_asn1_get0 ,