]>
Commit | Line | Data |
---|---|---|
7d615e21 P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | RAND_get0_primary, | |
6 | RAND_get0_public, | |
7 | RAND_get0_private | |
8 | - get access to the global EVP_RAND_CTX instances | |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/rand.h> | |
13 | ||
b4250010 DMSP |
14 | EVP_RAND_CTX *RAND_get0_primary(OSSL_LIB_CTX *ctx); |
15 | EVP_RAND_CTX *RAND_get0_public(OSSL_LIB_CTX *ctx); | |
16 | EVP_RAND_CTX *RAND_get0_private(OSSL_LIB_CTX *ctx); | |
7d615e21 | 17 | |
7d615e21 P |
18 | =head1 DESCRIPTION |
19 | ||
20 | The default RAND API implementation (RAND_OpenSSL()) utilizes three | |
21 | shared DRBG instances which are accessed via the RAND API: | |
22 | ||
23 | The I<public> and I<private> DRBG are thread-local instances, which are used | |
24 | by RAND_bytes() and RAND_priv_bytes(), respectively. | |
25 | The I<primary> DRBG is a global instance, which is not intended to be used | |
26 | directly, but is used internally to reseed the other two instances. | |
27 | ||
28 | These functions here provide access to the shared DRBG instances. | |
29 | ||
30 | =head1 RETURN VALUES | |
31 | ||
32 | RAND_get0_primary() returns a pointer to the I<primary> DRBG instance | |
b4250010 | 33 | for the given OSSL_LIB_CTX B<ctx>. |
7d615e21 P |
34 | |
35 | RAND_get0_public() returns a pointer to the I<public> DRBG instance | |
b4250010 | 36 | for the given OSSL_LIB_CTX B<ctx>. |
7d615e21 P |
37 | |
38 | RAND_get0_private() returns a pointer to the I<private> DRBG instance | |
b4250010 | 39 | for the given OSSL_LIB_CTX B<ctx>. |
7d615e21 P |
40 | |
41 | In all the above cases the B<ctx> parameter can | |
b4250010 | 42 | be NULL in which case the default OSSL_LIB_CTX is used. |
7d615e21 P |
43 | |
44 | =head1 NOTES | |
45 | ||
46 | It is not thread-safe to access the I<primary> DRBG instance. | |
47 | The I<public> and I<private> DRBG instance can be accessed safely, because | |
48 | they are thread-local. Note however, that changes to these two instances | |
49 | apply only to the current thread. | |
50 | ||
51 | For that reason it is recommended not to change the settings of these | |
52 | three instances directly. | |
53 | Instead, an application should change the default settings for new DRBG instances | |
54 | at initialization time, before creating additional threads. | |
55 | ||
56 | During initialization, it is possible to change the reseed interval | |
57 | and reseed time interval. | |
58 | It is also possible to exchange the reseeding callbacks entirely. | |
59 | ||
cb54d1b9 P |
60 | To set the type of DRBG that will be instantiated, use the |
61 | L<RAND_set_DRBG_type(3)> call before accessing the random number generation | |
62 | infrastructure. | |
63 | ||
7d615e21 P |
64 | =head1 SEE ALSO |
65 | ||
cb54d1b9 P |
66 | L<EVP_RAND(3)>, |
67 | L<RAND_set_DRBG_type(3)> | |
7d615e21 P |
68 | |
69 | =head1 HISTORY | |
70 | ||
71 | These functions were added in OpenSSL 3.0. | |
72 | ||
73 | =head1 COPYRIGHT | |
74 | ||
8020d79b | 75 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. |
7d615e21 P |
76 | |
77 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
78 | this file except in compliance with the License. You can obtain a copy | |
79 | in the file LICENSE in the source distribution or at | |
80 | L<https://www.openssl.org/source/license.html>. | |
81 | ||
82 | =cut |