]> git.ipfire.org Git - thirdparty/openssl.git/commitdiff
EVP: Add EVP_<TYPE>_description()
authorRichard Levitte <levitte@openssl.org>
Tue, 16 Mar 2021 13:23:54 +0000 (14:23 +0100)
committerRichard Levitte <levitte@openssl.org>
Fri, 2 Apr 2021 06:57:47 +0000 (08:57 +0200)
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)

24 files changed:
crypto/evp/asymcipher.c
crypto/evp/evp_lib.c
crypto/evp/evp_rand.c
crypto/evp/exchange.c
crypto/evp/kdf_lib.c
crypto/evp/kem.c
crypto/evp/keymgmt_meth.c
crypto/evp/mac_lib.c
crypto/evp/p_lib.c
crypto/evp/signature.c
doc/man3/EVP_ASYM_CIPHER_free.pod
doc/man3/EVP_DigestInit.pod
doc/man3/EVP_EncryptInit.pod
doc/man3/EVP_KDF.pod
doc/man3/EVP_KEM_free.pod
doc/man3/EVP_KEYEXCH_free.pod
doc/man3/EVP_KEYMGMT.pod
doc/man3/EVP_MAC.pod
doc/man3/EVP_PKEY_new.pod
doc/man3/EVP_RAND.pod
doc/man3/EVP_SIGNATURE_free.pod
include/openssl/evp.h
include/openssl/kdf.h
util/libcrypto.num

index 60f3ce67cf3605dbc2e098d50de91564c6afe156..08c8fb0088ccab24fe7ba7f0864558ea718623f2 100644 (file)
@@ -435,6 +435,11 @@ int EVP_ASYM_CIPHER_number(const EVP_ASYM_CIPHER *cipher)
     return cipher->name_id;
 }
 
+const char *EVP_ASYM_CIPHER_description(const EVP_ASYM_CIPHER *cipher)
+{
+    return cipher->description;
+}
+
 void EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,
                                      void (*fn)(EVP_ASYM_CIPHER *cipher,
                                                 void *arg),
index 31d2a7392b3a90d6e510bc3ac92c254be0be1a78..a707285c91a6e6e4aee928287ff580032629c55c 100644 (file)
@@ -645,6 +645,17 @@ const char *EVP_CIPHER_name(const EVP_CIPHER *cipher)
 #endif
 }
 
+const char *EVP_CIPHER_description(const EVP_CIPHER *cipher)
+{
+    if (cipher->description != NULL)
+        return cipher->description;
+#ifndef FIPS_MODULE
+    return OBJ_nid2ln(EVP_CIPHER_nid(cipher));
+#else
+    return NULL;
+#endif
+}
+
 int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher,
                             void (*fn)(const char *name, void *data),
                             void *data)
@@ -677,6 +688,17 @@ int EVP_MD_number(const EVP_MD *md)
     return md->name_id;
 }
 
+const char *EVP_MD_description(const EVP_MD *md)
+{
+    if (md->description != NULL)
+        return md->description;
+#ifndef FIPS_MODULE
+    return OBJ_nid2ln(EVP_MD_nid(md));
+#else
+    return NULL;
+#endif
+}
+
 const char *EVP_MD_name(const EVP_MD *md)
 {
     if (md->prov != NULL)
index 131550b4f360a78eb74c2e33583bfbe648bf4d10..cae21891ee8cb6771eacbf201a3ac39e27b78021 100644 (file)
@@ -295,6 +295,11 @@ const char *EVP_RAND_name(const EVP_RAND *rand)
     return evp_first_name(rand->prov, rand->name_id);
 }
 
+const char *EVP_RAND_description(const EVP_RAND *rand)
+{
+    return rand->description;
+}
+
 int EVP_RAND_is_a(const EVP_RAND *rand, const char *name)
 {
     return evp_is_a(rand->prov, rand->name_id, NULL, name);
index fd8e9210a17a7408bd2f6e82ae5d5424acbc2e46..07d5e4ab9b8e8ea8475e1765d1d294957d724d81 100644 (file)
@@ -465,6 +465,11 @@ int EVP_KEYEXCH_number(const EVP_KEYEXCH *keyexch)
     return keyexch->name_id;
 }
 
