B BIOCKKSEncrypted face verification
API documentation
Checking API
Google Cloud VM · HTTPS · encrypted storage

Test the complete biometric pipeline.

Enroll one reference face, verify a new selfie, and see exactly where encryption happens. The interface uses the same production API endpoints as an external client.

Start testing Understand the encryption
Quick start
  1. 1Paste your API keyThe production key is required for every request.
  2. 2Create a boxUpload one clear reference image containing one face.
  3. 3VerifyUse the returned box ID with a fresh selfie.
What happens to every image

One consistent pipeline

Images are decoded first. CKKS is applied only after AdaFace produces numbers.

01ValidateJPEG/PNG · max 10 MB
→
02Detect & alignExactly one face
→
03AdaFace512-number embedding
→
04NormalizeL2 unit vector
→
05CKKSEncrypt or compare
Interactive API tester

Run a verification

First paste the production API key. It stays in this browser tab and is sent only in the X-API-Key header.

⌁API keyRequired before any biometric request
No key entered
Step 1 · Enrollment

Create user box

Upload the trusted reference image used for future comparisons.

POST /v1/boxes
KUser RSA keypairThe browser creates it automatically. Only the public key is sent.
Generating
View or regenerate RSA keys

Generating a 3072-bit RSA-OAEP keypair…

Saved: encrypted image, wrapped AES key, encrypted embedding and encrypted metadata.
Storage and encryption

What is saved, and where?

There is no database in this version. Everything is stored as files on the dedicated Google Cloud persistent disk mounted at /data.

Google Cloud persistent disk

Filesystem storage, not a database

/data/boxes/box_…/image.encRaw reference image · AES-256-GCM
/data/boxes/box_…/image_key.wrappedImage AES key · RSA-OAEP wrapped
/data/boxes/box_…/embedding.ckks512-D face embedding · CKKS ciphertext
/data/boxes/box_…/metadata.encUser reference and public key · AES-GCM
/data/boxes/box_…/index.jsonMinimal box ownership locator
/data/audit/security.jsonlRequest audit events · no images or API keys

The 50 GB disk is snapshotted daily in me-west1 with 14-day retention.

Data lifecycle

Saved versus request-only

Saved encryptedReference imageReference embeddingPrivate metadata
Never persistedVerification selfiesPose imagesPlain embeddingsUser private RSA key
CKKS in plain language

Math on encrypted numbers

  1. 1AdaFace changes the aligned face into 512 numeric values.
  2. 2The vector is L2-normalized, so its dot product is cosine similarity.
  3. 3CKKS encrypts those numbers. It never encrypts the JPEG or PNG.
  4. 4TenSEAL computes an encrypted dot product between two ciphertext vectors.
  5. 5Only the one-number encrypted score is decrypted and compared with 0.60.
Request route

Where computation happens

Your browserHTTPSCaddyprivate Docker networkFastAPI + AdaFace + CKKSencrypted files/data disk
Current CKKS limitation

The CKKS secret key used to decrypt final scores is still available inside this VM. Move it to an isolated key service for a stronger production separation.