Merge pull request #1561 from alex/link-random

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

3 files changed, 44 insertions, 40 deletions

diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
index 9ce49c8d..ce566c5c 100644
--- a/docs/hazmat/primitives/mac/hmac.rst
+++ b/docs/hazmat/primitives/mac/hmac.rst
@@ -19,9 +19,9 @@ of a message.
 
     HMAC objects take a ``key`` and a
     :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider.
-    The ``key`` should be randomly generated bytes and is recommended to be
-    equal in length to the ``digest_size`` of the hash function chosen.
-    You must keep the ``key`` secret.
+    The ``key`` should be :doc:`randomly generated bytes </random-numbers>` and
+    is recommended to be equal in length to the ``digest_size`` of the hash
+    function chosen. You must keep the ``key`` secret.
 
     This is an implementation of :rfc:`2104`.
 
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::
 
diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst
index f19cf0e6..0d86f7cc 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -18,9 +18,9 @@ codes (HMAC).
     .. versionadded:: 0.3
 
     HOTP objects take a ``key``, ``length`` and ``algorithm`` parameter. The
-    ``key`` should be randomly generated bytes and is recommended to be 160
-    bits in length. The ``length`` parameter controls the length of the
-    generated one time password and must be >= 6 and <= 8.
+    ``key`` should be :doc:`randomly generated bytes </random-numbers>` and is
+    recommended to be 160 bits in length. The ``length`` parameter controls the
+    length of the generated one time password and must be >= 6 and <= 8.
 
     This is an implementation of :rfc:`4226`.
 
@@ -113,10 +113,10 @@ similar to the following code.
 .. class:: TOTP(key, length, algorithm, time_step, backend)
 
     TOTP objects take a ``key``, ``length``, ``algorithm`` and ``time_step``
-    parameter. The ``key`` should be randomly generated bytes and is recommended
-    to be as long as your hash function's output (e.g 256-bit for SHA256).
-    The ``length`` parameter controls the length of the generated one time
-    password and must be >= 6 and <= 8.
+    parameter. The ``key`` should be :doc:`randomly generated bytes
+    </random-numbers>` and is recommended to be as long as your hash function's
+    output (e.g 256-bit for SHA256). The ``length`` parameter controls the
+    length of the generated one time password and must be >= 6 and <= 8.
 
     This is an implementation of :rfc:`6238`.