+const char *EVP_KEYEXCH_description(const EVP_KEYEXCH *keyexch)
+{
+    return keyexch->description;
+}
+
 int EVP_KEYEXCH_is_a(const EVP_KEYEXCH *keyexch, const char *name)
 {
     return evp_is_a(keyexch->prov, keyexch->name_id, NULL, name);
index f5ff00d7e772253c036b5ad3801c9db2c5e3a8bc..1a1074b21ba1abe6f7d677717c50a43cf44da5dc 100644 (file)
@@ -95,6 +95,11 @@ const char *EVP_KDF_name(const EVP_KDF *kdf)
     return NULL;
 }
 
+const char *EVP_KDF_description(const EVP_KDF *kdf)
+{
+    return kdf->description;
+}
+
 int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name)
 {
     return evp_is_a(kdf->prov, kdf->name_id, NULL, name);
index d57290643bdf9e2ee8a81cf7d6042e0d6cacefe2..cd8924ef395bca3150b4c716a77c480db0f4604f 100644 (file)
@@ -343,6 +343,11 @@ int EVP_KEM_number(const EVP_KEM *kem)
     return kem->name_id;
 }
 
+const char *EVP_KEM_description(const EVP_KEM *kem)
+{
+    return kem->description;
+}
+
 void EVP_KEM_do_all_provided(OSSL_LIB_CTX *libctx,
                              void (*fn)(EVP_KEM *kem, void *arg),
                              void *arg)
index f7603f3fa2a9119e2c7ab72f33f851fbb2549ca8..cdd7c70ed910063edf3921f4372bf8505378b789 100644 (file)
@@ -251,6 +251,11 @@ int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt)
     return keymgmt->name_id;
 }
 
+const char *EVP_KEYMGMT_description(const EVP_KEYMGMT *keymgmt)
+{
+    return keymgmt->description;
+}
+
 const char *EVP_KEYMGMT_get0_first_name(const EVP_KEYMGMT *keymgmt)
 {
     return evp_first_name(keymgmt->prov, keymgmt->name_id);
index 746abf53c1f104199b5788f019900237f125d40f..e7eea3294bae646ad8be53e00104fb413bebf833 100644 (file)
@@ -170,6 +170,11 @@ const char *EVP_MAC_name(const EVP_MAC *mac)
     return NULL;
 }
 
+const char *EVP_MAC_description(const EVP_MAC *mac)
+{
+    return mac->description;
+}
+
 int EVP_MAC_is_a(const EVP_MAC *mac, const char *name)
 {
     return evp_is_a(mac->prov, mac->name_id, NULL, name);
index d4241063601ecddc6883233860657ceed079977f..f1ffb80e9040f1d8f8dad7badf2dba366faf379d 100644 (file)
@@ -1723,6 +1723,20 @@ int EVP_PKEY_size(const EVP_PKEY *pkey)
     return size < 0 ? 0 : size;
 }
 
+const char *EVP_PKEY_description(const EVP_PKEY *pkey)
+{
+    if (!evp_pkey_is_assigned(pkey))
+        return NULL;
+
+    if (evp_pkey_is_provided(pkey) && pkey->keymgmt->description != NULL)
+        return pkey->keymgmt->description;
+#ifndef FIPS_MODULE
+    if (pkey->ameth != NULL)
+        return pkey->ameth->info;
+#endif
+    return NULL;
+}
+
 void *evp_pkey_export_to_provider(EVP_PKEY *pk, OSSL_LIB_CTX *libctx,
                                   EVP_KEYMGMT **keymgmt,
                                   const char *propquery)
index 1a1235821e59d594a313074388953604a8ce37f0..7df984e1bf220c3c70751084ce07163585073b1c 100644 (file)
@@ -319,6 +319,11 @@ int EVP_SIGNATURE_number(const EVP_SIGNATURE *signature)
     return signature->name_id;
 }
 
