xref: /openssl/doc/man7/EVP_RAND-JITTER.pod (revision 1e7ff7be) 
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
47=head1 EXAMPLES
48
49 EVP_RAND *rand;
50 EVP_RAND_CTX *seed, *rctx;
51 unsigned char bytes[100];
52 OSSL_PARAM params[2], *p = params;
53 unsigned int strength = 128;
54
55 /* Create and instantiate a seed source */
56 rand = EVP_RAND_fetch(NULL, "JITTER", NULL);
57 seed = EVP_RAND_CTX_new(rand, NULL);
58 EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL);
59 EVP_RAND_free(rand);
60
61 /* Feed this into a DRBG */
62 rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
63 rctx = EVP_RAND_CTX_new(rand, seed);
64 EVP_RAND_free(rand);
65
66 /* Configure the DRBG */
67 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
68                                         SN_aes_256_ctr, 0);
69 *p = OSSL_PARAM_construct_end();
70 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
71
72 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
73
74 EVP_RAND_CTX_free(rctx);
75 EVP_RAND_CTX_free(seed);
76
77=head1 SEE ALSO
78
79L<EVP_RAND(3)>,
80L<EVP_RAND(3)/PARAMETERS>
81
82=head1 COPYRIGHT
83
84Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
85
86Licensed under the Apache License 2.0 (the "License").  You may not use
87this file except in compliance with the License.  You can obtain a copy
88in the file LICENSE in the source distribution or at
89L<https://www.openssl.org/source/license.html>.
90
91=cut
92