1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
.. hazmat::
Authenticated encryption
========================
.. module:: cryptography.hazmat.primitives.ciphers.aead
Authenticated encryption with associated data (AEAD) are encryption schemes
which provide both confidentiality and integrity for their ciphertext. They
also support providing integrity for associated data which is not encrypted.
.. class:: ChaCha20Poly1305(key)
.. versionadded:: 2.0
The ChaCha20Poly1305 construction is defined in :rfc:`7539` section 2.8.
It is a stream cipher combined with a MAC that offers strong integrity
guarantees.
:param key: A 32-byte key. This **must** be kept secret.
:type key: :term:`bytes-like`
:raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
OpenSSL does not support ChaCha20Poly1305.
.. doctest::
>>> import os
>>> from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
>>> data = b"a secret message"
>>> aad = b"authenticated but unencrypted data"
>>> key = ChaCha20Poly1305.generate_key()
>>> chacha = ChaCha20Poly1305(key)
>>> nonce = os.urandom(12)
>>> ct = chacha.encrypt(nonce, data, aad)
>>> chacha.decrypt(nonce, ct, aad)
b'a secret message'
.. classmethod:: generate_key()
Securely generates a random ChaCha20Poly1305 key.
:returns bytes: A 32 byte key.
.. method:: encrypt(nonce, data, associated_data)
.. warning::
Reuse of a ``nonce`` with a given ``key`` compromises the security
of any message with that ``nonce`` and ``key`` pair.
Encrypts the ``data`` provided and authenticates the
``associated_data``. The output of this can be passed directly
to the ``decrypt`` method.
:param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to encrypt.
:param bytes associated_data: Additional data that should be
authenticated with the key, but does not need to be encrypted. Can
be ``None``.
:returns bytes: The ciphertext bytes with the 16 byte tag appended.
:raises OverflowError: If ``data`` or ``associated_data`` is larger
than 2\ :sup:`32` bytes.
.. method:: decrypt(nonce, data, associated_data)
Decrypts the ``data`` and authenticates the ``associated_data``. If you
called encrypt with ``associated_data`` you must pass the same
``associated_data`` in decrypt or the integrity check will fail.
:param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a
key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to decrypt (with tag appended).
:param bytes associated_data: Additional data to authenticate. Can be
``None`` if none was passed during encryption.
:returns bytes: The original plaintext.
:raises cryptography.exceptions.InvalidTag: If the authentication tag
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
.. class:: AESGCM(key)
.. versionadded:: 2.0
The AES-GCM construction is composed of the
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
cipher utilizing Galois Counter Mode (GCM).
:param key: A 128, 192, or 256-bit key. This **must** be kept secret.
:type key: :term:`bytes-like`
.. doctest::
>>> import os
>>> from cryptography.hazmat.primitives.ciphers.aead import AESGCM
>>> data = b"a secret message"
>>> aad = b"authenticated but unencrypted data"
>>> key = AESGCM.generate_key(bit_length=128)
>>> aesgcm = AESGCM(key)
>>> nonce = os.urandom(12)
>>> ct = aesgcm.encrypt(nonce, data, aad)
>>> aesgcm.decrypt(nonce, ct, aad)
b'a secret message'
.. classmethod:: generate_key(bit_length)
Securely generates a random AES-GCM key.
:param bit_length: The bit length of the key to generate. Must be
128, 192, or 256.
:returns bytes: The generated key.
.. method:: encrypt(nonce, data, associated_data)
.. warning::
Reuse of a ``nonce`` with a given ``key`` compromises the security
of any message with that ``nonce`` and ``key`` pair.
Encrypts and authenticates the ``data`` provided as well as
authenticating the ``associated_data``. The output of this can be
passed directly to the ``decrypt`` method.
:param nonce: NIST `recommends a 96-bit IV length`_ for best
performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to encrypt.
:param bytes associated_data: Additional data that should be
authenticated with the key, but is not encrypted. Can be ``None``.
:returns bytes: The ciphertext bytes with the 16 byte tag appended.
:raises OverflowError: If ``data`` or ``associated_data`` is larger
than 2\ :sup:`32` bytes.
.. method:: decrypt(nonce, data, associated_data)
Decrypts the ``data`` and authenticates the ``associated_data``. If you
called encrypt with ``associated_data`` you must pass the same
``associated_data`` in decrypt or the integrity check will fail.
:param nonce: NIST `recommends a 96-bit IV length`_ for best
performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to decrypt (with tag appended).
:param bytes associated_data: Additional data to authenticate. Can be
``None`` if none was passed during encryption.
:returns bytes: The original plaintext.
:raises cryptography.exceptions.InvalidTag: If the authentication tag
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
.. class:: AESCCM(key, tag_length=16)
.. versionadded:: 2.0
.. note:
AES-CCM is provided largely for compatibility with existing protocols.
Due to its construction it is not as computationally efficient as
other AEAD ciphers.
The AES-CCM construction is composed of the
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
cipher utilizing Counter with CBC-MAC (CCM) (specified in :rfc:`3610`).
:param key: A 128, 192, or 256-bit key. This **must** be kept secret.
:type key: :term:`bytes-like`
:param int tag_length: The length of the authentication tag. This
defaults to 16 bytes and it is **strongly** recommended that you
do not make it shorter unless absolutely necessary. Valid tag
lengths are 4, 6, 8, 10, 12, 14, and 16.
:raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
OpenSSL does not support AES-CCM.
.. doctest::
>>> import os
>>> from cryptography.hazmat.primitives.ciphers.aead import AESCCM
>>> data = b"a secret message"
>>> aad = b"authenticated but unencrypted data"
>>> key = AESCCM.generate_key(bit_length=128)
>>> aesccm = AESCCM(key)
>>> nonce = os.urandom(13)
>>> ct = aesccm.encrypt(nonce, data, aad)
>>> aesccm.decrypt(nonce, ct, aad)
b'a secret message'
.. classmethod:: generate_key(bit_length)
Securely generates a random AES-CCM key.
:param bit_length: The bit length of the key to generate. Must be
128, 192, or 256.
:returns bytes: The generated key.
.. method:: encrypt(nonce, data, associated_data)
.. warning::
Reuse of a ``nonce`` with a given ``key`` compromises the security
of any message with that ``nonce`` and ``key`` pair.
Encrypts and authenticates the ``data`` provided as well as
authenticating the ``associated_data``. The output of this can be
passed directly to the ``decrypt`` method.
:param nonce: A value of between 7 and 13 bytes. The maximum
length is determined by the length of the ciphertext you are
encrypting and must satisfy the condition:
``len(data) < 2 ** (8 * (15 - len(nonce)))``
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to encrypt.
:param bytes associated_data: Additional data that should be
authenticated with the key, but is not encrypted. Can be ``None``.
:returns bytes: The ciphertext bytes with the tag appended.
:raises OverflowError: If ``data`` or ``associated_data`` is larger
than 2\ :sup:`32` bytes.
.. method:: decrypt(nonce, data, associated_data)
Decrypts the ``data`` and authenticates the ``associated_data``. If you
called encrypt with ``associated_data`` you must pass the same
``associated_data`` in decrypt or the integrity check will fail.
:param nonce: A value of between 7 and 13 bytes. This
is the same value used when you originally called encrypt.
**NEVER REUSE A NONCE** with a key.
:type nonce: :term:`bytes-like`
:param bytes data: The data to decrypt (with tag appended).
:param bytes associated_data: Additional data to authenticate. Can be
``None`` if none was passed during encryption.
:returns bytes: The original plaintext.
:raises cryptography.exceptions.InvalidTag: If the authentication tag
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
.. _`recommends a 96-bit IV length`: https://csrc.nist.gov/publications/detail/sp/800-38d/final
|
