1=pod
2
3=head1 NAME
4
5ossl_rand_get_entropy, ossl_rand_cleanup_entropy,
6ossl_rand_get_nonce, ossl_rand_cleanup_nonce
7- get seed material from the operating system
8
9=head1 SYNOPSIS
10
11 #include "crypto/rand.h"
12
13 size_t ossl_rand_get_entropy(OSSL_CORE_HANDLE *handle,
14                              unsigned char **pout, int entropy,
15                              size_t min_len, size_t max_len);
16 void ossl_rand_cleanup_entropy(OSSL_CORE_HANDLE *handle,
17                                unsigned char *buf, size_t len);
18 size_t ossl_rand_get_nonce(OSSL_CORE_HANDLE *handle,
19                            unsigned char **pout, size_t min_len,
20                            size_t max_len, const void *salt, size_t salt_len);
21 void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle,
22                              unsigned char *buf, size_t len);
23
24=head1 DESCRIPTION
25
26ossl_rand_get_entropy() retrieves seeding material from the operating system.
27The seeding material will have at least I<entropy> bytes of randomness and is
28stored in a buffer which contains at least I<min_len> and at most I<max_len>
29bytes.  The buffer address is stored in I<*pout> and the buffer length is
30returned to the caller.
31
32ossl_rand_cleanup_entropy() cleanses and frees any storage allocated by
33ossl_rand_get_entropy().  The seeding buffer is pointed to by I<buf> and is
34of length I<len> bytes.
35
36ossl_rand_get_nonce() retrieves a nonce using the passed I<salt> parameter
37of length I<salt_len> and operating system specific information.
38The I<salt> should contain uniquely identifying information and this is
39included, in an unspecified manner, as part of the output.
40The output is stored in a buffer which contains at least I<min_len> and at
41most I<max_len> bytes.  The buffer address is stored in I<*pout> and the
42buffer length returned to the caller.
43
44ossl_rand_cleanup_nonce() cleanses and frees any storage allocated by
45ossl_rand_get_nonce().  The nonce buffer is pointed to by I<buf> and is
46of length I<len> bytes.
47
48=head1 RETURN VALUES
49
50ossl_rand_get_entropy() and ossl_rand_get_nonce() return the number of bytes
51in I<*pout> or 0 on error.
52
53=head1 HISTORY
54
55The functions described here were all added in OpenSSL 3.0.
56
57=head1 COPYRIGHT
58
59Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
60
61Licensed under the Apache License 2.0 (the "License").  You may not use
62this file except in compliance with the License.  You can obtain a copy
63in the file LICENSE in the source distribution or at
64L<https://www.openssl.org/source/license.html>.
65
66=cut
67