doc/man3/RAND_DRBG_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RAND_DRBG_new,
   6 RAND_DRBG_secure_new,
   7 RAND_DRBG_set,
   8 RAND_DRBG_set_defaults,
   9 RAND_DRBG_instantiate,
  10 RAND_DRBG_uninstantiate,
  11 RAND_DRBG_free
  12 - initialize and cleanup a RAND_DRBG instance
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/rand_drbg.h>
  17
  18
  19  RAND_DRBG *RAND_DRBG_new(int type,
  20                           unsigned int flags,
  21                           RAND_DRBG *parent);
  22
  23  RAND_DRBG *RAND_DRBG_secure_new(int type,
  24                                  unsigned int flags,
  25                                  RAND_DRBG *parent);
  26
  27  int RAND_DRBG_set(RAND_DRBG *drbg,
  28                    int type, unsigned int flags);
  29
  30  int RAND_DRBG_set_defaults(int type, unsigned int flags);
  31
  32  int RAND_DRBG_instantiate(RAND_DRBG *drbg,
  33                            const unsigned char *pers, size_t perslen);
  34
  35  int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
  36
  37  void RAND_DRBG_free(RAND_DRBG *drbg);
  38
  39
  40 =head1 DESCRIPTION
  41
  42 RAND_DRBG_new() and RAND_DRBG_secure_new()
  43 create a new DRBG instance of the given B<type>, allocated from the heap resp.
  44 the secure heap
  45 (using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
  46
  47 RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
  48
  49 RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG
  50 instances.
  51
  52 Currently, all DRBG types are based on AES-CTR, so B<type> can be one of the
  53 following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr.
  54 Before the DRBG can be used to generate random bits, it is necessary to set
  55 its type and to instantiate it.
  56
  57 The optional B<flags> argument specifies a set of bit flags which can be
  58 joined using the | operator. Currently, the only flag is
  59 RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of a the derivation function
  60 ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1].
  61
  62 If a B<parent> instance is specified then this will be used instead of
  63 the default entropy source for reseeding the B<drbg>. It is said that the
  64 B<drbg> is I<chained> to its B<parent>.
  65 For more information, see the NOTES section.
  66
  67
  68 RAND_DRBG_instantiate()
  69 seeds the B<drbg> instance using random input from trusted entropy sources.
  70 Optionally, a personalization string B<pers> of length B<perslen> can be
  71 specified.
  72 To omit the personalization string, set B<pers>=NULL and B<perslen>=0;
  73
  74 RAND_DRBG_uninstantiate()
  75 clears the internal state of the B<drbg> and puts it back in the
  76 uninstantiated state.
  77
  78 =head1 RETURN VALUES
  79
  80
  81 RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
  82 instance allocated on the heap, resp. secure heap.
  83
  84 RAND_DRBG_set(),
  85 RAND_DRBG_instantiate(), and
  86 RAND_DRBG_uninstantiate()
  87 return 1 on success, and 0 on failure.
  88
  89 RAND_DRBG_free() does not return a value.
  90
  91 =head1 NOTES
  92
  93 The DRBG design supports I<chaining>, which means that a DRBG instance can
  94 use another B<parent> DRBG instance instead of the default entropy source
  95 to obtain fresh random input for reseeding, provided that B<parent> DRBG
  96 instance was properly instantiated, either from a trusted entropy source,
  97 or from yet another parent DRBG instance.
  98 For a detailed description of the reseeding process, see L<RAND_DRBG(7)>.
  99
 100 The default DRBG type and flags are applied only during creation of a DRBG
 101 instance.
 102 To ensure that they are applied to the global and thread-local DRBG instances
 103 (<master>, resp. <public> and <private>), it is necessary to call
 104 RAND_DRBG_set_defaults() before creating any thread and before calling any
 105 cryptographic routines that obtain random data directly or indirectly.
 106
 107 =head1 HISTORY
 108
 109 The RAND_DRBG functions were added in OpenSSL 1.1.1.
 110
 111 =head1 SEE ALSO
 112
 113 L<OPENSSL_zalloc(3)>,
 114 L<OPENSSL_secure_zalloc(3)>,
 115 L<RAND_DRBG_generate(3)>,
 116 L<RAND_DRBG(7)>
 117
 118 =head1 COPYRIGHT
 119
 120 Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
 121
 122 Licensed under the OpenSSL license (the "License").  You may not use
 123 this file except in compliance with the License.  You can obtain a copy
 124 in the file LICENSE in the source distribution or at
 125 L<https://www.openssl.org/source/license.html>.
 126
 127 =cut