Package Crypto :: Package Cipher :: Module blockalgo :: Class BlockAlgo
[frames] | no frames]

Class BlockAlgo

Known Subclasses:

Class modelling an abstract block cipher.
Instance Methods
 
__init__(self, factory, key, *args, **kwargs)
 
update(self, assoc_data)
Protect associated data
 
encrypt(self, plaintext)
Encrypt data with the key and the parameters set at initialization.
 
decrypt(self, ciphertext)
Decrypt data with the key and the parameters set at initialization.
 
digest(self)
Compute the binary MAC tag in an AEAD mode.
 
hexdigest(self)
Compute the printable MAC tag in an AEAD mode.
 
verify(self, mac_tag)
Validate the binary MAC tag in an AEAD mode.
 
hexverify(self, hex_mac_tag)
Validate the printable MAC tag in an AEAD mode.
 
encrypt_and_digest(self, plaintext)
Perform encrypt() and digest() in one step.
 
decrypt_and_verify(self, ciphertext, mac_tag)
Perform decrypt() and verify() in one step.
Method Details

update(self, assoc_data)

 

Protect associated data

When using an AEAD mode like CCM, EAX, GCM or SIV, and if there is any associated data, the caller has to invoke this function one or more times, before using decrypt or encrypt.

By associated data it is meant any data (e.g. packet headers) that will not be encrypted and will be transmitted in the clear. However, the receiver is still able to detect any modification to it. In CCM and GCM, the associated data is also called additional authenticated data (AAD). In EAX, the associated data is called header.

If there is no associated data, this method must not be called.

The caller may split associated data in segments of any size, and invoke this method multiple times, each time with the next segment.

Parameters:
  • assoc_data (byte string) - A piece of associated data. There are no restrictions on its size.

encrypt(self, plaintext)

 

Encrypt data with the key and the parameters set at initialization.

A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object.

For MODE_SIV (always) and MODE_CCM (when msg_len was not passed at initialization), this method can be called only once.

For all other modes, the data to encrypt can be broken up in two or more pieces and encrypt can be called multiple times.

That is, the statement:

>>> c.encrypt(a) + c.encrypt(b)

is equivalent to:

>>> c.encrypt(a+b)

That also means that you cannot reuse an object for encrypting or decrypting other data with the same key.

This function does not add any padding to the plaintext.

  • For MODE_ECB and MODE_CBC, plaintext length (in bytes) must be a multiple of block_size.
  • For MODE_CFB, plaintext length (in bytes) must be a multiple of segment_size/8.
  • For MODE_OFB, MODE_CTR and all AEAD modes plaintext can be of any length.
  • For MODE_OPENPGP, plaintext must be a multiple of block_size, unless it is the last chunk of the message.
Parameters:
  • plaintext (byte string) - The piece of data to encrypt.
Returns:
the encrypted data, as a byte string. It is as long as plaintext with one exception: when encrypting the first message chunk with MODE_OPENPGP, the encypted IV is prepended to the returned ciphertext.

decrypt(self, ciphertext)

 

Decrypt data with the key and the parameters set at initialization.

A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object.

For MODE_SIV (always) and MODE_CCM (when msg_len was not passed at initialization), this method can be called only once.

For all other modes, the data to decrypt can be broken up in two or more pieces and decrypt can be called multiple times.

That is, the statement:

>>> c.decrypt(a) + c.decrypt(b)

is equivalent to:

>>> c.decrypt(a+b)

That also means that you cannot reuse an object for encrypting or decrypting other data with the same key.

This function does not remove any padding from the plaintext.

  • For MODE_ECB and MODE_CBC, ciphertext length (in bytes) must be a multiple of block_size.
  • For MODE_CFB, ciphertext length (in bytes) must be a multiple of segment_size/8.
  • For MODE_OFB, MODE_CTR and all AEAD modes ciphertext can be of any length.
  • For MODE_OPENPGP, plaintext must be a multiple of block_size, unless it is the last chunk of the message.
  • For MODE_SIV, ciphertext can be of any length, but it must also include the MAC (concatenated at the end).
Parameters:
  • ciphertext (byte string) - The piece of data to decrypt (plus the MAC, for MODE_SIV only).
Returns:
the decrypted data (byte string).

digest(self)

 

Compute the binary MAC tag in an AEAD mode.

When using an AEAD mode like CCM or EAX, the caller invokes this function at the very end.

This method returns the MAC that shall be sent to the receiver, together with the ciphertext.

Returns:
the MAC, as a byte string.

hexdigest(self)

 

Compute the printable MAC tag in an AEAD mode.

This method is like digest.

Returns:
the MAC, as a hexadecimal string.

verify(self, mac_tag)

 

Validate the binary MAC tag in an AEAD mode.

When using an AEAD mode like CCM or EAX, the caller invokes this function at the very end.

This method checks if the decrypted message is indeed valid (that is, if the key is correct) and it has not been tampered with while in transit.

Parameters:
  • mac_tag (byte string) - This is the binary MAC, as received from the sender.
Raises:
  • ValueError - if the MAC does not match. The message has been tampered with or the key is incorrect.

hexverify(self, hex_mac_tag)

 

Validate the printable MAC tag in an AEAD mode.

This method is like verify.

Parameters:
  • hex_mac_tag (string) - This is the printable MAC, as received from the sender.
Raises:
  • ValueError - if the MAC does not match. The message has been tampered with or the key is incorrect.

encrypt_and_digest(self, plaintext)

 
Perform encrypt() and digest() in one step.
Parameters:
  • plaintext (byte string) - The piece of data to encrypt.
Returns:

a tuple with two byte strings:

  • the encrypted data
  • the MAC

decrypt_and_verify(self, ciphertext, mac_tag)

 
Perform decrypt() and verify() in one step.
Parameters:
  • ciphertext (byte string) - The piece of data to decrypt.
  • mac_tag (byte string) - This is the binary MAC, as received from the sender.
Returns:
the decrypted data (byte string).
Raises:
  • ValueError - if the MAC does not match. The message has been tampered with or the key is incorrect.