diff options
author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2017-09-28 23:46:49 +0800 |
---|---|---|
committer | Alex Gaynor <alex.gaynor@gmail.com> | 2017-09-28 11:46:49 -0400 |
commit | 62ebb429fe94693e5b94480025f3f3e0556b83b1 (patch) | |
tree | d4ecaceab10179e4ead9fc21e20b873dfe1fcbb9 /docs/hazmat/primitives | |
parent | ba61c2738e5a79480d135c280316e29080a4a777 (diff) | |
download | cryptography-62ebb429fe94693e5b94480025f3f3e0556b83b1.tar.gz cryptography-62ebb429fe94693e5b94480025f3f3e0556b83b1.tar.bz2 cryptography-62ebb429fe94693e5b94480025f3f3e0556b83b1.zip |
add ChaCha20 support (#3919)
* add ChaCha20 support
* review feedback
* 256 divided by 8 is what again?
* ...
Diffstat (limited to 'docs/hazmat/primitives')
-rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 49 |
1 files changed, 49 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index d6479a44..10a349b1 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -104,6 +104,55 @@ Algorithms :param bytes key: The secret key. This must be kept secret. Either ``128``, ``192``, or ``256`` bits long. +.. class:: ChaCha20(key) + + .. versionadded:: 2.1 + + .. note:: + + In most cases users should use + :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305` + instead of this class. `ChaCha20` alone does not provide integrity + so it must be combined with a MAC to be secure. + :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305` + does this for you. + + 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`` bits + (32 bytes) in length. + + :param bytes 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`` bits in + length. + + .. note:: + + In :rfc:`7539` the nonce is defined as a 96-bit value that is later + concatenated with a block counter (encoded as a 32-bit + little-endian). If you have a separate nonce and block counter + you will need to concatenate it yourself before passing it. For + example if you have an initial block counter of 2 and a 96-bit + nonce the concatenated nonce would be + ``struct.pack("<i", 2) + nonce``. + + .. doctest:: + + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.backends import default_backend + >>> nonce = os.urandom(16) + >>> algorithm = algorithms.ChaCha20(key, nonce) + >>> cipher = Cipher(algorithm, mode=None, backend=default_backend()) + >>> encryptor = cipher.encryptor() + >>> ct = encryptor.update(b"a secret message") + >>> decryptor = cipher.decryptor() + >>> decryptor.update(ct) + 'a secret message' + .. class:: TripleDES(key) Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a |