ADR-010 — Encryption Strategy for Database Fields

ADR

ADR-010

Title

Encryption Strategy for Database Fields

State

Accepted

Author

klenkes74

Decision Body

klenkes74

Valid from

2025-10-12

Expires

./.

1. Context

Sensitive data must be encrypted at rest in the database. The application uses Spring Boot with JPA/Hibernate and PostgreSQL. Two main approaches are available: application-side encryption using JPA AttributeConverter, or database-side encryption using PostgreSQL’s pgcrypto extension with Hibernate’s @ColumnTransformer.

2. Decision Drivers

3. Decision

We choose application-side encryption using JPA AttributeConverter.

This approach encrypts and decrypts field values in the application layer before persisting to or reading from the database. It is database-agnostic, integrates seamlessly with JPA entities, and simplifies migration and backup processes.

4. Consequences

  • Encryption logic is fully controlled in the application code

  • No dependency on database-specific features or extensions

  • Easier to test and maintain encryption routines

  • Database backups remain encrypted

  • Key management must be handled securely in the application

  • Slight performance overhead in the application layer

5. Options

5.1. Option 1: Application-side encryption (JPA AttributeConverter)

Pros:

  • Database-agnostic, works with any JPA-compatible database

  • Encryption logic is testable and maintainable in Java

  • No need for database extensions or custom SQL

  • Easy to migrate and backup encrypted data

Cons:

  • Key management and rotation must be implemented in the application

  • Performance impact on application server

  • All developers must follow encryption conventions

5.2. Option 2: Database-side encryption (pgcrypto + Hibernate @ColumnTransformer)

Pros:

  • Encryption and decryption handled by the database

  • Keys can be managed by the database administrator

  • Transparent for non-JPA clients

Cons:

  • Requires PostgreSQL and pgcrypto extension

  • Hibernate mapping with @ColumnTransformer is more complex

  • Migration to other databases is difficult

  • Backups may contain unencrypted data if not configured properly

6. Further Reading