From 3f96b687f7d27a32f37f7c6b4fdee45dae685b38 Mon Sep 17 00:00:00 2001
From: Matt Caswell <matt@openssl.org>
Date: Mon, 14 Sep 2020 16:30:50 +0100
Subject: [PATCH] Document 2 newly added functions

Adds documentation for EVP_PKEY_get0_first_alg_name() and
EVP_KEYMGMT_get0_first_name().

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/12850)
---
 doc/man3/EVP_KEYMGMT.pod   | 11 +++++++++++
 doc/man3/EVP_PKEY_is_a.pod | 16 +++++++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/doc/man3/EVP_KEYMGMT.pod b/doc/man3/EVP_KEYMGMT.pod
index 8e7afc6a22..d06b9ba369 100644
--- a/doc/man3/EVP_KEYMGMT.pod
+++ b/doc/man3/EVP_KEYMGMT.pod
@@ -9,6 +9,7 @@ EVP_KEYMGMT_free,
 EVP_KEYMGMT_provider,
 EVP_KEYMGMT_is_a,
 EVP_KEYMGMT_number,
+EVP_KEYMGMT_get0_first_name,
 EVP_KEYMGMT_do_all_provided,
 EVP_KEYMGMT_names_do_all,
 EVP_KEYMGMT_gettable_params,
@@ -29,6 +30,8 @@ EVP_KEYMGMT_gen_settable_params
  const OSSL_PROVIDER *EVP_KEYMGMT_provider(const EVP_KEYMGMT *keymgmt);
  int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
  int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt);
+ const char *EVP_KEYMGMT_get0_first_name(const EVP_KEYMGMT *keymgmt);
+
  void EVP_KEYMGMT_do_all_provided(OPENSSL_CTX *libctx,
                                   void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
                                   void *arg);
@@ -69,6 +72,12 @@ algorithm that's identifiable with I<name>.
 EVP_KEYMGMT_number() returns the internal dynamic number assigned to
 the I<keymgmt>.
 
+EVP_KEYMGMT_get0_first_name() returns the first algorithm name that is found for
+the given I<keymgmt>. Note that the I<keymgmt> may have multiple synonyms
+associated with it. In this case it is undefined which one will be returned.
+Ownership of the returned string is retained by the I<keymgmt> object and should
+not be freed by the caller.
+
 EVP_KEYMGMT_names_do_all() traverses all names for the I<keymgmt>, and
 calls I<fn> with each name and I<data>.
 
@@ -111,6 +120,8 @@ otherwise 0.
 
 EVP_KEYMGMT_number() returns an integer.
 
+EVP_KEYMGMT_get0_first_name() returns the name that is found or NULL on error.
+
 EVP_KEYMGMT_gettable_params(), EVP_KEYMGMT_settable_params() and
 EVP_KEYMGMT_gen_settable_params() return a constant B<OSSL_PARAM> array or
 NULL on error.
diff --git a/doc/man3/EVP_PKEY_is_a.pod b/doc/man3/EVP_PKEY_is_a.pod
index cfce3de5da..efc72ea110 100644
--- a/doc/man3/EVP_PKEY_is_a.pod
+++ b/doc/man3/EVP_PKEY_is_a.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-EVP_PKEY_is_a, EVP_PKEY_can_sign
+EVP_PKEY_is_a, EVP_PKEY_can_sign, EVP_PKEY_get0_first_alg_name
 - key type and capabilities functions
 
 =head1 SYNOPSIS
@@ -11,6 +11,8 @@ EVP_PKEY_is_a, EVP_PKEY_can_sign
 
  int EVP_PKEY_is_a(const EVP_PKEY *pkey, const char *name);
  int EVP_PKEY_can_sign(const EVP_PKEY *pkey);
+ const char *EVP_PKEY_get0_first_alg_name(const EVP_PKEY *key);
+
 
 =head1 DESCRIPTION
 
@@ -20,6 +22,12 @@ EVP_PKEY_can_sign() checks if the functionality for the key type of
 I<pkey> supports signing.  No other check is done, such as whether
 I<pkey> contains a private key.
 
+EVP_PKEY_get0_first_alg_name() returns the first algorithm name that is found
+for the given I<pkey>. Note that the I<pkey> may have multiple synonyms
+associated with it. In this case it is undefined which one will be returned.
+Ownership of the returned string is retained by the I<pkey> object and should
+not be freed by the caller.
+
 =head1 RETURN VALUES
 
 EVP_PKEY_is_a() returns 1 if I<pkey> has the key type I<name>,
@@ -28,6 +36,8 @@ otherwise 0.
 EVP_PKEY_can_sign() returns 1 if the I<pkey> key type functionality
 supports signing, otherwise 0.
 
+EVP_PKEY_get0_first_alg_name() returns the name that is found or NULL on error.
+
 =head1 EXAMPLES
 
 =head2 EVP_PKEY_is_a()
@@ -60,6 +70,10 @@ this as an crude example:
      }
      /* Sign something... */
 
+=head1 HISTORY
+
+The functions described here were added in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.