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