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
|
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 (and then decrypting)
content with AES is:
.. doctest::
>>> from cryptography.primitives.block import BlockCipher, ciphers, modes
>>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv))
>>> encryptor = cipher.encryptor()
>>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
>>> decryptor = cipher.decryptor()
>>> decryptor.update(ct) + decryptor.finalize()
b"a secret message"
:param cipher: One of the ciphers described below.
:param mode: One of the modes described below.
.. method:: encryptor()
:return :ref:`CipherContext <ciphercontext>`: encryption instance
.. method:: decryptor()
:return :ref:`CipherContext <ciphercontext>`: decryption instance
.. _ciphercontext:
.. class:: cryptography.primitives.interfaces.CipherContext()
When calling ``encryptor()`` or ``decryptor()`` on a BlockCipher object you
will receive a return object conforming to the CipherContext interface. You
can then call ``update(data)`` with data until you have fed everything into
the context. Once that is done call ``finalize()`` to finish the operation and
obtain the remainder of the data.
.. method:: update(data)
:param bytes data: The text you wish to pass into the context.
:return bytes: Returns the data that was encrypted or decrypted.
.. method:: finalize()
:return bytes: Returns the remainder of the data.
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.
.. class:: cryptography.primitives.block.ciphers.Camellia(key)
Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC.
It is considered to have comparable security and performance to AES, but
is not as widely studied or deployed.
:param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits.
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``.
.. class:: cryptography.primitives.block.modes.CTR(nonce)
.. warning::
Counter mode is not recommended for use with block ciphers that have a
block size of less than 128-bits.
CTR (Counter) is a mode of operation for block ciphers. It is considered
cryptographically strong.
:param bytes nonce: Should be random bytes. It is critical to never reuse a
``nonce`` with a given key. Any reuse of a nonce
with the same key compromises the security of every
message encrypted with that key. Must be the same
number of bytes as the ``block_size`` of the cipher
with a given key. The nonce does not need to be kept
secret and may be included alongside the ciphertext.
.. class:: cryptography.primitives.block.modes.OFB(initialization_vector)
OFB (Output Feedback) is a mode of operation for block ciphers. It
transforms a block cipher into a stream cipher.
: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``.
.. class:: cryptography.primitives.block.modes.CFB(initialization_vector)
CFB (Cipher Feedback) is a mode of operation for block ciphers. It
transforms a block cipher into a stream cipher.
: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``.
Insecure Modes
--------------
.. warning::
These modes are insecure. New applications should never make use of them,
and existing applications should strongly consider migrating away.
.. class:: cryptography.primitives.block.modes.ECB()
ECB (Electronic Code Book) is the simplest mode of operation for block
ciphers. Each block of data is encrypted in the same way. This means
identical plaintext blocks will always result in identical ciphertext
blocks, and thus result in information leakage
|
