Package Cryptodome :: Package Cipher :: Module AES

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 Cryptodome.Cipher import AES
>>>
>>> key = b'Sixteen byte key'
>>> cipher = AES.new(key, AES.MODE_CFB)
>>> msg = cipher.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.

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

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

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

>>> from Cryptodome.Cipher import AES
>>>
>>> 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"

If no nonce is supplied initially, a 11 bytes random nonce is generated, which is good for a maximum message size of 4G. See CCM.

Functions
 
new(key, mode, *args, **kwargs)
Create a new AES cipher
Variables
  MODE_ECB = 1
Electronic Code Book (ECB). See Cryptodome.Cipher._mode_ecb.EcbMode.
  MODE_CBC = 2
Cipher-Block Chaining (CBC). See Cryptodome.Cipher._mode_cbc.CbcMode.
  MODE_CFB = 3
Cipher FeedBack (CFB). See Cryptodome.Cipher._mode_cfb.CfbMode.
  MODE_OFB = 5
Output FeedBack (OFB). See Cryptodome.Cipher._mode_ofb.OfbMode.
  MODE_CTR = 6
CounTer Mode (CTR). See Cryptodome.Cipher._mode_ctr.CtrMode.
  MODE_OPENPGP = 7
OpenPGP Mode. See Cryptodome.Cipher._mode_openpgp.OpenPgpMode.
  MODE_CCM = 8
Counter with CBC-MAC (CCM) Mode. See Cryptodome.Cipher._mode_ccm.CcmMode.
  MODE_EAX = 9
EAX Mode. See Cryptodome.Cipher._mode_eax.EaxMode.
  MODE_SIV = 10
Syntethic Initialization Vector (SIV). See Cryptodome.Cipher._mode_siv.SivMode.
  MODE_GCM = 11
Galois Counter Mode (GCM). See Cryptodome.Cipher._mode_gcm.GcmMode.
  MODE_OCB = 12
Offset Code Book (OCB). See Cryptodome.Cipher._mode_ocb.OcbMode.
  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, mode, *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. If in doubt, use MODE_EAX.
  • iv (byte string) - (Only MODE_CBC, MODE_CFB, MODE_OFB, MODE_OPENPGP).

    The initialization vector to use for encryption or decryption.

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

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

    In not provided, a random byte string is used (you must then read its value with the iv attribute).

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

    A value that must never be reused for any other encryption done with this key.

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

    For MODE_OCB, its length must be in the range [1..15].

    For MODE_CTR, its length must be in the range [0..15].

    For the other modes, there are no restrictions on its length.

    The recommended length depends on the mode: 8 bytes for MODE_CTR, 11 bytes for MODE_CCM, 15 bytes for MODE_OCB and 16 bytes for the remaining modes.

    In not provided, a random byte string of the recommended length is used (you must then read its value with the nonce attribute).

  • 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 not specified, it will be assumed to be 8.
  • mac_len (integer) - (Only MODE_EAX, MODE_GCM, MODE_OCB, MODE_CCM) Length of the authentication tag, in bytes.

    It must be even and in the range [4..16]. The recommended value (and the default, if not specified) is 16.

  • msg_len (integer) - (Only MODE_CCM). Length of the message to (de)cipher. If not specified, encrypt must be called with the entire message. Similarly, decrypt can only be called once.
  • assoc_len (integer) - (Only MODE_CCM). Length of the associated data. If not specified, all associated data is buffered internally, which may represent a problem for very large messages.
  • initial_value (integer) - (Only MODE_CTR). The initial value for the counter within the counter block. By default it is 0.
  • use_aesni (boolean) - Use Intel AES-NI hardware extensions if available.
Returns:

an AES object, of the applicable mode: