Merge pull request #1561 from alex/link-random

Anywhere we tell someone to randomly generate something, link the RNG docs. Fixes #1559

1 files changed, 34 insertions, 30 deletions

diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index b21ef612..8d3769f5 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -205,13 +205,13 @@ Modes
 
     **Padding is required when using this mode.**
 
-    :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret and they can be included in a transmitted message.
-        Must be the same number of bytes as the ``block_size`` of the cipher.
-        Each time something is encrypted a new ``initialization_vector`` should
-        be generated. Do not reuse an ``initialization_vector`` with a given
-        ``key``, and particularly do not use a constant
-        ``initialization_vector``.
+    :param bytes initialization_vector: Must be :doc:`random bytes
+        </random-numbers>`. They do not need to be kept secret and they can be
+        included in a transmitted message. Must be the same number of bytes as
+        the ``block_size`` of the cipher. Each time something is encrypted a
+        new ``initialization_vector`` should be generated. Do not reuse an
+        ``initialization_vector`` with a given ``key``, and particularly do not
+        use a constant ``initialization_vector``.
 
     A good construction looks like:
 
@@ -244,12 +244,12 @@ Modes
 
     **This mode does not require padding.**
 
-    :param bytes nonce: Should be random bytes. It is critical to never reuse a
-        ``nonce`` with a given key.  Any reuse of a nonce with the same key
-        compromises the security of every message encrypted with that key. Must
-        be the same number of bytes as the ``block_size`` of the cipher with a
-        given key. The nonce does not need to be kept secret and may be
-        included with the ciphertext.
+    :param bytes nonce: Should be :doc:`random bytes </random-numbers>`. It is
+        critical to never reuse a ``nonce`` with a given key.  Any reuse of a
+        nonce with the same key compromises the security of every message
+        encrypted with that key. Must be the same number of bytes as the
+        ``block_size`` of the cipher with a given key. The nonce does not need
+        to be kept secret and may be included with the ciphertext.
 
 .. class:: OFB(initialization_vector)
 
@@ -258,10 +258,11 @@ Modes
 
     **This mode does not require padding.**
 
-    :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret and they can be included in a transmitted message.
-        Must be the same number of bytes as the ``block_size`` of the cipher.
-        Do not reuse an ``initialization_vector`` with a given ``key``.
+    :param bytes initialization_vector: Must be :doc:`random bytes
+        </random-numbers>`. They do not need to be kept secret and they can be
+        included in a transmitted message. Must be the same number of bytes as
+        the ``block_size`` of the cipher. Do not reuse an
+        ``initialization_vector`` with a given ``key``.
 
 .. class:: CFB(initialization_vector)
 
@@ -270,10 +271,11 @@ Modes
 
     **This mode does not require padding.**
 
-    :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret and they can be included in a transmitted message.
-        Must be the same number of bytes as the ``block_size`` of the cipher.
-        Do not reuse an ``initialization_vector`` with a given ``key``.
+    :param bytes initialization_vector: Must be :doc:`random bytes
+        </random-numbers>`. They do not need to be kept secret and they can be
+        included in a transmitted message. Must be the same number of bytes as
+        the ``block_size`` of the cipher. Do not reuse an
+        ``initialization_vector`` with a given ``key``.
 
 .. class:: CFB8(initialization_vector)
 
@@ -283,10 +285,11 @@ Modes
 
     **This mode does not require padding.**
 
-    :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret and they can be included in a transmitted message.
-        Must be the same number of bytes as the ``block_size`` of the cipher.
-        Do not reuse an ``initialization_vector`` with a given ``key``.
+    :param bytes initialization_vector: Must be :doc:`random bytes
+        </random-numbers>`. They do not need to be kept secret and they can be
+        included in a transmitted message. Must be the same number of bytes as
+        the ``block_size`` of the cipher. Do not reuse an
+        ``initialization_vector`` with a given ``key``.
 
 .. class:: GCM(initialization_vector, tag=None, min_tag_length=16)
 
@@ -306,11 +309,12 @@ Modes
 
     **This mode does not require padding.**
 
-    :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret and they can be included in a transmitted message.
-        NIST `recommends a 96-bit IV length`_ for performance critical
-        situations but it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an
-        ``initialization_vector`` with a given ``key``.
+    :param bytes initialization_vector: Must be :doc:`random bytes
+        </random-numbers>`. They do not need to be kept secret and they can be
+        included in a transmitted message. NIST `recommends a 96-bit IV
+        length`_ for performance critical situations but it can be up to
+        2\ :sup:`64` - 1 bits. Do not reuse an ``initialization_vector`` with a
+        given ``key``.
 
     .. note::