Anywhere we tell someone to randomly generate something, link the RNG docs. Fixes #1559
diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
index 9ce49c8..ce566c5 100644
--- a/docs/hazmat/primitives/mac/hmac.rst
+++ b/docs/hazmat/primitives/mac/hmac.rst
@@ -19,9 +19,9 @@
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 b21ef61..8d3769f 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -205,13 +205,13 @@
**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 @@
**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 @@
**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 @@
**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 @@
**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 @@
**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 f19cf0e..0d86f7c 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -18,9 +18,9 @@
.. 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 @@
.. 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`.