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
|
Symmetric Encryption
====================
.. testsetup::
import binascii
key = binascii.unhexlify(b"0" * 32)
iv = binascii.unhexlify(b"0" * 32)
Symmetric encryption is a way to encrypt (hide the plaintext value) material
where the encrypter and decrypter both use the same key.
.. class:: cryptography.primitives.block.BlockCipher(cipher, mode)
Block ciphers work by encrypting content in chunks, often 64- or 128-bits.
They combine an underlying algorithm (such as AES), with a mode (such as
CBC, CTR, or GCM). A simple example of encrypting content with AES is:
.. doctest::
>>> from cryptography.primitives.block import BlockCipher, ciphers, modes
>>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv))
>>> cipher.encrypt(b"a secret message") + cipher.finalize()
'...'
:param cipher: One of the ciphers described below.
:param mode: One of the modes described below.
``encrypt()`` should be called repeatedly with new plaintext, and once the
full plaintext is fed in, ``finalize()`` should be called.
.. method:: encrypt(plaintext)
:param bytes plaintext: The text you wish to encrypt.
:return bytes: Returns the ciphertext that was added.
.. method:: finalize()
:return bytes: Returns the remainder of the ciphertext.
Ciphers
~~~~~~~
.. class:: cryptography.primitives.block.ciphers.AES(key)
AES (Advanced Encryption Standard) is a block cipher standardized by NIST.
AES is both fast, and cryptographically strong. It is a good default
choice for encryption.
:param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits.
This must be kept secret.
Insecure Ciphers
----------------
.. class:: cryptography.primitives.block.ciphers.TripleDES(key)
Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a
block cipher standardized by NIST. Triple DES should be considered to be
cryptographically broken and should not be used for new applications, old
applications should strongly consider moving away from it.
:param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits
(note that DES functionally uses ``56``, ``112``, or
``168`` bits of the key, there is a parity byte in each
component of the key), in some materials these are
referred to as being up to three separate keys (each
``56`` bits long), they can simply be concatenated to
produce the full key. This must be kept secret.
Modes
~~~~~
.. class:: cryptography.primitives.block.modes.CBC(initialization_vector)
CBC (Cipher block chaining) is a mode of operation for block ciphers. It is
considered cryptographically strong.
:param bytes initialization_vector: Must be random bytes. They do not need
to be kept secret (they can be included
in a transmitted message). Must be the
same number of bytes as the
``block_size`` of the cipher. Do not
reuse an ``initialization_vector`` with
a given ``key``.
|
