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