diff options
Diffstat (limited to 'docs/hazmat/primitives/symmetric-encryption.rst')
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 64 |
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:: |