From: Pauli Date: Mon, 2 Sep 2019 03:58:22 +0000 (+1000) Subject: Update KDF documentation (section 7) X-Git-Tag: openssl-3.0.0-alpha1~1463 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=ccd7115a4158a34008975ae83c3a733ba0be9911;p=oweals%2Fopenssl.git Update KDF documentation (section 7) Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/9662) --- diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod new file mode 100644 index 0000000000..746e7fb972 --- /dev/null +++ b/doc/man7/EVP_KDF-HKDF.pod @@ -0,0 +1,154 @@ +=pod + +=head1 NAME + +EVP_KDF-HKDF - The HKDF EVP_KDF implementation + +=head1 DESCRIPTION + +Support for computing the B KDF through the B API. + +The EVP_KDF-HKDF algorithm implements the HKDF key derivation function. +HKDF follows the "extract-then-expand" paradigm, where the KDF logically +consists of two modules. The first stage takes the input keying material +and "extracts" from it a fixed-length pseudorandom key K. The second stage +"expands" the key K into several additional pseudorandom keys (the output +of the KDF). + +=head2 Identity + +"HKDF" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("properties") + +=item B ("digest") + +=item B ("key") + +=item B ("salt") + +These parameters work as described in L. + +=item B ("info") + +This parameter sets the info value. +The length of the context info buffer cannot exceed 1024 bytes; +this should be more than enough for any normal use of HKDF. + +=item B ("mode") or + +This parameter sets the mode for the HKDF operation. +There are three modes that are currently defined: + +=over 4 + +=item B "EXTRACT_AND_EXPAND" + +This is the default mode. Calling L on an EVP_KDF_CTX set +up for HKDF will perform an extract followed by an expand operation in one go. +The derived key returned will be the result after the expand operation. The +intermediate fixed-length pseudorandom key K is not returned. + +In this mode the digest, key, salt and info values must be set before a key is +derived otherwise an error will occur. + +=item B "EXTRACT_ONLY" + +In this mode calling L will just perform the extract +operation. The value returned will be the intermediate fixed-length pseudorandom +key K. The C parameter must match the size of K, which can be looked +up by calling EVP_KDF_size() after setting the mode and digest. + +The digest, key and salt values must be set before a key is derived otherwise +an error will occur. + +=item B "EXPAND_ONLY" + +In this mode calling L will just perform the expand +operation. The input key should be set to the intermediate fixed-length +pseudorandom key K returned from a previous extract operation. + +The digest, key and info values must be set before a key is derived otherwise +an error will occur. + +=back + +=back + +=head1 NOTES + +A context for HKDF can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The output length of an HKDF expand operation is specified via the C +parameter to the L function. When using +EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C parameter must equal the size of +the intermediate fixed-length pseudorandom key otherwise an error will occur. +For that mode, the fixed output size can be looked up by calling EVP_KDF_size() +after setting the mode and digest on the C. + +=head1 EXAMPLES + +This example derives 10 bytes using SHA-256 with the secret key "secret", +salt value "salt" and info value "label": + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[10]; + OSSL_PARAM params[5], *p = params; + + kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, + "label", (size_t)5); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, + "salt", (size_t)4); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + + EVP_KDF_CTX_free(kctx); + +=head1 CONFORMING TO + +RFC 5869 + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod new file mode 100644 index 0000000000..311e0a3769 --- /dev/null +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -0,0 +1,104 @@ +=pod + +=head1 NAME + +EVP_KDF-PBKDF2 - The PBKDF2 EVP_KDF implementation + +=head1 DESCRIPTION + +Support for computing the B password-based KDF through the B +API. + +The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key +derivation function, as described in SP800-132; it derives a key from a password +using a salt and iteration count. + +=head2 Identity + +"PBKDF2" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("pass") + +=item B ("salt") + +=item B ("iter") + +This parameter has a default value of 2048. + +=item B ("properties") + +=item B ("digest") + +These parameters work as described in L. + +=item B ("pkcs5") + +This parameter can be used to enable or disable SP800-132 compliance checks. +Setting the mode to 0 enables the compliance checks. + +The checks performed are: + +=over 4 + +=item - the iteration count is at least 1000. + +=item - the salt length is at least 128 bits. + +=item - the derived key length is at least 112 bits. + +=back + +The default provider uses a default mode of 1 for backwards compatibility, +and the fips provider uses a default mode of 0. + +The value string is expected to be a decimal number 0 or 1. + +=back + +=head1 NOTES + +A typical application of this algorithm is to derive keying material for an +encryption algorithm from a password in the B, a salt in B, +and an iteration count. + +Increasing the B parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. + +No assumption is made regarding the given password; it is simply treated as a +byte sequence. + +=head1 CONFORMING TO + +SP800-132 + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF-SCRYPT.pod b/doc/man7/EVP_KDF-SCRYPT.pod new file mode 100644 index 0000000000..ce22aaa7ca --- /dev/null +++ b/doc/man7/EVP_KDF-SCRYPT.pod @@ -0,0 +1,142 @@ +=pod + +=head1 NAME + +EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation + +=head1 DESCRIPTION + +Support for computing the B password-based KDF through the B +API. + +The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key +derivation function, as described in RFC 7914. It is memory-hard in the sense +that it deliberately requires a significant amount of RAM for efficient +computation. The intention of this is to render brute forcing of passwords on +systems that lack large amounts of main memory (such as GPUs or ASICs) +computationally infeasible. + +scrypt provides three work factors that can be customized: N, r and p. N, which +has to be a positive power of two, is the general work factor and scales CPU +time in an approximately linear fashion. r is the block size of the internally +used hash function and p is the parallelization factor. Both r and p need to be +greater than zero. The amount of RAM that scrypt requires for its computation +is roughly (128 * N * r * p) bytes. + +In the original paper of Colin Percival ("Stronger Key Derivation via +Sequential Memory-Hard Functions", 2009), the suggested values that give a +computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = +2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for +this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5 +GHz), this computation takes about 3 seconds. When N, r or p are not specified, +they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that +may be used by scrypt defaults to 1025 MiB. + +=head2 Identity + +"ID-SCRYPT" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("pass") + +=item B ("salt") + +These parameters work as described in L. + +=item B ("n") + +=item B ("r") + +=item B ("p") + +These parameters configure the scrypt work factors N, r and p. +N is a parameter of type uint64_t. +Both r and p are parameters of type uint32_t. + +=back + +=head1 NOTES + +A context for scrypt can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The output length of an scrypt key derivation is specified via the +B parameter to the L function. + +=head1 EXAMPLES + +This example derives a 64-byte long test vector using scrypt with the password +"password", salt "NaCl" and N = 1024, r = 8, p = 16. + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[64]; + OSSL_PARAM params[6], *p = params; + + kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, + "password", (size_t)8); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, + "NaCl", (size_t)4); + *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024); + *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8); + *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + + { + const unsigned char expected[sizeof(out)] = { + 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00, + 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe, + 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30, + 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62, + 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88, + 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda, + 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d, + 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40 + }; + + assert(!memcmp(out, expected, sizeof(out))); + } + + EVP_KDF_CTX_free(kctx); + +=head1 CONFORMING TO + +RFC 7914 + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod new file mode 100644 index 0000000000..be69606701 --- /dev/null +++ b/doc/man7/EVP_KDF-SS.pod @@ -0,0 +1,197 @@ +=pod + +=head1 NAME + +EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation + +=head1 DESCRIPTION + +The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF). +SSKDF derives a key using input such as a shared secret key (that was generated +during the execution of a key establishment scheme) and fixedinfo. +SSKDF is also informally referred to as 'Concat KDF'. + +=head2 Auxiliary function + +The implementation uses a selectable auxiliary function H, which can be one of: + +=over 4 + +=item B + +=item B + +=item B + +=back + +Both the HMAC and KMAC implementations set the key using the 'salt' value. +The hash and HMAC also require the digest to be set. + +=head2 Identity + +"SSKDF" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("properties") + +=item B ("digest") + +=item B ("mac") + +=item B ("maclen") + +=item B ("salt") + +These parameters work as described in L. + +=item B ("key") + +This parameter set the shared secret that is used for key derivation. + +=item B ("info") + +This parameter sets an optional value for fixedinfo, also known as otherinfo. + +=back + +=head1 NOTES + +A context for SSKDF can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The output length of an SSKDF is specified via the C +parameter to the L function. + +=head1 EXAMPLES + +This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" +and fixedinfo value "label": + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[10]; + OSSL_PARAM params[4], *p = params; + + kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, + "label", (size_t)5); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + + EVP_KDF_CTX_free(kctx); + +This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", +fixedinfo value "label" and salt "salt": + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[10]; + OSSL_PARAM params[6], *p = params; + + kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, + SN_hmac, strlen(SN_hmac)); + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, + "label", (size_t)5); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, + "salt", (size_t)4); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + + EVP_KDF_CTX_free(kctx); + +This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" +fixedinfo value "label", salt of "salt" and KMAC outlen of 20: + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[10]; + OSSL_PARAM params[7], *p = params; + + kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, + SN_kmac128, strlen(SN_kmac128)); + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_KEY, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, + "label", (size_t)5); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, + "salt", (size_t)4); + *p++ = OSSL_PARAM_construct_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + + EVP_KDF_CTX_free(kctx); + +=head1 CONFORMING TO + +NIST SP800-56Cr1. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright +(c) 2019, Oracle and/or its affiliates. All rights reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod new file mode 100644 index 0000000000..0ed57626ef --- /dev/null +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -0,0 +1,159 @@ +=pod + +=head1 NAME + +EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation + +=head1 DESCRIPTION + +Support for computing the B KDF through the B API. + +The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function. +It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs, +encryption keys and integrity keys. +Five inputs are required to perform key derivation: The hashing function +(for example SHA256), the Initial Key, the Exchange Hash, the Session ID, +and the derivation key type. + +=head2 Identity + +"SSHKDF" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("properties") + +=item B ("digest") + +=item B ("key") + +These parameters work as described in L. + +=item B ("xcghash") + +=item B ("session_id") + +These parameters set the respective values for the KDF. +If a value is already set, the contents are replaced. + +=item B ("type") + +This parameter sets the type for the SSHHKDF operation. +There are six supported types: + +=over 4 + +=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV + +The Initial IV from client to server. +A single char of value 65 (ASCII char 'A'). + +=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI + +The Initial IV from server to client +A single char of value 66 (ASCII char 'B'). + +=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV + +The Encryption Key from client to server +A single char of value 67 (ASCII char 'C'). + +=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI + +The Encryption Key from server to client +A single char of value 68 (ASCII char 'D'). + +=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV + +The Integrity Key from client to server +A single char of value 69 (ASCII char 'E'). + +=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI + +The Integrity Key from client to server +A single char of value 70 (ASCII char 'F'). + +=back + +=back + +=head1 NOTES + +A context for SSHKDF can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The output length of the SSHKDF derivation is specified via the C +parameter to the L function. +Since the SSHKDF output length is variable, calling L +to obtain the requisite length is not meaningful. The caller must +allocate a buffer of the desired length, and pass that buffer to the +L function along with the desired length. + +=head1 EXAMPLES + +This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate +"xcghash" and "session_id" values: + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char key[1024] = "01234..."; + unsigned char xcghash[32] = "012345..."; + unsigned char session_id[32] = "012345..."; + unsigned char out[8]; + size_t outlen = sizeof(out); + OSSL_PARAM params[6], *p = params; + + kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, + key, (size_t)1024); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH, + xcghash, (size_t)32); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, + session_id, (size_t)32); + *p++ = OSSL_PARAM_construct_int(OSSL_KDF_PARAM_SSHKDF_TYPE, + EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) + /* Error */ + + if (EVP_KDF_derive(kctx, out, &outlen) <= 0) + /* Error */ + + +=head1 CONFORMING TO + +RFC 4253 + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut + diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod new file mode 100644 index 0000000000..a04f811792 --- /dev/null +++ b/doc/man7/EVP_KDF-TLS1_PRF.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation + +=head1 DESCRIPTION + +Support for computing the B PRF through the B API. + +The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to +and including TLS 1.2. + +=head2 Identity + +"TLS1-PRF" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("properties") + +=item B ("digest") + +These parameters work as described in L. + +The C parameter is used to set the message digest +associated with the TLS PRF. +EVP_md5_sha1() is treated as a special case which uses the +PRF algorithm using both B and B as used in TLS 1.0 and 1.1. + +=item B ("secret") + +This parameter sets the secret value of the TLS PRF. +Any existing secret value is replaced. + +=item B ("seed") + +This parameter sets the context seed. +The length of the context seed cannot exceed 1024 bytes; +this should be more than enough for any normal use of the TLS PRF. + +=back + +=head1 NOTES + +A context for the TLS PRF can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The digest, secret value and seed must be set before a key is derived otherwise +an error will occur. + +The output length of the PRF is specified by the C parameter to the +EVP_KDF_derive() function. + +=head1 EXAMPLES + +This example derives 10 bytes using SHA-256 with the secret key "secret" +and seed value "seed": + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[10]; + OSSL_PARAM params[4], *p = params; + + kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, + "seed", (size_t)4); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + EVP_KDF_CTX_free(kctx); + +=head1 CONFORMING TO + +RFC 2246, RFC 5246 and NIST SP 800-135 r1 + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF-X942.pod b/doc/man7/EVP_KDF-X942.pod new file mode 100644 index 0000000000..0b02f2d403 --- /dev/null +++ b/doc/man7/EVP_KDF-X942.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +EVP_KDF-X942 - The X9.42-2001 asn1 EVP_KDF implementation + +=head1 DESCRIPTION + +The EVP_KDF-X942 algorithm implements the key derivation function (X942KDF). +X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to +derive a key using input such as a shared secret key and other info. The other +info is DER encoded data that contains a 32 bit counter. + +=head2 Identity + +"X942KDF" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("properties") + +=item B ("digest") + +These parameters work as described in L. + +=item B ("key") + +The shared secret used for key derivation. This parameter sets the secret. + +=item B ("ukm") + +This parameter is an optional random string that is provided +by the sender called "partyAInfo". +In CMS this is the user keying material. + +=item B ("cekalg") + +This parameter sets the CEK wrapping algorithm name. + +=back + +=head1 NOTES + +A context for X942KDF can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The output length of an X942KDF is specified via the C +parameter to the L function. + +=head1 EXAMPLES + +This example derives 24 bytes, with the secret key "secret" and a random user +keying material: + + EVP_KDF_CTX *kctx; + EVP_KDF_CTX *kctx; + unsigned char out[192/8]; + unsignred char ukm[64]; + OSSL_PARAM params[5], *p = params; + + if (RAND_bytes(ukm, sizeof(ukm)) <= 0) + error("RAND_bytes"); + + kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL); + if (kctx == NULL) + error("EVP_KDF_fetch"); + kctx = EVP_KDF_CTX_new(kdf); + if (kctx == NULL) + error("EVP_KDF_CTX_new"); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_UKM, ukm, sizeof(ukm)); + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG, + SN_id_smime_alg_CMS3DESwrap, + strlen(SN_id_smime_alg_CMS3DESwrap)); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) + error("EVP_KDF_set_params"); + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) + error("EVP_KDF_derive"); + + EVP_KDF_CTX_free(kctx); + +=head1 CONFORMING TO + +RFC 2631 + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF-X963.pod b/doc/man7/EVP_KDF-X963.pod new file mode 100644 index 0000000000..537d8c5fc5 --- /dev/null +++ b/doc/man7/EVP_KDF-X963.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +EVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation + +=head1 DESCRIPTION + +The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). +X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to +derive a key using input such as a shared secret key and shared info. + +=head2 Identity + +"X963KDF" is the name for this implementation; it +can be used with the EVP_KDF_fetch() function. + +=head2 Supported parameters + +The supported parameters are: + +=over 4 + +=item B ("properties") + +=item B ("digest") + +These parameters work as described in L. + +=item B ("key") + +The shared secret used for key derivation. +This parameter sets the secret. + +=item B ("info") + +This parameter specifies an optional value for shared info. + +=back + +=head1 NOTES + +X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, +X963KDF appends the counter to the secret, whereas SSKDF prepends the counter. + +A context for X963KDF can be obtained by calling: + + EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); + EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); + +The output length of an X963KDF is specified via the C +parameter to the L function. + +=head1 EXAMPLES + +This example derives 10 bytes, with the secret key "secret" and sharedinfo +value "label": + + EVP_KDF *kdf; + EVP_KDF_CTX *kctx; + unsigned char out[10]; + OSSL_PARAM params[4], *p = params; + + kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); + kctx = EVP_KDF_CTX_new(kdf); + EVP_KDF_free(kdf); + + *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, + SN_sha256, strlen(SN_sha256)); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, + "secret", (size_t)6); + *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, + "label", (size_t)5); + *p = OSSL_PARAM_construct_end(); + if (EVP_KDF_set_params(kctx, params) <= 0) { + error("EVP_KDF_set_params"); + } + if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { + error("EVP_KDF_derive"); + } + + EVP_KDF_CTX_free(kctx); + +=head1 CONFORMING TO + +"SEC 1: Elliptic Curve Cryptography" + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_KDF_HKDF.pod b/doc/man7/EVP_KDF_HKDF.pod deleted file mode 100644 index c511c7c705..0000000000 --- a/doc/man7/EVP_KDF_HKDF.pod +++ /dev/null @@ -1,180 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_HKDF - The HKDF EVP_KDF implementation - -=head1 DESCRIPTION - -Support for computing the B KDF through the B API. - -The EVP_KDF_HKDF algorithm implements the HKDF key derivation function. -HKDF follows the "extract-then-expand" paradigm, where the KDF logically -consists of two modules. The first stage takes the input keying material -and "extracts" from it a fixed-length pseudorandom key K. The second stage -"expands" the key K into several additional pseudorandom keys (the output -of the KDF). - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -=item B - -=item B - -These controls work as described in L. - -=item B - -This control does not expect any arguments. - -Resets the context info buffer to zero length. - -=item B - -This control expects two arguments: C, C - -Sets the info value to the first B bytes of the buffer B. If a -value is already set, the contents of the buffer are appended to the existing -value. - -The total length of the context info buffer cannot exceed 1024 bytes; -this should be more than enough for any normal use of HKDF. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "info" - -The value string is used as is. - -=item "hexinfo" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects one argument: C - -Sets the mode for the HKDF operation. There are three modes that are currently -defined: - -=over 4 - -=item EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND - -This is the default mode. Calling L on an EVP_KDF_CTX set -up for HKDF will perform an extract followed by an expand operation in one go. -The derived key returned will be the result after the expand operation. The -intermediate fixed-length pseudorandom key K is not returned. - -In this mode the digest, key, salt and info values must be set before a key is -derived otherwise an error will occur. - -=item EVP_KDF_HKDF_MODE_EXTRACT_ONLY - -In this mode calling L will just perform the extract -operation. The value returned will be the intermediate fixed-length pseudorandom -key K. The C parameter must match the size of K, which can be looked -up by calling EVP_KDF_size() after setting the mode and digest. - -The digest, key and salt values must be set before a key is derived otherwise -an error will occur. - -=item EVP_KDF_HKDF_MODE_EXPAND_ONLY - -In this mode calling L will just perform the expand -operation. The input key should be set to the intermediate fixed-length -pseudorandom key K returned from a previous extract operation. - -The digest, key and info values must be set before a key is derived otherwise -an error will occur. - -=back - -EVP_KDF_ctrl_str() type string: "mode" - -The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY" -or "EXPAND_ONLY". - -=back - -=head1 NOTES - -A context for HKDF can be obtained by calling: - - EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF); - -The output length of an HKDF expand operation is specified via the C -parameter to the L function. When using -EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C parameter must equal the size of -the intermediate fixed-length pseudorandom key otherwise an error will occur. -For that mode, the fixed output size can be looked up by calling EVP_KDF_size() -after setting the mode and digest on the C. - -=head1 EXAMPLES - -This example derives 10 bytes using SHA-256 with the secret key "secret", -salt value "salt" and info value "label": - - EVP_KDF_CTX *kctx; - unsigned char out[10]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { - error("EVP_KDF_CTRL_SET_MD"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) { - error("EVP_KDF_CTRL_SET_SALT"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { - error("EVP_KDF_CTRL_SET_KEY"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) { - error("EVP_KDF_CTRL_ADD_HKDF_INFO"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - - EVP_KDF_CTX_free(kctx); - -=head1 CONFORMING TO - -RFC 5869 - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man7/EVP_KDF_PBKDF2.pod b/doc/man7/EVP_KDF_PBKDF2.pod deleted file mode 100644 index e914f3713c..0000000000 --- a/doc/man7/EVP_KDF_PBKDF2.pod +++ /dev/null @@ -1,107 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_PBKDF2 - The PBKDF2 EVP_KDF implementation - -=head1 DESCRIPTION - -Support for computing the B password-based KDF through the B -API. - -The EVP_KDF_PBKDF2 algorithm implements the PBKDF2 password-based key -derivation function, as described in SP800-132; it derives a key from a password -using a salt and iteration count. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -=item B - -=item B - -This control has a default value of 2048. - -=item B - -These controls work as described in L. - -=item B - -This control expects one argument: C - -This control can be used to enable or disable SP800-132 compliance checks. - -Setting the mode to 0 enables the compliance checks. - -The checks performed are: - -=over 4 - -=item - the iteration count is at least 1000. - -=item - the salt length is at least 128 bits. - -=item - the derived key length is at least 112 bits. - -=back - -The default provider uses a default mode of 1 for backwards compatibility, -and the fips provider uses a default mode of 0. - -EVP_KDF_ctrl_str() type string: "pkcs5" - -The value string is expected to be a decimal number 0 or 1. - -=back - -=head1 NOTES - -A typical application of this algorithm is to derive keying material for an -encryption algorithm from a password in the B, a salt in B, -and an iteration count. - -Increasing the B parameter slows down the algorithm which makes it -harder for an attacker to perform a brute force attack using a large number -of candidate passwords. - -No assumption is made regarding the given password; it is simply treated as a -byte sequence. - -=head1 CONFORMING TO - -SP800-132 - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -This functionality was added to OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man7/EVP_KDF_SCRYPT.pod b/doc/man7/EVP_KDF_SCRYPT.pod deleted file mode 100644 index aa50164e06..0000000000 --- a/doc/man7/EVP_KDF_SCRYPT.pod +++ /dev/null @@ -1,149 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_SCRYPT - The scrypt EVP_KDF implementation - -=head1 DESCRIPTION - -Support for computing the B password-based KDF through the B -API. - -The EVP_KDF_SCRYPT algorithm implements the scrypt password-based key -derivation function, as described in RFC 7914. It is memory-hard in the sense -that it deliberately requires a significant amount of RAM for efficient -computation. The intention of this is to render brute forcing of passwords on -systems that lack large amounts of main memory (such as GPUs or ASICs) -computationally infeasible. - -scrypt provides three work factors that can be customized: N, r and p. N, which -has to be a positive power of two, is the general work factor and scales CPU -time in an approximately linear fashion. r is the block size of the internally -used hash function and p is the parallelization factor. Both r and p need to be -greater than zero. The amount of RAM that scrypt requires for its computation -is roughly (128 * N * r * p) bytes. - -In the original paper of Colin Percival ("Stronger Key Derivation via -Sequential Memory-Hard Functions", 2009), the suggested values that give a -computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = -2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for -this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5 -GHz), this computation takes about 3 seconds. When N, r or p are not specified, -they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that -may be used by scrypt defaults to 1025 MiB. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -=item B - -These controls work as described in L. - -=item B - -=item B - -=item B - -B expects one argument: C - -B expects one argument: C - -B expects one argument: C - -These controls configure the scrypt work factors N, r and p. - -EVP_KDF_ctrl_str() type strings: "N", "r" and "p", respectively. - -The corresponding value strings are expected to be decimal numbers. - -=back - -=head1 NOTES - -A context for scrypt can be obtained by calling: - - EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT); - -The output length of an scrypt key derivation is specified via the -B parameter to the L function. - -=head1 EXAMPLES - -This example derives a 64-byte long test vector using scrypt with the password -"password", salt "NaCl" and N = 1024, r = 8, p = 16. - - EVP_KDF_CTX *kctx; - unsigned char out[64]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_PASS, "password", (size_t)8) <= 0) { - error("EVP_KDF_CTRL_SET_PASS"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "NaCl", (size_t)4) <= 0) { - error("EVP_KDF_CTRL_SET_SALT"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_N, (uint64_t)1024) <= 0) { - error("EVP_KDF_CTRL_SET_SCRYPT_N"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_R, (uint32_t)8) <= 0) { - error("EVP_KDF_CTRL_SET_SCRYPT_R"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_P, (uint32_t)16) <= 0) { - error("EVP_KDF_CTRL_SET_SCRYPT_P"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - - { - const unsigned char expected[sizeof(out)] = { - 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00, - 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe, - 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30, - 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62, - 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88, - 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda, - 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d, - 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40 - }; - - assert(!memcmp(out, expected, sizeof(out))); - } - - EVP_KDF_CTX_free(kctx); - -=head1 CONFORMING TO - -RFC 7914 - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man7/EVP_KDF_SS.pod b/doc/man7/EVP_KDF_SS.pod deleted file mode 100644 index 5c56fbd1b0..0000000000 --- a/doc/man7/EVP_KDF_SS.pod +++ /dev/null @@ -1,222 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_SS - The Single Step / One Step EVP_KDF implementation - -=head1 DESCRIPTION - -The EVP_KDF_SS algorithm implements the Single Step key derivation function (SSKDF). -SSKDF derives a key using input such as a shared secret key (that was generated -during the execution of a key establishment scheme) and fixedinfo. -SSKDF is also informally referred to as 'Concat KDF'. - -=head2 Auxiliary function - -The implementation uses a selectable auxiliary function H, which can be one of: - -=over 4 - -=item B - -=item B - -=item B - -=back - -Both the HMAC and KMAC implementations set the key using the 'salt' value. -The hash and HMAC also require the digest to be set. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -=item B - -=item B - -=item B - -These controls work as described in L. - -=item B - -This control expects two arguments: C, C - -The shared secret used for key derivation. This control sets the secret. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "secret" - -The value string is used as is. - -=item "hexsecret" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects two arguments: C, C - -An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "info" - -The value string is used as is. - -=item "hexinfo" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=back - -=head1 NOTES - -A context for SSKDF can be obtained by calling: - -EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); - -The output length of an SSKDF is specified via the C -parameter to the L function. - -=head1 EXAMPLES - -This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" -and fixedinfo value "label": - - EVP_KDF_CTX *kctx; - unsigned char out[10]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { - error("EVP_KDF_CTRL_SET_MD"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { - error("EVP_KDF_CTRL_SET_KEY"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) { - error("EVP_KDF_CTRL_SET_SSKDF_INFO"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - - EVP_KDF_CTX_free(kctx); - -This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", -fixedinfo value "label" and salt "salt": - - EVP_KDF_CTX *kctx; - unsigned char out[10]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) { - error("EVP_KDF_CTRL_SET_MAC"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { - error("EVP_KDF_CTRL_SET_MD"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { - error("EVP_KDF_CTRL_SET_KEY"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) { - error("EVP_KDF_CTRL_SET_SSKDF_INFO"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) { - error("EVP_KDF_CTRL_SET_SALT"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - - EVP_KDF_CTX_free(kctx); - -This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" -fixedinfo value "label", salt of "salt" and KMAC outlen of 20: - - EVP_KDF_CTX *kctx; - unsigned char out[10]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) { - error("EVP_KDF_CTRL_SET_MAC"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { - error("EVP_KDF_CTRL_SET_MD"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { - error("EVP_KDF_CTRL_SET_KEY"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) { - error("EVP_KDF_CTRL_SET_SSKDF_INFO"); - } - /* If not specified the salt will be set to a default value */ - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) { - error("EVP_KDF_CTRL_SET_SALT"); - } - /* If not specified the default size will be the size of the derived key */ - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) { - error("EVP_KDF_CTRL_SET_MAC_SIZE"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - - EVP_KDF_CTX_free(kctx); - - -=head1 CONFORMING TO - -NIST SP800-56Cr1. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -This functionality was added to OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright -(c) 2019, Oracle and/or its affiliates. All rights reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man7/EVP_KDF_SSHKDF.pod b/doc/man7/EVP_KDF_SSHKDF.pod deleted file mode 100644 index 04a646c866..0000000000 --- a/doc/man7/EVP_KDF_SSHKDF.pod +++ /dev/null @@ -1,175 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_SSHKDF - The SSHKDF EVP_KDF implementation - -=head1 DESCRIPTION - -Support for computing the B KDF through the B API. - -The EVP_KDF_SSHKDF algorithm implements the SSHKDF key derivation function. -It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs, -encryption keys and integrity keys. -Five inputs are required to perform key derivation: The hashing function -(for example SHA256), the Initial Key, the Exchange Hash, the Session ID, -and the derivation key type. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -=item B - -These controls work as described in L. - -=item B - -=item B - -These controls expect two arguments: C, C - -They set the respective values to the first B bytes of the buffer -B. If a value is already set, the contents are replaced. - -EVP_KDF_ctrl_str() takes two type strings for these controls: - -=over 4 - -=item "xcghash" - -=item "session_id" - -The value string is used as is. - -=item "hexxcghash" - -=item "hexsession_id" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects one argument: C - -Sets the type for the SSHHKDF operation. There are six supported types: - -=over 4 - -=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV - -The Initial IV from client to server. -A single char of value 65 (ASCII char 'A'). - -=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI - -The Initial IV from server to client -A single char of value 66 (ASCII char 'B'). - -=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV - -The Encryption Key from client to server -A single char of value 67 (ASCII char 'C'). - -=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI - -The Encryption Key from server to client -A single char of value 68 (ASCII char 'D'). - -=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV - -The Integrity Key from client to server -A single char of value 69 (ASCII char 'E'). - -=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI - -The Integrity Key from client to server -A single char of value 70 (ASCII char 'F'). - -=back - -EVP_KDF_ctrl_str() type string: "type" - -The value is a string of length one character. The only valid values -are the numerical values of the ASCII characters: "A" (65) to "F" (70). - -=back - -=head1 NOTES - -A context for SSHKDF can be obtained by calling: - - EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SSHKDF); - -The output length of the SSHKDF derivation is specified via the C -parameter to the L function. -Since the SSHKDF output length is variable, calling L -to obtain the requisite length is not meaningful. The caller must -allocate a buffer of the desired length, and pass that buffer to the -L function along with the desired length. - -=head1 EXAMPLES - -This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate -"xcghash" and "session_id" values: - - EVP_KDF_CTX *kctx; - unsigned char key[1024] = "01234..."; - unsigned char xcghash[32] = "012345..."; - unsigned char session_id[32] = "012345..."; - unsigned char out[8]; - size_t outlen = sizeof(out); - kctx = EVP_KDF_CTX_new_id(EVP_KDF_SSHKDF); - - if (EVP_KDF_CTX_set_md(kctx, EVP_sha256()) <= 0) - /* Error */ - if (EVP_KDF_CTX_set1_key(kctx, key, 1024) <= 0) - /* Error */ - if (EVP_KDF_CTX_set1_sshkdf_xcghash(kctx, xcghash, 32) <= 0) - /* Error */ - if (EVP_KDF_CTX_set1_sshkdf_session_id(kctx, session_id, 32) <= 0) - /* Error */ - if (EVP_KDF_CTX_set_sshkdf_type(kctx, - EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV) <= 0) - /* Error */ - if (EVP_KDF_derive(kctx, out, &outlen) <= 0) - /* Error */ - - -=head1 CONFORMING TO - -RFC 4253 - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut - diff --git a/doc/man7/EVP_KDF_TLS1_PRF.pod b/doc/man7/EVP_KDF_TLS1_PRF.pod deleted file mode 100644 index 02331ece5e..0000000000 --- a/doc/man7/EVP_KDF_TLS1_PRF.pod +++ /dev/null @@ -1,146 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_TLS1_PRF - The TLS1 PRF EVP_KDF implementation - -=head1 DESCRIPTION - -Support for computing the B PRF through the B API. - -The EVP_KDF_TLS1_PRF algorithm implements the PRF used by TLS versions up to -and including TLS 1.2. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -This control works as described in L. - -The C control is used to set the message digest associated -with the TLS PRF. EVP_md5_sha1() is treated as a special case which uses the -PRF algorithm using both B and B as used in TLS 1.0 and 1.1. - -=item B - -This control expects two arguments: C, C - -Sets the secret value of the TLS PRF to B bytes of the buffer B. -Any existing secret value is replaced. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "secret" - -The value string is used as is. - -=item "hexsecret" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control does not expect any arguments. - -Resets the context seed buffer to zero length. - -=item B - -This control expects two arguments: C, C - -Sets the seed to B bytes of B. If a seed is already set it is -appended to the existing value. - -The total length of the context seed buffer cannot exceed 1024 bytes; -this should be more than enough for any normal use of the TLS PRF. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "seed" - -The value string is used as is. - -=item "hexseed" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=back - -=head1 NOTES - -A context for the TLS PRF can be obtained by calling: - - EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL); - -The digest, secret value and seed must be set before a key is derived otherwise -an error will occur. - -The output length of the PRF is specified by the C parameter to the -EVP_KDF_derive() function. - -=head1 EXAMPLES - -This example derives 10 bytes using SHA-256 with the secret key "secret" -and seed value "seed": - - EVP_KDF_CTX *kctx; - unsigned char out[10]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF); - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { - error("EVP_KDF_CTRL_SET_MD"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_TLS_SECRET, - "secret", (size_t)6) <= 0) { - error("EVP_KDF_CTRL_SET_TLS_SECRET"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) { - error("EVP_KDF_CTRL_ADD_TLS_SEED"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - EVP_KDF_CTX_free(kctx); - -=head1 CONFORMING TO - -RFC 2246, RFC 5246 and NIST SP 800-135 r1 - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 COPYRIGHT - -Copyright 2018 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man7/EVP_KDF_X942.pod b/doc/man7/EVP_KDF_X942.pod deleted file mode 100644 index 644cad8cbe..0000000000 --- a/doc/man7/EVP_KDF_X942.pod +++ /dev/null @@ -1,150 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation - -=head1 DESCRIPTION - -The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF). -X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to -derive a key using input such as a shared secret key and other info. The other -info is DER encoded data that contains a 32 bit counter. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -This control works as described in L. - -=item B - -This control expects two arguments: C, C - -The shared secret used for key derivation. This control sets the secret. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "secret" - -The value string is used as is. - -=item "hexsecret" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects two arguments: C, C - -An optional random string that is provided by the sender called "partyAInfo". -In CMS this is the user keying material. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "ukm" - -The value string is used as is. - -=item "hexukm" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects one argument: C - -The CEK wrapping algorithm name. - -EVP_KDF_ctrl_str() type string: "cekalg" - -The value string is used as is. - -=back - -=head1 NOTES - -A context for X942KDF can be obtained by calling: - -EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942); - -The output length of an X942KDF is specified via the C -parameter to the L function. - -=head1 EXAMPLES - -This example derives 24 bytes, with the secret key "secret" and a random user -keying material: - - EVP_KDF_CTX *kctx; - unsigned char out[192/8]; - unsignred char ukm[64]; - - if (RAND_bytes(ukm, sizeof(ukm)) <= 0) - error("RAND_bytes"); - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942); - if (kctx == NULL) - error("EVP_KDF_CTX_new_id"); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) - error("EVP_KDF_CTRL_SET_MD"); - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) - error("EVP_KDF_CTRL_SET_KEY"); - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0) - error("EVP_KDF_CTRL_SET_UKM"); - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG, - SN_id_smime_alg_CMS3DESwrap) <= 0) - error("EVP_KDF_CTRL_SET_CEK_ALG"); - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) - error("EVP_KDF_derive"); - - EVP_KDF_CTX_free(kctx); - -=head1 CONFORMING TO - -RFC 2631 - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -This functionality was added to OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man7/EVP_KDF_X963.pod b/doc/man7/EVP_KDF_X963.pod deleted file mode 100644 index 130c9235a9..0000000000 --- a/doc/man7/EVP_KDF_X963.pod +++ /dev/null @@ -1,136 +0,0 @@ -=pod - -=head1 NAME - -EVP_KDF_X963 - The X9.63-2001 EVP_KDF implementation - -=head1 DESCRIPTION - -The EVP_KDF_X963 algorithm implements the key derivation function (X963KDF). -X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to -derive a key using input such as a shared secret key and shared info. - -=head2 Numeric identity - -B is the numeric identity for this implementation; it -can be used with the EVP_KDF_CTX_new_id() function. - -=head2 Supported controls - -The supported controls are: - -=over 4 - -=item B - -This control works as described in L. - -=item B - -This control expects two arguments: C, C - -The shared secret used for key derivation. This control sets the secret. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "secret" - -The value string is used as is. - -=item "hexsecret" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=item B - -This control expects two arguments: C, C - -An optional value for shared info. This control sets the shared info. - -EVP_KDF_ctrl_str() takes two type strings for this control: - -=over 4 - -=item "info" - -The value string is used as is. - -=item "hexinfo" - -The value string is expected to be a hexadecimal number, which will be -decoded before being passed on as the control value. - -=back - -=back - -=head1 NOTES - -X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, -X963KDF appends the counter to the secret, whereas SSKDF prepends the counter. - -A context for X963KDF can be obtained by calling: - -EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963); - -The output length of an X963KDF is specified via the C -parameter to the L function. - -=head1 EXAMPLES - -This example derives 10 bytes, with the secret key "secret" and sharedinfo -value "label": - - EVP_KDF_CTX *kctx; - unsigned char out[10]; - - kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963); - - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { - error("EVP_KDF_CTRL_SET_MD"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { - error("EVP_KDF_CTRL_SET_KEY"); - } - if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SHARED_INFO, "label", (size_t)5) <= 0) { - error("EVP_KDF_CTRL_SET_SHARED_INFO"); - } - if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { - error("EVP_KDF_derive"); - } - - EVP_KDF_CTX_free(kctx); - -=head1 CONFORMING TO - -"SEC 1: Elliptic Curve Cryptography" - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -This functionality was added to OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut