Package com.babelqueue.gdpr

Interface Cipher

All Known Implementing Classes:

AesGcmCipher

public interface Cipher

The field-level protection primitive that the caller provides — a seam onto a KMS, a Vault transit engine, an HSM, a tokenisation service, or the reference AesGcmCipher below. protect runs encrypt(byte[]) over every x-gdpr-sensitive leaf's value (after it is canonically JSON-encoded); unprotect runs decrypt(java.lang.String) to restore it. Keeping this an interface is what holds GR-7: the core never pulls a crypto/KMS dependency — only a caller who binds a concrete backend does.

Contract for an implementation:

• encrypt(byte[]) takes the canonical JSON bytes of one field value (see Gdpr.protect(java.util.Map<java.lang.String, java.lang.Object>, java.util.Map<java.lang.String, java.lang.Object>, com.babelqueue.gdpr.Cipher)) and returns the ciphertext as a String that is valid for placement inside a JSON document (the AesGcmCipher reference returns Base64, which is). The same plaintext MAY encrypt to a different string each call — a random nonce/IV is expected and good.
• decrypt(java.lang.String) is the exact inverse: given a string encrypt produced, it returns the original JSON bytes byte-for-byte. A string it did not produce, or one produced under a different key, MUST throw rather than return silent garbage, so a wrong-key consume fails loudly (the message then takes retry / dead-letter).
• Both MUST be safe for concurrent use; a producer/consumer fans the same Cipher across threads.

Method Summary

Modifier and Type	Method	Description
byte[]	decrypt(String ciphertext)	Reverses encrypt(byte[]), returning the original field-value JSON bytes.
String	encrypt(byte[] plaintext)	Protects one field value (its canonical JSON bytes) and returns a JSON-safe ciphertext string.

Method Details

encrypt

String encrypt(byte[] plaintext)
        throws Exception

Protects one field value (its canonical JSON bytes) and returns a JSON-safe ciphertext string.

Parameters:

plaintext - the canonical JSON bytes of one field value

Returns:

the ciphertext, encoded so it is safe to place inside a JSON string

Throws:

Exception - if encryption fails (surfaced wrapped by Gdpr.protect(java.util.Map<java.lang.String, java.lang.Object>, java.util.Map<java.lang.String, java.lang.Object>, com.babelqueue.gdpr.Cipher))

decrypt

byte[] decrypt(String ciphertext)
        throws Exception

Reverses encrypt(byte[]), returning the original field-value JSON bytes.

Parameters:

ciphertext - a string produced by encrypt(byte[])

Returns:

the original field-value JSON bytes

Throws:

Exception - if the input is not a valid ciphertext, is tampered, or was produced under a different key (surfaced as DecryptException by Gdpr.unprotect(java.util.Map<java.lang.String, java.lang.Object>, java.util.Map<java.lang.String, java.lang.Object>, com.babelqueue.gdpr.Cipher))