EVP: Add EVP_<TYPE>_description()

The following operation types are covered:

EVP_MD, EVP_CIPHER, EVP_MAC, EVP_RAND, EVP_KEYMGMT, EVP_SIGNATURE,
EVP_ASYM_CIPHER, EVP_KEM, EVP_KEYEXCH, EVP_KDF.  Also EVP_PKEY.

For EVP_MD and EVP_CIPHER, OBJ_nid2ln() is used as a fallback for
legacy implementations.

For EVP_PKEY, the info field of the EVP_PKEY_ASN1_METHOD is used as a
fallback for legacy implementations.

Fixes #14514

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14656)

11 files changed, 76 insertions, 9 deletions

diff --git a/doc/man3/EVP_ASYM_CIPHER_free.pod b/doc/man3/EVP_ASYM_CIPHER_free.pod
index 6558d0c0c4..2500109e45 100644
--- a/doc/man3/EVP_ASYM_CIPHER_free.pod
+++ b/doc/man3/EVP_ASYM_CIPHER_free.pod
@@ -5,6 +5,7 @@
 EVP_ASYM_CIPHER_fetch, EVP_ASYM_CIPHER_free, EVP_ASYM_CIPHER_up_ref,
 EVP_ASYM_CIPHER_number, EVP_ASYM_CIPHER_is_a, EVP_ASYM_CIPHER_provider,
 EVP_ASYM_CIPHER_do_all_provided, EVP_ASYM_CIPHER_names_do_all,
+EVP_ASYM_CIPHER_description,
 EVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params
 - Functions to manage EVP_ASYM_CIPHER algorithm objects
 
@@ -26,6 +27,7 @@ EVP_ASYM_CIPHER_gettable_ctx_params, EVP_ASYM_CIPHER_settable_ctx_params
  int EVP_ASYM_CIPHER_names_do_all(const EVP_ASYM_CIPHER *cipher,
                                   void (*fn)(const char *name, void *data),
                                   void *data);
+ const char *EVP_ASYM_CIPHER_description(const EVP_ASYM_CIPHER *cipher);
  const OSSL_PARAM *EVP_ASYM_CIPHER_gettable_ctx_params(const EVP_ASYM_CIPHER *cip);
  const OSSL_PARAM *EVP_ASYM_CIPHER_settable_ctx_params(const EVP_ASYM_CIPHER *cip);
 
@@ -64,6 +66,10 @@ I<cipher>.
 EVP_ASYM_CIPHER_names_do_all() traverses all names for I<cipher>, and calls
 I<fn> with each name and I<data>.
 
+EVP_ASYM_CIPHER_description() returns a description of the I<cipher>, meant
+for display and human consumption.  The description is at the discretion of
+the I<cipher> implementation.
+
 EVP_ASYM_CIPHER_gettable_ctx_params() and EVP_ASYM_CIPHER_settable_ctx_params()
 return a constant B<OSSL_PARAM> array that describes the names and types of key
 parameters that can be retrieved or set by a key encryption algorithm using
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 043717758e..6299aa3d20 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -12,7 +12,8 @@ EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params,
 EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags,
 EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit,
 EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
-EVP_MD_is_a, EVP_MD_name, EVP_MD_number, EVP_MD_names_do_all, EVP_MD_provider,
+EVP_MD_is_a, EVP_MD_name, EVP_MD_description, EVP_MD_number,
+EVP_MD_names_do_all, EVP_MD_provider,
 EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags,
 EVP_MD_CTX_name,
 EVP_MD_CTX_md, EVP_MD_CTX_type, EVP_MD_CTX_size, EVP_MD_CTX_block_size,
@@ -64,6 +65,7 @@ EVP_MD_do_all_provided
  int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
 
  const char *EVP_MD_name(const EVP_MD *md);
