Cryptographic Key Management

@Service
public class EnvelopeEncryptionService {
 
    private final KmsClient kms;
    private final String masterKeyId;
 
    public EncryptedRecord encrypt(byte[] plaintext, String context) {
        // KMS generates a data key and returns it twice: plaintext to use now,
        // and encrypted under the master key to store. The master key stays
        // inside KMS throughout.
        var dataKey = kms.generateDataKey(b -> b
                .keyId(masterKeyId)
                .keySpec(DataKeySpec.AES_256)
                // Encryption context is bound into the operation and must match
                // on decrypt — it prevents a data key being used out of context.
                .encryptionContext(Map.of("purpose", context)));
 
        byte[] plaintextKey = dataKey.plaintext().asByteArray();
        try {
            byte[] ciphertext = aesGcm(plaintextKey, plaintext);
            return new EncryptedRecord(ciphertext,
                    dataKey.ciphertextBlob().asByteArray(), context);
        } finally {
            // Wipe the plaintext key from memory the instant it is done with.
            Arrays.fill(plaintextKey, (byte) 0);
        }
    }
 
    public byte[] decrypt(EncryptedRecord record) {
        var decrypted = kms.decrypt(b -> b
                .ciphertextBlob(SdkBytes.fromByteArray(record.encryptedDataKey()))
                .encryptionContext(Map.of("purpose", record.context())));
 
        byte[] plaintextKey = decrypted.plaintext().asByteArray();
        try {
            return aesGcmDecrypt(plaintextKey, record.ciphertext());
        } finally {
            Arrays.fill(plaintextKey, (byte) 0);
        }
    }
}

@Scheduled(cron = "0 0 3 1 * *")   // monthly
public void rotateMasterKey() {
    // KMS rotates the master key material. Existing data keys were encrypted
    // under the old version; KMS can still decrypt them because it retains
    // old versions. New data keys use the new version automatically.
    kms.enableKeyRotation(b -> b.keyId(masterKeyId));
    // No data is re-encrypted. Only the master key version advances.
}

// Re-encrypt data keys under a new master version WITHOUT touching the data.
public void rewrapDataKeys(List<EncryptedRecord> records) {
    records.forEach(record -> {
        var rewrapped = kms.reEncrypt(b -> b
                .ciphertextBlob(SdkBytes.fromByteArray(record.encryptedDataKey()))
                .sourceKeyId(oldMasterKeyId)
                .destinationKeyId(newMasterKeyId));
        record.updateEncryptedDataKey(rewrapped.ciphertextBlob().asByteArray());
    });
}

// Java accesses an HSM through the PKCS#11 standard interface via a provider.
Provider hsmProvider = Security.getProvider("SunPKCS11").configure("/etc/hsm/pkcs11.cfg");
Security.addProvider(hsmProvider);
 
KeyStore keyStore = KeyStore.getInstance("PKCS11", hsmProvider);
keyStore.load(null, hsmPin.toCharArray());
// The private key handle references a key that never leaves the device.
PrivateKey signingKey = (PrivateKey) keyStore.getKey("signing-key", null);