1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation 6b077aed3SPierre Pronchery 7b077aed3SPierre Pronchery=head1 DESCRIPTION 8b077aed3SPierre Pronchery 9b077aed3SPierre ProncherySupport for computing the B<TLS1> PRF through the B<EVP_KDF> API. 10b077aed3SPierre Pronchery 11b077aed3SPierre ProncheryThe EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to 12b077aed3SPierre Proncheryand including TLS 1.2. 13b077aed3SPierre Pronchery 14*0d0c8621SEnji CooperThe output is considered to be keying material. 15*0d0c8621SEnji Cooper 16b077aed3SPierre Pronchery=head2 Identity 17b077aed3SPierre Pronchery 18b077aed3SPierre Pronchery"TLS1-PRF" is the name for this implementation; it 19b077aed3SPierre Proncherycan be used with the EVP_KDF_fetch() function. 20b077aed3SPierre Pronchery 21b077aed3SPierre Pronchery=head2 Supported parameters 22b077aed3SPierre Pronchery 23b077aed3SPierre ProncheryThe supported parameters are: 24b077aed3SPierre Pronchery 25b077aed3SPierre Pronchery=over 4 26b077aed3SPierre Pronchery 27b077aed3SPierre Pronchery=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 28b077aed3SPierre Pronchery 29b077aed3SPierre Pronchery=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 30b077aed3SPierre Pronchery 31b077aed3SPierre ProncheryThese parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 32b077aed3SPierre Pronchery 33b077aed3SPierre ProncheryThe B<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest 34b077aed3SPierre Proncheryassociated with the TLS PRF. 35b077aed3SPierre ProncheryEVP_md5_sha1() is treated as a special case which uses the 36b077aed3SPierre ProncheryPRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. 37b077aed3SPierre Pronchery 38b077aed3SPierre Pronchery=item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string> 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncheryThis parameter sets the secret value of the TLS PRF. 41b077aed3SPierre ProncheryAny existing secret value is replaced. 42b077aed3SPierre Pronchery 43b077aed3SPierre Pronchery=item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string> 44b077aed3SPierre Pronchery 45b077aed3SPierre ProncheryThis parameter sets the context seed. 46b077aed3SPierre ProncheryThe length of the context seed cannot exceed 1024 bytes; 47b077aed3SPierre Proncherythis should be more than enough for any normal use of the TLS PRF. 48b077aed3SPierre Pronchery 49b077aed3SPierre Pronchery=back 50b077aed3SPierre Pronchery 51b077aed3SPierre Pronchery=head1 NOTES 52b077aed3SPierre Pronchery 53b077aed3SPierre ProncheryA context for the TLS PRF can be obtained by calling: 54b077aed3SPierre Pronchery 55b077aed3SPierre Pronchery EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); 56b077aed3SPierre Pronchery EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 57b077aed3SPierre Pronchery 58b077aed3SPierre ProncheryThe digest, secret value and seed must be set before a key is derived otherwise 59b077aed3SPierre Proncheryan error will occur. 60b077aed3SPierre Pronchery 61b077aed3SPierre ProncheryThe output length of the PRF is specified by the I<keylen> parameter to the 62b077aed3SPierre ProncheryEVP_KDF_derive() function. 63b077aed3SPierre Pronchery 64b077aed3SPierre Pronchery=head1 EXAMPLES 65b077aed3SPierre Pronchery 66b077aed3SPierre ProncheryThis example derives 10 bytes using SHA-256 with the secret key "secret" 67b077aed3SPierre Proncheryand seed value "seed": 68b077aed3SPierre Pronchery 69b077aed3SPierre Pronchery EVP_KDF *kdf; 70b077aed3SPierre Pronchery EVP_KDF_CTX *kctx; 71b077aed3SPierre Pronchery unsigned char out[10]; 72b077aed3SPierre Pronchery OSSL_PARAM params[4], *p = params; 73b077aed3SPierre Pronchery 74b077aed3SPierre Pronchery kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); 75b077aed3SPierre Pronchery kctx = EVP_KDF_CTX_new(kdf); 76b077aed3SPierre Pronchery EVP_KDF_free(kdf); 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 79b077aed3SPierre Pronchery SN_sha256, strlen(SN_sha256)); 80b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 81b077aed3SPierre Pronchery "secret", (size_t)6); 82b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, 83b077aed3SPierre Pronchery "seed", (size_t)4); 84b077aed3SPierre Pronchery *p = OSSL_PARAM_construct_end(); 85b077aed3SPierre Pronchery if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 86b077aed3SPierre Pronchery error("EVP_KDF_derive"); 87b077aed3SPierre Pronchery } 88b077aed3SPierre Pronchery EVP_KDF_CTX_free(kctx); 89b077aed3SPierre Pronchery 90b077aed3SPierre Pronchery=head1 CONFORMING TO 91b077aed3SPierre Pronchery 92b077aed3SPierre ProncheryRFC 2246, RFC 5246 and NIST SP 800-135 r1 93b077aed3SPierre Pronchery 94b077aed3SPierre Pronchery=head1 SEE ALSO 95b077aed3SPierre Pronchery 96b077aed3SPierre ProncheryL<EVP_KDF(3)>, 97b077aed3SPierre ProncheryL<EVP_KDF_CTX_new(3)>, 98b077aed3SPierre ProncheryL<EVP_KDF_CTX_free(3)>, 99b077aed3SPierre ProncheryL<EVP_KDF_CTX_set_params(3)>, 100b077aed3SPierre ProncheryL<EVP_KDF_derive(3)>, 101b077aed3SPierre ProncheryL<EVP_KDF(3)/PARAMETERS> 102b077aed3SPierre Pronchery 103b077aed3SPierre Pronchery=head1 HISTORY 104b077aed3SPierre Pronchery 105b077aed3SPierre ProncheryThis functionality was added in OpenSSL 3.0. 106b077aed3SPierre Pronchery 107b077aed3SPierre Pronchery=head1 COPYRIGHT 108b077aed3SPierre Pronchery 109b077aed3SPierre ProncheryCopyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved. 110b077aed3SPierre Pronchery 111b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 112b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 113b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 114b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 115b077aed3SPierre Pronchery 116b077aed3SPierre Pronchery=cut 117