xref: /openssl/doc/man7/EVP_RAND-JITTER.pod (revision 47ebeb1c) 
1=pod
2
3=head1 NAME
4
5EVP_RAND-JITTER - The randomness seed source EVP_RAND implementation
6
7=head1 DESCRIPTION
8
9Support for deterministic random number generator seeding through the
10B<EVP_RAND> API.
11
12This software seed source produces randomness based on tiny CPU
13"jitter" fluctuations.
14
15It is available when OpenSSL is compiled with B<enable-jitter>
16option. When available it is listed in B<openssl list
17-random-generators> and B<openssl info -seeds>.
18
19=head2 Identity
20
21"JITTER" is the name for this implementation; it can be used with the
22EVP_RAND_fetch() function.
23
24=head2 Supported parameters
25
26The supported parameters are:
27
28=over 4
29
30=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
31
32=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
33
34=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
35
36These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
37
38=back
39
40=head1 NOTES
41
42A context for the seed source can be obtained by calling:
43
44 EVP_RAND *rand = EVP_RAND_fetch(NULL, "JITTER", NULL);
45 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
46
47The B<enable-jitter> option was added in OpenSSL 3.4.
48
49By specifying the B<enable-fips-jitter> configuration option, the FIPS
50provider will use an internal jitter source for its entropy.  Enabling
51this option will cause the FIPS provider to operate in a non-compliant
52mode unless an entropy assessment
53L<ESV|https://csrc.nist.gov/Projects/cryptographic-module-validation-program/entropy-validations>
54and validation through the
55L<CMVP|https://csrc.nist.gov/projects/cryptographic-module-validation-program>
56are additionally conducted.  This option was added in OpenSSL 3.5.
57
58=head1 EXAMPLES
59
60 EVP_RAND *rand;
61 EVP_RAND_CTX *seed, *rctx;
62 unsigned char bytes[100];
63 OSSL_PARAM params[2], *p = params;
64 unsigned int strength = 128;
65
66 /* Create and instantiate a seed source */
67 rand = EVP_RAND_fetch(NULL, "JITTER", NULL);
68 seed = EVP_RAND_CTX_new(rand, NULL);
69 EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL);
70 EVP_RAND_free(rand);
71
72 /* Feed this into a DRBG */
73 rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
74 rctx = EVP_RAND_CTX_new(rand, seed);
75 EVP_RAND_free(rand);
76
77 /* Configure the DRBG */
78 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
79                                         SN_aes_256_ctr, 0);
80 *p = OSSL_PARAM_construct_end();
81 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
82
83 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
84
85 EVP_RAND_CTX_free(rctx);
86 EVP_RAND_CTX_free(seed);
87
88=head1 SEE ALSO
89
90L<EVP_RAND(3)>,
91L<EVP_RAND(3)/PARAMETERS>
92
93=head1 COPYRIGHT
94
95Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
96
97Licensed under the Apache License 2.0 (the "License").  You may not use
98this file except in compliance with the License.  You can obtain a copy
99in the file LICENSE in the source distribution or at
100L<https://www.openssl.org/source/license.html>.
101
102=cut
103