diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/primitives/cryptographic-hashes.rst | 4 | ||||
| -rw-r--r-- | docs/primitives/symmetric-encryption.rst | 53 |
2 files changed, 47 insertions, 10 deletions
diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index d4dde042..aeb30f40 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -1,11 +1,13 @@ Message Digests =============== -.. class:: cryptography.primitives.hashes.BaseHash +.. class:: cryptography.primitives.hashes.BaseHash(data=None) Abstract base class that implements a common interface for all hash algorithms that follow here. + If ``data`` is provided ``update(data)`` is called upon construction. + .. method:: update(data) :param bytes data: The bytes you wish to hash. diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 7899e67d..73d8ad37 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -15,29 +15,47 @@ where the encrypter and decrypter both use the same key. Block ciphers work by encrypting content in chunks, often 64- or 128-bits. They combine an underlying algorithm (such as AES), with a mode (such as - CBC, CTR, or GCM). A simple example of encrypting content with AES is: + CBC, CTR, or GCM). A simple example of encrypting (and then decrypting) + content with AES is: .. doctest:: >>> from cryptography.primitives.block import BlockCipher, ciphers, modes >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv)) - >>> cipher.encrypt(b"a secret message") + cipher.finalize() - '...' + >>> encryptor = cipher.encryptor() + >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() + >>> decryptor = cipher.decryptor() + >>> decryptor.update(ct) + decryptor.finalize() + 'a secret message' :param cipher: One of the ciphers described below. :param mode: One of the modes described below. - ``encrypt()`` should be called repeatedly with new plaintext, and once the - full plaintext is fed in, ``finalize()`` should be called. + .. method:: encryptor() - .. method:: encrypt(plaintext) + :return :class:`CipherContext`: encryption instance - :param bytes plaintext: The text you wish to encrypt. - :return bytes: Returns the ciphertext that was added. + .. method:: decryptor() + + :return :class:`CipherContext`: decryption instance + +.. class:: cryptography.primitives.interfaces.CipherContext() + + When calling ``encryptor()`` or ``decryptor()`` on a BlockCipher object you + will receive a return object conforming to the CipherContext interface. You + can then call ``update(data)`` with data until you have fed everything into + the context. Once that is done call ``finalize()`` to finish the operation and + obtain the remainder of the data. + + + .. method:: update(data) + + :param bytes data: The text you wish to pass into the context. + :return bytes: Returns the data that was encrypted or decrypted. .. method:: finalize() - :return bytes: Returns the remainder of the ciphertext. + :return bytes: Returns the remainder of the data. Ciphers ~~~~~~~ @@ -61,6 +79,23 @@ Ciphers This must be kept secret. +.. class:: cryptography.primitives.block.ciphers.TripleDES(key) + + Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a + block cipher standardized by NIST. Triple DES has known cryptoanalytic + flaws, however none of them currently enable a practical attack. + Nonetheless, Triples DES is not reccomended for new applications because it + is incredibly slow; old applications should consider moving away from it. + + :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits + (note that DES functionally uses ``56``, ``112``, or + ``168`` bits of the key, there is a parity byte in each + component of the key), in some materials these are + referred to as being up to three separate keys (each + ``56`` bits long), they can simply be concatenated to + produce the full key. This must be kept secret. + + Modes ~~~~~ |