From 5f3db274a3b427803ec6f4dc7b50943d6d18c4e6 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 10:56:35 -0700 Subject: Start of docs --- docs/hazmat/primitives/index.rst | 1 + docs/hazmat/primitives/padding.rst | 44 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 docs/hazmat/primitives/padding.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 3927f3f0..ee1e251c 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -14,3 +14,4 @@ Primitives cryptographic-hashes hmac symmetric-encryption + padding diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst new file mode 100644 index 00000000..995ed9f3 --- /dev/null +++ b/docs/hazmat/primitives/padding.rst @@ -0,0 +1,44 @@ +.. danger:: + + This is a "Hazardous Materials" module. You should **ONLY** use it if + you're 100% absolutely sure that you know what you're doing because this + module is full of land mines, dragons, and dinosaurs with laser guns. + + +Padding +======= + + +Padding is a way to take data that may or may not be be a multiple of the block +size for a cipher and extend it out so that it is. This is required for many +block cipher modes as they require the data to be encrypted to be an exact +multiple of the block size. + + +.. class:: cryptography.primitives.padding.PKCS7(block_size) + + PKCS7 padding is a generalization of PKCS5 padding (also known as standard + padding). PKCS7 padding works by appending ``N`` bytes with the value of + ``chr(N)``, where ``N`` is the number of bytes required to make the final + block of data the same size as the block size. A simple example of padding + is: + + .. doctest:: + + >>> from cryptography.primitives import padding + >>> padder = padding.PKCS7(128) + >>> padder.pad(b"1111111111") + '1111111111\x06\x06\x06\x06\x06\x06' + + :param block_size: The size of the block in bits that the data is being + padded to. + + .. method:: pad(data) + + :param data: The data that should be padded. + :rtype bytes: The padded data. + + .. method:: unpad(data) + + :param data: The data that should be unpadded. + :rtype bytes: The unpadded data. -- cgit v1.2.3 From b2d5efdc5a6e7f6df635b4bc60882bb2e5f14a66 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 11:15:30 -0700 Subject: More docs --- docs/hazmat/primitives/padding.rst | 35 ++++++++++++++++++++++++- docs/hazmat/primitives/symmetric-encryption.rst | 15 +++++------ 2 files changed, 41 insertions(+), 9 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index 995ed9f3..ebcc6104 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -8,6 +8,7 @@ Padding ======= +.. currentmodule:: cryptography.hazmat.primitives.padding Padding is a way to take data that may or may not be be a multiple of the block size for a cipher and extend it out so that it is. This is required for many @@ -15,7 +16,7 @@ block cipher modes as they require the data to be encrypted to be an exact multiple of the block size. -.. class:: cryptography.primitives.padding.PKCS7(block_size) +.. class:: PKCS7(block_size) PKCS7 padding is a generalization of PKCS5 padding (also known as standard padding). PKCS7 padding works by appending ``N`` bytes with the value of @@ -42,3 +43,35 @@ multiple of the block size. :param data: The data that should be unpadded. :rtype bytes: The unpadded data. + + .. method:: padder() + + :returns: A padding + :class:`~cryptography.hazmat.primitives.interfaces.PaddingContext` + provider. + + .. method:: unpadder() + + :returns: An unpadding + :class:`~cryptography.hazmat.primitives.interfaces.PaddingContext` + provider. + + +.. currentmodule:: cryptography.hazmat.primitives.interfaces + +.. class:: PaddingContext + + When calling ``padder()`` or ``unpadder()`` you will receive an a return + object conforming to the ``PaddingContext`` 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 data you wish to pass into the context. + :return bytes: Returns the data that was padded or unpadded. + + .. method:: finalize() + + :return bytes: Returns the remainder of the data. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 758a4648..9a5bce07 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -54,18 +54,17 @@ where the encrypter and decrypter both use the same key. .. currentmodule:: cryptography.hazmat.primitives.interfaces -.. class:: 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. +.. class:: 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. + :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. .. method:: finalize() -- cgit v1.2.3 From 07082782db43d697627f6eaf2d0b7c8ca209ab6a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 11:18:23 -0700 Subject: typo --- docs/hazmat/primitives/padding.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index ebcc6104..7cbadeb9 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -26,7 +26,7 @@ multiple of the block size. .. doctest:: - >>> from cryptography.primitives import padding + >>> from cryptography.hazmat.primitives import padding >>> padder = padding.PKCS7(128) >>> padder.pad(b"1111111111") '1111111111\x06\x06\x06\x06\x06\x06' -- cgit v1.2.3 From 22e2eaee0b48318c3a3e5eda7ce9174ac8cfce6a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 11:42:14 -0700 Subject: Removed helper --- docs/hazmat/primitives/padding.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index 7cbadeb9..1ad2bb83 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -28,7 +28,10 @@ multiple of the block size. >>> from cryptography.hazmat.primitives import padding >>> padder = padding.PKCS7(128) - >>> padder.pad(b"1111111111") + >>> padder = padder.padder() + >>> padder.update(b"1111111111") + '' + >>> padder.finalize() '1111111111\x06\x06\x06\x06\x06\x06' :param block_size: The size of the block in bits that the data is being -- cgit v1.2.3 From f0bec9c3efe7f6def1b9b4ae53f0278e7cfbadba Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 13:35:57 -0700 Subject: Remove removed methods from docs --- docs/hazmat/primitives/padding.rst | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index 1ad2bb83..4b05acd1 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -37,16 +37,6 @@ multiple of the block size. :param block_size: The size of the block in bits that the data is being padded to. - .. method:: pad(data) - - :param data: The data that should be padded. - :rtype bytes: The padded data. - - .. method:: unpad(data) - - :param data: The data that should be unpadded. - :rtype bytes: The unpadded data. - .. method:: padder() :returns: A padding -- cgit v1.2.3 From 60ad3e182476d84daeb7cff9d333623a688edd61 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 29 Oct 2013 14:26:11 -0700 Subject: Clean up var naming --- docs/hazmat/primitives/padding.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index 4b05acd1..ba3ddcc0 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -27,8 +27,7 @@ multiple of the block size. .. doctest:: >>> from cryptography.hazmat.primitives import padding - >>> padder = padding.PKCS7(128) - >>> padder = padder.padder() + >>> padder = padding.PKCS7(128).padder() >>> padder.update(b"1111111111") '' >>> padder.finalize() -- cgit v1.2.3