The CipherCell

The CipherCell is CipherStash's standard format for storing encrypted data in a database. It is a JSON-based structure that combines encrypted values, searchable encrypted metadata, and non-sensitive metadata into a single, self-contained record. CipherCells are designed to make encrypted data practical to work with in real applications: they can be stored in existing databases (such as PostgreSQL jsonb columns), indexed, queried, and audited — without exposing plaintext.

What a CipherCell contains

A CipherCell typically includes:

• Encrypted data
  • The ciphertext for one or more sensitive values.
  • Each value is encrypted independently using strong authenticated encryption and unique per-value keys.
• Searchable Encrypted Metadata (SEM)
  • Additional cryptographic material derived from the plaintext that enables secure querying using searchable encryption.
  • This metadata allows operations such as equality checks, range queries, or text search to be performed without decrypting the data.
  • The database can evaluate queries over this metadata, but cannot recover the original values.
• Non-sensitive metadata
  • Plaintext fields that are safe to expose, such as schema identifiers, versioning information, timestamps, or application-level IDs.
  • Keeping this metadata unencrypted allows efficient filtering, indexing, and integration with existing tooling.

How CipherCells are used

CipherCells are stored directly in the database, usually in a JSON-compatible column. Encrypt Query Language (EQL) understands this structure and provides database functions and operators that work over CipherCells, enabling encrypted search and filtering while preserving strong security guarantees.

From an application's perspective, a CipherCell behaves like a regular database value:

• Applications write encrypted data as JSON
• Databases store and index it
• Queries operate on Searchable Encrypted Metadata (SEM)
• Decryption happens only in trusted application code with the right keys and claims

Why CipherCells exist

The CipherCell format solves a common problem with encryption at rest: traditional encryption makes data opaque and hard to query. CipherCells retain the benefits of encryption while enabling:

• Fine-grained, per-value protection
• Searchable encryption over structured data
• Compatibility with existing databases and ORMs
• Clear separation between sensitive and non-sensitive information

In short, a CipherCell is the unit of encrypted storage in CipherStash — a portable, self-describing JSON record that makes encrypted data usable, searchable, and auditable by default.

Structure

A CipherCell is stored as a JSON object with the following top-level structure:

{
  "i": {
    "t": "table_name",
    "c": "column_name"
  },
  "v": 2,
  "c": "encrypted_data_in_messagepack_base85",
  "hm": "2e182f0c444d1d51f5f70f32d778b2eaa854f5921a4a2acaa4446c44055cb777",
  "ob": ["ore_block_1", "ore_block_2"],
  "bf": [1234, 5678, 9012]
}

Top-level fields

i - Identifier

The table and column identifier for this encrypted data.

Type: Object with t (table) and c (column) properties

Required: Yes

{
  "i": {
    "t": "users",
    "c": "email"
  }
}

This field identifies which table and column the encrypted data belongs to, enabling proper decryption and index usage.

v - Version

The encryption version used for this CipherCell.

Type: Integer

Required: Yes

{
  "v": 2
}

The version field allows for cryptographic algorithm upgrades over time while maintaining backward compatibility.

c - Ciphertext (required unless sv is present)

The encrypted record containing the actual plaintext data.

Type: String (MessagePack encoded and Base85 encoded)

Required: Yes (unless sv field is present)

{
  "c": "Xk}0>Z*pVbW@%*8a%F0@"
}

a - Array item flag

Indicates whether this CipherCell represents an item within an array.

Type: Boolean

Required: No

{
  "a": true
}

Searchable Encrypted Metadata (SEM)

The CipherCell can contain various types of searchable encrypted metadata, each enabling different query capabilities. All SEM fields are optional and only included when the corresponding index type is configured.

hm - HMAC-SHA256

Enables exact match queries using HMAC-SHA256.

Type: Hex-encoded string (64 characters)

Index Type: Exact

{
  "hm": "2e182f0c444d1d51f5f70f32d778b2eaa854f5921a4a2acaa4446c44055cb777"
}

ob - ORE Block

Enables range queries and ordering using Order Revealing Encryption.

Type: Array of strings

Index Type: Order / Range

{
  "ob": [
    "01a2b3c4d5e6f7g8h9i0",
    "j1k2l3m4n5o6p7q8r9s0"
  ]
}

bf - Bloom Filter

Enables substring and pattern matching queries using encrypted Bloom filters with trigrams.

Type: Array of integers

Index Type: Match

{
  "bf": [1234, 5678, 9012, 3456, 7890]
}

b3 - Blake3

Blake3 hash for exact matches in structured encryption vectors.

Type: Hex-encoded string

Used in: SteVec (Structured Encryption Vector) subfield

s - Selector

Selector value for field selection in structured encryption vectors.

Type: String

Used in: SteVec (Structured Encryption Vector) subfield

ocf - ORE CLWW Fixed-Width

ORE CLWW (Chenette-Lewi-Weis-Wu) fixed-width scheme for 64-bit integer values in structured encryption vectors.

Type: String

Used in: SteVec (Structured Encryption Vector) subfield

ocv - ORE CLWW Variable-Width

ORE CLWW variable-width scheme for string comparison in structured encryption vectors.

Type: String

Used in: SteVec (Structured Encryption Vector) subfield

sv - Structured Encryption Vector (SteVec) (required unless c is present)

Nested array of CipherCells for supporting containment queries and JSON-style operations.

Type: Array of CipherCell objects

Required: Yes (unless c attribute is present)

{
  "sv": [
    {
      "c": "Xk}0>Z*pVbW@%*8a%F0@",
      "hm": "hash1...",
      "s": "selector1"
    },
    {
      "c": "Yl~1?A+qWcX#&+9b&G1#",
      "hm": "hash2...",
      "s": "selector2"
    }
  ]
}

SteVec enables queries on array elements and JSON document structures while maintaining encryption. Each element in the sv array is itself a CipherCell that can contain SEM fields like b3, s, ocf, and ocv.

Complete example

Here's a complete CipherCell with multiple index types enabled:

{
  "i": {
    "t": "products",
    "c": "price"
  },
  "v": 2,
  "c": "Xk}0>Z*pVbW@%*8a%F0@Yl~1?A+qWcX#&+9b&G1#",
  "hm": "2e182f0c444d1d51f5f70f32d778b2eaa854f5921a4a2acaa4446c44055cb777",
  "ob": [
    "01a2b3c4d5e6f7g8h9i0",
    "j1k2l3m4n5o6p7q8r9s0",
    "t1u2v3w4x5y6z7a8b9c0"
  ],
  "bf": [1234, 5678, 9012, 3456, 7890, 2345, 6789]
}

This CipherCell:

• Belongs to the price column of the products table
• Uses encryption version 2
• Contains the encrypted plaintext value
• Supports exact match queries via hm
• Supports range queries and ordering via ob
• Supports pattern matching via bf

Design principles

Minimal storage

Only the index types that are actually configured for a column are included in the CipherCell. This minimizes storage overhead and ensures optimal performance.

Composable indexes

Multiple index types can be combined on a single column, enabling both exact matches and range queries, or exact matches and pattern matching, depending on application needs.

Forward compatibility

The version field (v) enables cryptographic algorithm upgrades without requiring full database re-encryption. Older versions can coexist with newer versions during migration.

Standardized format

The CipherCell format is consistent across all CipherStash SDKs and tools, ensuring interoperability and portability of encrypted data.

Database storage

CipherCells can be stored as JSON in any database that supports JSON data types. However, for search to be supported using the Encryption SDK or CipherStash Proxy, the eql_v2.encrypted database type must be used which is available when the Encrypt Query Language (EQL) helpers have been installed.