• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. hazmat::
2
3Symmetric Padding
4=================
5
6.. module:: cryptography.hazmat.primitives.padding
7
8Padding is a way to take data that may or may not be a multiple of the block
9size for a cipher and extend it out so that it is. This is required for many
10block cipher modes as they require the data to be encrypted to be an exact
11multiple of the block size.
12
13
14.. class:: PKCS7(block_size)
15
16    PKCS7 padding is a generalization of PKCS5 padding (also known as standard
17    padding). PKCS7 padding works by appending ``N`` bytes with the value of
18    ``chr(N)``, where ``N`` is the number of bytes required to make the final
19    block of data the same size as the block size. A simple example of padding
20    is:
21
22    .. doctest::
23
24        >>> from cryptography.hazmat.primitives import padding
25        >>> padder = padding.PKCS7(128).padder()
26        >>> padded_data = padder.update(b"11111111111111112222222222")
27        >>> padded_data
28        b'1111111111111111'
29        >>> padded_data += padder.finalize()
30        >>> padded_data
31        b'11111111111111112222222222\x06\x06\x06\x06\x06\x06'
32        >>> unpadder = padding.PKCS7(128).unpadder()
33        >>> data = unpadder.update(padded_data)
34        >>> data
35        b'1111111111111111'
36        >>> data + unpadder.finalize()
37        b'11111111111111112222222222'
38
39    :param block_size: The size of the block in :term:`bits` that the data is
40        being padded to.
41    :raises ValueError: Raised if block size is not a multiple of 8 or is not
42        between 0 and 2040 inclusive.
43
44    .. method:: padder()
45
46        :returns: A padding
47            :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
48            instance.
49
50    .. method:: unpadder()
51
52        :returns: An unpadding
53            :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
54            instance.
55
56
57.. class:: ANSIX923(block_size)
58
59    .. versionadded:: 1.3
60
61    `ANSI X.923`_ padding works by appending ``N-1`` bytes with the value of
62    ``0`` and a last byte with the value of ``chr(N)``, where ``N`` is the
63    number of bytes required to make the final block of data the same size as
64    the block size. A simple example of padding is:
65
66    .. doctest::
67
68        >>> padder = padding.ANSIX923(128).padder()
69        >>> padded_data = padder.update(b"11111111111111112222222222")
70        >>> padded_data
71        b'1111111111111111'
72        >>> padded_data += padder.finalize()
73        >>> padded_data
74        b'11111111111111112222222222\x00\x00\x00\x00\x00\x06'
75        >>> unpadder = padding.ANSIX923(128).unpadder()
76        >>> data = unpadder.update(padded_data)
77        >>> data
78        b'1111111111111111'
79        >>> data + unpadder.finalize()
80        b'11111111111111112222222222'
81
82    :param block_size: The size of the block in :term:`bits` that the data is
83        being padded to.
84    :raises ValueError: Raised if block size is not a multiple of 8 or is not
85        between 0 and 2040 inclusive.
86
87    .. method:: padder()
88
89        :returns: A padding
90            :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
91            instance.
92
93    .. method:: unpadder()
94
95        :returns: An unpadding
96            :class:`~cryptography.hazmat.primitives.padding.PaddingContext`
97            instance.
98
99
100.. class:: PaddingContext
101
102    When calling ``padder()`` or ``unpadder()`` the result will conform to the
103    ``PaddingContext`` interface. You can then call ``update(data)`` with data
104    until you have fed everything into the context. Once that is done call
105    ``finalize()`` to finish the operation and obtain the remainder of the
106    data.
107
108    .. method:: update(data)
109
110        :param bytes data: The data you wish to pass into the context.
111        :return bytes: Returns the data that was padded or unpadded.
112        :raises TypeError: Raised if data is not bytes.
113        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`.
114        :raises TypeError: This exception is raised if ``data`` is not ``bytes``.
115
116    .. method:: finalize()
117
118        Finalize the current context and return the rest of the data.
119
120        After ``finalize`` has been called this object can no longer be used;
121        :meth:`update` and :meth:`finalize` will raise an
122        :class:`~cryptography.exceptions.AlreadyFinalized` exception.
123
124        :return bytes: Returns the remainder of the data.
125        :raises TypeError: Raised if data is not bytes.
126        :raises ValueError: When trying to remove padding from incorrectly
127                            padded data.
128
129.. _`ANSI X.923`: https://en.wikipedia.org/wiki/Padding_%28cryptography%29#ANSI_X9.23
130