aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat/primitives/symmetric-encryption.rst
diff options
context:
space:
mode:
authorAlex Gaynor <alex.gaynor@gmail.com>2014-12-19 10:29:56 -0800
committerAlex Gaynor <alex.gaynor@gmail.com>2014-12-19 10:29:56 -0800
commit9b6fd8e8b6876cbc88d8cfbe452bb38af256f22d (patch)
tree57b8600328f6175ccd2a156b80868c831de55dea /docs/hazmat/primitives/symmetric-encryption.rst
parente4a0e8ad6ae0322635b47284e5d9ad1725bf9731 (diff)
downloadcryptography-9b6fd8e8b6876cbc88d8cfbe452bb38af256f22d.tar.gz
cryptography-9b6fd8e8b6876cbc88d8cfbe452bb38af256f22d.tar.bz2
cryptography-9b6fd8e8b6876cbc88d8cfbe452bb38af256f22d.zip
Anywhere we tell someone to randomly generate something, link the RNG docs. Fixes #1559
Diffstat (limited to 'docs/hazmat/primitives/symmetric-encryption.rst')
-rw-r--r--docs/hazmat/primitives/symmetric-encryption.rst64
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::