symcrypto

class symcrypto.AuthenticatedCryptoAbstraction(key, alg=0, mode=2)

Bases: symcrypto.SymmetricCryptoAbstraction

Implements Authenticated Encryption with Associated Data (AEAD) abstraction. The associated data is optional, and this version is backwards compatible with the same class without the associated data option.

>>> from hashlib import sha256
>>> import charm.toolbox.symcrypto
>>> key = sha256(b'shameful secret key').digest()
>>> cipher = charm.toolbox.symcrypto.AuthenticatedCryptoAbstraction(key)
>>> ciphertext = cipher.encrypt('My age is 42.')
>>> cipher.decrypt(ciphertext)
b'My age is 42.'
>>> ciphertext2 = cipher.encrypt(b'My age is 42.')
>>> cipher.decrypt(ciphertext2)
b'My age is 42.'
>>> ad = b''
>>> ciphertextAssociatedData = cipher.encrypt('Some network PDU.', associatedData=ad)
>>> cipher.decrypt(ciphertextAssociatedData)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./charm/toolbox/symcrypto.py", line 233, in decrypt
    raise ValueError("Invalid mac. Your data was tampered with or your key is wrong")
ValueError: Invalid mac. Your data was tampered with or your key is wrong
>>> cipher.decrypt(ciphertextAssociatedData, associatedData='wrong data')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./charm/toolbox/symcrypto.py", line 233, in decrypt
    raise ValueError("Invalid mac. Your data was tampered with or your key is wrong")
ValueError: Invalid mac. Your data was tampered with or your key is wrong
>>> cipher.decrypt(ciphertextAssociatedData, associatedData=b'')
b'Some network PDU.'
>>>

decrypt(cipherText, associatedData='')

Decrypts a ciphertext in AEAD mode (Authenticated Encryption with Associated Data) using the superclass symmetric encryption parameters. The MAC is computed with both the ciphertext and associated data (and other cryptosystem parameters), but the associated data is not encrypted, nor available within the ciphertext structure.

ciphertext : str or byte str

The message to be decrypted.

associatedData : str or byte str, optional

Associated data that will be MACed together with the ciphertext and algorithm. This associated text must be in plaintext.

byte str

The decrypted plaintext, if the ciphertext was successfuly authenticated. Raise exception otherwise.

ValueError

If the MAC is invalid.

The IV is included in the computation of the MAC. In fact, all cipher parameters are included: the encryption function returns a JSON object from a dictionary composed of the cipher parameters (e.g., algorithm, mode, IV), and the ciphertext. The MAC function uses the whole JSON object/string to compute the MAC, prepended with the HMAC algorithm + associatedData.

The MAC key is computed as sha2(b’Poor Mans Key Extractor” + key).

encrypt(msg, associatedData='')

Encrypts a message in AEAD mode (Authenticated Encryption with Associated Data) using the superclass symmetric encryption parameters. The MAC is computed with both the ciphertext and associated data (and other cryptosystem parameters), but the associated data is not encrypted, nor saved within the ciphertext structure.

msg : str or byte str

The message to be encrypted.

associatedData : str or byte str, optional

Associated data that will be MACed together with the ciphertext and algorithm; the associated data will not be encrypted.

dict

Dictionary structure containing:

msg: {‘ALG’: symmetric cryptosystem.

‘MODE’: symmetric encryption mode. ‘IV’: the IV for the encryption algorithm. ‘CipherText’: the padded ciphertext (padding according to PKCS 7).

}

“alg”: The HMAC algorithm. “digest”: The MAC computed as MAC = HMAC(key, alg + associatedData + msg)

The IV is included in the computation of the MAC. In fact, all cipher parameters are included: the encryption function returns a JSON object from a dictionary composed of the cipher parameters (e.g., algorithm, mode, IV), and the ciphertext. The MAC function uses the whole JSON object/string to compute the MAC, prepended with the HMAC algorithm + associatedData.

The MAC key is computed as sha2(b’Poor Mans Key Extractor” + key).

class symcrypto.MessageAuthenticator(key, alg='HMAC_SHA2')

Bases: object

Abstraction for constructing and verifying authenticated messages

A large number of the schemes can only encrypt group elements and do not provide an efficient mechanism for encoding byte in those elements. As such we don’t pick a symmetric key and encrypt it asymmetrically. Rather, we hash a random group element to get the symmetric key.

>>> from charm.toolbox.pairinggroup import PairingGroup,GT,extract_key
>>> groupObj = PairingGroup('SS512')
>>> key = groupObj.random(GT)
>>> m = MessageAuthenticator(extract_key(key))
>>> AuthenticatedMessage = m.mac('Hello World')
>>> m.verify(AuthenticatedMessage)
True

mac(msg, associatedData=b'')

Authenticates (MAC) a message. The MAC is computed as: MAC = HMAC(key, algorithm + associatedData + message).

msg : str or byte str

The message serving as input to the HMAC algorithm, in addition to the HMAC algorithm and associated data.

associatedData : str or byte str, optional

Associated data that will be MACed together with the ciphertext and algorithm; the associated data will not be encrypted.

dict

Dictionary composed of the MAC algorithm, the MACed message (or ciphertext), and the digest computed by MACing HMAC_algorithm + associatedData + msg.

verify(msgAndDigest, associatedData=b'')

Verifies whether the MAC digest from input ciphertext and digest matches the computed one over ciphertext and associated data.

msgAndDigest : dict

Dictionary composed of the MAC algorithm, the MACed message (or ciphertext), and the digest computed by MACing HMAC_algorithm + associatedData + msg. It is the format generated by the mac() function within this class.

associatedData : str or byte str, optional

Associated data that will be MACed together with the ciphertext and algorithm; the associated data will not be encrypted.

bool

True if the digests match, False otherwise.

ValueError

If the HMAC algorithm is not supported.

class symcrypto.SymmetricCryptoAbstraction(key, alg=0, mode=2)

Bases: object

Abstraction for symmetric encryption and decryption of data. Ideally provide an INDCCA2 secure symmetric container for arbitrary data. Currently only supports primitives that JSON can encode and decode.

A large number of the schemes can only encrypt group elements and do not provide an efficient mechanism for encoding byte in those elements. As such we don’t pick a symmetric key and encrypt it asymmetrically. Rather, we hash a random group element to get the symmetric key.

>>> from charm.toolbox.pairinggroup import PairingGroup,GT,extract_key
>>> groupObj = PairingGroup('SS512')
>>> a = SymmetricCryptoAbstraction(extract_key(groupObj.random(GT)))
>>> ct = a.encrypt(b"Friendly Fire Isn't")
>>> a.decrypt(ct)
b"Friendly Fire Isn't"

decrypt(cipherText)

encrypt(message)