From ef0fcf26c920c011948f078481739f4e2c31535f Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 6 Nov 2013 11:12:45 -0800 Subject: Add a default_backend and start updating docs. --- docs/hazmat/primitives/symmetric-encryption.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 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 eef359d6..42d2090c 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -12,6 +12,9 @@ Symmetric Encryption key = binascii.unhexlify(b"0" * 32) iv = binascii.unhexlify(b"0" * 32) + from cryptography.hazmat.bindings import default_backend + backend = default_backend() + Symmetric encryption is a way to encrypt (hide the plaintext value) material where the sender and receiver both use the same key. Note that symmetric @@ -22,7 +25,7 @@ For this reason it is *strongly* recommended to combine encryption with a message authentication code, such as :doc:`HMAC `, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. -.. class:: Cipher(algorithm, mode) +.. class:: Cipher(algorithm, mode, backend) Cipher objects combine an algorithm (such as :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a @@ -33,8 +36,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: - >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv)) + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, mode + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() -- cgit v1.2.3 From 846460ae25554cbf007c0b65f8d7997d543ea53e Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 6 Nov 2013 11:24:50 -0800 Subject: Fix doctests. --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (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 42d2090c..e7d019da 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -36,7 +36,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: - >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, mode + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() -- cgit v1.2.3 From 63fa19ace98c2c88a6065acc9e944a71480ff651 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 20 Nov 2013 10:49:13 -0800 Subject: Use backend as keyword argument everywhere. --- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 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 e7d019da..76f68a12 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -37,7 +37,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend) + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() @@ -179,7 +179,7 @@ Weak Ciphers >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes >>> algorithm = algorithms.ARC4(key) - >>> cipher = Cipher(algorithm, mode=None) + >>> cipher = Cipher(algorithm, mode=None, backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") >>> decryptor = cipher.decryptor() -- cgit v1.2.3 From 663295d015d4aa65258f14d91c6350726604350c Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 20 Nov 2013 13:55:08 -0800 Subject: Document all the parameters including cross references to specific providers where appropriate. --- docs/hazmat/primitives/symmetric-encryption.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 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 76f68a12..f63ad90a 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -44,8 +44,16 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. >>> decryptor.update(ct) + decryptor.finalize() 'a secret message' - :param algorithms: One of the algorithms described below. - :param mode: One of the modes described below. + :param algorithms: A + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider such as those described + :ref:`below `. + :param mode: A :class:`~cryptography.hazmat.primitives.interfaces.Mode` + provider such as those described + :ref:`below `. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend` + provider. .. method:: encryptor() @@ -98,6 +106,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :meth:`update` and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. +.. _symmetric-encryption-algorithms: + Algorithms ~~~~~~~~~~ -- cgit v1.2.3 From 797dd83d81915d5bab8791e513fcb26051870eb7 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 22 Nov 2013 13:08:58 -0800 Subject: Documentation! --- docs/hazmat/primitives/symmetric-encryption.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (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 eef359d6..35b0d9a8 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -75,6 +75,15 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. everything into the context. Once that is done call ``finalize()`` to finish the operation and obtain the remainder of the data. + Block ciphers require that plaintext or ciphertext always be a multiple of + their block size, because of that **padding** is often required to make a + message the correct size. ``CipherContext`` will not automatically apply + any padding; you'll need to add your own. For block ciphers the reccomended + padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you + are using a stream cipher mode (such as + :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry + about this. + .. method:: update(data) :param bytes data: The data you wish to pass into the context. @@ -90,6 +99,13 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. method:: finalize() :return bytes: Returns the remainder of the data. + :raises cryptography.exceptions.IncorrectPadding: This is raised when + the data provided + isn't correctly + padded to be a + multiple of the + algorithm's block + size. Once ``finalize`` is called this object can no longer be used and :meth:`update` and :meth:`finalize` will raise -- cgit v1.2.3 From bae899ad36bcb99dbec94aaf026ef1650f2b1242 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 22 Nov 2013 16:54:55 -0800 Subject: Change teh exception --- docs/hazmat/primitives/symmetric-encryption.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 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 35b0d9a8..732af33c 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -99,13 +99,9 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. method:: finalize() :return bytes: Returns the remainder of the data. - :raises cryptography.exceptions.IncorrectPadding: This is raised when - the data provided - isn't correctly - padded to be a - multiple of the - algorithm's block - size. + :raises ValueError: This is raised when the data provided isn't + correctly padded to be a multiple of the + algorithm's block size. Once ``finalize`` is called this object can no longer be used and :meth:`update` and :meth:`finalize` will raise -- cgit v1.2.3