From: Matt Caswell Date: Fri, 4 Oct 2019 11:46:33 +0000 (+0100) Subject: Documentation updates due to naming tweaks X-Git-Tag: openssl-3.0.0-alpha1~922 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=e44192d14b0557538611de4018170d702c9709d7 Documentation updates due to naming tweaks Also documents our new canonical naming. Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/10092) --- 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. 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. 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 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 command can be used to list the +currently available algorithms. -dhKeyAgreement +The names of the algorithms shown from L 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 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);