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-Managedcustody (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.ssnhere
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
ssnare encrypted by Kibo automatically; the stored value is ciphertext - Reads of
ssnare 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:
- SDK serialises the request payload
- Gateway routes to the data pillar
- Data pillar inspects the schema and identifies
ssnas encryption-enabled - Plaintext
ssnis sent to Kibo over the mutually authenticated channel - 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)
- Data pillar stores ciphertext + DEK reference in the row
- Audit log records both the insert event (data pillar) and the encrypt event (Kibo ledger)
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:
- SDK request authenticated through Gate
- Data pillar fetches the row;
ssnis ciphertext - Policy layer checks the caller is authorised to read
ssn(per the field-level read policy you declared) - If authorised, the ciphertext + DEK reference is sent to Kibo
- 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)
- Data pillar returns the plaintext to the SDK
- 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.selectevent from the data pillar - A
data.read.field.revealedevent from Kibo, with the samerequestId, the samesubject, 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
- Kibo Overview — the custody ladder and the Application Cryptographic Oracle Protocol underlying this flow.
- Kibo BYOK — climbing from Platform-Managed to your own KMS without code changes.
- Architect — DevOps → Confidential Client Node Attestation — for high-throughput workloads that need attested-TEE DEK distribution.