Users should review the migration guide to determine whether data re-encryption is also required.

Migration

This release introduces AesCbcBytesEncryptor and AesGcmBytesEncryptor as secure replacements for AesBytesEncryptor, which is now deprecated. Encryptors.standard(), Encryptors.stronger(), Encryptors.text(), and Encryptors.delux() are deprecated for the same reason.

Scenarios That Require No DB-Level Migration

If you supplied a SecretKey--either with CipherAlgorithm.CBC and a non-null ivGenerator or with CipherAlgorithm.GCM--the new encryptors produce byte-for-byte equivalent ciphertext.

In those cases, the code can be updated in the following way with no further steps:

Scenarios That Require DB-Level Migration

If you are using the Encryptors API, are using AesBytesEncryptor with a password, or are using CipherAlgorithm.CBC with a null ivGenerator, the old and new encryptors are not compatible for one or more of the following reasons:

1. CBC no longer uses a null IV by default, and
2. The old password-based constructors derive keys using PBKDF2-HMAC-SHA1 with 1,024 iterations, while the new encryptors use PBKDF2-HMAC-SHA256 with 600,000 iterations.

In these cases, ciphertext written by an old encryptor can only be decrypted by an old encryptor instance, so a direct swap is not possible without a migration step.

The replacement APIs in these cases are as follows:

Encryptors.text() and Encryptors.delux() return a TextEncryptor that hex-encodes its output, whereas AesCbcBytesEncryptor/AesGcmBytesEncryptor return a BytesEncryptor operating on raw bytes, so callers that need string-in/string-out semantics are responsible for the encoding step themselves.

Spring Security offers no migration API for encrypted material, but the effort should be quite similar to when your organization rotates the encryption password or secret key as a normal business operation. While you should perform your own analysis to decide how to migrate your data, the following pseudocode illustrates what this could look like:

BytesEncryptor v1 = Encryptors.stronger(oldPassword, salt);
BytesEncryptor v2 = AesGcmBytesEncryptor.withPassword(newPassword, salt);
for (Entity e : entities) {
    byte[] b = e.getEncryptedData();
    e.setEncryptedData(v2.encrypt(v1.decrypt(b)));
    e.save();
}

Note that since this migration upgrades the key derivation algorithm, it is a good opportunity to rotate the password, as this snippet additionally illustrates.