doc/man3/RAND_DRBG_generate.pod

   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 HISTORY
  69
  70 The RAND_DRBG functions were added in OpenSSL 1.1.1.
  71
  72 =head1 SEE ALSO
  73
  74 L<RAND_bytes(3)>,
  75 L<RAND_DRBG_set_reseed_interval(3)>,
  76 L<RAND_DRBG_set_reseed_time_interval(3)>,
  77 L<RAND_DRBG(7)>
  78
  79 =head1 COPYRIGHT
  80
  81 Copyright 2017-2018 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