xref: /openssl/doc/man7/EVP_RAND-HASH-DRBG.pod (revision 7ed6de99)
1=pod
2
3=head1 NAME
4
5EVP_RAND-HASH-DRBG - The HASH DRBG EVP_RAND implementation
6
7=head1 DESCRIPTION
8
9Support for the hash deterministic random bit generator through the
10B<EVP_RAND> API.
11
12=head2 Identity
13
14"HASH-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 "digest" (B<OSSL_DRBG_PARAM_DIGEST>) <UTF8 string>
50
51These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
52
53=item "fips-indicator" (B<OSSL_DRBG_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
54
55=item "digest-check" (B<OSSL_DRBG_PARAM_FIPS_DIGEST_CHECK>) <integer>
56
57These parameters work as described in L<provider-rand(7)/PARAMETERS>.
58
59=back
60
61=head1 NOTES
62
63When the FIPS provider is installed using the B<-no_drbg_truncated_digests>
64option to fipsinstall, only these digests are permitted (as per
65L<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>):
66
67=over 4
68
69=item SHA-1
70
71=item SHA2-256
72
73=item SHA2-512
74
75=item SHA3-256
76
77=item SHA3-512
78
79=back
80
81A context for HASH DRBG can be obtained by calling:
82
83 EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
84 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
85
86=head1 EXAMPLES
87
88 EVP_RAND *rand;
89 EVP_RAND_CTX *rctx;
90 unsigned char bytes[100];
91 OSSL_PARAM params[2], *p = params;
92 unsigned int strength = 128;
93
94 rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
95 rctx = EVP_RAND_CTX_new(rand, NULL);
96 EVP_RAND_free(rand);
97
98 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha512, 0);
99 *p = OSSL_PARAM_construct_end();
100 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
101
102 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
103
104 EVP_RAND_CTX_free(rctx);
105
106=head1 CONFORMING TO
107
108NIST SP 800-90A and SP 800-90B
109
110=head1 SEE ALSO
111
112L<EVP_RAND(3)>,
113L<EVP_RAND(3)/PARAMETERS>,
114L<openssl-fipsinstall(1)>
115
116=head1 HISTORY
117
118OpenSSL 3.1.1 introduced the B<-no_drbg_truncated_digests> option to
119fipsinstall which restricts the permitted digests when using the FIPS
120provider in a complaint manner.  For details refer to
121L<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>.
122
123=head1 COPYRIGHT
124
125Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
126
127Licensed under the Apache License 2.0 (the "License").  You may not use
128this file except in compliance with the License.  You can obtain a copy
129in the file LICENSE in the source distribution or at
130L<https://www.openssl.org/source/license.html>.
131
132=cut
133