| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation
|
|---|
| 6 |
|
|---|
| 7 | =head1 DESCRIPTION
|
|---|
| 8 |
|
|---|
| 9 | Support for computing the B<SSHKDF> KDF through the B<EVP_KDF> API.
|
|---|
| 10 |
|
|---|
| 11 | The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function.
|
|---|
| 12 | It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs,
|
|---|
| 13 | encryption keys and integrity keys.
|
|---|
| 14 | Five inputs are required to perform key derivation: The hashing function
|
|---|
| 15 | (for example SHA256), the Initial Key, the Exchange Hash, the Session ID,
|
|---|
| 16 | and the derivation key type.
|
|---|
| 17 |
|
|---|
| 18 | =head2 Identity
|
|---|
| 19 |
|
|---|
| 20 | "SSHKDF" is the name for this implementation; it
|
|---|
| 21 | can be used with the EVP_KDF_fetch() function.
|
|---|
| 22 |
|
|---|
| 23 | =head2 Supported parameters
|
|---|
| 24 |
|
|---|
| 25 | The supported parameters are:
|
|---|
| 26 |
|
|---|
| 27 | =over 4
|
|---|
| 28 |
|
|---|
| 29 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
|
|---|
| 30 |
|
|---|
| 31 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
|
|---|
| 32 |
|
|---|
| 33 | =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
|
|---|
| 34 |
|
|---|
| 35 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
|
|---|
| 36 |
|
|---|
| 37 | =item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string>
|
|---|
| 38 |
|
|---|
| 39 | =item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string>
|
|---|
| 40 |
|
|---|
| 41 | These parameters set the respective values for the KDF.
|
|---|
| 42 | If a value is already set, the contents are replaced.
|
|---|
| 43 |
|
|---|
| 44 | =item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <UTF8 string>
|
|---|
| 45 |
|
|---|
| 46 | This parameter sets the type for the SSHKDF operation.
|
|---|
| 47 | There are six supported types:
|
|---|
| 48 |
|
|---|
| 49 | =over 4
|
|---|
| 50 |
|
|---|
| 51 | =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
|
|---|
| 52 |
|
|---|
| 53 | The Initial IV from client to server.
|
|---|
| 54 | A single char of value 65 (ASCII char 'A').
|
|---|
| 55 |
|
|---|
| 56 | =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
|
|---|
| 57 |
|
|---|
| 58 | The Initial IV from server to client
|
|---|
| 59 | A single char of value 66 (ASCII char 'B').
|
|---|
| 60 |
|
|---|
| 61 | =item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
|
|---|
| 62 |
|
|---|
| 63 | The Encryption Key from client to server
|
|---|
| 64 | A single char of value 67 (ASCII char 'C').
|
|---|
| 65 |
|
|---|
| 66 | =item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
|
|---|
| 67 |
|
|---|
| 68 | The Encryption Key from server to client
|
|---|
| 69 | A single char of value 68 (ASCII char 'D').
|
|---|
| 70 |
|
|---|
| 71 | =item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
|
|---|
| 72 |
|
|---|
| 73 | The Integrity Key from client to server
|
|---|
| 74 | A single char of value 69 (ASCII char 'E').
|
|---|
| 75 |
|
|---|
| 76 | =item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
|
|---|
| 77 |
|
|---|
| 78 | The Integrity Key from client to server
|
|---|
| 79 | A single char of value 70 (ASCII char 'F').
|
|---|
| 80 |
|
|---|
| 81 | =back
|
|---|
| 82 |
|
|---|
| 83 | =back
|
|---|
| 84 |
|
|---|
| 85 | =head1 NOTES
|
|---|
| 86 |
|
|---|
| 87 | A context for SSHKDF can be obtained by calling:
|
|---|
| 88 |
|
|---|
| 89 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
|
|---|
| 90 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
|
|---|
| 91 |
|
|---|
| 92 | The output length of the SSHKDF derivation is specified via the I<keylen>
|
|---|
| 93 | parameter to the L<EVP_KDF_derive(3)> function.
|
|---|
| 94 | Since the SSHKDF output length is variable, calling L<EVP_KDF_CTX_get_kdf_size(3)>
|
|---|
| 95 | to obtain the requisite length is not meaningful. The caller must
|
|---|
| 96 | allocate a buffer of the desired length, and pass that buffer to the
|
|---|
| 97 | L<EVP_KDF_derive(3)> function along with the desired length.
|
|---|
| 98 |
|
|---|
| 99 | =head1 EXAMPLES
|
|---|
| 100 |
|
|---|
| 101 | This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
|
|---|
| 102 | "xcghash" and "session_id" values:
|
|---|
| 103 |
|
|---|
| 104 | EVP_KDF *kdf;
|
|---|
| 105 | EVP_KDF_CTX *kctx;
|
|---|
| 106 | char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV;
|
|---|
| 107 | unsigned char key[1024] = "01234...";
|
|---|
| 108 | unsigned char xcghash[32] = "012345...";
|
|---|
| 109 | unsigned char session_id[32] = "012345...";
|
|---|
| 110 | unsigned char out[8];
|
|---|
| 111 | size_t outlen = sizeof(out);
|
|---|
| 112 | OSSL_PARAM params[6], *p = params;
|
|---|
| 113 |
|
|---|
| 114 | kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
|
|---|
| 115 | kctx = EVP_KDF_CTX_new(kdf);
|
|---|
| 116 | EVP_KDF_free(kdf);
|
|---|
| 117 |
|
|---|
| 118 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
|
|---|
| 119 | SN_sha256, strlen(SN_sha256));
|
|---|
| 120 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
|
|---|
| 121 | key, (size_t)1024);
|
|---|
| 122 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH,
|
|---|
| 123 | xcghash, (size_t)32);
|
|---|
| 124 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID,
|
|---|
| 125 | session_id, (size_t)32);
|
|---|
| 126 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE,
|
|---|
| 127 | &type, sizeof(type));
|
|---|
| 128 | *p = OSSL_PARAM_construct_end();
|
|---|
| 129 | if (EVP_KDF_derive(kctx, out, outlen, params) <= 0)
|
|---|
| 130 | /* Error */
|
|---|
| 131 |
|
|---|
| 132 |
|
|---|
| 133 | =head1 CONFORMING TO
|
|---|
| 134 |
|
|---|
| 135 | RFC 4253
|
|---|
| 136 |
|
|---|
| 137 | =head1 SEE ALSO
|
|---|
| 138 |
|
|---|
| 139 | L<EVP_KDF(3)>,
|
|---|
| 140 | L<EVP_KDF_CTX_new(3)>,
|
|---|
| 141 | L<EVP_KDF_CTX_free(3)>,
|
|---|
| 142 | L<EVP_KDF_CTX_set_params(3)>,
|
|---|
| 143 | L<EVP_KDF_CTX_get_kdf_size(3)>,
|
|---|
| 144 | L<EVP_KDF_derive(3)>,
|
|---|
| 145 | L<EVP_KDF(3)/PARAMETERS>
|
|---|
| 146 |
|
|---|
| 147 | =head1 HISTORY
|
|---|
| 148 |
|
|---|
| 149 | This functionality was added in OpenSSL 3.0.
|
|---|
| 150 |
|
|---|
| 151 | =head1 COPYRIGHT
|
|---|
| 152 |
|
|---|
| 153 | Copyright 2016-2022 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 154 |
|
|---|
| 155 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 156 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 157 | in the file LICENSE in the source distribution or at
|
|---|
| 158 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 159 |
|
|---|
| 160 | =cut
|
|---|
| 161 |
|
|---|
