Package Crypto :: Package Cipher :: Module AES
[frames] | no frames]

Module AES

AES symmetric cipher

AES (Advanced Encryption Standard) is a symmetric block cipher standardized by NIST . It has a fixed data block size of 16 bytes. Its keys can be 128, 192, or 256 bits long.

AES is very fast and secure, and it is the de facto standard for symmetric encryption.

As an example, encryption can be done as follows:

>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>> key = b'Sixteen byte key'
>>> iv = get_random_bytes(16)
>>> cipher = AES.new(key, AES.MODE_CFB, iv)
>>> msg = iv + cipher.encrypt(b'Attack at dawn')

A more complicated example is based on CCM, (see MODE_CCM) an AEAD mode that provides both confidentiality and authentication for a message.

It optionally allows the header of the message to remain in the clear, whilst still being authenticated. The encryption is done as follows:

>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>>
>>> hdr = b'To your eyes only'
>>> plaintext = b'Attack at dawn'
>>> key = b'Sixteen byte key'
>>> nonce = get_random_bytes(11)
>>> cipher = AES.new(key, AES.MODE_CCM, nonce)
>>> cipher.update(hdr)
>>> msg = nonce, hdr, cipher.encrypt(plaintext), cipher.digest()

We assume that the tuple msg is transmitted to the receiver:

>>> nonce, hdr, ciphertext, mac = msg
>>> key = b'Sixteen byte key'
>>> cipher = AES.new(key, AES.MODE_CCM, nonce)
>>> cipher.update(hdr)
>>> plaintext = cipher.decrypt(ciphertext)
>>> try:
>>>     cipher.verify(mac)
>>>     print "The message is authentic: hdr=%s, pt=%s" % (hdr, plaintext)
>>> except ValueError:
>>>     print "Key incorrect or message corrupted"
Classes
  AESCipher
AES cipher object
Functions
 
new(key, *args, **kwargs)
Create a new AES cipher
Variables
  MODE_ECB = 1
Electronic Code Book (ECB).
  MODE_CBC = 2
Cipher-Block Chaining (CBC).
  MODE_CFB = 3
Cipher FeedBack (CFB).
  MODE_PGP = 4
This mode should not be used.
  MODE_OFB = 5
Output FeedBack (OFB).
  MODE_CTR = 6
CounTer Mode (CTR).
  MODE_OPENPGP = 7
OpenPGP Mode.
  MODE_CCM = 8
Counter with CBC-MAC (CCM) Mode.
  MODE_EAX = 9
EAX Mode.
  MODE_SIV = 10
Syntethic Initialization Vector (SIV).
  MODE_GCM = 11
Galois Counter Mode (GCM).
  block_size = 16
Size of a data block (in bytes)
  key_size = (16, 24, 32)
Size of a key (in bytes)
Function Details

new(key, *args, **kwargs)

 
Create a new AES cipher
Parameters:
  • key (byte string) - The secret key to use in the symmetric cipher. It must be 16 (AES-128), 24 (AES-192), or 32 (AES-256) bytes long.

    Only in MODE_SIV, it needs to be 32, 48, or 64 bytes long.

  • mode (a MODE_* constant) - The chaining mode to use for encryption or decryption. Default is MODE_ECB.
  • IV (byte string) - (Only MODE_CBC, MODE_CFB, MODE_OFB, MODE_OPENPGP).

    The initialization vector to use for encryption or decryption.

    It is ignored for MODE_ECB and MODE_CTR.

    For MODE_OPENPGP, IV must be block_size bytes long for encryption and block_size +2 bytes for decryption (in the latter case, it is actually the encrypted IV which was prefixed to the ciphertext). It is mandatory.

    For all other modes, it must be 16 bytes long.

  • nonce (byte string) - (Only MODE_CCM, MODE_EAX, MODE_GCM, MODE_SIV).

    A mandatory value that must never be reused for any other encryption.

    For MODE_CCM, its length must be in the range [7..13]. 11 or 12 bytes are reasonable values in general. Bear in mind that with CCM there is a trade-off between nonce length and maximum message size.

    For the other modes, there are no restrictions on its length, but it is recommended to use at least 16 bytes.

  • counter (callable) - (Only MODE_CTR). A stateful function that returns the next counter block, which is a byte string of block_size bytes. For better performance, use Crypto.Util.Counter.
  • segment_size (integer) - (Only MODE_CFB).The number of bits the plaintext and ciphertext are segmented in. It must be a multiple of 8. If 0 or not specified, it will be assumed to be 8.
  • mac_len (integer) - (Only MODE_CCM). Length of the MAC, in bytes. It must be even and in the range [4..16]. The default is 16.

    (Only MODE_EAX and MODE_GCM). Length of the MAC, in bytes. It must be no larger than 16 bytes (which is the default).

  • msg_len (integer) - (Only MODE_CCM). Length of the message to (de)cipher. If not specified, encrypt or decrypt may only be called once.
  • assoc_len (integer) - (Only MODE_CCM). Length of the associated data. If not specified, all data is internally buffered.
  • use_aesni (boolean) - Use AES-NI if available.
Returns:
an AESCipher object

Variables Details

MODE_ECB

Electronic Code Book (ECB). See blockalgo.MODE_ECB.
Value:
1

MODE_CBC

Cipher-Block Chaining (CBC). See blockalgo.MODE_CBC.
Value:
2

MODE_CFB

Cipher FeedBack (CFB). See blockalgo.MODE_CFB.
Value:
3

MODE_OFB

Output FeedBack (OFB). See blockalgo.MODE_OFB.
Value:
5

MODE_CTR

CounTer Mode (CTR). See blockalgo.MODE_CTR.
Value:
6

MODE_OPENPGP

OpenPGP Mode. See blockalgo.MODE_OPENPGP.
Value:
7

MODE_CCM

Counter with CBC-MAC (CCM) Mode. See blockalgo.MODE_CCM.
Value:
8

MODE_EAX

EAX Mode. See blockalgo.MODE_EAX.
Value:
9

MODE_SIV

Syntethic Initialization Vector (SIV). See blockalgo.MODE_SIV.
Value:
10

MODE_GCM

Galois Counter Mode (GCM). See blockalgo.MODE_GCM.
Value:
11