Skip to main content

Client-Side Encryption

Bring-your-own-key and hold-your-own-key answer who controls the key. Client-side encryption answers where the plaintext lives: it never leaves your process. You encrypt the bytes locally — inside your application, against your own KMS — and hand the platform a sealed envelope it cannot open. Kibo stores and audits that envelope; it never sees the plaintext, and it never sees the key that protects it.

This is the SDK realization of the BYOK and HYOK custody modes. The encryption runs in an audited Rust core that ships inside the SDK; the platform's role is reduced to holding opaque ciphertext and recording the operation. There is no platform-managed path here by design — if the platform can decrypt for you, the plaintext was never client-side. The application-level crypto.* calls route to this path automatically on a BYOK or HYOK project, so the same code works in every custody mode (see Custody architecture).

Your processplaintext never leavesApplicationplaintext bytesplaintextAudited coreRust, in the SDKencrypt, decryptYour KMSholds the keyBYOK or HYOKyour short-lived tokenKibostores and audits thesealed envelopenever sees plaintextor keysealed envelope
Plaintext stays inside your process: the core encrypts against your own KMS, and Kibo receives only the sealed envelope.

1. Language coverage​

The client-side encryption binding is available in nine SDKs. Each wraps the same audited core, so the input model and the envelope format are identical across all of them.

LanguagePackage
TypeScript / JavaScript@k9o/kibo
Pythonk9o (module k9o.kibo)
Gok9o.dev/sdk-go/kibo
Javadev.k9o:kibo
Kotlindev.k9o:kibo
.NET / C#K9o.Kibo
Rubyk9o (K9o::Kibo)
SwiftK9OKibo
React Native@k9o/kibo-react-native

Three SDKs do not expose this binding: Rust is the audited core — the other bindings are generated from it, so there is no separate package to install; PHP and Flutter do not currently carry the client-side encryption binding (their SDKs cover the data plane and Gate respectively).

2. The round-trip​

The minimal flow is an encrypt that returns a sealed envelope, and a decrypt that returns your bytes back. The example below uses BYOK against AWS KMS with the software attestation tier and an empty encryption context — the simplest real configuration.

TypeScript
import { encrypt, decrypt, type KiboEncryptInput } from "@k9o/kibo";

const base = {
provider: "aws-kms" as const,
posture: "byok" as const,
kms_cred: { secret: process.env.KMS_TOKEN!, expires_at_unix_secs: 9_999_999_999 },
key_ref: { version: 1, external_ref: "arn:aws:kms:us-east-1:000000000000:key/abc-123" },
provider_config: { aws_region: "us-east-1" },
attestation_tier: "software" as const,
encryption_context: [],
} satisfies Partial<KiboEncryptInput>;

const { envelope } = await encrypt({ ...base, plaintext: new TextEncoder().encode("hello") });

// strategy / attestation_tier / encryption_context MUST match the encrypt call
const { plaintext } = await decrypt({
kms_cred: base.kms_cred,
provider_config: base.provider_config,
envelope,
strategy: "local_envelope",
attestation_tier: "software",
encryption_context: [],
});

Showing example in TypeScript

The Swift, Kotlin, and Java bindings are generated from the same Rust core as the others and expose the identical input shape shown above; their round-trips are exercised in CI against the platform-injected native library.

:::warning The decrypt anti-substitution rule decrypt does not read strategy, attestation_tier, or encryption_context back out of the envelope — you re-supply all three, and they must match the values used at encrypt time. This is deliberate: binding those parameters into the decrypt call rather than trusting the envelope is what prevents an attacker from substituting a different envelope or downgrading the attestation tier. A mismatch fails the decrypt. Store whatever you need to reproduce them alongside the envelope. :::

3. The encrypt input, field by field​

The minimal example sets seven fields. The full input model is the same in every language (snake_case fields in TypeScript / Python / Ruby / Go, record or data-class constructors in .NET / Java / Kotlin / Swift):

FieldMeaning
providerYour KMS: aws-kms, gcp-kms, azure-kv, or hashicorp-vault.
posturebyok or hyok. There is no platform-managed value — that path does not use client-side encryption.
kms_cred{ secret, expires_at_unix_secs }. The secret is a customer-issued, short-lived federated token to your own KMS — never a platform key. It is zeroized in-core after use and is never logged or returned.
key_ref{ version, external_ref }. external_ref is provider-specific (AWS key ARN, GCP resource name, Azure key URL, or Vault <mount>/<key>:<ver>); version is the monotonic KEK-rotation counter.
provider_config{ aws_region?, vault_address? } — only the field for the compiled-in provider is read.
attestation_tiersoftware, hardware_backed, or confidential — bound into the AAD.
encryption_contextAn array of { key, value } pairs bound into the AAD. The kibo: key prefix is reserved.
plaintextThe bytes to encrypt.
strategylocal_envelope (default) or customer_kms_oracle.
oracle_modebrokered or direct — only with the oracle strategy.
posture_policyAn optional project crypto-posture floor; omit for the most-permissive default.

encrypt returns { envelope } — an opaque, sealed blob. It is meaningless to the platform: you store it yourself, or in the platform's zk-DEK store, and pass it straight back to decrypt. The platform never holds anything it can open.

4. Per-runtime setup​

Most bindings need no initialization — call encrypt and decrypt directly. Two have a setup step:

  • React Native takes the WebAssembly core once, with init({ core }) at app start; encrypt and decrypt initialise on first use once a core was supplied. React Native cannot load the module dynamically.
  • Ruby exposes K9o::Kibo::NATIVE_AVAILABLE to guard for the native library and raises KIBO_NATIVE_UNAVAILABLE if it is missing.

In TypeScript on Node the module is lazy-loaded, so no initialization is needed. Go, Java, Kotlin, .NET, and Swift need no initialization.

5. Errors​

A posture-floor violation surfaces with the code K9O_CRYPTO_POSTURE_FLOOR_VIOLATION and carries dimension, requested, and declared in its context. Failures from your own KMS surface as the upstream KMS error. The error type follows each binding's convention: KError (TypeScript, Python, Java, .NET), K9o::KError (Ruby), KiboException (Kotlin), K9OKiboError (Swift), KiboError (React Native), and a *kibo.Error with Code / Message / Context (Go).

6. See also​

  • Overview — the four custody modes and where each project's key lives.
  • BYOK · HYOK — the customer-held custody modes this binding encrypts under.
  • SKR — SKR (Secure Key Release), the hardware-backed attestation tier you can bind into the AAD.
  • Audit Ledger — the signed record every client-side operation writes.