From 9b6fd8e8b6876cbc88d8cfbe452bb38af256f22d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 19 Dec 2014 10:29:56 -0800 Subject: Anywhere we tell someone to randomly generate something, link the RNG docs. Fixes #1559 --- docs/hazmat/primitives/mac/hmac.rst | 6 +-- docs/hazmat/primitives/symmetric-encryption.rst | 64 +++++++++++++------------ docs/hazmat/primitives/twofactor.rst | 14 +++--- 3 files changed, 44 insertions(+), 40 deletions(-) (limited to 'docs/hazmat/primitives') 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 ` 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 + `. 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 `. 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 + `. 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 + `. 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 + `. 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 + `. 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 ` 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 + ` 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`. -- cgit v1.2.3