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