RAND.pod 3.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182
  1. =pod
  2. =head1 NAME
  3. RAND
  4. - the OpenSSL random generator
  5. =head1 DESCRIPTION
  6. Random numbers are a vital part of cryptography, they are needed to provide
  7. unpredictability for tasks like key generation, creating salts, and many more.
  8. Software-based generators must be seeded with external randomness before they
  9. can be used as a cryptographically-secure pseudo-random number generator
  10. (CSPRNG).
  11. The availability of common hardware with special instructions and
  12. modern operating systems, which may use items such as interrupt jitter
  13. and network packet timings, can be reasonable sources of seeding material.
  14. OpenSSL comes with a default implementation of the RAND API which is based on
  15. the deterministic random bit generator (DRBG) model as described in
  16. [NIST SP 800-90A Rev. 1]. The default random generator will initialize
  17. automatically on first use and will be fully functional without having
  18. to be initialized ('seeded') explicitly.
  19. It seeds and reseeds itself automatically using trusted random sources
  20. provided by the operating system.
  21. As a normal application developer, you do not have to worry about any details,
  22. just use L<RAND_bytes(3)> to obtain random data.
  23. Having said that, there is one important rule to obey: Always check the error
  24. return value of L<RAND_bytes(3)> and do not take randomness for granted.
  25. Although (re-)seeding is automatic, it can fail because no trusted random source
  26. is available or the trusted source(s) temporarily fail to provide sufficient
  27. random seed material.
  28. In this case the CSPRNG enters an error state and ceases to provide output,
  29. until it is able to recover from the error by reseeding itself.
  30. For more details on reseeding and error recovery, see L<EVP_RAND(7)>.
  31. For values that should remain secret, you can use L<RAND_priv_bytes(3)>
  32. instead.
  33. This method does not provide 'better' randomness, it uses the same type of
  34. CSPRNG.
  35. The intention behind using a dedicated CSPRNG exclusively for private
  36. values is that none of its output should be visible to an attacker (e.g.,
  37. used as salt value), in order to reveal as little information as
  38. possible about its internal state, and that a compromise of the "public"
  39. CSPRNG instance will not affect the secrecy of these private values.
  40. In the rare case where the default implementation does not satisfy your special
  41. requirements, the default RAND internals can be replaced by your own
  42. L<EVP_RAND(3)> objects.
  43. Changing the default random generator should be necessary
  44. only in exceptional cases and is not recommended, unless you have a profound
  45. knowledge of cryptographic principles and understand the implications of your
  46. changes.
  47. =head1 DEAFULT SETUP
  48. The default OpenSSL RAND method is based on the EVP_RAND deterministic random
  49. bit generator (DRBG) classes.
  50. A DRBG is a certain type of cryptographically-secure pseudo-random
  51. number generator (CSPRNG), which is described in [NIST SP 800-90A Rev. 1].
  52. =head1 SEE ALSO
  53. L<RAND_bytes(3)>,
  54. L<RAND_priv_bytes(3)>,
  55. L<EVP_RAND(3)>,
  56. L<RAND_get0_primary(3)>,
  57. L<EVP_RAND(7)>
  58. =head1 COPYRIGHT
  59. Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
  60. Licensed under the Apache License 2.0 (the "License"). You may not use
  61. this file except in compliance with the License. You can obtain a copy
  62. in the file LICENSE in the source distribution or at
  63. L<https://www.openssl.org/source/license.html>.
  64. =cut