cyphera-hibernate

Transparent field-level format-preserving encryption for Hibernate. Annotate a field, data is protected on write and accessed on read. Zero boilerplate.

Built on io.cyphera:cyphera from Maven Central.

Quick Start

Add the dependency:

<dependency>
    <groupId>io.cyphera</groupId>
    <artifactId>cyphera-hibernate</artifactId>
    <version>VERSION</version>
</dependency>

Add cyphera.json to your classpath or /etc/cyphera/cyphera.json. Annotate your fields:

@Entity
public class Customer {

    @Id
    private Long id;

    private String name;

    @CypheraProtect("ssn")
    private String ssn;

    @CypheraProtect("credit_card")
    private String creditCard;
}

That's it. The Hibernate Integrator auto-discovers @CypheraProtect fields at boot. No converter classes, no config classes, no wiring.

• INSERT/UPDATE: ssn → T01i6J-xF-07pX in the database
• SELECT: T01i6J-xF-07pX → 123-45-6789 back to the entity
• Your code only sees plaintext. The database only sees ciphertext.

Build

mvn package -DskipTests

Install / Deploy

1. Add the Maven dependency
2. Place cyphera.json on classpath or at /etc/cyphera/cyphera.json (or set CYPHERA_CONFIGURATION_FILE env var)
3. Annotate fields with @CypheraProtect("configuration_name")
4. Done — the Integrator handles the rest via META-INF/services auto-discovery

Column Sizing

Headers add 3 characters. Ensure your columns have room: existing width + 3. Or set header_enabled: false in the configuration for same-length output.

How It Works

1. Boot: CypheraIntegrator auto-discovered via META-INF/services. Registers event listeners.
2. Scan: On first access, scans entity fields for @CypheraProtect and caches field→configuration mapping.
3. Write: PreInsert/PreUpdate modify the Hibernate state array — database gets ciphertext, entity keeps plaintext.
4. Read: PostLoad decrypts fields on the entity after loading.
5. SDK: CypheraHolder auto-discovers cyphera.json if not explicitly configured.

Alternative Modes

Explicit @Type (full Hibernate control)

@Type(value = CypheraType.class, parameters = @Parameter(name = "configuration", value = "ssn"))
private String ssn;

JPA Compatibility (non-Hibernate providers)

@Converter
public class SsnConverter extends io.cyphera.hibernate.compat.CypheraConverter {
    public SsnConverter() { super("ssn"); }
}

Operations

Configuration

• Auto-discover: CYPHERA_CONFIGURATION_FILE env → ./cyphera.json → /etc/cyphera/cyphera.json
• Explicit: CypheraHolder.set(Cyphera.fromFile("path")) at bootstrap
• Spring Boot: auto-config handles it (if cyphera-spring is also on classpath)

Troubleshooting

• "Unknown configuration" — @CypheraProtect("...") doesn't match cyphera.json
• Integrator not loading — check META-INF/services is in the JAR
• No configuration file — ensure cyphera.json exists at one of the auto-discover locations

Configuration File

{
  "configurations": {
    "ssn": { "engine": "ff1", "key_ref": "my-key", "header": "T01" },
    "credit_card": { "engine": "ff1", "key_ref": "my-key", "header": "T02" }
  },
  "keys": {
    "my-key": { "material": "2B7E151628AED2A6ABF7158809CF4F3C" }
  }
}

Future

• SPI extension points: custom ConfigurationResolver, FieldProcessor, MetadataResolver
• Spring Boot auto-configuration for CypheraHolder
• Hibernate 5 @TypeDef compatibility
• Audit logging integration

License

Apache 2.0 — Copyright 2026 Horizon Digital Engineering LLC