diff options
Diffstat (limited to 'doc/man7/EVP_KDF-SSHKDF.pod')
| -rw-r--r-- | doc/man7/EVP_KDF-SSHKDF.pod | 159 |
1 files changed, 159 insertions, 0 deletions
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<SSHKDF> KDF through the B<EVP_KDF> 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<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string> + +=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string> + +=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string> + +These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. + +=item B<OSSL_KDF_PARAM_SSHKDF_XCGHASH> ("xcghash") <octet string> + +=item B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID> ("session_id") <octet string> + +These parameters set the respective values for the KDF. +If a value is already set, the contents are replaced. + +=item B<OSSL_KDF_PARAM_SSHKDF_TYPE> ("type") <int> + +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<keylen> +parameter to the L<EVP_KDF-derive(3)> function. +Since the SSHKDF output length is variable, calling L<EVP_KDF-size()> +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<EVP_KDF-derive(3)> 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<EVP_KDF>, +L<EVP_KDF-CTX_new_id(3)>, +L<EVP_KDF-CTX_free(3)>, +L<EVP_KDF-ctrl(3)>, +L<EVP_KDF-size(3)>, +L<EVP_KDF-derive(3)>, +L<EVP_KDF(3)/PARAMETERS> + +=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<https://www.openssl.org/source/license.html>. + +=cut + |