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