1=pod 2 3=head1 NAME 4 5EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9Support for computing the B<TLS1> PRF through the B<EVP_KDF> API. 10 11The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to 12and including TLS 1.2. 13 14The output is considered to be keying material. 15 16=head2 Identity 17 18"TLS1-PRF" is the name for this implementation; it 19can be used with the EVP_KDF_fetch() function. 20 21=head2 Supported parameters 22 23The supported parameters are: 24 25=over 4 26 27=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 28 29=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 30 31These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 32 33The B<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest 34associated with the TLS PRF. 35EVP_md5_sha1() is treated as a special case which uses the 36PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. 37 38=item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string> 39 40This parameter sets the secret value of the TLS PRF. 41Any existing secret value is replaced. 42 43=item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string> 44 45This parameter sets the context seed. 46The length of the context seed cannot exceed 1024 bytes; 47this should be more than enough for any normal use of the TLS PRF. 48 49=back 50 51The OpenSSL FIPS provider also supports the following parameters: 52 53=over 4 54 55=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 56 57A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 58This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" 59related parameter is set to 0 and the check fails. 60 61=item "ems_check" (B<OSSL_KDF_PARAM_FIPS_EMS_CHECK>) <integer> 62 63The default value of 1 causes an error during EVP_KDF_derive() if 64"master secret" is used instead of "extended master secret" Setting this to zero 65will ignore the error and set the approved "fips-indicator" to 0. 66This option breaks FIPS compliance if it causes the approved "fips-indicator" 67to return 0. 68 69=item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <integer> 70 71The default value of 1 causes an error during EVP_KDF_CTX_set_params() if 72used digest is not approved. 73Setting this to zero will ignore the error and set the approved 74"fips-indicator" to 0. 75This option breaks FIPS compliance if it causes the approved "fips-indicator" 76to return 0. 77 78According to SP 800-135r1, the following are approved digest algorithms: 79SHA2-256, SHA2-384, SHA2-512. 80 81=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 82 83The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 84length of used key-derivation key (B<OSSL_KDF_PARAM_SECRET>) is shorter than 112 85bits. 86Setting this to zero will ignore the error and set the approved 87"fips-indicator" to 0. 88This option breaks FIPS compliance if it causes the approved "fips-indicator" 89to return 0. 90 91=back 92 93=head1 NOTES 94 95A context for the TLS PRF can be obtained by calling: 96 97 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); 98 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 99 100The digest, secret value and seed must be set before a key is derived otherwise 101an error will occur. 102 103The output length of the PRF is specified by the I<keylen> parameter to the 104EVP_KDF_derive() function. 105 106=head1 EXAMPLES 107 108This example derives 10 bytes using SHA-256 with the secret key "secret" 109and seed value "seed": 110 111 EVP_KDF *kdf; 112 EVP_KDF_CTX *kctx; 113 unsigned char out[10]; 114 OSSL_PARAM params[4], *p = params; 115 116 kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); 117 kctx = EVP_KDF_CTX_new(kdf); 118 EVP_KDF_free(kdf); 119 120 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 121 SN_sha256, strlen(SN_sha256)); 122 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 123 "secret", (size_t)6); 124 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, 125 "seed", (size_t)4); 126 *p = OSSL_PARAM_construct_end(); 127 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 128 error("EVP_KDF_derive"); 129 } 130 EVP_KDF_CTX_free(kctx); 131 132=head1 CONFORMING TO 133 134RFC 2246, RFC 5246 and NIST SP 800-135 r1 135 136=head1 SEE ALSO 137 138L<EVP_KDF(3)>, 139L<EVP_KDF_CTX_new(3)>, 140L<EVP_KDF_CTX_free(3)>, 141L<EVP_KDF_CTX_set_params(3)>, 142L<EVP_KDF_derive(3)>, 143L<EVP_KDF(3)/PARAMETERS> 144 145=head1 HISTORY 146 147This functionality was added in OpenSSL 3.0. 148 149=head1 COPYRIGHT 150 151Copyright 2018-2024 The OpenSSL Project Authors. All Rights Reserved. 152 153Licensed under the Apache License 2.0 (the "License"). You may not use 154this file except in compliance with the License. You can obtain a copy 155in the file LICENSE in the source distribution or at 156L<https://www.openssl.org/source/license.html>. 157 158=cut 159