From dec09fc490a09785744e4885f705f231c7ba1eec Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 17:23:16 -0500 Subject: update docs to reflect new encryptor API --- docs/primitives/symmetric-encryption.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 7899e67d..4f404789 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -21,7 +21,8 @@ where the encrypter and decrypter both use the same key. >>> from cryptography.primitives.block import BlockCipher, ciphers, modes >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv)) - >>> cipher.encrypt(b"a secret message") + cipher.finalize() + >>> context = cipher.encryptor() + >>> context.update(b"a secret message") + context.finalize() '...' :param cipher: One of the ciphers described below. -- cgit v1.2.3 From 653463f0e133def71425a26fdd80bfe7c8ad5961 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 21 Oct 2013 17:55:01 -0500 Subject: address review comments * inline some methods * refactor enc/dec classes * modify docs --- docs/primitives/symmetric-encryption.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 4f404789..a8d9485d 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -15,14 +15,17 @@ 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)) - >>> context = cipher.encryptor() - >>> context.update(b"a secret message") + context.finalize() + >>> encrypt = cipher.encryptor() + >>> ct = encrypt.update(b"a secret message") + encrypt.finalize() + >>> decrypt = cipher.decryptor() + >>> decrypt.update(ct) + decrypt.finalize() '...' :param cipher: One of the ciphers described below. -- cgit v1.2.3 From 3e0895c66f3e220d9beaf4f3c53a687a81669bc8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 21 Oct 2013 22:19:29 -0500 Subject: rename variables in encrypt/decrypt example --- docs/primitives/symmetric-encryption.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index a8d9485d..1ec1ee01 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -22,10 +22,10 @@ where the encrypter and decrypter both use the same key. >>> from cryptography.primitives.block import BlockCipher, ciphers, modes >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv)) - >>> encrypt = cipher.encryptor() - >>> ct = encrypt.update(b"a secret message") + encrypt.finalize() - >>> decrypt = cipher.decryptor() - >>> decrypt.update(ct) + decrypt.finalize() + >>> encryptor = cipher.encryptor() + >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() + >>> decryptor = cipher.decryptor() + >>> decryptor.update(ct) + decryptor.finalize() '...' :param cipher: One of the ciphers described below. -- cgit v1.2.3 From 5399fd087268b671c61ad3710cdec6d540c02f22 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 21 Oct 2013 23:48:25 -0500 Subject: Create CipherContext interface & document it * Rename BlockCipherEncryption/DecryptionContexts to just CipherEncryption/DecryptionContext * Moved register to interfaces.py from modes.py since it is generic and can be used to decorate the _CipherEncryption/DecryptionContexts --- docs/primitives/symmetric-encryption.rst | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 1ec1ee01..2021356c 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -15,7 +15,7 @@ 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 (and then decrypting) + CBC, CTR, or GCM).A simple example of encrypting (and then decrypting) content with AES is: .. doctest:: @@ -31,17 +31,32 @@ where the encrypter and decrypter both use the same key. :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 :ref:`CipherContext `: encryption instance - :param bytes plaintext: The text you wish to encrypt. - :return bytes: Returns the ciphertext that was added. + .. method:: decryptor() + + :return :ref:`CipherContext `: decryption instance + +.. _ciphercontext: +.. 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 ~~~~~~~ -- cgit v1.2.3 From d1afe39ac8961d865974b746ff072ecedc9abeee Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 22 Oct 2013 08:24:44 -0500 Subject: fix typo and show result of decryption in docs --- docs/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 2021356c..544c7163 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -15,7 +15,7 @@ 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 (and then decrypting) + CBC, CTR, or GCM). A simple example of encrypting (and then decrypting) content with AES is: .. doctest:: @@ -26,7 +26,7 @@ where the encrypter and decrypter both use the same key. >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() >>> decryptor.update(ct) + decryptor.finalize() - '...' + b"a secret message" :param cipher: One of the ciphers described below. :param mode: One of the modes described below. -- cgit v1.2.3 From f1903e96777ac8722357a45dbc5da3276c9f8e06 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 22 Oct 2013 10:11:27 -0500 Subject: fix doc test failure --- docs/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 544c7163..72bf9711 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -26,7 +26,7 @@ where the encrypter and decrypter both use the same key. >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() >>> decryptor.update(ct) + decryptor.finalize() - b"a secret message" + "a secret message" :param cipher: One of the ciphers described below. :param mode: One of the modes described below. -- cgit v1.2.3 From f6cf956321ad99fe5bf071eb8832dbf2192c0ff5 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 22 Oct 2013 10:36:00 -0500 Subject: more docs --- docs/primitives/symmetric-encryption.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 72bf9711..79d712e5 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -26,20 +26,19 @@ where the encrypter and decrypter both use the same key. >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() >>> decryptor.update(ct) + decryptor.finalize() - "a secret message" + 'a secret message' :param cipher: One of the ciphers described below. :param mode: One of the modes described below. .. method:: encryptor() - :return :ref:`CipherContext `: encryption instance + :return :class:`CipherContext`: encryption instance .. method:: decryptor() - :return :ref:`CipherContext `: decryption instance + :return :class:`CipherContext`: decryption instance -.. _ciphercontext: .. class:: cryptography.primitives.interfaces.CipherContext() When calling ``encryptor()`` or ``decryptor()`` on a BlockCipher object you -- cgit v1.2.3