| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | RAND_DRBG_generate,
|
|---|
| 6 | RAND_DRBG_bytes
|
|---|
| 7 | - generate random bytes using the given drbg instance
|
|---|
| 8 |
|
|---|
| 9 | =head1 SYNOPSIS
|
|---|
| 10 |
|
|---|
| 11 | #include <openssl/rand_drbg.h>
|
|---|
| 12 |
|
|---|
| 13 | int RAND_DRBG_generate(RAND_DRBG *drbg,
|
|---|
| 14 | unsigned char *out, size_t outlen,
|
|---|
| 15 | int prediction_resistance,
|
|---|
| 16 | const unsigned char *adin, size_t adinlen);
|
|---|
| 17 |
|
|---|
| 18 | int RAND_DRBG_bytes(RAND_DRBG *drbg,
|
|---|
| 19 | unsigned char *out, size_t outlen);
|
|---|
| 20 |
|
|---|
| 21 |
|
|---|
| 22 | =head1 DESCRIPTION
|
|---|
| 23 |
|
|---|
| 24 | RAND_DRBG_generate() generates B<outlen> random bytes using the given
|
|---|
| 25 | DRBG instance B<drbg> and stores them in the buffer at B<out>.
|
|---|
| 26 |
|
|---|
| 27 | Before generating the output, the DRBG instance checks whether the maximum
|
|---|
| 28 | number of generate requests (I<reseed interval>) or the maximum timespan
|
|---|
| 29 | (I<reseed time interval>) since its last seeding have been reached.
|
|---|
| 30 | If this is the case, the DRBG reseeds automatically.
|
|---|
| 31 | Additionally, an immediate reseeding can be requested by setting the
|
|---|
| 32 | B<prediction_resistance> flag to 1. See NOTES section for more details.
|
|---|
| 33 |
|
|---|
| 34 | The caller can optionally provide additional data to be used for reseeding
|
|---|
| 35 | by passing a pointer B<adin> to a buffer of length B<adinlen>.
|
|---|
| 36 | This additional data is mixed into the internal state of the random
|
|---|
| 37 | generator but does not contribute to the entropy count.
|
|---|
| 38 | The additional data can be omitted by setting B<adin> to NULL and
|
|---|
| 39 | B<adinlen> to 0;
|
|---|
| 40 |
|
|---|
| 41 | RAND_DRBG_bytes() generates B<outlen> random bytes using the given
|
|---|
| 42 | DRBG instance B<drbg> and stores them in the buffer at B<out>.
|
|---|
| 43 | This function is a wrapper around the RAND_DRBG_generate() call,
|
|---|
| 44 | which collects some additional data from low entropy sources
|
|---|
| 45 | (e.g., a high resolution timer) and calls
|
|---|
| 46 | RAND_DRBG_generate(drbg, out, outlen, 0, adin, adinlen).
|
|---|
| 47 |
|
|---|
| 48 |
|
|---|
| 49 | =head1 RETURN VALUES
|
|---|
| 50 |
|
|---|
| 51 | RAND_DRBG_generate() and RAND_DRBG_bytes() return 1 on success,
|
|---|
| 52 | and 0 on failure.
|
|---|
| 53 |
|
|---|
| 54 | =head1 NOTES
|
|---|
| 55 |
|
|---|
| 56 | The I<reseed interval> and I<reseed time interval> of the B<drbg> are set to
|
|---|
| 57 | reasonable default values, which in general do not have to be adjusted.
|
|---|
| 58 | If necessary, they can be changed using L<RAND_DRBG_set_reseed_interval(3)>
|
|---|
| 59 | and L<RAND_DRBG_set_reseed_time_interval(3)>, respectively.
|
|---|
| 60 |
|
|---|
| 61 | A request for prediction resistance can only be satisfied by pulling fresh
|
|---|
| 62 | entropy from one of the approved entropy sources listed in section 5.5.2 of
|
|---|
| 63 | [NIST SP 800-90C].
|
|---|
| 64 | Since the default DRBG implementation does not have access to such an approved
|
|---|
| 65 | entropy source, a request for prediction resistance will always fail.
|
|---|
| 66 | In other words, prediction resistance is currently not supported yet by the DRBG.
|
|---|
| 67 |
|
|---|
| 68 | =head1 SEE ALSO
|
|---|
| 69 |
|
|---|
| 70 | L<RAND_bytes(3)>,
|
|---|
| 71 | L<RAND_DRBG_set_reseed_interval(3)>,
|
|---|
| 72 | L<RAND_DRBG_set_reseed_time_interval(3)>,
|
|---|
| 73 | L<RAND_DRBG(7)>
|
|---|
| 74 |
|
|---|
| 75 | =head1 HISTORY
|
|---|
| 76 |
|
|---|
| 77 | The RAND_DRBG functions were added in OpenSSL 1.1.1.
|
|---|
| 78 |
|
|---|
| 79 | =head1 COPYRIGHT
|
|---|
| 80 |
|
|---|
| 81 | Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 82 |
|
|---|
| 83 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 84 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 85 | in the file LICENSE in the source distribution or at
|
|---|
| 86 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 87 |
|
|---|
| 88 | =cut
|
|---|
