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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
|
.. hazmat::
Interfaces
==========
``cryptography`` uses `Abstract Base Classes`_ as interfaces to describe the
properties and methods of most primitive constructs. Backends may also use
this information to influence their operation. Interfaces should also be used
to document argument and return types.
.. _`Abstract Base Classes`: https://docs.python.org/3/library/abc.html
Symmetric ciphers
-----------------
.. currentmodule:: cryptography.hazmat.primitives.interfaces
.. class:: CipherAlgorithm
A named symmetric encryption algorithm.
.. attribute:: name
:type: str
The standard name for the mode, for example, "AES", "Camellia", or
"Blowfish".
.. attribute:: key_size
:type: int
The number of bits in the key being used.
.. class:: BlockCipherAlgorithm
A block cipher algorithm.
.. attribute:: block_size
:type: int
The number of bits in a block.
Cipher modes
~~~~~~~~~~~~
Interfaces used by the symmetric cipher modes described in
:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`.
.. class:: Mode
A named cipher mode.
.. attribute:: name
:type: str
This should be the standard shorthand name for the mode, for example
Cipher-Block Chaining mode is "CBC".
The name may be used by a backend to influence the operation of a
cipher in conjunction with the algorithm's name.
.. method:: validate_for_algorithm(algorithm)
:param CipherAlgorithm algorithm:
Checks that the combination of this mode with the provided algorithm
meets any necessary invariants. This should raise an exception if they
are not met.
For example, the :class:`~cryptography.hazmat.primitives.modes.CBC`
mode uses this method to check that the provided initialization
vector's length matches the block size of the algorithm.
.. class:: ModeWithInitializationVector
A cipher mode with an initialization vector.
.. attribute:: initialization_vector
:type: bytes
Exact requirements of the initialization are described by the
documentation of individual modes.
.. class:: ModeWithNonce
A cipher mode with a nonce.
.. attribute:: nonce
:type: bytes
Exact requirements of the nonce are described by the documentation of
individual modes.
Asymmetric interfaces
---------------------
.. class:: AsymmetricSignatureContext
.. versionadded:: 0.2
.. method:: update(data)
:param bytes data: The data you want to sign.
.. method:: finalize()
:return bytes signature: The signature.
.. class:: AsymmetricVerificationContext
.. versionadded:: 0.2
.. method:: update(data)
:param bytes data: The data you wish to verify using the signature.
.. method:: verify()
:raises cryptography.exceptions.InvalidSignature: If the signature does
not validate.
.. class:: AsymmetricPadding
.. versionadded:: 0.2
.. attribute:: name
RSA
~~~
In 0.8 the RSA key interfaces were moved to the
:mod:`cryptography.hazmat.primitives.asymmetric.rsa` module.
.. class:: EllipticCurve
.. versionadded:: 0.5
A named elliptic curve.
.. attribute:: name
:type: string
The name of the curve. Usually the name used for the ASN.1 OID such as
``secp256k1``.
.. attribute:: key_size
:type: int
The bit length of the curve's base point.
Elliptic Curve
~~~~~~~~~~~~~~
.. class:: EllipticCurveSignatureAlgorithm
.. versionadded:: 0.5
A signature algorithm for use with elliptic curve keys.
.. attribute:: algorithm
:type: :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
The digest algorithm to be used with the signature scheme.
.. class:: EllipticCurvePrivateKey
.. versionadded:: 0.5
An elliptic curve private key for use with an algorithm such as `ECDSA`_ or
`EdDSA`_.
.. method:: signer(signature_algorithm)
Sign data which can be verified later by others using the public key.
The signature is formatted as DER-encoded bytes, as specified in
:rfc:`6979`.
:param signature_algorithm: An instance of a
:class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm`
provider.
:returns:
:class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
:type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
.. method:: public_key()
:return: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey`
The EllipticCurvePublicKey object for this private key.
.. class:: EllipticCurvePrivateKeyWithNumbers
.. versionadded:: 0.6
Extends :class:`EllipticCurvePrivateKey`.
.. method:: private_numbers()
Create a
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateNumbers`
object.
:returns: An
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateNumbers`
instance.
.. class:: EllipticCurvePublicKey
.. versionadded:: 0.5
An elliptic curve public key.
.. method:: verifier(signature, signature_algorithm)
Verify data was signed by the private key associated with this public
key.
:param bytes signature: The signature to verify. DER encoded as
specified in :rfc:`6979`.
:param signature_algorithm: An instance of a
:class:`~cryptography.hazmat.primitives.interfaces.EllipticCurveSignatureAlgorithm`
provider.
:returns:
:class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
.. attribute:: curve
:type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve`
The elliptic curve for this key.
.. class:: EllipticCurvePublicKeyWithNumbers
.. versionadded:: 0.6
Extends :class:`EllipticCurvePublicKey`.
.. method:: public_numbers()
Create a
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers`
object.
:returns: An
:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers`
instance.
Hash algorithms
---------------
.. class:: HashAlgorithm
.. attribute:: name
:type: str
The standard name for the hash algorithm, for example: ``"sha256"`` or
``"whirlpool"``.
.. attribute:: digest_size
:type: int
The size of the resulting digest in bytes.
.. attribute:: block_size
:type: int
The internal block size of the hash algorithm in bytes.
.. class:: HashContext
.. attribute:: algorithm
A :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` that
will be used by this context.
.. method:: update(data)
:param bytes data: The data you want to hash.
.. method:: finalize()
:return: The final digest as bytes.
.. method:: copy()
:return: A :class:`~cryptography.hazmat.primitives.interfaces.HashContext`
that is a copy of the current context.
Key derivation functions
------------------------
.. class:: KeyDerivationFunction
.. versionadded:: 0.2
.. method:: derive(key_material)
:param bytes key_material: The input key material. Depending on what
key derivation function you are using this
could be either random bytes, or a user
supplied password.
:return: The new key.
:raises cryptography.exceptions.AlreadyFinalized: This is raised when
:meth:`derive` or
:meth:`verify` is
called more than
once.
This generates and returns a new key from the supplied key material.
.. method:: verify(key_material, expected_key)
:param bytes key_material: The input key material. This is the same as
``key_material`` in :meth:`derive`.
:param bytes expected_key: The expected result of deriving a new key,
this is the same as the return value of
:meth:`derive`.
:raises cryptography.exceptions.InvalidKey: This is raised when the
derived key does not match
the expected key.
:raises cryptography.exceptions.AlreadyFinalized: This is raised when
:meth:`derive` or
:meth:`verify` is
called more than
once.
This checks whether deriving a new key from the supplied
``key_material`` generates the same key as the ``expected_key``, and
raises an exception if they do not match. This can be used for
something like checking whether a user's password attempt matches the
stored derived key.
`Message Authentication Code`_
------------------------------
.. class:: CMACContext
:class:`CMACContext` has been deprecated in favor of :class:`MACContext`.
.. versionadded:: 0.4
.. method:: update(data)
:param bytes data: The data you want to authenticate.
.. method:: finalize()
:return: The message authentication code.
.. method:: copy()
:return: A :class:`~cryptography.hazmat.primitives.interfaces.CMACContext`
that is a copy of the current context.
.. class:: MACContext
.. versionadded:: 0.7
.. method:: update(data)
:param bytes data: The data you want to authenticate.
.. method:: finalize()
:return: The message authentication code.
.. method:: copy()
:return: A
:class:`~cryptography.hazmat.primitives.interfaces.MACContext` that
is a copy of the current context.
.. method:: verify(signature)
:param bytes signature: The signature to verify.
:raises cryptography.exceptions.InvalidSignature: This is raised when
the provided signature does not match the expected signature.
.. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
.. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem
.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm
.. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
.. _`ECDSA`: https://en.wikipedia.org/wiki/ECDSA
.. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA
|