1=pod 2 3=head1 NAME 4 5EVP_RAND-HMAC-DRBG - The HMAC DRBG EVP_RAND implementation 6 7=head1 DESCRIPTION 8 9Support for the HMAC deterministic random bit generator through the 10B<EVP_RAND> API. 11 12=head2 Identity 13 14"HMAC-DRBG" is the name for this implementation; it can be used with the 15EVP_RAND_fetch() function. 16 17=head2 Supported parameters 18 19The supported parameters are: 20 21=over 4 22 23=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer> 24 25=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> 26 27=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> 28 29=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> 30 31=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> 32 33=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> 34 35=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> 36 37=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer> 38 39=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer> 40 41=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer> 42 43=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer> 44 45=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_COUNTER>) <unsigned integer> 46 47=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string> 48 49=item "mac" (B<OSSL_DRBG_PARAM_MAC>) <UTF8 string> 50 51=item "digest" (B<OSSL_DRBG_PARAM_DIGEST>) <UTF8 string> 52 53These parameters work as described in L<EVP_RAND(3)/PARAMETERS>. 54 55=item "fips-indicator" (B<OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 56 57=item "digest-check" (B<OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK>) <integer> 58 59These parameters work as described in L<provider-rand(7)/PARAMETERS>. 60 61=back 62 63=head1 NOTES 64 65When using the FIPS provider, only these digests are permitted (as per 66L<FIPS 140-3 IG D.R|https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>): 67 68=over 4 69 70=item SHA-1 71 72=item SHA2-256 73 74=item SHA2-512 75 76=item SHA3-256 77 78=item SHA3-512 79 80=back 81 82A context for HMAC DRBG can be obtained by calling: 83 84 EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL); 85 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL); 86 87=head1 EXAMPLES 88 89 EVP_RAND *rand; 90 EVP_RAND_CTX *rctx; 91 unsigned char bytes[100]; 92 OSSL_PARAM params[3], *p = params; 93 unsigned int strength = 128; 94 95 rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL); 96 rctx = EVP_RAND_CTX_new(rand, NULL); 97 EVP_RAND_free(rand); 98 99 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0); 100 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0); 101 *p = OSSL_PARAM_construct_end(); 102 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params); 103 104 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0); 105 106 EVP_RAND_CTX_free(rctx); 107 108=head1 CONFORMING TO 109 110NIST SP 800-90A and SP 800-90B 111 112=head1 SEE ALSO 113 114L<EVP_RAND(3)>, 115L<EVP_RAND(3)/PARAMETERS>, 116L<openssl-fipsinstall(1)> 117 118 119=head1 HISTORY 120 121OpenSSL 3.1.1 introduced the B<-no_drbg_truncated_digests> option to 122fipsinstall which restricts the permitted digests when using the FIPS 123provider in a complaint manner. For details refer to 124L<FIPS 140-3 IG D.R|https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>). 125 126=head1 COPYRIGHT 127 128Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved. 129 130Licensed under the Apache License 2.0 (the "License"). You may not use 131this file except in compliance with the License. You can obtain a copy 132in the file LICENSE in the source distribution or at 133L<https://www.openssl.org/source/license.html>. 134 135=cut 136
