If you've ever had to encrypt a nationalId, a creditCardNumber, or a medicalRecord field in a Spring Boot entity, you already know the drill. You write an AttributeConverter, you wire up a Cipher instance, you generate an IV, you figure out where the key lives, you get the...
If you've ever had to encrypt a nationalId, a creditCardNumber, or a medicalRecord field in a Spring Boot entity, you already know the drill. You write an AttributeConverter, you wire up a Cipher instance, you generate an IV, you figure out where the key lives, you get the GCM tag handling wrong once, you fix it, and three weeks later you finally trust it enough to ship.
We've done this enough times — across healthcare and fintech projects — that we stopped doing it manually. This post walks through the full implementation from scratch, the mistakes that are easy to make along the way, and then shows the one-annotation version we eventually packaged into Nucleus, our open-core Java framework.
Why GCM, and not just AES-CBC
If you search "AES encryption Java" you'll find a lot of CBC-mode examples. Don't use them for new code. CBC gives you confidentiality but no integrity check — an attacker can flip bits in the ciphertext and you won't know it happened until something downstream breaks in a weird way, or worse, doesn't break at all.
GCM (Galois/Counter Mode) gives you both confidentiality and authentication in one pass. It produces an authentication tag alongside the ciphertext, and decryption fails loudly if either the ciphertext or the tag has been tampered with. It's also the mode behind TLS 1.3, which is a reasonable signal that it's held up to scrutiny. The relevant specification is NIST SP 800-38D.
Building it by hand
Here's a minimal, correct implementation. This is the version you'd write before you have a framework to lean on.
public class AesGcmEncryptor {
private static final String ALGORITHM = "AES/GCM/NoPadding";
private static final int GCM_TAG_LENGTH_BITS = 128;
private static final int GCM_IV_LENGTH_BYTES = 12;
private final SecretKey key;
public AesGcmEncryptor(SecretKey key) {
this.key = key;
}
public String encrypt(String plaintext) {
try {
byte[] iv = new byte[GCM_IV_LENGTH_BYTES];
SecureRandom.getInstanceStrong().nextBytes(iv);
Cipher cipher = Cipher.getInstance(ALGORITHM);
GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv);
cipher.init(Cipher.ENCRYPT_MODE, key, spec);
byte[] ciphertext = cipher.doFinal(plaintext.getBytes(StandardCharsets.UTF_8));
// Prepend the IV so it travels with the ciphertext
ByteBuffer buffer = ByteBuffer.allocate(iv.length + ciphertext.length);
buffer.put(iv).put(ciphertext);
return Base64.getEncoder().encodeToString(buffer.array());
} catch (GeneralSecurityException e) {
throw new EncryptionException("Failed to encrypt field", e);
}
}
public String decrypt(String encoded) {
try {
byte[] decoded = Base64.getDecoder().decode(encoded);
ByteBuffer buffer = ByteBuffer.wrap(decoded);
byte[] iv = new byte[GCM_IV_LENGTH_BYTES];
buffer.get(iv);
byte[] ciphertext = new byte[buffer.remaining()];
buffer.get(ciphertext);
Cipher cipher = Cipher.getInstance(ALGORITHM);
GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH_BITS, iv);
cipher.init(Cipher.DECRYPT_MODE, key, spec);
byte[] plaintext = cipher.doFinal(ciphertext);
return new String(plaintext, StandardCharsets.UTF_8);
} catch (GeneralSecurityException e) {
throw new EncryptionException("Failed to decrypt field — data may be tampered or corrupted", e);
}
}
}
A few details that matter and are easy to skip past:
- The IV must be random and unique per encryption call, but it doesn't need to be secret. Prepending it to the ciphertext (as above) is the standard approach — you need it to decrypt, and it carries no information about the key.
- 12 bytes (96 bits) is the recommended IV length for GCM. Using a different length is technically possible but changes the internal computation in ways that reduce the security margin. Don't deviate without a specific reason.
-
Never reuse an IV with the same key. This is the one mistake that actually breaks GCM's security guarantees — IV reuse can leak the authentication key. If you're generating IVs randomly with
SecureRandomper call, this is a non-issue at realistic volumes. -
SecureRandom.getInstanceStrong(), notnew Random(). This trips people up constantly.Randomis not cryptographically secure and predictable IVs undermine the whole scheme.
Wiring it into JPA
The encryptor above is useless until it's actually applied to entity fields. The idiomatic way is a JPA AttributeConverter:
@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {
private final AesGcmEncryptor encryptor;
public EncryptedStringConverter(AesGcmEncryptor encryptor) {
this.encryptor = encryptor;
}
@Override
public String convertToDatabaseColumn(String attribute) {
return attribute == null ? null : encryptor.encrypt(attribute);
}
@Override
public String convertToEntityAttribute(String dbData) {
return dbData == null ? null : encryptor.decrypt(dbData);
}
}
Then on your entity:
@Entity
public class Patient {
@Id
private UUID id;
@Convert(converter = EncryptedStringConverter.class)
private String nationalId;
@Convert(converter = EncryptedStringConverter.class)
private String diagnosis;
// standard fields, no encryption needed
private String firstName;
}
This works. It's also the point where most teams stop, because it's "good enough" — and it is, functionally. But there are a few gaps that tend to surface a few months later:
-
Key management is now manually wired through a constructor, which usually means it ends up in
application.ymlor, worse, hardcoded for "just this once" during a demo. -
There's no audit trail. If a regulator or auditor asks "who decrypted this patient's data and when," a plain
AttributeConvertergives you nothing. -
Querying encrypted fields breaks.
WHERE nationalId = ?no longer works because the database only sees ciphertext. Every team rediscovers this independently, usually in a sprint planning meeting that goes long. - You're now repeating this converter wiring on every sensitive field, in every entity, in every project.
None of these are hard problems individually. But solving all four, correctly, every time, across every project, is exactly the kind of thing that's worth doing once and reusing.
The one-annotation version
This is what we ended up building into Nucleus's encryption module:
@Entity
public class Patient extends BaseEntity {
@SensitiveData
private String nationalId;
@SensitiveData
private String diagnosis;
private String firstName;
}
@SensitiveData triggers AES-256-GCM encryption at the field level automatically — same algorithm, same IV handling, same NIST SP 800-38D-aligned implementation described above, but the boilerplate is gone. A few things it handles that the hand-rolled version above doesn't:
- Key management is pulled from a configured key provider rather than threaded through constructors. Key rotation is supported without a data migration.
-
Deterministic lookup hashes are generated alongside the encrypted value for fields you need to query on, so
WHERE nationalId = ?-style lookups keep working without decrypting the whole table. - It plugs into the GDPR module, so encrypted fields are automatically eligible for the consent and retention policies tracked there — encryption and compliance aren't two separate systems you have to keep in sync.
The annotation isn't doing anything magical — it's the same AttributeConverter pattern under the hood, generated and wired automatically based on what we kept rebuilding by hand across projects.
When you don't need any of this
If you're encrypting one or two fields in a side project, the hand-rolled AesGcmEncryptor above is genuinely fine — there's no need to pull in a framework for that. Where this starts to matter is when you have GDPR or HIPAA obligations across a real schema, multiple entities with sensitive fields, and an actual audit requirement. That's the point where doing it five times by hand starts costing more than the framework would.
If you want to see the full module — including the key rotation flow and the GDPR integration — it's part of the open-core release:
- Docs: clinvio.hu/nucleus/docs
- Source: open-core on GitHub (link in the repo)
Happy to go deeper on the key rotation mechanics or the deterministic-hash lookup approach in the comments if anyone's curious — those are the two parts that generate the most questions when we walk through this internally.
