public/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation updates due to naming tweaks

Browse source 
Also documents our new canonical naming.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10092)
This commit is contained in:
Matt Caswell 2019-10-04 12:46:33 +01:00
parent cc35c3ed8f
commit e44192d14b
7 changed files with 56 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

16
doc/man1/openssl-kdf.pod
View file

@ -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

2
doc/man7/EVP_KDF-KB.pod
View file

@ -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,

6
doc/man7/EVP_KDF-SCRYPT.pod
View file

@ -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);

4
doc/man7/EVP_MAC-KMAC.pod
View file

@ -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

2
doc/man7/EVP_MAC-Poly1305.pod
View file

@ -15,7 +15,7 @@ used with EVP_MAC_fetch():
=over 4
=item "Poly1305", "default=yes"
=item "POLY1305", "default=yes"
=back

2
doc/man7/EVP_MAC-Siphash.pod
View file

@ -15,7 +15,7 @@ used with EVP_MAC_fetch():
=over 4
=item "Siphash", "default=yes"
=item "SIPHASH", "default=yes"
=back

103
doc/man7/provider.pod
View file

@ -216,11 +216,38 @@ 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.
=head3 Algorithm naming
Algorithm names are case insensitive. Any particular algorithm can have multiple
aliases associated with it. The canonical OpenSSL naming scheme follows this
format:
ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?]
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.
SUBNAME may be present where multiple algorithms are combined together,
e.g. MD5-SHA1.
SIZE is only present if multiple versions of an algorithm exist with different
sizes (e.g. AES-128-CBC, AES-256-CBC)
MODE is only present where applicable.
Other aliases may exist for example where standards bodies or common practice
use alternative names or names that OpenSSL has used historically.
=head1 OPENSSL PROVIDERS
OpenSSL comes with a set of providers.
All the algorithm names mentioned can be used as an algorithm
identifier to the appropriate fetching function.
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.
The names of the algorithms shown from L<openssl-list(1)> can be used as an
algorithm identifier to the appropriate fetching function.
=head2 Default provider
@ -229,30 +256,6 @@ 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.
It currently offers the following named algorithms:
=over 4
=item Digests
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
=item Symmetric ciphers
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
=item Key Exchange
dhKeyAgreement
=back
=head2 FIPS provider
The FIPS provider is a dynamically loadable module, and must therefore
@ -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);