Symmetric Encryption¶
Scapi implements three main categories of symmetric encryption:
- An encryption based on modes of operation using a pseudo-random permutation and a randomized IV. The randomized IV is crucial for security. CBCEnc and CTREnc belong to this category.
- An authenticated encryption where the message gets first encrypted and then mac-ed. EncryptThenMac belongs to this category.
- Homomorphic encryption. Even though we do not currently implement any concrete homomorphic encryption, we provide the interfaces for future possible implementations.
The symmetric encryption family of classes implements three main functionalities that correspond to the cryptographer’s language in which an encryption scheme is composed of three algorithms:
- Generation of the key.
- Encryption of the plaintext.
- Decryption of the ciphertext.
Note
We note that for authenticated encryption, two secret keys will be used, one for the encryption and one for the authentication.
Contents
The SymmetricEnc Interface¶
- public interface SymmetricEnc extends Eav, Indistinguishable¶
This is the main interface for the Symmetric Encryption family. Any symmetric encryption scheme belongs by default at least to the Eavsdropper Security Level and to the Indistinguishable Security Level.
Encryption and Decryption¶
- public SymmetricCiphertext encrypt(Plaintext plaintext)¶
Encrypts a plaintext. It lets the system choose the random IV.
Parameters: - plaintext –
Throws: - IllegalArgumentException – if the given plaintext does not match this encryption scheme.
- IllegalStateException – if no secret key was set.
Returns: an IVCiphertext, which contains the IV used and the encrypted data.
- public SymmetricCiphertext encrypt(Plaintext plaintext, byte[] iv)¶
This function encrypts a plaintext. It lets the user choose the random IV.
Parameters: - plaintext –
- iv – random bytes to use in the encryption pf the message.
Throws: - IllegalArgumentException – if the given plaintext does not match this encryption scheme.
- IllegalBlockSizeException – if the given IV length is not as the block size.
- IllegalStateException – if no secret key was set.
Returns: an IVCiphertext, which contains the IV used and the encrypted data.
- public Plaintext decrypt(SymmetricCiphertext ciphertext)¶
This function performs the decryption of a ciphertext returning the corresponding decrypted plaintext.
Parameters: - ciphertext – The Ciphertext to decrypt.
Throws: - IllegalArgumentException – if the given ciphertext does not match this encryption scheme.
- IllegalStateException – if no secret key was set.
Returns: the decrypted plaintext.
Key Generation¶
- public SecretKey generateKey(AlgorithmParameterSpec keyParams)¶
Generates a secret key to initialize this symmetric encryption.
Parameters: - keyParams – algorithmParameterSpec contains parameters for the key generation of this symmetric encryption.
Throws: - InvalidParameterSpecException – if the given keyParams does not match this symmetric encryption.
Returns: the generated secret key.
- public SecretKey generateKey(int keySize)¶
Generates a secret key to initialize this symmetric encryption.
Parameters: - keySize – is the required secret key size in bits.
Returns: the generated secret key.
Key Handling¶
- public boolean isKeySet()¶
An object trying to use an instance of symmetric encryption needs to check if it has already been initialized.
Returns: true if the object was initialized by calling the function setKey.
- public void setKey(SecretKey secretKey)¶
Sets the secret key for this symmetric encryption. The key can be changed at any time.
Parameters: - secretKey – secret key.
Throws: - InvalidKeyException – if the given key does not match this encryption scheme.
The CBCEnc Interface¶
These is a marker interface, for the CBC method:
- public interface CBCEnc extends SymmetricEnc, Cpa¶
The CTREnc Interface¶
These is a marker interface, for the CTR method:
- public interface CTREnc extends SymmetricEnc, Cpa¶
Basic Usage¶
Sender usage:
//Create an encryption object. The created object is a CTR-AES encryption scheme object.
SymmetricEnc encryptor = new ScCTREncRandomIV("AES");
//Generate a SecretKey using the created object and set it.
SecretKey key = encryptor.generateKey(128);
encryptor.setKey(key);
//Get a plaintext to encrypt, and encrypt the plaintext.
...
SymmetricCiphertext cipher = Encryptor.encrypt(plaintext);
//Send the cipher to the decryptor.
...
Receiver usage:
//Create the same SymmetricEnc object as the sender’s encryption object, and set the key.
//Get the ciphertext and decrypt it to get the plaintext.
Plaintext plaintext = decryptor.decrypt(cipher);
The AuthenticatedEnc Interface¶
- public interface AuthenticatedEnc extends SymmetricEnc, Cca2¶
- public class ScEncryptThenMac implements AuthenticatedEnc¶
This class implements a type of authenticated encryption: encrypt then mac.
The encryption algorithm first encrypts the message and then calculates a mac on the encrypted message.
The decrypt algorithm receives an encrypted message and a tag. It first verifies the encrypted message with the tag. If verifies, then it proceeds to decrypt using the underlying decrypt algorithm, if not returns a null response.
This encryption scheme achieves Cca2 and NonMalleable security level.
Basic Usage¶
//Create the PRP that is used by the encryption object.
AES aes = new BcAES();
//Create encryption object.
SymmetricEnc enc = new ScCTREncRandomIV(aes);
//Create the PRP that is used by the Mac object.
TripleDES tripleDes = new BcTripleDES();
//Create Mac object.
Mac cbcMac = new ScCbcMacPrepending(tripleDes);
//Create the encrypt-then-mac object using encryption and authentication objects.
ScEncryptThenMac encThenMac = new ScEncryptThenMac(enc, cbcMac);
// prepare the plaintext
Plaintext plaintext;
...
// encrypt
SymmetricCiphertext cipher = encThenMac.encrypt(plaintext);
// decrypt
Plaintext decrypted = encThenMac.decrypt(cypher);