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') 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 f1569b6abbba6920ca343c62721098e0ce8c7f9c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 22 Nov 2013 13:09:38 -0800 Subject: One more documentation --- docs/exceptions.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index ab1b28fe..b0435b0c 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -13,3 +13,7 @@ Exceptions This is raised when a backend doesn't support the requested algorithm (or combination of algorithms). + +.. class:: IncorrectPadding + + This is raised when a block cipher's content isn't correctly padded. -- 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/exceptions.rst | 5 ----- docs/hazmat/primitives/padding.rst | 8 +++++++- docs/hazmat/primitives/symmetric-encryption.rst | 10 +++------- 3 files changed, 10 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index b0435b0c..c6f5a7cc 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -12,8 +12,3 @@ Exceptions This is raised when a backend doesn't support the requested algorithm (or combination of algorithms). - - -.. class:: IncorrectPadding - - This is raised when a block cipher's content isn't correctly padded. diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index aebb4d4d..4d79ac8f 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -25,8 +25,14 @@ multiple of the block size. >>> padder = padding.PKCS7(128).padder() >>> padder.update(b"1111111111") '' - >>> padder.finalize() + >>> padded_data = padder.finalize() + >>> padded_data '1111111111\x06\x06\x06\x06\x06\x06' + >>> unpadder = padding.PKCS7(128).unpadder() + >>> unpadder.update(padded_data) + '' + >>> unpadder.finalize() + '1111111111' :param block_size: The size of the block in bits that the data is being padded to. 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