+ const char *EVP_MD_description(const EVP_MD *md);
  int EVP_MD_number(const EVP_MD *md);
  int EVP_MD_is_a(const EVP_MD *md, const char *name);
  int EVP_MD_names_do_all(const EVP_MD *md,
@@ -314,6 +316,11 @@ recommended to use EVP_MD_names_do_all() instead.
 Traverses all names for the I<md>, and calls I<fn> with each name and
 I<data>.  This is only useful with fetched B<EVP_MD>s.
 
+=item EVP_MD_description()
+
+Returns a description of the digest, meant for display and human consumption.
+The description is at the discretion of the digest implementation.
+
 =item EVP_MD_provider()
 
 Returns an B<OSSL_PROVIDER> pointer to the provider that implements the given
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 9090dc8ad3..303e93fe06 100644
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -34,6 +34,7 @@ EVP_get_cipherbynid,
 EVP_get_cipherbyobj,
 EVP_CIPHER_is_a,
 EVP_CIPHER_name,
+EVP_CIPHER_description,
 EVP_CIPHER_number,
 EVP_CIPHER_names_do_all,
 EVP_CIPHER_provider,
@@ -143,6 +144,7 @@ EVP_CIPHER_do_all_provided
                              void (*fn)(const char *name, void *data),
                              void *data);
  const char *EVP_CIPHER_name(const EVP_CIPHER *cipher);
+ const char *EVP_CIPHER_description(const EVP_CIPHER *cipher);
  const OSSL_PROVIDER *EVP_CIPHER_provider(const EVP_CIPHER *cipher);
  int EVP_CIPHER_block_size(const EVP_CIPHER *e);
  int EVP_CIPHER_key_length(const EVP_CIPHER *e);
@@ -408,6 +410,10 @@ EVP_CIPHER_names_do_all() traverses all names for the I<cipher>, and
 calls I<fn> with each name and I<data>.  This is only useful with
 fetched B<EVP_CIPHER>s.
 
+EVP_CIPHER_description() returns a description of the cipher, meant for
+display and human consumption.  The description is at the discretion of the
+cipher implementation.
+
 EVP_CIPHER_provider() returns an B<OSSL_PROVIDER> pointer to the provider
 that implements the given B<EVP_CIPHER>.
 
diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod
index 5d7fa72b16..c3d0464d2e 100644
--- a/doc/man3/EVP_KDF.pod
+++ b/doc/man3/EVP_KDF.pod
@@ -6,7 +6,7 @@ EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref,
 EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup,
 EVP_KDF_CTX_reset, EVP_KDF_derive,
 EVP_KDF_CTX_get_kdf_size, EVP_KDF_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
-EVP_KDF_number, EVP_KDF_name, EVP_KDF_names_do_all,
+EVP_KDF_number, EVP_KDF_name, EVP_KDF_names_do_all, EVP_KDF_description,
 EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided,
 EVP_KDF_get_params, EVP_KDF_gettable_params,
 EVP_KDF_gettable_ctx_params, EVP_KDF_settable_ctx_params,
@@ -34,6 +34,7 @@ EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines
  int EVP_KDF_number(const EVP_KDF *kdf);
  int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);
  const char *EVP_KDF_name(const EVP_KDF *kdf);
