1 files changed, 56 insertions, 11 deletions
diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst
index a60f5ac8..9581df88 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-Padding
-=======
+Symmetric Padding
+=================
 
 .. module:: cryptography.hazmat.primitives.padding
 
@@ -25,33 +25,76 @@ multiple of the block size.
         >>> padder = padding.PKCS7(128).padder()
         >>> padded_data = padder.update(b"11111111111111112222222222")
         >>> padded_data
-        '1111111111111111'
+        b'1111111111111111'
         >>> padded_data += padder.finalize()
         >>> padded_data
-        '11111111111111112222222222\x06\x06\x06\x06\x06\x06'
+        b'11111111111111112222222222\x06\x06\x06\x06\x06\x06'
         >>> unpadder = padding.PKCS7(128).unpadder()
         >>> data = unpadder.update(padded_data)
         >>> data
-        '1111111111111111'
+        b'1111111111111111'
         >>> data + unpadder.finalize()
-        '11111111111111112222222222'
+        b'11111111111111112222222222'
 
-    :param block_size: The size of the block in bits that the data is being
-                       padded to.
+    :param block_size: The size of the block in :term:`bits` that the data is
+        being padded to.
     :raises ValueError: Raised if block size is not a multiple of 8 or is not
-        between 0 and 256.
+        between 0 and 2040 inclusive.
 
     .. method:: padder()
 
         :returns: A padding
             :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
-            provider.
+            instance.
 
     .. method:: unpadder()
 
         :returns: An unpadding
             :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
-            provider.
+            instance.
+
+
+.. class:: ANSIX923(block_size)
+
+    .. versionadded:: 1.3
+
+    `ANSI X.923`_ padding works by appending ``N-1`` bytes with the value of
+    ``0`` and a last byte 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::
+
+        >>> padder = padding.ANSIX923(128).padder()
+        >>> padded_data = padder.update(b"11111111111111112222222222")
+        >>> padded_data
+        b'1111111111111111'
+        >>> padded_data += padder.finalize()
+        >>> padded_data
+        b'11111111111111112222222222\x00\x00\x00\x00\x00\x06'
+        >>> unpadder = padding.ANSIX923(128).unpadder()
+        >>> data = unpadder.update(padded_data)
+        >>> data
+        b'1111111111111111'
+        >>> data + unpadder.finalize()
+        b'11111111111111112222222222'
+
+    :param block_size: The size of the block in :term:`bits` that the data is
+        being padded to.
+    :raises ValueError: Raised if block size is not a multiple of 8 or is not
+        between 0 and 2040 inclusive.
+
+    .. method:: padder()
+
+        :returns: A padding
+            :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
+            instance.
+
+    .. method:: unpadder()
+
+        :returns: An unpadding
+            :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
+            instance.
 
 
 .. class:: PaddingContext
@@ -82,3 +125,5 @@ multiple of the block size.
         :raises TypeError: Raised if data is not bytes.
         :raises ValueError: When trying to remove padding from incorrectly
                             padded data.
+
+.. _`ANSI X.923`: https://en.wikipedia.org/wiki/Padding_%28cryptography%29#ANSI_X9.23