Fixed #568 -- Document that users should use urandom for all their random numbers

2 files changed, 21 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 49e99be4..9114b895 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -59,6 +59,7 @@ The recipes layer
     :maxdepth: 2
 
     fernet
+    random-numbers
     exceptions
     glossary
 
diff --git a/docs/random-numbers.rst b/docs/random-numbers.rst
new file mode 100644
index 00000000..aa89c8e4
--- /dev/null
+++ b/docs/random-numbers.rst
@@ -0,0 +1,20 @@
+Random number generation
+========================
+
+When generating random data for use in cryptographic operations, such as an
+initialization vector for encryption in
+:class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode, you do not
+want to use the standard :mod:`random` module APIs. This is because they do not
+provide a cryptographically secure random number generator, resulting in
+various security issues in different algorithms.
+
+Therefore, it is our recommendation to always use your operating system's
+provided random number generator, which is available as ``os.urandom()``. For
+example, if you need 16 bytes of random data for an initialization vector, you
+can obtain them with:
+
+.. doctest::
+
+    >>> import os
+    >>> os.urandom(16)
+    '...'