+ const char *EVP_KDF_description(const EVP_KDF *kdf);
  const OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
  void EVP_KDF_do_all_provided(OSSL_LIB_CTX *libctx,
                               void (*fn)(EVP_KDF *kdf, void *arg),
@@ -179,6 +180,10 @@ recommended to use EVP_KDF_names_do_all() instead.
 EVP_KDF_names_do_all() traverses all names for I<kdf>, and calls
 I<fn> with each name and I<data>.
 
+EVP_KDF_description() returns a description of the I<kdf>, meant for display
+and human consumption.  The description is at the discretion of the I<kdf>
+implementation.
+
 =head1 PARAMETERS
 
 The standard parameter names are:
diff --git a/doc/man3/EVP_KEM_free.pod b/doc/man3/EVP_KEM_free.pod
index 69302880c7..0551afcf8d 100644
--- a/doc/man3/EVP_KEM_free.pod
+++ b/doc/man3/EVP_KEM_free.pod
@@ -4,7 +4,7 @@
 
 EVP_KEM_fetch, EVP_KEM_free, EVP_KEM_up_ref,
 EVP_KEM_number, EVP_KEM_is_a, EVP_KEM_provider,
-EVP_KEM_do_all_provided, EVP_KEM_names_do_all,
+EVP_KEM_do_all_provided, EVP_KEM_names_do_all, EVP_KEM_description,
 EVP_KEM_gettable_ctx_params, EVP_KEM_settable_ctx_params
 - Functions to manage EVP_KEM algorithm objects
 
@@ -23,6 +23,7 @@ EVP_KEM_gettable_ctx_params, EVP_KEM_settable_ctx_params
                               void (*fn)(EVP_KEM *kem, void *arg), void *arg);
  int EVP_KEM_names_do_all(const EVP_KEM *kem,
                           void (*fn)(const char *name, void *data), void *data);
+ const char *EVP_KEM_description(const EVP_KEM *kem);
  const OSSL_PARAM *EVP_KEM_gettable_ctx_params(const EVP_KEM *kem);
  const OSSL_PARAM *EVP_KEM_settable_ctx_params(const EVP_KEM *kem);
 
@@ -58,6 +59,10 @@ EVP_KEM_number() returns the internal dynamic number assigned to I<kem>.
 EVP_KEM_names_do_all() traverses all names for I<kem>, and calls I<fn> with
 each name and I<data>.
 
+EVP_KEM_description() returns a description of the I<kem>, meant for display
+and human consumption.  The description is at the discretion of the I<kem>
+implementation.
+
 EVP_KEM_gettable_ctx_params() and EVP_KEM_settable_ctx_params() return
 a constant B<OSSL_PARAM> array that describes the names and types of key
 parameters that can be retrieved or set by a key encapsulation algorithm using
diff --git a/doc/man3/EVP_KEYEXCH_free.pod b/doc/man3/EVP_KEYEXCH_free.pod
index 83dafde007..a040e7d604 100644
--- a/doc/man3/EVP_KEYEXCH_free.pod
+++ b/doc/man3/EVP_KEYEXCH_free.pod
@@ -5,6 +5,7 @@
 EVP_KEYEXCH_fetch, EVP_KEYEXCH_free, EVP_KEYEXCH_up_ref, EVP_KEYEXCH_provider,
 EVP_KEYEXCH_is_a, EVP_KEYEXCH_do_all_provided,
 EVP_KEYEXCH_number, EVP_KEYEXCH_names_do_all,
+EVP_KEYEXCH_description,
 EVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params
 - Functions to manage EVP_KEYEXCH algorithm objects
 
@@ -25,6 +26,7 @@ EVP_KEYEXCH_gettable_ctx_params, EVP_KEYEXCH_settable_ctx_params
  int EVP_KEYEXCH_names_do_all(const EVP_KEYEXCH *exchange,
                               void (*fn)(const char *name, void *data),
                               void *data);
+ const char *EVP_KEYEXCH_description(const EVP_KEYEXCH *keyexch);
  const OSSL_PARAM *EVP_KEYEXCH_gettable_ctx_params(const EVP_KEYEXCH *keyexch);
  const OSSL_PARAM *EVP_KEYEXCH_settable_ctx_params(const EVP_KEYEXCH *keyexch);
 
@@ -56,6 +58,10 @@ the I<exchange>.
 EVP_KEYEXCH_names_do_all() traverses all names for the I<exchange>, and
 calls I<fn> with each name and I<data>.
 
+EVP_KEYEXCH_description() returns a description of the I<keyexch>, meant for
+display and human consumption.  The description is at the discretion of the
+I<keyexch> implementation.
+
 EVP_KEYEXCH_do_all_provided() traverses all key exchange implementations by
 all activated providers in the library context I<libctx>, and for each
 of the implementations, calls I<fn> with the implementation method and
