Skip to content

Cryptographic Integrity

Xybern Redact provides three layers of cryptographic protection for your audit vault:

  1. HMAC-SHA256 record signing, each vault record is individually signed
  2. Merkle tree batch sealing, sealed batches prove record inclusion without revealing content
  3. Customer-managed key encryption, your upstream API key is encrypted at rest with your own key

HMAC Record Signing

Generating a Key

Go to Settings → Integrity & Encryption and click Generate HMAC Key. A cryptographically random 32-byte key is generated server-side and stored in your workspace settings (encrypted if you have a customer key configured).

The dashboard shows only the key's fingerprint (first 12 hex chars of SHA-256 of the key), the key itself is never returned after generation.

What Gets Signed

Every vault record written after key generation is signed over these fields:

id, workspace_id, doc_hash_original, doc_hash_anonymized,
response_hash, entities_stripped_count, chain_hash, created_at

The record_hmac field in the vault record holds the HMAC-SHA256 hex digest.

Rotating the Key

Click Rotate HMAC Key to generate a new key. Important: records signed with the old key cannot be verified with the new key. Export a PDF audit report and seal a Merkle batch before rotating if you need a complete verifiable archive.

Customer-Managed Encryption

By default, the upstream LLM API key is stored in your workspace settings (database-level encryption). For stricter requirements, you can encrypt it with a key you control so Xybern never holds the plaintext.

AES-256-GCM (Customer Key)

  1. Generate a 32-byte random key and hex-encode it (64 hex characters)
  2. In Settings → Integrity & Encryption, paste the key in Customer AES-256 Key
  3. Click Save Encryption Settings

From that point, the upstream API key is encrypted with AES-256-GCM (random 12-byte nonce per encryption, authentication tag verified on decryption) before storage. Xybern decrypts it only at request time, in memory, to forward to the upstream provider.

To generate a suitable key:

import secrets
print(secrets.token_hex(32))   # 64-char hex string

openssl rand -hex 32

Keep this key safe. If it is lost, the upstream API key cannot be decrypted and must be re-entered.

AWS KMS

If you use AWS KMS:

  1. Create a symmetric KMS key in your AWS account
  2. Grant the Xybern service IAM role kms:Encrypt and kms:Decrypt on that key
  3. Paste the key ARN in Settings → Integrity & Encryption → AWS KMS Key ARN

Format: arn:aws:kms:us-east-1:123456789012:key/mrk-...

When KMS is configured, Redact calls kms:Encrypt to store the upstream API key and kms:Decrypt to retrieve it at request time. The plaintext never touches Xybern's storage layer.

KMS vs AES-256

KMS provides hardware-backed key management, audit logs via CloudTrail, and key rotation managed by AWS. AES-256-GCM is simpler but requires you to manage and protect the key yourself. For regulated industries, KMS is preferred.

Independent Verification

The cryptographic design is fully open: given the HMAC key and a vault record, any party can verify its authenticity. Given a Merkle root and an inclusion proof, any party can verify record membership without access to other records in the batch.

Neither verification operation requires network access to Xybern's infrastructure. An auditor with: - The vault export (PDF or raw record data) - The workspace HMAC key - The Merkle root values

…can independently verify the complete audit trail offline.

Summary Table

Feature Algorithm Where Stored
Record signing HMAC-SHA256 record_hmac on each vault record
Batch integrity SHA-256 Merkle tree root_hash in redact_merkle_roots
Chain linkage SHA-256 chain hash chain_hash on each vault record
Upstream key (AES) AES-256-GCM Workspace settings (encrypted blob)
Upstream key (KMS) AWS KMS symmetric Workspace settings (KMS ciphertext blob)
HMAC key Stored encrypted or plaintext Workspace settings