doc/man7/RAND.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RAND
   6 - the OpenSSL random generator
   7
   8 =head1 DESCRIPTION
   9
  10 Random numbers are a vital part of cryptography, they are needed to provide
  11 unpredictability for tasks like key generation, creating salts, and many more.
  12 Software-based generators must be seeded with external randomness before they
  13 can be used as a cryptographically-secure pseudo-random number generator
  14 (CSPRNG).
  15 The availability of common hardware with special instructions and
  16 modern operating systems, which may use items such as interrupt jitter
  17 and network packet timings, can be reasonable sources of seeding material.
  18
  19 OpenSSL comes with a default implementation of the RAND API which is based on
  20 the deterministic random bit generator (DRBG) model as described in
  21 [NIST SP 800-90A Rev. 1]. The default random generator will initialize
  22 automatically on first use and will be fully functional without having
  23 to be initialized ('seeded') explicitly.
  24 It seeds and reseeds itself automatically using trusted random sources
  25 provided by the operating system.
  26
  27 As a normal application developer, you don't have to worry about any details,
  28 just use L<RAND_bytes(3)> to obtain random data.
  29 Having said that, there is one important rule to obey: Always check the error
  30 return value of L<RAND_bytes(3)> and don't take randomness for granted.
  31
  32 For long-term secrets, you can use L<RAND_priv_bytes(3)> instead.
  33 This method does not provide 'better' randomness, it uses the same type of CSPRNG.
  34 The intention behind using a dedicated CSPRNG exclusively for long-term secrets is
  35 that none  of its output should be visible to an attacker (e.g used as salt value),
  36 in order  to reveal as little information as possible about its internal state.
  37
  38 In the rare case where the default implementation does not satisfy your special
  39 requirements, there are two options:
  40
  41 =over 2
  42
  43 =item *
  44
  45 Replace the default RAND method by your own RAND method using
  46 L<RAND_set_rand_method(3)>.
  47
  48 =item *
  49
  50 Modify the default settings of the OpenSSL RAND method by modifying the security
  51 parameters of the underlying DRBG, which is described in detail in L<RAND_DRBG(7)>.
  52
  53 =back
  54
  55 Changing the default random generator or its default parameters should be necessary
  56 only in exceptional cases and is not recommended, unless you have a profound knowledge
  57 of cryptographic principles and understand the implications of your changes.
  58
  59 =head1 SEE ALSO
  60
  61 L<RAND_add(3)>,
  62 L<RAND_bytes(3)>,
  63 L<RAND_priv_bytes(3)>,
  64 L<RAND_get_rand_method(3)>
  65 L<RAND_set_rand_method(3)>
  66 L<RAND_OpenSSL(3)>,
  67 L<RAND_DRBG(7)>,
  68
  69 =head1 COPYRIGHT
  70
  71 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
  72
  73 Licensed under the OpenSSL license (the "License").  You may not use
  74 this file except in compliance with the License.  You can obtain a copy
  75 in the file LICENSE in the source distribution or at
  76 L<https://www.openssl.org/source/license.html>.
  77
  78 =cut