1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_KDF-KRB5KDF - The RFC3961 Krb5 KDF EVP_KDF implementation 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 DESCRIPTION 8*b077aed3SPierre Pronchery 9*b077aed3SPierre ProncherySupport for computing the B<KRB5KDF> KDF through the B<EVP_KDF> API. 10*b077aed3SPierre Pronchery 11*b077aed3SPierre ProncheryThe EVP_KDF-KRB5KDF algorithm implements the key derivation function defined 12*b077aed3SPierre Proncheryin RFC 3961, section 5.1 and is used by Krb5 to derive session keys. 13*b077aed3SPierre ProncheryThree inputs are required to perform key derivation: a cipher, (for example 14*b077aed3SPierre ProncheryAES-128-CBC), the initial key, and a constant. 15*b077aed3SPierre Pronchery 16*b077aed3SPierre Pronchery=head2 Identity 17*b077aed3SPierre Pronchery 18*b077aed3SPierre Pronchery"KRB5KDF" is the name for this implementation; 19*b077aed3SPierre Proncheryit can be used with the EVP_KDF_fetch() function. 20*b077aed3SPierre Pronchery 21*b077aed3SPierre Pronchery=head2 Supported parameters 22*b077aed3SPierre Pronchery 23*b077aed3SPierre ProncheryThe supported parameters are: 24*b077aed3SPierre Pronchery 25*b077aed3SPierre Pronchery=over 4 26*b077aed3SPierre Pronchery 27*b077aed3SPierre Pronchery=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 28*b077aed3SPierre Pronchery 29*b077aed3SPierre Pronchery=item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string> 30*b077aed3SPierre Pronchery 31*b077aed3SPierre Pronchery=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 32*b077aed3SPierre Pronchery 33*b077aed3SPierre ProncheryThese parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=item "constant" (B<OSSL_KDF_PARAM_CONSTANT>) <octet string> 36*b077aed3SPierre Pronchery 37*b077aed3SPierre ProncheryThis parameter sets the constant value for the KDF. 38*b077aed3SPierre ProncheryIf a value is already set, the contents are replaced. 39*b077aed3SPierre Pronchery 40*b077aed3SPierre Pronchery=back 41*b077aed3SPierre Pronchery 42*b077aed3SPierre Pronchery=head1 NOTES 43*b077aed3SPierre Pronchery 44*b077aed3SPierre ProncheryA context for KRB5KDF can be obtained by calling: 45*b077aed3SPierre Pronchery 46*b077aed3SPierre Pronchery EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KRB5KDF", NULL); 47*b077aed3SPierre Pronchery EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 48*b077aed3SPierre Pronchery 49*b077aed3SPierre ProncheryThe output length of the KRB5KDF derivation is specified via the I<keylen> 50*b077aed3SPierre Proncheryparameter to the L<EVP_KDF_derive(3)> function, and MUST match the key 51*b077aed3SPierre Proncherylength for the chosen cipher or an error is returned. Moreover, the 52*b077aed3SPierre Proncheryconstant's length must not exceed the block size of the cipher. 53*b077aed3SPierre ProncherySince the KRB5KDF output length depends on the chosen cipher, calling 54*b077aed3SPierre ProncheryL<EVP_KDF_CTX_get_kdf_size(3)> to obtain the requisite length returns the correct length 55*b077aed3SPierre Proncheryonly after the cipher is set. Prior to that B<EVP_MAX_KEY_LENGTH> is returned. 56*b077aed3SPierre ProncheryThe caller must allocate a buffer of the correct length for the chosen 57*b077aed3SPierre Proncherycipher, and pass that buffer to the L<EVP_KDF_derive(3)> function along 58*b077aed3SPierre Proncherywith that length. 59*b077aed3SPierre Pronchery 60*b077aed3SPierre Pronchery=head1 EXAMPLES 61*b077aed3SPierre Pronchery 62*b077aed3SPierre ProncheryThis example derives a key using the AES-128-CBC cipher: 63*b077aed3SPierre Pronchery 64*b077aed3SPierre Pronchery EVP_KDF *kdf; 65*b077aed3SPierre Pronchery EVP_KDF_CTX *kctx; 66*b077aed3SPierre Pronchery unsigned char key[16] = "01234..."; 67*b077aed3SPierre Pronchery unsigned char constant[] = "I'm a constant"; 68*b077aed3SPierre Pronchery unsigned char out[16]; 69*b077aed3SPierre Pronchery size_t outlen = sizeof(out); 70*b077aed3SPierre Pronchery OSSL_PARAM params[4], *p = params; 71*b077aed3SPierre Pronchery 72*b077aed3SPierre Pronchery kdf = EVP_KDF_fetch(NULL, "KRB5KDF", 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_CIPHER, 77*b077aed3SPierre Pronchery SN_aes_128_cbc, 78*b077aed3SPierre Pronchery strlen(SN_aes_128_cbc)); 79*b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 80*b077aed3SPierre Pronchery key, (size_t)16); 81*b077aed3SPierre Pronchery *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_CONSTANT, 82*b077aed3SPierre Pronchery constant, strlen(constant)); 83*b077aed3SPierre Pronchery *p = OSSL_PARAM_construct_end(); 84*b077aed3SPierre Pronchery if (EVP_KDF_derive(kctx, out, outlen, params) <= 0) 85*b077aed3SPierre Pronchery /* Error */ 86*b077aed3SPierre Pronchery 87*b077aed3SPierre Pronchery EVP_KDF_CTX_free(kctx); 88*b077aed3SPierre Pronchery 89*b077aed3SPierre Pronchery=head1 CONFORMING TO 90*b077aed3SPierre Pronchery 91*b077aed3SPierre ProncheryRFC 3961 92*b077aed3SPierre Pronchery 93*b077aed3SPierre Pronchery=head1 SEE ALSO 94*b077aed3SPierre Pronchery 95*b077aed3SPierre ProncheryL<EVP_KDF(3)>, 96*b077aed3SPierre ProncheryL<EVP_KDF_CTX_free(3)>, 97*b077aed3SPierre ProncheryL<EVP_KDF_CTX_get_kdf_size(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 2016-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*b077aed3SPierre Pronchery 116