xref: /openssl/doc/man7/EVP_RAND-SEED-SRC.pod (revision 58d92621)
1=pod
2
3=head1 NAME
4
5EVP_RAND-SEED-SRC - 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
12The seed sources used are specified at the time OpenSSL is configured for
13building using the B<--with-rand-seed=> option.  By default, operating system
14randomness sources are used.
15
16=head2 Identity
17
18"SEED-SRC" is the name for this implementation; it can be used with the
19EVP_RAND_fetch() function.
20
21=head2 Supported parameters
22
23The supported parameters are:
24
25=over 4
26
27=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
28
29=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
30
31=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
32
33These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
34
35=back
36
37=head1 NOTES
38
39A context for the seed source can be obtained by calling:
40
41 EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
42 EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
43
44=head1 EXAMPLES
45
46 EVP_RAND *rand;
47 EVP_RAND_CTX *seed, *rctx;
48 unsigned char bytes[100];
49 OSSL_PARAM params[2], *p = params;
50 unsigned int strength = 128;
51
52 /* Create and instantiate a seed source */
53 rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
54 seed = EVP_RAND_CTX_new(rand, NULL);
55 EVP_RAND_instantiate(seed, strength, 0, NULL, 0, NULL);
56 EVP_RAND_free(rand);
57
58 /* Feed this into a DRBG */
59 rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
60 rctx = EVP_RAND_CTX_new(rand, seed);
61 EVP_RAND_free(rand);
62
63 /* Configure the DRBG */
64 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
65                                         SN_aes_256_ctr, 0);
66 *p = OSSL_PARAM_construct_end();
67 EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
68
69 EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
70
71 EVP_RAND_CTX_free(rctx);
72 EVP_RAND_CTX_free(seed);
73
74=head1 SEE ALSO
75
76L<EVP_RAND(3)>,
77L<EVP_RAND(3)/PARAMETERS>
78
79=head1 COPYRIGHT
80
81Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
82
83Licensed under the Apache License 2.0 (the "License").  You may not use
84this file except in compliance with the License.  You can obtain a copy
85in the file LICENSE in the source distribution or at
86L<https://www.openssl.org/source/license.html>.
87
88=cut
89