diff --git a/doc/man3/EVP_KEYMGMT.pod b/doc/man3/EVP_KEYMGMT.pod
index 6eb4e5567d..d62f1cb3f5 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_description,
 EVP_KEYMGMT_get0_first_name,
 EVP_KEYMGMT_do_all_provided,
 EVP_KEYMGMT_names_do_all,
@@ -31,6 +32,7 @@ EVP_KEYMGMT_gen_settable_params
  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);
+ const char *EVP_KEYMGMT_description(const EVP_KEYMGMT *keymgmt);
 
  void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
                                   void (*fn)(EVP_KEYMGMT *keymgmt, void *arg),
@@ -81,6 +83,10 @@ 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>.
 
+EVP_KEYMGMT_description() returns a description of the I<keymgmt>, meant for
+display and human consumption.  The description is at the discretion of the
+I<keymgmt> implementation.
+
 EVP_KEYMGMT_do_all_provided() traverses all key keymgmt implementations by
 all activated providers in the library context I<libctx>, and for each
 of the implementations, calls I<fn> with the implementation method and
@@ -125,6 +131,9 @@ EVP_KEYMGMT_number() returns an integer.
 
 EVP_KEYMGMT_get0_first_name() returns the name that is found or NULL on error.
 
+EVP_KEYMGMT_description() returns a pointer to a decription, or NULL if
+there isn't one.
+
 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_MAC.pod b/doc/man3/EVP_MAC.pod
index b4ad7209dd..a4da280ab4 100644
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -2,8 +2,8 @@
 
 =head1 NAME
 
-EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free,
-EVP_MAC_is_a, EVP_MAC_number, EVP_MAC_name, EVP_MAC_names_do_all,
+EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free, EVP_MAC_is_a,
+EVP_MAC_number, EVP_MAC_name, EVP_MAC_names_do_all, EVP_MAC_description,
 EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
 EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
 EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
@@ -29,6 +29,7 @@ EVP_MAC_do_all_provided - EVP MAC routines
  int EVP_MAC_names_do_all(const EVP_MAC *mac,
                           void (*fn)(const char *name, void *data),
                           void *data);
+ const char *EVP_MAC_description(const EVP_MAC *mac);
  const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
  int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
 
@@ -205,6 +206,10 @@ recommended to use EVP_MAC_names_do_all() instead.
 EVP_MAC_names_do_all() traverses all names for I<mac>, and calls
 I<fn> with each name and I<data>.
 
+EVP_MAC_description() returns a description of the I<mac>, meant for display
+and human consumption.  The description is at the discretion of the mac
+implementation.
+
 =head1 PARAMETERS
 
 Parameters are identified by name as strings, and have an expected
diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod
index ee55396de3..d98d7c240e 100644
--- a/doc/man3/EVP_PKEY_new.pod
+++ b/doc/man3/EVP_PKEY_new.pod
@@ -7,6 +7,7 @@ EVP_PKEY_new,
 EVP_PKEY_up_ref,
 EVP_PKEY_dup,
 EVP_PKEY_free,
+EVP_PKEY_description,
 EVP_PKEY_new_raw_private_key_ex,
 EVP_PKEY_new_raw_private_key,
 EVP_PKEY_new_raw_public_key_ex,
@@ -27,6 +28,7 @@ EVP_PKEY_get_raw_public_key
  int EVP_PKEY_up_ref(EVP_PKEY *key);
  EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key);
  void EVP_PKEY_free(EVP_PKEY *key);
+ const char *EVP_PKEY_description(const EVP_PKEY *key);
 
  EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx,
                                            const char *keytype,
@@ -90,6 +92,10 @@ a raw key, otherwise the duplication will fail.
 EVP_PKEY_free() decrements the reference count of I<key> and, if the reference
 count is zero, frees it up. If I<key> is NULL, nothing is done.
 
