cyphera-spring

Format-preserving encryption for Spring Boot — auto-configured starter powered by Cyphera.

Built on io.cyphera:cyphera from Maven Central.

Quick Start

Add the dependency:

<dependency>
    <groupId>io.cyphera</groupId>
    <artifactId>cyphera-spring-boot-starter</artifactId>
    <version>VERSION</version>
</dependency>

Add cyphera.json to your classpath, inject CypheraClient, and protect data:

@Autowired
private CypheraClient cyphera;

String protectedSsn = cyphera.protect("123-45-6789", "ssn");
// → "T01i6J-xF-07pX" (header-prefixed, dashes preserved)

String accessed = cyphera.access(protectedSsn);
// → "123-45-6789"

Build

From source

mvn package -DskipTests

Via Docker

docker build -t cyphera-spring .

Install / Deploy

1. Add the Maven dependency to your Spring Boot project
2. Place cyphera.json on the classpath (e.g. src/main/resources/cyphera.json)
3. Spring auto-configures CypheraClient — inject it anywhere

Configuration

# application.yml
cyphera:
  configuration-file: classpath:cyphera.json
  # configuration-file: file:/etc/cyphera/cyphera.json  # external file

Usage

@Autowired
private CypheraClient cyphera;

// Protect — the named configuration determines engine, alphabet, key
String protectedValue = cyphera.protect("123-45-6789", "ssn");
// → "T01i6J-xF-07pX"

// Access — header-driven, no configuration name needed
String original = cyphera.access(protectedValue);
// → "123-45-6789"

// Access with explicit configuration (escape hatch for headerless configurations)
String original = cyphera.access(protectedValue, "ssn");

// Direct SDK access for advanced use
Cyphera sdk = cyphera.sdk();

API

Method	Description
protect(value, configuration)	Protect using a named configuration
access(protectedValue)	Access using the embedded header (primary)
access(protectedValue, configuration)	Access with explicit configuration name (escape hatch)
sdk()	Access the underlying Cyphera SDK instance

Operations

Configuration

• Default location: classpath:cyphera.json
• Override with cyphera.configuration-file in application.yml
• Supports classpath:, file:, and absolute paths
• Configuration changes require application restart

Monitoring

• Bean creation logged at startup — check for CypheraAutoConfiguration in logs
• Errors throw RuntimeException — handle in your application error handling

Upgrading

1. Bump the cyphera-spring-boot-starter version in pom.xml
2. Rebuild and redeploy your application

Troubleshooting

• Bean not created — check that cyphera.json exists on the classpath
• "Unknown configuration" — configuration name doesn't match cyphera.json
• "No matching header" — the protected value doesn't start with a known header

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

• JPA AttributeConverter for transparent field-level encryption on entities
• Dynamic configuration reload without restart
• Actuator health indicator for Cyphera status
• Spring Security integration for role-based access policies

License

Apache 2.0 — Copyright 2026 Horizon Digital Engineering LLC