Home | History | Annotate | Line # | Download | only in man7 
      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 The output is considered to be keying material.
     19 
     20 =head2 Identity
     21 
     22 "SSHKDF" is the name for this implementation; it
     23 can be used with the EVP_KDF_fetch() function.
     24 
     25 =head2 Supported parameters
     26 
     27 The supported parameters are:
     28 
     29 =over 4
     30 
     31 =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
     32 
     33 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
     34 
     35 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
     36 
     37 These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
     38 
     39 =item "xcghash" (B<OSSL_KDF_PARAM_SSHKDF_XCGHASH>) <octet string>
     40 
     41 =item "session_id" (B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID>) <octet string>
     42 
     43 These parameters set the respective values for the KDF.
     44 If a value is already set, the contents are replaced.
     45 
     46 =item "type" (B<OSSL_KDF_PARAM_SSHKDF_TYPE>) <UTF8 string>
     47 
     48 This parameter sets the type for the SSHKDF operation.
     49 There are six supported types:
     50 
     51 =over 4
     52 
     53 =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
     54 
     55 The Initial IV from client to server.
     56 A single char of value 65 (ASCII char 'A').
     57 
     58 =item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
     59 
     60 The Initial IV from server to client
     61 A single char of value 66 (ASCII char 'B').
     62 
     63 =item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
     64 
     65 The Encryption Key from client to server
     66 A single char of value 67 (ASCII char 'C').
     67 
     68 =item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
     69 
     70 The Encryption Key from server to client
     71 A single char of value 68 (ASCII char 'D').
     72 
     73 =item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
     74 
     75 The Integrity Key from client to server
     76 A single char of value 69 (ASCII char 'E').
     77 
     78 =item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
     79 
     80 The Integrity Key from client to server
     81 A single char of value 70 (ASCII char 'F').
     82 
     83 =back
     84 
     85 =back
     86 
     87 The OpenSSL FIPS provider also supports the following parameters:
     88 
     89 =over 4
     90 
     91 =item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
     92 
     93 A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
     94 This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check"
     95 related parameter is set to 0 and the check fails.
     96 
     97 =item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <integer>
     98 
     99 The default value of 1 causes an error during EVP_KDF_CTX_set_params() if
    100 used digest is not approved.
    101 Setting this to zero will ignore the error and set the approved
    102 "fips-indicator" to 0.
    103 This option breaks FIPS compliance if it causes the approved "fips-indicator"
    104 to return 0.
    105 
    106 According to SP 800-135r1, the following are approved digest algorithms: SHA-1,
    107 SHA2-224, SHA2-256, SHA2-384, SHA2-512.
    108 
    109 =item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer>
    110 
    111 The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the
    112 length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112
    113 bits.
    114 Setting this to zero will ignore the error and set the approved
    115 "fips-indicator" to 0.
    116 This option breaks FIPS compliance if it causes the approved "fips-indicator"
    117 to return 0.
    118 
    119 =back
    120 
    121 =head1 NOTES
    122 
    123 A context for SSHKDF can be obtained by calling:
    124 
    125  EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
    126  EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
    127 
    128 The output length of the SSHKDF derivation is specified via the I<keylen>
    129 parameter to the L<EVP_KDF_derive(3)> function.
    130 Since the SSHKDF output length is variable, calling L<EVP_KDF_CTX_get_kdf_size(3)>
    131 to obtain the requisite length is not meaningful. The caller must
    132 allocate a buffer of the desired length, and pass that buffer to the
    133 L<EVP_KDF_derive(3)> function along with the desired length.
    134 
    135 =head1 EXAMPLES
    136 
    137 This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
    138 "xcghash" and "session_id" values:
    139 
    140  EVP_KDF *kdf;
    141  EVP_KDF_CTX *kctx;
    142  char type = EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV;
    143  unsigned char key[1024] = "01234...";
    144  unsigned char xcghash[32] = "012345...";
    145  unsigned char session_id[32] = "012345...";
    146  unsigned char out[8];
    147  size_t outlen = sizeof(out);
    148  OSSL_PARAM params[6], *p = params;
    149 
    150  kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
    151  kctx = EVP_KDF_CTX_new(kdf);
    152  EVP_KDF_free(kdf);
    153 
    154  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
    155                                          SN_sha256, strlen(SN_sha256));
    156  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
    157                                           key, (size_t)1024);
    158  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH,
    159                                           xcghash, (size_t)32);
    160  *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_SESSION_ID,
    161                                           session_id, (size_t)32);
    162  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE,
    163                                          &type, sizeof(type));
    164  *p = OSSL_PARAM_construct_end();
    165  if (EVP_KDF_derive(kctx, out, outlen, params) <= 0)
    166      /* Error */
    167 
    168 
    169 =head1 CONFORMING TO
    170 
    171 RFC 4253
    172 
    173 =head1 SEE ALSO
    174 
    175 L<EVP_KDF(3)>,
    176 L<EVP_KDF_CTX_new(3)>,
    177 L<EVP_KDF_CTX_free(3)>,
    178 L<EVP_KDF_CTX_set_params(3)>,
    179 L<EVP_KDF_CTX_get_kdf_size(3)>,
    180 L<EVP_KDF_derive(3)>,
    181 L<EVP_KDF(3)/PARAMETERS>
    182 
    183 =head1 HISTORY
    184 
    185 This functionality was added in OpenSSL 3.0.
    186 
    187 =head1 COPYRIGHT
    188 
    189 Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
    190 
    191 Licensed under the Apache License 2.0 (the "License").  You may not use
    192 this file except in compliance with the License.  You can obtain a copy
    193 in the file LICENSE in the source distribution or at
    194 L<https://www.openssl.org/source/license.html>.
    195 
    196 =cut
    197 
    198