From 3c68250ad9bfb275c760fcce4c72c78c99b57c34 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 10 Dec 2018 12:13:31 +0800 Subject: allow bytes-like for key/iv/data for symmetric encryption (#4621) * allow bytearrays for key/iv for symmetric encryption * bump pypy/cffi requirements * update docs, fix some tests * old openssl is naught but pain * revert a typo * use trusty for old pypy * better error msg again * restore match --- docs/hazmat/primitives/symmetric-encryption.rst | 69 ++++++++++++++++--------- 1 file changed, 44 insertions(+), 25 deletions(-) (limited to 'docs/hazmat/primitives/symmetric-encryption.rst') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 31f240c4..4924ddd6 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -92,8 +92,9 @@ Algorithms AES is both fast, and cryptographically strong. It is a good default choice for encryption. - :param bytes key: The secret key. This must be kept secret. Either ``128``, + :param key: The secret key. This must be kept secret. Either ``128``, ``192``, or ``256`` :term:`bits` long. + :type key: :term:`bytes-like` .. class:: Camellia(key) @@ -101,8 +102,9 @@ Algorithms It is considered to have comparable security and performance to AES but is not as widely studied or deployed. - :param bytes key: The secret key. This must be kept secret. Either ``128``, + :param key: The secret key. This must be kept secret. Either ``128``, ``192``, or ``256`` :term:`bits` long. + :type key: :term:`bytes-like` .. class:: ChaCha20(key) @@ -120,15 +122,17 @@ Algorithms ChaCha20 is a stream cipher used in several IETF protocols. It is standardized in :rfc:`7539`. - :param bytes key: The secret key. This must be kept secret. ``256`` + :param key: The secret key. This must be kept secret. ``256`` :term:`bits` (32 bytes) in length. + :type key: :term:`bytes-like` - :param bytes nonce: Should be unique, a :term:`nonce`. It is + :param nonce: Should be unique, a :term:`nonce`. 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. The nonce does not need to be kept secret and may be included with the ciphertext. This must be ``128`` :term:`bits` in length. + :type nonce: :term:`bytes-like` .. note:: @@ -161,12 +165,13 @@ Algorithms Nonetheless, Triple DES is not recommended for new applications because it is incredibly slow; old applications should consider moving away from it. - :param bytes key: The secret key. This must be kept secret. Either ``64``, + :param key: The secret key. This must be kept secret. Either ``64``, ``128``, or ``192`` :term:`bits` long. DES only uses ``56``, ``112``, or ``168`` bits of the key as there is a parity byte in each component of the key. Some writing refers to there being up to three separate keys that are each ``56`` bits long, they can simply be concatenated to produce the full key. + :type key: :term:`bytes-like` .. class:: CAST5(key) @@ -177,8 +182,9 @@ Algorithms a variable key length cipher and supports keys from 40-128 :term:`bits` in length. - :param bytes key: The secret key, This must be kept secret. 40 to 128 + :param key: The secret key, This must be kept secret. 40 to 128 :term:`bits` in length in increments of 8 bits. + :type key: :term:`bytes-like` .. class:: SEED(key) @@ -188,8 +194,9 @@ Algorithms (KISA). It is defined in :rfc:`4269` and is used broadly throughout South Korean industry, but rarely found elsewhere. - :param bytes key: The secret key. This must be kept secret. ``128`` + :param key: The secret key. This must be kept secret. ``128`` :term:`bits` in length. + :type key: :term:`bytes-like` Weak ciphers ------------ @@ -206,8 +213,9 @@ Weak ciphers susceptible to attacks when using weak keys. The author has recommended that users of Blowfish move to newer algorithms such as :class:`AES`. - :param bytes key: The secret key. This must be kept secret. 32 to 448 + :param key: The secret key. This must be kept secret. 32 to 448 :term:`bits` in length in increments of 8 bits. + :type key: :term:`bytes-like` .. class:: ARC4(key) @@ -215,9 +223,10 @@ Weak ciphers initial stream output. Its use is strongly discouraged. ARC4 does not use mode constructions. - :param bytes key: The secret key. This must be kept secret. Either ``40``, + :param key: The secret key. This must be kept secret. Either ``40``, ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` :term:`bits` in length. + :type key: :term:`bytes-like` .. doctest:: @@ -238,8 +247,9 @@ Weak ciphers is susceptible to attacks when using weak keys. It is recommended that you do not use this cipher for new applications. - :param bytes key: The secret key. This must be kept secret. ``128`` + :param key: The secret key. This must be kept secret. ``128`` :term:`bits` in length. + :type key: :term:`bytes-like` .. _symmetric-encryption-modes: @@ -256,13 +266,14 @@ Modes **Padding is required when using this mode.** - :param bytes initialization_vector: Must be :doc:`random bytes + :param 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``. + :type initialization_vector: :term:`bytes-like` A good construction looks like: @@ -295,12 +306,13 @@ Modes **This mode does not require padding.** - :param bytes nonce: Should be unique, a :term:`nonce`. It is + :param nonce: Should be unique, a :term:`nonce`. 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. + :type nonce: :term:`bytes-like` .. class:: OFB(initialization_vector) @@ -309,11 +321,12 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be :doc:`random bytes + :param 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``. + :type initialization_vector: :term:`bytes-like` .. class:: CFB(initialization_vector) @@ -322,11 +335,12 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be :doc:`random bytes + :param 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``. + :type initialization_vector: :term:`bytes-like` .. class:: CFB8(initialization_vector) @@ -336,11 +350,12 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be :doc:`random bytes + :param 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``. + :type initialization_vector: :term:`bytes-like` .. class:: GCM(initialization_vector, tag=None, min_tag_length=16) @@ -368,12 +383,13 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be unique, a :term:`nonce`. + :param initialization_vector: Must be unique, a :term:`nonce`. 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 :term:`bits`. Do not reuse an ``initialization_vector`` with a given ``key``. + :type initialization_vector: :term:`bytes-like` .. note:: @@ -495,11 +511,11 @@ Modes **This mode does not require padding.** - :param bytes tweak: The tweak is a 16 byte value typically derived from + :param tweak: The tweak is a 16 byte value typically derived from something like the disk sector number. A given ``(tweak, key)`` pair should not be reused, although doing so is less catastrophic than in CTR mode. - + :type tweak: :term:`bytes-like` Insecure modes -------------- @@ -544,7 +560,8 @@ Interfaces .. method:: update(data) - :param bytes data: The data you wish to pass into the context. + :param data: The data you wish to pass into the context. + :type data: :term:`bytes-like` :return bytes: Returns the data that was encrypted or decrypted. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` @@ -567,7 +584,8 @@ Interfaces requirement and you will be making many small calls to ``update_into``. - :param bytes data: The data you wish to pass into the context. + :param data: The data you wish to pass into the context. + :type data: :term:`bytes-like` :param buf: A writable Python buffer that the data will be written into. This buffer should be ``len(data) + n - 1`` bytes where ``n`` is the block size (in bytes) of the cipher and mode combination. @@ -629,7 +647,8 @@ Interfaces .. method:: authenticate_additional_data(data) - :param bytes data: Any data you wish to authenticate but not encrypt. + :param data: Any data you wish to authenticate but not encrypt. + :type data: :term:`bytes-like` :raises: :class:`~cryptography.exceptions.AlreadyFinalized` .. class:: AEADEncryptionContext @@ -747,7 +766,7 @@ Interfaces used by the symmetric cipher modes described in .. attribute:: initialization_vector - :type: bytes + :type: :term:`bytes-like` Exact requirements of the initialization are described by the documentation of individual modes. @@ -759,7 +778,7 @@ Interfaces used by the symmetric cipher modes described in .. attribute:: nonce - :type: bytes + :type: :term:`bytes-like` Exact requirements of the nonce are described by the documentation of individual modes. @@ -771,7 +790,7 @@ Interfaces used by the symmetric cipher modes described in .. attribute:: tag - :type: bytes + :type: :term:`bytes-like` Exact requirements of the tag are described by the documentation of individual modes. @@ -785,7 +804,7 @@ Interfaces used by the symmetric cipher modes described in .. attribute:: tweak - :type: bytes + :type: :term:`bytes-like` Exact requirements of the tweak are described by the documentation of individual modes. -- cgit v1.2.3