1=pod 2 3=head1 NAME 4 5EVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). 10X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to 11derive a key using input such as a shared secret key and shared info. 12 13=head2 Identity 14 15"X963KDF" is the name for this implementation; it 16can be used with the EVP_KDF_fetch() function. 17 18=head2 Supported parameters 19 20The supported parameters are: 21 22=over 4 23 24=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 25 26=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 27 28These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 29 30=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 31 32The shared secret used for key derivation. 33This parameter sets the secret. 34 35=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> 36 37This parameter specifies an optional value for shared info. 38 39=back 40 41The OpenSSL FIPS provider also supports the following parameters: 42 43=over 4 44 45=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 46 47A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 48This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" 49related parameter is set to 0 and the check fails. 50 51=item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <int> 52 53The default value of 1 causes an error during EVP_KDF_CTX_set_params() if 54used digest is not approved. 55Setting this to zero will ignore the error and set the approved 56"fips-indicator" to 0. 57This option breaks FIPS compliance if it causes the approved "fips-indicator" 58to return 0. 59 60According to ANSI X9.63-2001, the following are approved digest algorithms: 61SHA2-224, SHA2-256, SHA2-384, SHA2-512, SHA2-512/224, SHA2-512/256, SHA3-224, 62SHA3-256, SHA3-384, SHA3-512. 63 64=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 65 66The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 67length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112 68bits. 69Setting this to zero will ignore the error and set the approved 70"fips-indicator" to 0. 71This option breaks FIPS compliance if it causes the approved "fips-indicator" 72to return 0. 73 74=back 75 76=head1 NOTES 77 78X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function, 79X963KDF appends the counter to the secret, whereas SSKDF prepends the counter. 80 81A context for X963KDF can be obtained by calling: 82 83 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); 84 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 85 86The output length of an X963KDF is specified via the I<keylen> 87parameter to the L<EVP_KDF_derive(3)> function. 88 89=head1 EXAMPLES 90 91This example derives 10 bytes, with the secret key "secret" and sharedinfo 92value "label": 93 94 EVP_KDF *kdf; 95 EVP_KDF_CTX *kctx; 96 unsigned char out[10]; 97 OSSL_PARAM params[4], *p = params; 98 99 kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL); 100 kctx = EVP_KDF_CTX_new(kdf); 101 EVP_KDF_free(kdf); 102 103 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 104 SN_sha256, strlen(SN_sha256)); 105 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, 106 "secret", (size_t)6); 107 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 108 "label", (size_t)5); 109 *p = OSSL_PARAM_construct_end(); 110 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 111 error("EVP_KDF_derive"); 112 } 113 114 EVP_KDF_CTX_free(kctx); 115 116=head1 CONFORMING TO 117 118"SEC 1: Elliptic Curve Cryptography" 119 120=head1 SEE ALSO 121 122L<EVP_KDF(3)>, 123L<EVP_KDF_CTX_new(3)>, 124L<EVP_KDF_CTX_free(3)>, 125L<EVP_KDF_CTX_set_params(3)>, 126L<EVP_KDF_CTX_get_kdf_size(3)>, 127L<EVP_KDF_derive(3)>, 128L<EVP_KDF(3)/PARAMETERS> 129 130=head1 HISTORY 131 132This functionality was added in OpenSSL 3.0. 133 134=head1 COPYRIGHT 135 136Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 137 138Licensed under the Apache License 2.0 (the "License"). You may not use 139this file except in compliance with the License. You can obtain a copy 140in the file LICENSE in the source distribution or at 141L<https://www.openssl.org/source/license.html>. 142 143=cut 144
