Guide to the Cipher Class

1. Overview

Simply put, encryption is the process of encoding a message such that only authorized users can understand or access it.

The message, referred to as plaintext, is encrypted using an encryption algorithm – a cipher – generating ciphertext that can only be read by authorized users via decryption.

In this article, we describe in detail the core Cipher class, which provides cryptographic encryption and decryption functionality in Java.

2. Cipher Class

Java Cryptography Extension (JCE) is the part of the Java Cryptography Architecture (JCA) that provides an application with cryptographic ciphers for data encryption and decryption as well as hashing of private data.

The Cipher class — located in the javax.crypto package — forms the core of the JCE framework, providing the functionality for encryption and decryption.

2.1. Cipher Instantiation

To instantiate a Cipher object, we call the static getInstance method, passing the name of the requested transformation. Optionally, the name of a provider may be specified.

Let’s write an example class illustrating the instantiation of a Cipher:

public class Encryptor {

    public byte[] encryptMessage(byte[] message, byte[] keyBytes) 
      throws InvalidKeyException, NoSuchPaddingException, NoSuchAlgorithmException {
        Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
        //...
    }
}

The transformation AES/ECB/PKCS5Padding tells the getInstance method to instantiate the Cipher object as an AES cipher with ECB mode of operation and PKCS5 padding scheme.

We can also instantiate the Cipher object by specifying only the algorithm in the transformation:

Cipher cipher = Cipher.getInstance("AES");

In this case, Java will use provider-specific default values for the mode and padding scheme.

Note that getInstance will throw a NoSuchAlgorithmException if the transformation is null, empty, or in an invalid format, or if the provider doesn’t support it.

It will throw a NoSuchPaddingException if the transformation contains an unsupported padding scheme.

2.2. Thread-Safety

The Cipher class is a stateful one without any form of internal synchronization. As a matter of fact, methods like init() or update() will change the internal state of a particular Cipher instance.

Therefore, the Cipher class is not thread-safe. So we should create one Cipher instance per encryption/decryption need.

2.3. Keys

The Key interface represents keys for cryptographic operations. Keys are opaque containers that hold an encoded key, the key’s encoding format, and its cryptographic algorithm.

Keys are generally obtained through key generators, certificates, or key specifications using a key factory.

Let’s create a symmetric Key from the supplied key bytes:

SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");

2.4. Cipher Initialization

We call the init() method to initialize the Cipher object with a Key or Certificate and an opmode indicating the operation mode of the cipher.

Optionally, we can pass in a source of randomness. By default, a SecureRandom implementation of the highest-priority installed provider is used. Otherwise, it’ll use a system-provided source.

We can specify a set of algorithm-specific parameters optionally. For example, we can pass an IvParameterSpec to specify an initialization vector.

Here are the available cipher operation modes:

• ENCRYPT_MODE: initialize cipher object to encryption mode
• DECRYPT_MODE: initialize cipher object to decryption mode
• WRAP_MODE: initialize cipher object to key-wrapping mode
• UNWRAP_MODE: initialize cipher object to key-unwrapping mode

Let’s initialize the Cipher object:

Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
cipher.init(Cipher.ENCRYPT_MODE, secretKey);
// ...

Now, the init method throws an InvalidKeyException if the supplied key is inappropriate for initializing the cipher, like when a key length/encoding is invalid.

It’s also thrown when the cipher requires certain algorithm parameters that cannot be determined from the key, or if the key has a key size that exceeds the maximum allowable key size (determined from the configured JCE jurisdiction policy files).

Let’s look at an example using a Certificate:

public byte[] encryptMessage(byte[] message, Certificate certificate) 
  throws InvalidKeyException, NoSuchPaddingException, NoSuchAlgorithmException {
 
    Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
    cipher.init(Cipher.ENCRYPT_MODE, certificate);
    // ...
}

The Cipher object gets the public key for data encryption from the certificate by calling the getPublicKey method.

2.5. Encryption and Decryption

After initializing the Cipher object, we call the doFinal() method to perform the encryption or decryption operation. This method returns a byte array containing the encrypted or decrypted message.

The doFinal() method also resets the Cipher object to the state it was in when previously initialized via a call to init() method, making the Cipher object available to encrypt or decrypt additional messages.

Let’s call doFinal in our encryptMessage method:

public byte[] encryptMessage(byte[] message, byte[] keyBytes)
  throws InvalidKeyException, NoSuchPaddingException, NoSuchAlgorithmException, 
    BadPaddingException, IllegalBlockSizeException {
 
    Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
    SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
    cipher.init(Cipher.ENCRYPT_MODE, secretKey);
    return cipher.doFinal(message);
}

To perform a decrypt operation, we change the opmode to DECRYPT_MODE:

public byte[] decryptMessage(byte[] encryptedMessage, byte[] keyBytes) 
  throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidKeyException, 
    BadPaddingException, IllegalBlockSizeException {
 
    Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
    SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
    cipher.init(Cipher.DECRYPT_MODE, secretKey);
    return cipher.doFinal(encryptedMessage);
}

2.6. Providers

Designed to use a provider-based architecture, the JCE allows for qualified cryptography libraries such as BouncyCastle to be plugged in as security providers and new algorithms to be added seamlessly.

Now let’s add BouncyCastle as a security provider. We can add a security provider either statically or dynamically.

To add BouncyCastle statically, we modify the java.security file located in <JAVA_HOME>/jre/lib/security folder.

We add the line at the end of the list:

...
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=org.bouncycastle.jce.provider.BouncyCastleProvider

When adding the provider property, the property key is in the format security.provider.N where the number N is one more than the last one on the list.

We can also add the BouncyCastle security provider dynamically without having to modify the security file:

Security.addProvider(new BouncyCastleProvider());

We can now specify the provider during cipher initialization:

Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding", "BC");

BC specifies BouncyCastle as the provider. We can get the list of registered providers via the Security.getProviders() method.

3. Testing Encryption and Decryption

Let’s write an example test to illustrate message encryption and decryption.

In this test, we use AES encryption algorithm with a 128-bit key and assert that the decrypted result is equal to the original message text:

@Test
public void whenIsEncryptedAndDecrypted_thenDecryptedEqualsOriginal() 
  throws Exception {
 
    String encryptionKeyString =  "thisisa128bitkey";
    String originalMessage = "This is a secret message";
    byte[] encryptionKeyBytes = encryptionKeyString.getBytes();

    Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
    SecretKey secretKey = new SecretKeySpec(encryptionKeyBytes, "AES");
    cipher.init(Cipher.ENCRYPT_MODE, secretKey);

    byte[] encryptedMessageBytes = cipher.doFinal(message.getBytes());

    cipher.init(Cipher.DECRYPT_MODE, secretKey);

    byte[] decryptedMessageBytes = cipher.doFinal(encryptedMessageBytes);
    assertThat(originalMessage).isEqualTo(new String(decryptedMessageBytes));
}

4. Conclusion

In this article, we discussed the Cipher class and presented usage examples. More details on the Cipher class and the JCE Framework can be found in the class documentation and the Java Cryptography Architecture (JCA) Reference Guide.