1=pod
2
3=head1 NAME
4
5ossl_rand_get_entropy, ossl_rand_get_user_entropy,
6ossl_rand_cleanup_entropy, ossl_rand_cleanup_user_entropy,
7ossl_rand_get_nonce, ossl_rand_get_user_nonce,
8ossl_rand_cleanup_nonce, ossl_rand_cleanup_user_nonce
9- get seed material from the operating system
10
11=head1 SYNOPSIS
12
13 #include "crypto/rand.h"
14
15 size_t ossl_rand_get_entropy(OSSL_CORE_HANDLE *handle,
16                              unsigned char **pout, int entropy,
17                              size_t min_len, size_t max_len);
18 size_t ossl_rand_get_user_entropy(OSSL_CORE_HANDLE *handle,
19                                   unsigned char **pout, int entropy,
20                                   size_t min_len, size_t max_len);
21 void ossl_rand_cleanup_entropy(OSSL_CORE_HANDLE *handle,
22                                unsigned char *buf, size_t len);
23 void ossl_rand_cleanup_user_entropy(OSSL_CORE_HANDLE *handle,
24                                     unsigned char *buf, size_t len);
25 size_t ossl_rand_get_nonce(OSSL_CORE_HANDLE *handle,
26                            unsigned char **pout, size_t min_len,
27                            size_t max_len, const void *salt, size_t salt_len);
28 size_t ossl_rand_get_user_nonce(OSSL_CORE_HANDLE *handle, unsigned char **pout,
29                                 size_t min_len, size_t max_len,
30                                 const void *salt, size_t salt_len);
31 void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle,
32                              unsigned char *buf, size_t len);
33 void ossl_rand_cleanup_user_nonce(OSSL_CORE_HANDLE *handle,
34                                   unsigned char *buf, size_t len);
35
36=head1 DESCRIPTION
37
38ossl_rand_get_entropy() retrieves seeding material from the operating system.
39The seeding material will have at least I<entropy> bytes of randomness and is
40stored in a buffer which contains at least I<min_len> and at most I<max_len>
41bytes.  The buffer address is stored in I<*pout> and the buffer length is
42returned to the caller.
43
44ossl_rand_get_user_entropy() is the same as ossl_rand_get_entropy()
45except that it retrieves the seeding material from the library context's
46DRBG seed source.  By default this is the operating system but it can
47be changed by calling L<RAND_set_seed_source_type(3)>.
48
49ossl_rand_cleanup_entropy() cleanses and frees any storage allocated by
50ossl_rand_get_entropy().  The entropy buffer is pointed to by I<buf>
51and is of length I<len> bytes.
52
53ossl_rand_cleanup_user_entropy() cleanses and frees any storage allocated by
54ossl_rand_get_user_entropy().  The entropy buffer is pointed to by I<buf>
55and is of length I<len> bytes.
56
57ossl_rand_get_nonce() retrieves a nonce using the passed I<salt> parameter
58of length I<salt_len> and operating system specific information.
59The I<salt> should contain uniquely identifying information and this is
60included, in an unspecified manner, as part of the output.
61The output is stored in a buffer which contains at least I<min_len> and at
62most I<max_len> bytes.  The buffer address is stored in I<*pout> and the
63buffer length returned to the caller.
64
65ossl_rand_get_user_nonce() is the same as ossl_rand_get_nonce() except
66that it retrieves the seeding material from the library context's DRBG
67seed source.  By default this is the operating system but it can be
68changed by calling L<RAND_set_seed_source_type(3)>.
69
70ossl_rand_cleanup_nonce() cleanses and frees any storage allocated by
71ossl_rand_get_nonce() or ossl_rand_get_user_nonce().  The nonce buffer
72is pointed to by I<buf> and is of length I<len> bytes.
73
74=head1 NOTES
75
76FIPS providers 3.0.0, 3.0.8 and 3.0.9 incorrectly pass a provider
77internal pointer to ossl_rand_get_entropy(), ossl_rand_cleanup_entropy(),
78ossl_rand_get_nonce() and ossl_rand_cleanup_nonce().  This pointer cannot
79be safely dereferenced.
80
81=head1 RETURN VALUES
82
83ossl_rand_get_entropy(), ossl_rand_get_user_entropy(),
84ossl_rand_get_nonce() and ossl_rand_get_user_nonce() return the number
85of bytes in I<*pout> or 0 on error.
86
87=head1 HISTORY
88
89The functions ossl_rand_get_user_entropy(), ossl_rand_get_user_nonce(),
90ossl_rand_cleanup_user_entropy(), and ossl_rand_cleanup_user_nonce()
91were added in OpenSSL 3.1.4 and 3.2.0.
92
93The remaining functions described here were all added in OpenSSL 3.0.
94
95=head1 COPYRIGHT
96
97Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
98
99Licensed under the Apache License 2.0 (the "License").  You may not use
100this file except in compliance with the License.  You can obtain a copy
101in the file LICENSE in the source distribution or at
102L<https://www.openssl.org/source/license.html>.
103
104=cut
105