From 5f3db274a3b427803ec6f4dc7b50943d6d18c4e6 Mon Sep 17 00:00:00 2001
From: Alex Gaynor <alex.gaynor@gmail.com>
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/primitives')

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