[openssl] master update
Matt Caswell
matt at openssl.org
Thu Nov 21 15:54:28 UTC 2019
The branch master has been updated
via e44192d14b0557538611de4018170d702c9709d7 (commit)
via cc35c3ed8ffdc07bb53a2908b8a186fd866ac8d5 (commit)
from ab5c77b4766e0992751d86560193ca42b49cf316 (commit)
- Log -----------------------------------------------------------------
commit e44192d14b0557538611de4018170d702c9709d7
Author: Matt Caswell <matt at openssl.org>
Date: Fri Oct 4 12:46:33 2019 +0100
Documentation updates due to naming tweaks
Also documents our new canonical naming.
Reviewed-by: Paul Dale <paul.dale at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10092)
commit cc35c3ed8ffdc07bb53a2908b8a186fd866ac8d5
Author: Matt Caswell <matt at openssl.org>
Date: Fri Oct 4 11:50:49 2019 +0100
Tweak some algorithm naming inconsistencies
Make some algorithms names better match our "canonical" style.
Reviewed-by: Paul Dale <paul.dale at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10092)
-----------------------------------------------------------------------
Summary of changes:
doc/man1/openssl-kdf.pod | 16 +++----
doc/man7/EVP_KDF-KB.pod | 2 +-
doc/man7/EVP_KDF-SCRYPT.pod | 6 +--
doc/man7/EVP_MAC-KMAC.pod | 4 +-
doc/man7/EVP_MAC-Poly1305.pod | 2 +-
doc/man7/EVP_MAC-Siphash.pod | 2 +-
doc/man7/provider.pod | 99 +++++++++++++++++--------------------------
include/openssl/core_names.h | 6 +--
providers/defltprov.c | 27 ++++++------
providers/fips/fipsprov.c | 10 ++---
providers/legacyprov.c | 4 +-
11 files changed, 79 insertions(+), 99 deletions(-)
diff --git a/doc/man1/openssl-kdf.pod b/doc/man1/openssl-kdf.pod
index 2bba8d3ef2..d89f84fd43 100644
--- a/doc/man1/openssl-kdf.pod
+++ b/doc/man1/openssl-kdf.pod
@@ -83,7 +83,7 @@ To see the list of supported digests, use the command I<list -digest-commands>.
Specifies the name of a supported KDF algorithm which will be used.
The supported algorithms names include TLS1-PRF, HKDF, SSKDF, PBKDF2,
-SSHKDF, X942KDF, X963KDF and id-scrypt.
+SSHKDF, X942KDF, X963KDF and SCRYPT.
=back
@@ -91,35 +91,35 @@ SSHKDF, X942KDF, X963KDF and id-scrypt.
Use TLS1-PRF to create a hex-encoded derived key from a secret key and seed:
- openssl kdf -keylen 16 -kdfopt digest:SHA256 -kdfopt key:secret \
+ openssl kdf -keylen 16 -kdfopt digest:SHA2-256 -kdfopt key:secret \
-kdfopt seed:seed TLS1-PRF
Use HKDF to create a hex-encoded derived key from a secret key, salt and info:
- openssl kdf -keylen 10 -kdfopt digest:SHA256 -kdfopt key:secret \
+ openssl kdf -keylen 10 -kdfopt digest:SHA2-256 -kdfopt key:secret \
-kdfopt salt:salt -kdfopt info:label HKDF
Use SSKDF with KMAC to create a hex-encoded derived key from a secret key, salt and info:
- openssl kdf -keylen 64 -kdfopt mac:KMAC128 -kdfopt maclen:20 \
+ openssl kdf -keylen 64 -kdfopt mac:KMAC-128 -kdfopt maclen:20 \
-kdfopt hexkey:b74a149a161545 -kdfopt hexinfo:348a37a2 \
-kdfopt hexsalt:3638271ccd68a2 SSKDF
Use SSKDF with HMAC to create a hex-encoded derived key from a secret key, salt and info:
- openssl kdf -keylen 16 -kdfopt mac:HMAC -kdfopt digest:SHA256 \
+ openssl kdf -keylen 16 -kdfopt mac:HMAC -kdfopt digest:SHA2-256 \
-kdfopt hexkey:b74a149a -kdfopt hexinfo:348a37a2 \
-kdfopt hexsalt:3638271c SSKDF
Use SSKDF with Hash to create a hex-encoded derived key from a secret key, salt and info:
- openssl kdf -keylen 14 -kdfopt digest:SHA256 \
+ openssl kdf -keylen 14 -kdfopt digest:SHA2-256 \
-kdfopt hexkey:6dbdc23f045488 \
-kdfopt hexinfo:a1b2c3d4 SSKDF
Use SSHKDF to create a hex-encoded derived key from a secret key, hash and session_id:
- openssl kdf -keylen 16 -kdfopt digest:SHA256 \
+ openssl kdf -keylen 16 -kdfopt digest:SHA2-256 \
-kdfopt hexkey:0102030405 \
-kdfopt hexxcghash:06090A \
-kdfopt hexsession_id:01020304 \
@@ -134,7 +134,7 @@ Use scrypt to create a hex-encoded derived key from a password and salt:
openssl kdf -keylen 64 -kdfopt pass:password -kdfopt salt:NaCl \
-kdfopt N:1024 -kdfopt r:8 -kdfopt p:16 \
- -kdfopt maxmem_bytes:10485760 id-scrypt
+ -kdfopt maxmem_bytes:10485760 SCRYPT
=head1 NOTES
diff --git a/doc/man7/EVP_KDF-KB.pod b/doc/man7/EVP_KDF-KB.pod
index bbfd56304c..8b1b350759 100644
--- a/doc/man7/EVP_KDF-KB.pod
+++ b/doc/man7/EVP_KDF-KB.pod
@@ -80,7 +80,7 @@ Label "label", and Context "context".
EVP_KDF_free(kdf);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
- "SHA256", 0);
+ "SHA2-256", 0);
*p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
"HMAC", 0);
*p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
diff --git a/doc/man7/EVP_KDF-SCRYPT.pod b/doc/man7/EVP_KDF-SCRYPT.pod
index 570f60e2f3..1459d07cfa 100644
--- a/doc/man7/EVP_KDF-SCRYPT.pod
+++ b/doc/man7/EVP_KDF-SCRYPT.pod
@@ -34,7 +34,7 @@ may be used by scrypt defaults to 1025 MiB.
=head2 Identity
-"ID-SCRYPT" is the name for this implementation; it
+"SCRYPT" is the name for this implementation; it
can be used with the EVP_KDF_fetch() function.
=head2 Supported parameters
@@ -65,7 +65,7 @@ Both r and p are parameters of type B<uint32_t>.
A context for scrypt can be obtained by calling:
- EVP_KDF *kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL);
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
The output length of an scrypt key derivation is specified via the
@@ -81,7 +81,7 @@ This example derives a 64-byte long test vector using scrypt with the password
unsigned char out[64];
OSSL_PARAM params[6], *p = params;
- kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL);
+ kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
kctx = EVP_KDF_CTX_new(kdf);
EVP_KDF_free(kdf);
diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index 0801a19781..43c10262ee 100644
--- a/doc/man7/EVP_MAC-KMAC.pod
+++ b/doc/man7/EVP_MAC-KMAC.pod
@@ -16,9 +16,9 @@ properties, to be used with EVP_MAC_fetch():
=over 4
-=item "KMAC128", "default=yes"
+=item "KMAC-128", "default=yes"
-=item "KMAC256", "default=yes"
+=item "KMAC-256", "default=yes"
=back
diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod
index 1a998e8ac1..c54e30e141 100644
--- a/doc/man7/EVP_MAC-Poly1305.pod
+++ b/doc/man7/EVP_MAC-Poly1305.pod
@@ -15,7 +15,7 @@ used with EVP_MAC_fetch():
=over 4
-=item "Poly1305", "default=yes"
+=item "POLY1305", "default=yes"
=back
diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod
index 40eba8d498..50d09c159b 100644
--- a/doc/man7/EVP_MAC-Siphash.pod
+++ b/doc/man7/EVP_MAC-Siphash.pod
@@ -15,7 +15,7 @@ used with EVP_MAC_fetch():
=over 4
-=item "Siphash", "default=yes"
+=item "SIPHASH", "default=yes"
=back
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
index f13418d0d0..c3405b6f22 100644
--- a/doc/man7/provider.pod
+++ b/doc/man7/provider.pod
@@ -216,42 +216,45 @@ In this case an algorithm implementation is implicitly fetched using
default search criteria and an algorithm name that is consistent with
the type of EVP_PKEY being used.
-=head1 OPENSSL PROVIDERS
+=head3 Algorithm naming
-OpenSSL comes with a set of providers.
-All the algorithm names mentioned can be used as an algorithm
-identifier to the appropriate fetching function.
+Algorithm names are case insensitive. Any particular algorithm can have multiple
+aliases associated with it. The canonical OpenSSL naming scheme follows this
+format:
-=head2 Default provider
+ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]
-The default provider is built in as part of the F<libcrypto> library.
-Should it be needed (if other providers are loaded and offer
-implementations of the same algorithms), the property "default=yes"
-can be used as a search criterion for these implementations.
+VERSION is only present if there are multiple versions of an algorithm (e.g.
+MD2, MD4, MD5). It may be omitted if there is only one version.
-It currently offers the following named algorithms:
+SUBNAME may be present where multiple algorithms are combined together,
+e.g. MD5-SHA1.
-=over 4
+SIZE is only present if multiple versions of an algorithm exist with different
+sizes (e.g. AES-128-CBC, AES-256-CBC)
-=item Digests
+MODE is only present where applicable.
-SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
-SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256, SM3,
-BLAKE2b512, BLAKE2s256, KMAC128, KMAC256, MD5, MD5-SHA1
+Other aliases may exist for example where standards bodies or common practice
+use alternative names or names that OpenSSL has used historically.
-=item Symmetric ciphers
+=head1 OPENSSL PROVIDERS
-AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
-AES-128-CBC, AES-256-OFB, AES-192-OFB, AES-128-OFB, AES-256-CFB,
-AES-192-CFB, AES-128-CFB, AES-256-CFB1, AES-192-CFB1, AES-128-CFB1,
-AES-256-CFB8, AES-192-CFB8, AES-128-CFB8, AES-256-CTR, AES-192-CTR,
-AES-128-CTR, id-aes256-GCM, id-aes192-GCM, id-aes128-GCM
+OpenSSL comes with a set of providers.
-=item Key Exchange
+The algorithms available in each of these providers may vary due to build time
+configuration options. The L<openssl-list(1)> command can be used to list the
+currently available algorithms.
-dhKeyAgreement
+The names of the algorithms shown from L<openssl-list(1)> can be used as an
+algorithm identifier to the appropriate fetching function.
-=back
+=head2 Default provider
+
+The default provider is built in as part of the F<libcrypto> library.
+Should it be needed (if other providers are loaded and offer
+implementations of the same algorithms), the property "default=yes"
+can be used as a search criterion for these implementations.
=head2 FIPS provider
@@ -262,22 +265,6 @@ Should it be needed (if other providers are loaded and offer
implementations of the same algorithms), the property "fips=yes" can
be used as a search criterion for these implementations.
-It currently offers the following FIPS approved named algorithms:
-
-=over 4
-
-=item Digests
-
-SHA1, SHA224, SHA256, SHA384, SHA512, SHA512-224, SHA512-256,
-SHA3-224, SHA3-256, SHA3-384, SHA3-512, KMAC128, KMAC256
-
-=item Symmetric ciphers
-
-AES-256-ECB, AES-192-ECB, AES-128-ECB, AES-256-CBC, AES-192-CBC,
-AES-128-CBC, AES-256-CTR, AES-192-CTR, AES-128-CTR
-
-=back
-
=head2 Legacy provider
The legacy provider is a dynamically loadable module, and must therefore
@@ -287,23 +274,13 @@ Should it be needed (if other providers are loaded and offer
implementations of the same algorithms), the property "legacy=yes" can be
used as a search criterion for these implementations.
-It currently offers the following named algorithms:
-
-=over 4
-
-=item Digest algorithms:
-
-RIPEMD160, MD2, MD4, MDC2, whirlpool.
-
-=back
-
=head1 EXAMPLES
=head2 Fetching
-Fetch any available implementation of SHA256 in the default context:
+Fetch any available implementation of SHA2-256 in the default context:
- EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", NULL);
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", NULL);
...
EVP_MD_meth_free(md);
@@ -313,34 +290,34 @@ Fetch any available implementation of AES-128-CBC in the default context:
...
EVP_CIPHER_meth_free(cipher);
-Fetch an implementation of SHA256 from the default provider in the default
+Fetch an implementation of SHA2-256 from the default provider in the default
context:
- EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=yes");
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "default=yes");
...
EVP_MD_meth_free(md);
-Fetch an implementation of SHA256 that is not from the default provider in the
+Fetch an implementation of SHA2-256 that is not from the default provider in the
default context:
- EVP_MD *md = EVP_MD_fetch(NULL, "SHA256", "default=no");
+ EVP_MD *md = EVP_MD_fetch(NULL, "SHA2-256", "default=no");
...
EVP_MD_meth_free(md);
-Fetch an implementation of SHA256 from the default provider in the specified
+Fetch an implementation of SHA2-256 from the default provider in the specified
context:
- EVP_MD *md = EVP_MD_fetch(ctx, "SHA256", "default=yes");
+ EVP_MD *md = EVP_MD_fetch(ctx, "SHA2-256", "default=yes");
...
EVP_MD_meth_free(md);
Load the legacy provider into the default context and then fetch an
-implementation of whirlpool from it:
+implementation of WHIRLPOOL from it:
/* This only needs to be done once - usually at application start up */
OSSL_PROVIDER *legacy = OSSL_PROVIDER_load(NULL, "legacy");
- EVP_MD *md = EVP_MD_fetch(NULL, "whirlpool", "legacy=yes");
+ EVP_MD *md = EVP_MD_fetch(NULL, "WHIRLPOOL", "legacy=yes");
...
EVP_MD_meth_free(md);
@@ -355,7 +332,7 @@ other providers:
OSSL_PROVIDER *default = OSSL_PROVIDER_load(NULL, "default");
EVP_MD *md_whirlpool = EVP_MD_fetch(NULL, "whirlpool", NULL);
- EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
+ EVP_MD *md_sha256 = EVP_MD_fetch(NULL, "SHA2-256", NULL);
...
EVP_MD_meth_free(md_whirlpool);
EVP_MD_meth_free(md_sha256);
diff --git a/include/openssl/core_names.h b/include/openssl/core_names.h
index cdc493bae1..1e8b764fb4 100644
--- a/include/openssl/core_names.h
+++ b/include/openssl/core_names.h
@@ -85,8 +85,8 @@ extern "C" {
/* Known DIGEST names (not a complete list) */
#define OSSL_DIGEST_NAME_MD5 "MD5"
-#define OSSL_DIGEST_NAME_KECCAK_KMAC128 "KECCAK_KMAC128"
-#define OSSL_DIGEST_NAME_KECCAK_KMAC256 "KECCAK_KMAC256"
+#define OSSL_DIGEST_NAME_KECCAK_KMAC128 "KECCAK-KMAC-128"
+#define OSSL_DIGEST_NAME_KECCAK_KMAC256 "KECCAK-KMAC-256"
/* MAC parameters */
#define OSSL_MAC_PARAM_KEY "key" /* octet string */
@@ -141,7 +141,7 @@ extern "C" {
/* Known KDF names */
#define OSSL_KDF_NAME_HKDF "HKDF"
#define OSSL_KDF_NAME_PBKDF2 "PBKDF2"
-#define OSSL_KDF_NAME_SCRYPT "id-scrypt"
+#define OSSL_KDF_NAME_SCRYPT "SCRYPT"
#define OSSL_KDF_NAME_SSHKDF "SSHKDF"
#define OSSL_KDF_NAME_SSKDF "SSKDF"
#define OSSL_KDF_NAME_TLS1_PRF "TLS1-PRF"
diff --git a/providers/defltprov.c b/providers/defltprov.c
index ceb3fd0896..354c7a4a6d 100644
--- a/providers/defltprov.c
+++ b/providers/defltprov.c
@@ -73,6 +73,9 @@ static int deflt_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[])
* We add diverse other names where applicable, such as the names that
* NIST uses, or that are used for ASN.1 OBJECT IDENTIFIERs, or names
* we have used historically.
+ *
+ * Algorithm names are case insensitive, but we use all caps in our "canonical"
+ * names for consistency.
*/
static const OSSL_ALGORITHM deflt_digests[] = {
/* Our primary name:NIST name[:our older names] */
@@ -93,11 +96,11 @@ static const OSSL_ALGORITHM deflt_digests[] = {
{ "SHA3-512", "default=yes", sha3_512_functions },
/*
- * KECCAK_KMAC128 and KECCAK_KMAC256 as hashes are mostly useful for
- * the KMAC128 and KMAC256.
+ * KECCAK-KMAC-128 and KECCAK-KMAC-256 as hashes are mostly useful for
+ * the KMAC-128 and KMAC-256.
*/
- { "KECCAK_KMAC128", "default=yes", keccak_kmac_128_functions },
- { "KECCAK_KMAC256", "default=yes", keccak_kmac_256_functions },
+ { "KECCAK-KMAC-128:KECCAK-KMAC128", "default=yes", keccak_kmac_128_functions },
+ { "KECCAK-KMAC-256:KECCAK-KMAC256", "default=yes", keccak_kmac_256_functions },
/* Our primary name:NIST name */
{ "SHAKE-128:SHAKE128", "default=yes", shake_128_functions },
@@ -111,8 +114,8 @@ static const OSSL_ALGORITHM deflt_digests[] = {
* If we assume that "2b" and "2s" are versions, that pattern
* fits with ours. We also add our historical names.
*/
- { "BLAKE2s-256:BLAKE2s256", "default=yes", blake2s256_functions },
- { "BLAKE2b-512:BLAKE2b512", "default=yes", blake2b512_functions },
+ { "BLAKE2S-256:BLAKE2s256", "default=yes", blake2s256_functions },
+ { "BLAKE2B-512:BLAKE2b512", "default=yes", blake2b512_functions },
#endif /* OPENSSL_NO_BLAKE2 */
#ifndef OPENSSL_NO_SM3
@@ -314,21 +317,21 @@ static const OSSL_ALGORITHM deflt_ciphers[] = {
static const OSSL_ALGORITHM deflt_macs[] = {
#ifndef OPENSSL_NO_BLAKE2
- { "BLAKE2bMAC", "default=yes", blake2bmac_functions },
- { "BLAKE2sMAC", "default=yes", blake2smac_functions },
+ { "BLAKE2BMAC", "default=yes", blake2bmac_functions },
+ { "BLAKE2SMAC", "default=yes", blake2smac_functions },
#endif
#ifndef OPENSSL_NO_CMAC
{ "CMAC", "default=yes", cmac_functions },
#endif
{ "GMAC", "default=yes", gmac_functions },
{ "HMAC", "default=yes", hmac_functions },
- { "KMAC128", "default=yes", kmac128_functions },
- { "KMAC256", "default=yes", kmac256_functions },
+ { "KMAC-128:KMAC128", "default=yes", kmac128_functions },
+ { "KMAC-256:KMAC256", "default=yes", kmac256_functions },
#ifndef OPENSSL_NO_SIPHASH
- { "SipHash", "default=yes", siphash_functions },
+ { "SIPHASH", "default=yes", siphash_functions },
#endif
#ifndef OPENSSL_NO_POLY1305
- { "Poly1305", "default=yes", poly1305_functions },
+ { "POLY1305", "default=yes", poly1305_functions },
#endif
{ NULL, NULL, NULL }
};
diff --git a/providers/fips/fipsprov.c b/providers/fips/fipsprov.c
index 05e5dd4a49..a12163fa97 100644
--- a/providers/fips/fipsprov.c
+++ b/providers/fips/fipsprov.c
@@ -349,11 +349,11 @@ static const OSSL_ALGORITHM fips_digests[] = {
{ "SHA3-384", "fips=yes", sha3_384_functions },
{ "SHA3-512", "fips=yes", sha3_512_functions },
/*
- * KECCAK_KMAC128 and KECCAK_KMAC256 as hashes are mostly useful for
+ * KECCAK-KMAC-128 and KECCAK-KMAC-256 as hashes are mostly useful for
* KMAC128 and KMAC256.
*/
- { "KECCAK_KMAC128", "fips=yes", keccak_kmac_128_functions },
- { "KECCAK_KMAC256", "fips=yes", keccak_kmac_256_functions },
+ { "KECCAK-KMAC-128:KECCAK-KMAC128", "fips=yes", keccak_kmac_128_functions },
+ { "KECCAK-KMAC-256:KECCAK-KMAC256", "fips=yes", keccak_kmac_256_functions },
{ NULL, NULL, NULL }
};
@@ -402,8 +402,8 @@ static const OSSL_ALGORITHM fips_macs[] = {
#endif
{ "GMAC", "fips=yes", gmac_functions },
{ "HMAC", "fips=yes", hmac_functions },
- { "KMAC128", "fips=yes", kmac128_functions },
- { "KMAC256", "fips=yes", kmac256_functions },
+ { "KMAC-128:KMAC128", "fips=yes", kmac128_functions },
+ { "KMAC-256:KMAC256", "fips=yes", kmac256_functions },
{ NULL, NULL, NULL }
};
diff --git a/providers/legacyprov.c b/providers/legacyprov.c
index 11a050e203..5937328638 100644
--- a/providers/legacyprov.c
+++ b/providers/legacyprov.c
@@ -68,11 +68,11 @@ static const OSSL_ALGORITHM legacy_digests[] = {
#endif /* OPENSSL_NO_MDC2 */
#ifndef OPENSSL_NO_WHIRLPOOL
- { "whirlpool", "legacy=yes", wp_functions },
+ { "WHIRLPOOL", "legacy=yes", wp_functions },
#endif /* OPENSSL_NO_WHIRLPOOL */
#ifndef OPENSSL_NO_RMD160
- { "RIPEMD160:RIPEMD:RMD160", "legacy=yes", ripemd160_functions },
+ { "RIPEMD-160:RIPEMD160:RIPEMD:RMD160", "legacy=yes", ripemd160_functions },
#endif /* OPENSSL_NO_RMD160 */
{ NULL, NULL, NULL }
More information about the openssl-commits
mailing list