Skip to main content

Querying the Secure Field

Some fields are sensitive in a way that demands more than the platform's encryption-at-rest baseline — credit cards, social security numbers, health data, anything where exposure has regulatory or contractual weight. For these, the right pattern is field-level encryption: each individual field is encrypted with a Data Encryption Key (DEK) before storage, and the plaintext is only available on demand to authorised callers.

Kibo's encrypted-field model gives you this without managing keys yourself. The plaintext field travels from the SDK to Kibo over a mutually authenticated channel; Kibo encrypts the value (using software-protected in-process encryption at the Hardened baseline, or inside a hardware TEE in Secure Key Release (SKR) mode); only the ciphertext is stored. On read, the same path goes the other way. Plaintext keys never touch the client; the application code looks almost identical to plaintext field handling.

This tutorial walks through encrypting a ssn field on a customers collection and reading it back.

Prerequisites​

  • A project with Platform-Managed custody (or any custody mode — the API is identical)
  • The SDK installed and initialised per Building Your First App Kernel
  • A collection with a field you want to encrypt — we'll use customers.ssn here

Step 1 — Mark the field as encrypted​

In the Console, open the customers collection schema. For the ssn field, set encryption: enabled. This tells the platform:

  • Writes to ssn are encrypted by Kibo automatically; the stored value is ciphertext
  • Reads of ssn are decrypted by Kibo automatically when the calling context is authorised
  • The field is excluded from full-text indexes and from raw-SQL projections to prevent ciphertext leakage

Save the schema. Existing rows in the collection are not retroactively encrypted (encryption is per-write); see the migration playbook for the retroactive case if you need it.

Step 2 — Write an encrypted value​

The application code is the same as plaintext:

import { createClient } from '@k9o/core';
const k9o = createClient({ orgSlug: 'your-org', projectSlug: 'your-project', apiKey: process.env.K9O_API_KEY! });

const { data } = await k9o.from('customers').insert({
name: 'Alex Lee',
ssn: '123-45-6789', // platform encrypts this before storage
});

console.log(data.id); // cust_kQ3pZ9rL2sW8

What happens under the hood:

  1. SDK serialises the request payload
  2. Gateway routes to the data pillar
  3. Data pillar inspects the schema and identifies ssn as encryption-enabled
  4. Plaintext ssn is sent to Kibo over the mutually authenticated channel
  5. Kibo generates (or reuses, per cache discipline) a DEK, encrypts the plaintext, and returns the ciphertext (in SKR mode this step executes inside a hardware TEE)
  6. Data pillar stores ciphertext + DEK reference in the row
  7. Audit log records both the insert event (data pillar) and the encrypt event (Kibo ledger)
SDKinsert callGatewayroutes requestData pillarschema checkKiboencrypts valueplaintext ssnciphertextStored rowciphertext + DEK referenceAudit loginsert event (data pillar) and encrypt event (Kibo ledger)
On a write, Kibo returns the ciphertext and the data pillar stores it with a DEK reference; both the insert and the encrypt event are audit-logged.

The plaintext SSN was visible to your application code (it appeared in the insert call) and to Kibo. It was never written to disk in plaintext, never logged in plaintext, never transmitted in plaintext anywhere except over the authenticated SDK channel.

Step 3 — Read it back​

Application code remains identical:

const { data } = await k9o
.from('customers')
.select()
.eq('id', 'cust_kQ3pZ9rL2sW8');
const customer = data[0];

console.log(customer.ssn); // "123-45-6789"

Under the hood:

  1. SDK request authenticated through Gate
  2. Data pillar fetches the row; ssn is ciphertext
  3. Policy layer checks the caller is authorised to read ssn (per the field-level read policy you declared)
  4. If authorised, the ciphertext + DEK reference is sent to Kibo
  5. Kibo unwraps the DEK and decrypts the field, returning the plaintext over the authenticated channel (in SKR mode, unwrapping and decryption execute inside a hardware TEE)
  6. Data pillar returns the plaintext to the SDK
  7. Audit log records the read with the calling subject identity

If the caller is not authorised — for example, a support role that should not see SSNs — the field is returned as null or as a masked placeholder (***-**-6789 if you configure the schema to do so), and the access denial is audit-logged.

Step 4 — Query selectively​

Queries against encrypted columns are opt-in and equality-only. The platform supports two searchable modes, depending on how the field is declared:

Mode-C — blind index (blind_indexed: true). Declare the field with blind_indexed: true in the schema. The platform maintains a keyed hash index alongside the ciphertext; equality and in lookups work against that index without decrypting any row:

// eq and in are supported on blind-indexed fields
const matches = await k9o.from('customers')
.select()
.eq('ssn', '123-45-6789');

const batch = await k9o.from('customers')
.select()
.in('ssn', ['123-45-6789', '987-65-4321']);

Mode-D — vault token search (store: 'vault', searchable: true). The field's plaintext moves into the Kibo vault; a deterministic token is stored in the column. Equality lookup exchanges the search value for its token and queries the token column:

// Equality lookup on a vault-tokenised searchable field
const matches = await k9o.from('customers')
.select()
.eq('pan_token', '4111-xxxx-xxxx-1111');

What is not supported. Range operators (gt, lt, gte, lte), LIKE / full-text search, sorting on protected columns, and any other non-equality operator are rejected at the gateway — the platform returns K9O_ENCRYPTED_COLUMN_OPERATION_UNSUPPORTED (400). There is no server-side decrypt-and-filter loop; unsupported operators are refused rather than run slowly.

Step 5 — Verify in the audit log​

Open Audit → Recent events and look for two correlated entries:

  • A data.customers.select event from the data pillar
  • A data.read.field.revealed event from Kibo, with the same requestId, the same subject, and the field reference (customers.ssn)

Both events are signed; the chain is intact. The forensic question "who decrypted Alex Lee's SSN at 14:23 UTC" has a cryptographically attributable answer.

What just happened​

You added field-level encryption to a sensitive column without:

  • Managing DEKs yourself
  • Shipping plaintext keys to the client
  • Writing application code to call encrypt/decrypt
  • Losing the ability to query the field (for equality, at least)

The same model scales to any custody mode. If you climb the ladder to BYOK, the field's DEKs become wrapped under your KMS-held CEK; the application code does not change.

Next​