+EVP_PKEY_description() returns a description of the type of B<EVP_PKEY>, meant
+for display and human consumption.  The description is at the discretion of the
+key type implementation.
+
 EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. Unless an
 engine should be used for the key type, a provider for the key is found using
 the library context I<libctx> and the property query string I<propq>. The
diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod
index f550ec18e3..ab0fdbcb48 100644
--- a/doc/man3/EVP_RAND.pod
+++ b/doc/man3/EVP_RAND.pod
@@ -4,11 +4,12 @@
 
 EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
 EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
-EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
-EVP_RAND_nonce, EVP_RAND_enable_locking,
-EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state,
+EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, EVP_RAND_nonce,
+EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_strength,
+EVP_RAND_state,
 EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number,
-EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params,
+EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_description,
+EVP_RAND_get_ctx_params,
 EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
 EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
 EVP_RAND_CTX_gettable_params, EVP_RAND_CTX_settable_params,
@@ -39,6 +40,7 @@ EVP_RAND_STATE_ERROR - EVP RAND routines
  const OSSL_PARAM *EVP_RAND_CTX_settable_params(EVP_RAND_CTX *ctx);
  int EVP_RAND_number(const EVP_RAND *rand);
  const char *EVP_RAND_name(const EVP_RAND *rand);
+ const char *EVP_RAND_description(const EVP_RAND *rand);
  int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
  const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
  void EVP_RAND_do_all_provided(OSSL_LIB_CTX *libctx,
@@ -248,6 +250,10 @@ EVP_RAND_name() returns the canonical name of I<rand>.
 EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
 I<fn> with each name and I<data>.
 
+EVP_RAND_description() returns a description of the rand, meant for display
+and human consumption.  The description is at the discretion of the rand
+implementation.
+
 EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
 currently zeroed.  This is used by the FIPS provider to support the mandatory
 self tests.
diff --git a/doc/man3/EVP_SIGNATURE_free.pod b/doc/man3/EVP_SIGNATURE_free.pod
index cfc3b4c3bf..de1b22f387 100644
--- a/doc/man3/EVP_SIGNATURE_free.pod
+++ b/doc/man3/EVP_SIGNATURE_free.pod
@@ -5,6 +5,7 @@
 EVP_SIGNATURE_fetch, EVP_SIGNATURE_free, EVP_SIGNATURE_up_ref,
 EVP_SIGNATURE_number, EVP_SIGNATURE_is_a, EVP_SIGNATURE_provider,
 EVP_SIGNATURE_do_all_provided, EVP_SIGNATURE_names_do_all,
+EVP_SIGNATURE_description,
 EVP_SIGNATURE_gettable_ctx_params, EVP_SIGNATURE_settable_ctx_params
 - Functions to manage EVP_SIGNATURE algorithm objects
 
@@ -26,6 +27,7 @@ EVP_SIGNATURE_gettable_ctx_params, EVP_SIGNATURE_settable_ctx_params
  int EVP_SIGNATURE_names_do_all(const EVP_SIGNATURE *signature,
                                 void (*fn)(const char *name, void *data),
                                 void *data);
+ const char *EVP_SIGNATURE_description(const EVP_SIGNATURE *signature);
  const OSSL_PARAM *EVP_SIGNATURE_gettable_ctx_params(const EVP_SIGNATURE *sig);
  const OSSL_PARAM *EVP_SIGNATURE_settable_ctx_params(const EVP_SIGNATURE *sig);
 
@@ -64,6 +66,10 @@ I<signature>.
 EVP_SIGNATURE_names_do_all() traverses all names for I<signature>, and calls
 I<fn> with each name and I<data>.
 
+EVP_SIGNATURE_description() returns a description of the I<signature>, meant
+for display and human consumption.  The description is at the discretion of
+the I<signature> implementation.
+
 EVP_SIGNATURE_gettable_ctx_params() and EVP_SIGNATURE_settable_ctx_params()
 return a constant B<OSSL_PARAM> array that describes the names and types of key
 parameters that can be retrieved or set by a signature algorithm using