+const char *EVP_SIGNATURE_description(const EVP_SIGNATURE *signature)
+{
+    return signature->description;
+}
+
 void EVP_SIGNATURE_do_all_provided(OSSL_LIB_CTX *libctx,
                                    void (*fn)(EVP_SIGNATURE *signature,
                                               void *arg),
index 6558d0c0c49a3eaf5f385f65c0b8b05e51370a4b..2500109e45de63c9b28a86f2a9c0de01a6d5ca03 100644 (file)
@@ -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
index 043717758e4cbb5e964c3489535ceb3800acd685..6299aa3d2040a35b44cb2b12b6b876b35eef95d4 100644 (file)
@@ -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
index 9090dc8ad3c86e81e8fc6bfa9cdfca169b1e3a33..303e93fe0601279b3ab296823ebcfb14e41327ae 100644 (file)
@@ -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>.
 
index 5d7fa72b1653975eafb442be7bfc770222b44cdf..c3d0464d2e458669bbe0861a493cc6a19612af7c 100644 (file)
@@ -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:
index 69302880c7749f81c71ae19d5a04a5935bd04b17..0551afcf8d8a0410795d9c8b5d7ed6829023ff86 100644 (file)
@@ -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
index 83dafde0078496a359d5884be9ee0d3fc0e8a524..a040e7d60433e2f2f29efb57d410bd86687fda46 100644 (file)
@@ -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
index 6eb4e5567dee1d2951c2b450375fc18b137bb04b..d62f1cb3f57672fa5c586656791b0fe1b75084e3 100644 (file)
@@ -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.
index b4ad7209dd7cbb143b2a383149ce4601c494537a..a4da280ab45c9b613b29d23d212b67f2dddb0cdc 100644 (file)
@@ -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
index ee55396de3b31d611fd786cca0a291ce541229f1..d98d7c240e69635b47d2bee484ebe55c01370678 100644 (file)
@@ -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
index f550ec18e3c04809760b33d852fcd6e3e43ecbe8..ab0fdbcb4808efdf71de970866b3eb62277d0f26 100644 (file)
@@ -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.
index cfc3b4c3bf1929109d5b3dbd1da17271b22962d7..de1b22f38722a49b6dcd0b385516312cbe98e1fc 100644 (file)
@@ -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
index 7d1823dbacc3af0b538ea9e168854fac7c81ff1a..ed54575e84555bfdbb5a4eed96d35ba0946ff4da 100644 (file)
@@ -526,6 +526,7 @@ typedef int (EVP_PBE_KEYGEN) (EVP_CIPHER_CTX *ctx, const char *pass,
 int EVP_MD_type(const EVP_MD *md);
 # define EVP_MD_nid(e)                   EVP_MD_type(e)
 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,
@@ -557,6 +558,7 @@ void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
 
 int EVP_CIPHER_nid(const EVP_CIPHER *cipher);
 const char *EVP_CIPHER_name(const EVP_CIPHER *cipher);
+const char *EVP_CIPHER_description(const EVP_CIPHER *cipher);
 int EVP_CIPHER_number(const EVP_CIPHER *cipher);
 int EVP_CIPHER_is_a(const EVP_CIPHER *cipher, const char *name);
 int EVP_CIPHER_names_do_all(const EVP_CIPHER *cipher,
@@ -1151,6 +1153,7 @@ int EVP_MAC_up_ref(EVP_MAC *mac);
 void EVP_MAC_free(EVP_MAC *mac);
 int EVP_MAC_number(const EVP_MAC *mac);
 const char *EVP_MAC_name(const EVP_MAC *mac);
+const char *EVP_MAC_description(const EVP_MAC *mac);
 int EVP_MAC_is_a(const EVP_MAC *mac, const char *name);
 const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
 int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
@@ -1188,6 +1191,7 @@ int EVP_RAND_up_ref(EVP_RAND *rand);
 void EVP_RAND_free(EVP_RAND *rand);
 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 *md);
 int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
 const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
 int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
@@ -1320,6 +1324,7 @@ EVP_PKEY *EVP_PKEY_new(void);
 int EVP_PKEY_up_ref(EVP_PKEY *pkey);
 EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *pkey);
 void EVP_PKEY_free(EVP_PKEY *pkey);
+const char *EVP_PKEY_description(const EVP_PKEY *pkey);
 
 EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp,
                         long length);
@@ -1671,6 +1676,7 @@ int EVP_KEYMGMT_up_ref(EVP_KEYMGMT *keymgmt);
 void EVP_KEYMGMT_free(EVP_KEYMGMT *keymgmt);
 const OSSL_PROVIDER *EVP_KEYMGMT_provider(const EVP_KEYMGMT *keymgmt);
 const char *EVP_KEYMGMT_get0_first_name(const EVP_KEYMGMT *keymgmt);
+const char *EVP_KEYMGMT_description(const EVP_KEYMGMT *keymgmt);
 int EVP_KEYMGMT_number(const EVP_KEYMGMT *keymgmt);
 int EVP_KEYMGMT_is_a(const EVP_KEYMGMT *keymgmt, const char *name);
 void EVP_KEYMGMT_do_all_provided(OSSL_LIB_CTX *libctx,
@@ -1755,6 +1761,7 @@ EVP_SIGNATURE *EVP_SIGNATURE_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                                    const char *properties);
 int EVP_SIGNATURE_is_a(const EVP_SIGNATURE *signature, const char *name);
 int EVP_SIGNATURE_number(const EVP_SIGNATURE *signature);
