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