Home | History | Annotate | Line # | Download | only in man7 
      1 =pod
      2 
      3 =head1 NAME
      4 
      5 EVP_RAND-HMAC-DRBG - The HMAC DRBG EVP_RAND implementation
      6 
      7 =head1 DESCRIPTION
      8 
      9 Support for the HMAC deterministic random bit generator through the
     10 B<EVP_RAND> API.
     11 
     12 =head2 Identity
     13 
     14 "HMAC-DRBG" is the name for this implementation; it can be used with the
     15 EVP_RAND_fetch() function.
     16 
     17 =head2 Supported parameters
     18 
     19 The 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 
     53 These 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 
     59 These parameters work as described in L<provider-rand(7)/PARAMETERS>.
     60 
     61 =back
     62 
     63 =head1 NOTES
     64 
     65 When using the FIPS provider, only these digests are permitted (as per
     66 L<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 The default HMAC-DRBG implementation attempts to fetch the required internal
     69 algorithms from the provider they are built into (eg the default provider)
     70 regardless of the properties provided. Should the provider not implement
     71 the required algorithms then properties will be used to find a different
     72 implementation.
     73 
     74 =over 4
     75 
     76 =item SHA-1
     77 
     78 =item SHA2-256
     79 
     80 =item SHA2-512
     81 
     82 =item SHA3-256
     83 
     84 =item SHA3-512
     85 
     86 =back
     87 
     88 A context for HMAC DRBG can be obtained by calling:
     89 
     90  EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
     91  EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
     92 
     93 =head1 EXAMPLES
     94 
     95  EVP_RAND *rand;
     96  EVP_RAND_CTX *rctx;
     97  unsigned char bytes[100];
     98  OSSL_PARAM params[3], *p = params;
     99  unsigned int strength = 128;
    100 
    101  rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
    102  rctx = EVP_RAND_CTX_new(rand, NULL);
    103  EVP_RAND_free(rand);
    104 
    105  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0);
    106  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0);
    107  *p = OSSL_PARAM_construct_end();
    108  EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
    109 
    110  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
    111 
    112  EVP_RAND_CTX_free(rctx);
    113 
    114 =head1 CONFORMING TO
    115 
    116 NIST SP 800-90A and SP 800-90B
    117 
    118 =head1 SEE ALSO
    119 
    120 L<EVP_RAND(3)>,
    121 L<EVP_RAND(3)/PARAMETERS>,
    122 L<openssl-fipsinstall(1)>
    123 
    124 
    125 =head1 HISTORY
    126 
    127 OpenSSL 3.1.1 introduced the B<-no_drbg_truncated_digests> option to
    128 fipsinstall which restricts the permitted digests when using the FIPS
    129 provider in a complaint manner.  For details refer to
    130 L<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>).
    131 
    132 =head1 COPYRIGHT
    133 
    134 Copyright 2020-2025 The OpenSSL Project Authors. All Rights Reserved.
    135 
    136 Licensed under the Apache License 2.0 (the "License").  You may not use
    137 this file except in compliance with the License.  You can obtain a copy
    138 in the file LICENSE in the source distribution or at
    139 L<https://www.openssl.org/source/license.html>.
    140 
    141 =cut
    142