+const char *EVP_SIGNATURE_description(const EVP_SIGNATURE *signature);
 void EVP_SIGNATURE_do_all_provided(OSSL_LIB_CTX *libctx,
                                    void (*fn)(EVP_SIGNATURE *signature,
                                               void *data),
@@ -1772,6 +1779,7 @@ EVP_ASYM_CIPHER *EVP_ASYM_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                                        const char *properties);
 int EVP_ASYM_CIPHER_is_a(const EVP_ASYM_CIPHER *cipher, const char *name);
 int EVP_ASYM_CIPHER_number(const EVP_ASYM_CIPHER *cipher);
+const char *EVP_ASYM_CIPHER_description(const EVP_ASYM_CIPHER *cipher);
 void EVP_ASYM_CIPHER_do_all_provided(OSSL_LIB_CTX *libctx,
                                      void (*fn)(EVP_ASYM_CIPHER *cipher,
                                                 void *arg),
@@ -1789,6 +1797,7 @@ EVP_KEM *EVP_KEM_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                        const char *properties);
 int EVP_KEM_is_a(const EVP_KEM *wrap, const char *name);
 int EVP_KEM_number(const EVP_KEM *wrap);
+const char *EVP_KEM_description(const EVP_KEM *wrap);
 void EVP_KEM_do_all_provided(OSSL_LIB_CTX *libctx,
                              void (*fn)(EVP_KEM *wrap, void *arg), void *arg);
 int EVP_KEM_names_do_all(const EVP_KEM *wrap,
@@ -2045,6 +2054,7 @@ EVP_KEYEXCH *EVP_KEYEXCH_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
 OSSL_PROVIDER *EVP_KEYEXCH_provider(const EVP_KEYEXCH *exchange);
 int EVP_KEYEXCH_is_a(const EVP_KEYEXCH *keyexch, const char *name);
 int EVP_KEYEXCH_number(const EVP_KEYEXCH *keyexch);
+const char *EVP_KEYEXCH_description(const EVP_KEYEXCH *keyexch);
 void EVP_KEYEXCH_do_all_provided(OSSL_LIB_CTX *libctx,
                                  void (*fn)(EVP_KEYEXCH *keyexch, void *data),
                                  void *data);
index 4c1397f909dcdfbe78e5a783a91aef0c4514d386..96a25ff7c15ddd8bcc3a87828918fb7b97b9ad4b 100644 (file)
@@ -34,6 +34,7 @@ EVP_KDF_CTX *EVP_KDF_CTX_new(EVP_KDF *kdf);
 void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
 EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
 int EVP_KDF_number(const EVP_KDF *kdf);
+const char *EVP_KDF_description(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 OSSL_PROVIDER *EVP_KDF_provider(const EVP_KDF *kdf);
index eb84f1763ec6e766186dce4fde84cda817ae397c..49fc731085540817e69e6945011118e644dce08b 100644 (file)
@@ -5336,3 +5336,14 @@ EVP_PKEY_derive_set_peer_ex             ?        3_0_0   EXIST::FUNCTION:
 OSSL_DECODER_description                ?      3_0_0   EXIST::FUNCTION:
 OSSL_ENCODER_description                ?      3_0_0   EXIST::FUNCTION:
 OSSL_STORE_LOADER_description           ?      3_0_0   EXIST::FUNCTION:
+EVP_MD_description                      ?      3_0_0   EXIST::FUNCTION:
+EVP_CIPHER_description                  ?      3_0_0   EXIST::FUNCTION:
+EVP_MAC_description                     ?      3_0_0   EXIST::FUNCTION:
+EVP_RAND_description                    ?      3_0_0   EXIST::FUNCTION:
+EVP_PKEY_description                    ?      3_0_0   EXIST::FUNCTION:
+EVP_KEYMGMT_description                 ?      3_0_0   EXIST::FUNCTION:
+EVP_SIGNATURE_description               ?      3_0_0   EXIST::FUNCTION:
+EVP_ASYM_CIPHER_description             ?      3_0_0   EXIST::FUNCTION:
+EVP_KEM_description                     ?      3_0_0   EXIST::FUNCTION:
+EVP_KEYEXCH_description                 ?      3_0_0   EXIST::FUNCTION:
+EVP_KDF_description                     ?      3_0_0   EXIST::FUNCTION: