README

Protect.php FFI provides PHP bindings for the CipherStash Client SDK via PHP's Foreign Function Interface (FFI). Field-level encryption operations happen directly in your application using a unique key for each encrypted value, managed by CipherStash ZeroKMS and backed by AWS KMS. The encrypted data can be stored in any JSONB-compatible database while maintaining searchability on PostgreSQL.

This library operates at a low level, providing direct access to the native cryptographic operations. It requires manual memory management and detailed encryption configuration, designed for advanced use cases where you need fine-grained control over the encryption process.

Important

For most applications, you'll want to use the Protect.php library instead, as it provides a more convenient API built on top of these bindings.

Installation

Install Protect.php FFI via Composer:

composer require cipherstash/protectphp-ffi

Requirements

Protect.php FFI requires PHP 8.1 or higher with the FFI extension (included in most distributions). This library includes prebuilt native libraries for the following platforms:

• macOS: Apple Silicon (ARM64) and Intel (x86_64) processors
• Linux: x86_64 and ARM64 architectures with GNU libc
• Windows: x86_64 architecture with MSVC runtime

Configuration

Before using Protect.php FFI, you must configure your CipherStash credentials. Set these environment variables in your application:

CS_CLIENT_ID=your-client-id
CS_CLIENT_ACCESS_KEY=your-client-access-key
CS_CLIENT_KEY=your-client-key
CS_WORKSPACE_CRN=your-workspace-crn

Credentials can be generated by logging in or signing up for CipherStash and setting up a new workspace via the CipherStash CLI or CipherStash Dashboard.

Database Setup

Protect.php FFI works with any database that supports JSONB storage. The encrypted data is structured as an Encrypt Query Language (EQL) JSON payload.

For advanced querying capabilities (searching, sorting, filtering), you'll need PostgreSQL with the EQL extension. EQL provides the eql_v2_encrypted type:

CREATE TABLE users (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    email eql_v2_encrypted,
    name eql_v2_encrypted,
    balance eql_v2_encrypted,
    contact eql_v2_encrypted,
    notes eql_v2_encrypted,
    CONSTRAINT unique_email UNIQUE ((email->>'hm')) -- Enforce unique emails
);

See the EQL installation instructions to get started.

Encryption Configuration

The encryption configuration defines your schema and determines what types of operations are supported on encrypted data. It consists of a JSON structure that specifies tables, columns, data types, and encryption indexes.

Basic structure:

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
            'balance' => [
                'cast_as' => 'int',
                'indexes' => [
                    'unique' => (object) [],
                    'ore' => (object) [],
                ],
            ],
            'notes' => [
                'cast_as' => 'text',
                'indexes' => [
                    'match' => (object) [],
                ],
            ],
            'contact' => [
                'cast_as' => 'jsonb',
                'indexes' => [
                    'ste_vec' => [
                        'prefix' => 'users.contact',
                    ],
                ],
            ],
        ],
    ],
];

Configuration parameters:

Parameter	Type	Required	Description
v	int	✓	Schema version for backward compatibility (must be 2)
tables	object	✓	Table definitions containing column configurations
tables.<table>	object	✓	Column definitions for the specified table
tables.<table>.<column>	object	✓	Configuration for the specified column
tables.<table>.<column>.cast_as	string	✗	Data type for processing before encryption (defaults to text)
tables.<table>.<column>.indexes	object	✗	Encryption indexes for query patterns
tables.<table>.<column>.indexes.<index_type>	object	✗	Configuration parameters for the specified index type (see individual index type documentation)
tables.<table>.<column>.indexes.<index_type>.<param>	mixed	✗	Index-specific configuration parameter

Important

When configuring indexes without parameters, you must use (object) [] instead of an empty array []. This ensures PHP's json_encode() produces a JSON object ({}) rather than a JSON array ([]), which is required by the native library's configuration parser.

Data Types

The cast_as parameter determines how plaintext data is processed before encryption:

Type	Description	Example Input
text	String data	john@example.com
boolean	Boolean values	true or false
small_int	16-bit integer numbers	32767
int	32-bit integer numbers	2147483647
big_int	64-bit integer numbers	9223372036854775807
real	Single-precision floating point	25.99
double	Double-precision floating point	3.141592653589793
date	Date strings in ISO format	2020-11-10
jsonb	JSON data	{"key": "value"}

Index Types

The indexes parameter determines what queries are supported on encrypted data:

Index Type	Description	Response Parameter	Supported Queries
unique	Exact equality queries and uniqueness constraints	hm	=
ore	Equality, range comparisons, range queries, and ordering	ob	=, >, <, BETWEEN, ORDER BY
match	Full-text search queries	bf	~~
ste_vec	JSONB containment queries	sv	@>, <@

Unique Index (unique)

Enables exact equality queries and database uniqueness constraints. Uses the hm response parameter to generate HMAC-based hashes for exact equality matching.

Basic usage:

'users' => [
    'email' => [
        'cast_as' => 'text',
        'indexes' => [
            'unique' => (object) [], // Uses defaults
        ],
    ],
],

Configuration parameters:

Parameter	Type	Required	Default	Description
token_filters	array	✗	[]	Text processing filters applied before hashing
token_filters[].kind	string	✗	-	Filter type: downcase to convert to lowercase

With custom parameters:

'users' => [
    'email' => [
        'cast_as' => 'text',
        'indexes' => [
            'unique' => [
                'token_filters' => [
                    ['kind' => 'downcase'],
                ],
            ],
        ],
    ],
],

For database-level uniqueness constraints, add a unique constraint on the hm response parameter:

CONSTRAINT unique_email UNIQUE ((email->>'hm'))

Order Revealing Encryption Index (ore)

Enables equality, range operations, and ordering on encrypted data. Uses the ob response parameter to create order-preserving encrypted values for equality checks, range comparisons, and sorting operations.

Basic usage:

'users' => [
    'balance' => [
        'cast_as' => 'int',
        'indexes' => [
            'ore' => (object) [],
        ],
    ],
],

Configuration parameters:

This index type has no configurable parameters.

Match Index (match)

Enables full-text search on encrypted text data using bloom filters. Uses the bf response parameter to create bloom filter representations of tokenized text for probabilistic matching.

Basic usage:

'users' => [
    'notes' => [
        'cast_as' => 'text',
        'indexes' => [
            'match' => (object) [], // Uses defaults
        ],
    ],
],

Configuration parameters:

Parameter	Type	Required	Default	Description
tokenizer	object	✗	{"kind": "standard"}	Text tokenization method
tokenizer.kind	string	✗	standard	Tokenizer type: standard or ngram
tokenizer.token_length	integer	✗	3	Token length for ngram tokenizer
token_filters	array	✗	[]	Text processing filters
token_filters[].kind	string	✗	-	Filter type: downcase
k	integer	✗	6	Hash function count for bloom filter
m	integer	✗	2048	Bloom filter size in bits
include_original	boolean	✗	false	Include original text in search results

With custom parameters:

'users' => [
    'notes' => [
        'cast_as' => 'text',
        'indexes' => [
            'match' => [
                'tokenizer' => [
                    'kind' => 'ngram',
                    'token_length' => 3,
                ],
                'token_filters' => [
                    ['kind' => 'downcase'],
                ],
                'k' => 8,
                'm' => 1024,
                'include_original' => true,
            ],
        ],
    ],
],

Structured Text Encryption Vector Index (ste_vec)

Enables containment queries on encrypted JSONB data. Uses the sv response parameter to create structured text encryption vectors that preserve JSON path relationships for encrypted JSONB containment matching.

Basic usage:

'users' => [
    'contact' => [
        'cast_as' => 'jsonb',
        'indexes' => [
            'ste_vec' => [
                'prefix' => 'users.contact',
            ],
        ],
    ],
],

Configuration parameters:

Parameter	Type	Required	Default	Description
prefix	string	✓	-	Domain separator for cryptographic hashing that must be unique per column (recommended format is table.column)

Creating a Client

Create a client instance with your encryption configuration to perform encryption and decryption operations:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                ],
            ],
            'balance' => [
                'cast_as' => 'int',
                'indexes' => [
                    'unique' => (object) [],
                    'ore' => (object) [],
                ],
            ],
            'notes' => [
                'cast_as' => 'text',
                'indexes' => [
                    'match' => (object) [],
                ],
            ],
            'contact' => [
                'cast_as' => 'jsonb',
                'indexes' => [
                    'ste_vec' => [
                        'prefix' => 'users.contact',
                    ],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    // ...
} finally {
    // Always cleanup to prevent memory leaks
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Encrypting Data

Encrypt plaintext data for specific table columns using the encrypt() method. This method accepts a client pointer and individual parameters for the plaintext string, column name, and table name. The encryption configuration defines how each column should be encrypted and what data type it represents:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $encryptResultJson = $client->encrypt(
        client: $clientPtr,
        plaintext: 'john@example.com',
        column: 'email',
        table: 'users',
    );

    // {"k":"ct","c":"mBbKlk}G7QdaGiNj$dL7#+AOrA^}*VJx...","dt":"text","hm":"f3ca71fd39ae9d3d1d1fc25141bcb6da...","ob":null,"bf":[1124,2134,987,1456,743,2201],"i":{"t":"users","c":"email"},"v":2}
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Important

The plaintext parameter must always be a string. The cast_as configuration parameter determines how the string is processed by the native library before encryption, not the input format, and indicates the intended data type for parsing decrypted strings. Convert all values to strings before calling this method.

Encryption Response

The encrypt() method returns a JSON string containing the encrypted envelope. The response format depends on the configured indexes.

Standard Indexes Response

For columns configured with the unique, ore, and/or match indexes:

{
    "k": "ct",
    "c": "mBbKlk}G7QdaGiNj$dL7#+AOrA^}*VJx...",
    "dt": "text",
    "hm": "f3ca71fd39ae9d3d1d1fc25141bcb6da...",
    "ob": null,
    "bf": [1124,2134,987,1456,743,2201],
    "i": {
        "t": "users",
        "c": "email"
    },
    "v": 2
}

Response parameters:

Parameter	Type	Source	Description
k	string	Always	Key type identifier (always ct for ciphertext)
c	string	Always	Base85-encoded ciphertext containing the encrypted data
dt	string	Always	Data type for casting (from cast_as configuration parameter)
hm	string|null	unique	HMAC index for exact equality queries and uniqueness constraints
ob	array|null	ore	Order-revealing encryption index for range queries
bf	array|null	match	Bloom filter index for full-text search queries
i	object	Always	Table and column identifier for this encrypted value: {"t":"table","c":"column"}
v	int	Always	Schema version for backward compatibility

STE Vec Index Response

For columns configured with the ste_vec index:

{
    "k": "sv",
    "c": "mBbLQ2^Io|1eh_K2*n^LSCVVQuGhkL>w...",
    "dt": "jsonb",
    "sv": [
        {
            "s": "dd4659b9c279af040dd05ce21b2a22f7...",
            "t": "22303061363334333330316661653633...",
            "r": "mBbLQ2^Io|1eh_K2*n^LSCVVQuGhkL>w...",
            "pa": false
        }
    ],
    "i": {
        "t": "users",
        "c": "contact"
    },
    "v": 2
}

Response parameters:

Parameter	Type	Source	Description
k	string	Always	Key type identifier (always sv for structured vector)
c	string	Always	Base85-encoded ciphertext containing the encrypted data
dt	string	Always	Data type for casting (from cast_as configuration parameter)
sv	array|null	ste_vec	Structured text encryption vector for JSONB containment queries
sv[].s	string	ste_vec	Tokenized selector representing the encrypted JSON path to the value
sv[].t	string	ste_vec	Encrypted term value for equality and order-preserving queries
sv[].r	string	ste_vec	Base85-encoded ciphertext containing the encrypted record data
sv[].pa	boolean	ste_vec	Whether the parent JSON element is an array
i	object	Always	Table and column identifier for this encrypted value: {"t":"table","c":"column"}
v	int	Always	Schema version for backward compatibility

Decrypting Data

Decrypt ciphertext back to its original plaintext using the decrypt() method. This method accepts a client pointer and the base85-encoded ciphertext string from the encryption response:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $encryptResultJson = $client->encrypt(
        client: $clientPtr,
        plaintext: 'john@example.com',
        column: 'email',
        table: 'users',
    );

    $encryptResult = json_decode(json: $encryptResultJson, associative: true, flags: JSON_THROW_ON_ERROR);

    $ciphertext = $encryptResult['c'];

    $decryptResult = $client->decrypt($clientPtr, $ciphertext); // john@example.com
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Returns the decrypted plaintext as a string.

Encryption Context

Provide additional encryption context for an additional layer of security by binding encrypted data to specific contextual information of your choosing. This prevents data encrypted with one context from being decrypted with a different context, even when using the same encryption keys.

Context Types

The context parameter determines what contextual authentication is supported:

Context Type	Supported Index Types	Description
identity_claim	unique, ore, match	Identity-aware encryption using JWT claims (requires CTS authentication)
tag	unique, ore, match	Label-aware encryption using string tags
value	unique, ore, match	Attribute-aware encryption using key-value pairs

Important

Encryption context is not supported with ste_vec indexes and will cause decryption to fail.

Identity Claim Context

Identity claim context binds encrypted data to specific user identities using JWT claims. This enables identity-aware encryption where data can only be decrypted by authenticated users who match the identity criteria.

Identity claim context requires CipherStash Token Service (CTS) authentication for both encryption and decryption operations. The FFI layer supports identity claim parsing but cannot perform cryptographic operations with identity claims without valid CTS tokens. Use the Protect.php library for this type of encryption context.

Tag Context

Tag context binds encrypted data to specific string labels. This enables label-aware encryption where data can only be decrypted when the same tag context is provided:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $context = [
        'tag' => ['pii', 'hipaa'],
    ];

    $contextJson = json_encode($context, JSON_THROW_ON_ERROR);

    $encryptResultJson = $client->encrypt(
        client: $clientPtr,
        plaintext: 'john@example.com',
        column: 'email',
        table: 'users',
        contextJson: $contextJson,
    );

    $encryptResult = json_decode(json: $encryptResultJson, associative: true, flags: JSON_THROW_ON_ERROR);

    $ciphertext = $encryptResult['c'];

    $decryptResult = $client->decrypt($clientPtr, $ciphertext, $contextJson); // john@example.com
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Value Context

Value context binds encrypted data to specific key-value pairs. This enables attribute-aware encryption where data can only be decrypted when the same value context is provided:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $context = [
        'value' => [
            ['key' => 'tenant_id', 'value' => 'tenant_2ynTJf38e9HvuAO8jaX5kAyVaKI'],
            ['key' => 'role', 'value' => 'admin'],
        ],
    ];

    $contextJson = json_encode($context, JSON_THROW_ON_ERROR);

    $encryptResultJson = $client->encrypt(
        client: $clientPtr,
        plaintext: 'john@example.com',
        column: 'email',
        table: 'users',
        contextJson: $contextJson,
    );

    $encryptResult = json_decode(json: $encryptResultJson, associative: true, flags: JSON_THROW_ON_ERROR);

    $ciphertext = $encryptResult['c'];

    $decryptResult = $client->decrypt($clientPtr, $ciphertext, $contextJson); // john@example.com
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Warning

You must use the same context for both encryption and decryption operations. Wrong contexts will result in decryption failures.

Bulk Operations

For improved performance when handling multiple records, use bulk encryption and decryption operations:

Bulk Encryption

Encrypt multiple plaintext strings using the encryptBulk() method. This method accepts a client pointer and a JSON array of objects, where each object specifies the plaintext, column, table, and optional context for encryption:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
            'notes' => [
                'cast_as' => 'text',
                'indexes' => [
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $items = [
        [
            'plaintext' => 'john@example.com',
            'column' => 'email',
            'table' => 'users',
        ],
        [
            'plaintext' => 'Account flagged for fraud monitoring after suspicious transaction pattern detected. Customer disputed charges on 2007-07-27. Priority support required for high-value client.',
            'column' => 'notes',
            'table' => 'users',
        ],
    ];

    $itemsJson = json_encode($items, JSON_THROW_ON_ERROR);
    $encryptResultsJson = $client->encryptBulk($clientPtr, $itemsJson);
    // [{"k":"ct","c":"mBbKuXT|+vBh~K2WV-!n5_W3DBFd4`Mp...","dt":"text","hm":"f3ca71fd39ae9d3d1d1fc25141bcb6da...","ob":null,"bf":[1124,2134,987,1456,743,2201],"i":{"t":"users","c":"email"},"v":2},{"k":"ct","c":"mBbJ<8tOEI+Z`KFUV`q&kmdWtO#DKxW|...","dt":"text","hm":null,"ob":null,"bf":[1397,378,1463,1673,1474,1226],"i":{"t":"users","c":"notes"},"v":2}]
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Returns a JSON array of encrypted envelopes where each element follows the same structure as documented in the Encryption Response section.

Bulk Decryption

Decrypt multiple ciphertext strings using the decryptBulk() method. This method accepts a client pointer and a JSON array of objects, where each object contains a ciphertext with the base85-encoded ciphertext string and an optional context for decryption:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
            'notes' => [
                'cast_as' => 'text',
                'indexes' => [
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $items = [
        [
            'plaintext' => 'john@example.com',
            'column' => 'email',
            'table' => 'users',
            'context' => [
                'tag' => ['pii', 'hipaa'],
            ],
        ],
        [
            'plaintext' => 'Account flagged for fraud monitoring after suspicious transaction pattern detected. Customer disputed charges on 2007-07-27. Priority support required for high-value client.',
            'column' => 'notes',
            'table' => 'users',
        ],
    ];

    $itemsJson = json_encode($items, JSON_THROW_ON_ERROR);
    $encryptResultsJson = $client->encryptBulk($clientPtr, $itemsJson);
    $encryptResults = json_decode(json: $encryptResultsJson, associative: true, flags: JSON_THROW_ON_ERROR);

    $decryptItems = array_map(function ($item, $encryptResult) {
        $decryptItem = ['ciphertext' => $encryptResult['c']];

        if (isset($item['context'])) {
            $decryptItem['context'] = $item['context'];
        }

        return $decryptItem;
    }, $items, $encryptResults);

    $decryptItemsJson = json_encode($decryptItems, JSON_THROW_ON_ERROR);
    // [{"ciphertext":"mBbK>BcAYctW$Gy)vK2)Y$&nBBKz{oL1...","context":{"tag":["pii","hipaa"]}},{"ciphertext":"mBbJ<8tOEI+Z`KFUV`q&kmdWtO#DKxW|..."}]

    $decryptResultsJson = $client->decryptBulk($clientPtr, $decryptItemsJson);
    // ["john@example.com", "Account flagged for fraud monitoring after suspicious transaction pattern detected. Customer disputed charges on 2007-07-27. Priority support required for high-value client."]
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Returns a JSON array of decrypted plaintext strings in the same order as the input JSON array.

Searchable Encryption

Create search terms that enable querying encrypted data without decryption using the createSearchTerms() method. This method accepts a client pointer and a JSON array of objects, where each object specifies the plaintext, column, table, and optional context for generating search terms:

use CipherStash\Protect\FFI\Client;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
            'balance' => [
                'cast_as' => 'int',
                'indexes' => [
                    'unique' => (object) [],
                    'ore' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $items = [
        [
            'plaintext' => 'john@example.com',
            'column' => 'email',
            'table' => 'users',
            'context' => [
                'tag' => ['pii', 'hipaa'],
            ],
        ],
        [
            'plaintext' => '1575000',
            'column' => 'balance',
            'table' => 'users',
        ],
    ];

    $itemsJson = json_encode($items, JSON_THROW_ON_ERROR);
    $searchTermResultsJson = $client->createSearchTerms($clientPtr, $itemsJson);
    // [{"hm":"f3ca71fd39ae9d3d1d1fc25141bcb6da...","ob":null,"bf":[1124,2134,987,1456,743,2201],"i":{"t":"users","c":"email"}},{"hm":"a8d5f2e9c4b7a1f3e8d2c5b9f6a3e7d1...","ob":["99f7adadadadadadc68b2822197a849e..."],"bf":null,"i":{"t":"users","c":"balance"}}]
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

This feature integrates with EQL and is currently only supported on PostgreSQL databases.

Querying with Search Terms

These examples demonstrate how to use search terms with PostgreSQL and EQL for querying encrypted data without decryption. Each query uses the complete search terms object, and EQL automatically selects the appropriate index for the query operation.

Exact Equality Queries

For exact equality queries, EQL uses the unique index (hm response parameter) from your search terms:

-- Find user by email address
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE email = '{"hm":"f3ca71fd39ae9d3d1d1fc25141bcb6da...","ob":null,"bf":[1124,2134,987,1456,743,2201],"i":{"t":"users","c":"email"}}'::jsonb;

Equality, Range, and Sorting Queries

For equality, range comparisons, and sorting, EQL uses the ore index (ob response parameter) from your search terms:

-- Find users with exact balance amount
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE balance = '{"hm":"a8d5f2e9c4b7a1f3e8d2c5b9f6a3e7d1...","ob":["99f7adadadadadadc68b2822197a849e..."],"bf":null,"i":{"t":"users","c":"balance"}}'::jsonb;

-- Find users above specified balance
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE balance >= '{"hm":"a8d5f2e9c4b7a1f3e8d2c5b9f6a3e7d1...","ob":["99f7adadadadadadc68b2822197a849e..."],"bf":null,"i":{"t":"users","c":"balance"}}'::jsonb;

-- Find users with balance in specified range
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE balance BETWEEN
      '{"hm":"a8d5f2e9c4b7a1f3e8d2c5b9f6a3e7d1...","ob":["99f7adadadadadadc68b2822197a849e..."],"bf":null,"i":{"t":"users","c":"balance"}}'::jsonb
  AND '{"hm":"a8d5f2e9c4b7a1f3e8d2c5b9f6a3e7d1...","ob":["99f7adadadadadadc68b2822197a849e..."],"bf":null,"i":{"t":"users","c":"balance"}}'::jsonb;

-- Order users by balance from lowest to highest
SELECT * FROM users
ORDER BY balance ASC;

-- Order users by balance from highest to lowest
SELECT * FROM users
ORDER BY balance DESC;

Full-Text Search Queries

For searching within text content, EQL uses the match index (bf response parameter) from your search terms:

-- Find users with notes containing specified terms
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE notes ~~ '{"hm":null,"ob":null,"bf":[1397,378,1463,1673,1474,1226],"i":{"t":"users","c":"notes"}}'::jsonb;

JSONB Containment Queries

For structured data queries, EQL uses the ste_vec index (sv response parameter) from your search terms:

-- Find records where encrypted data contains specified values
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE contact @> '{"sv":[{"s":"dd4659b9c279af040dd05ce21b2a22f7...","t":"22303061363334333330316661653633...","r":"mBbL}QHJ&a(@rwS5n)u^G+Fb+t}Soo-h...","pa":false}],"i":{"t":"users","c":"contact"}}'::jsonb;

-- Find records where encrypted data is contained by specified values
-- Using search terms (encrypted ahead of time, plaintext not loggable):
SELECT * FROM users
WHERE contact <@ '{"sv":[{"s":"df08a4c4157bdb5bf6fa9be89cf18d10...","t":"22303063343133306135646334356130...","r":"mBbL}QHJ&a(@rwS5n)u^G+Fb+Ex8ofB!...","pa":false}],"i":{"t":"users","c":"contact"}}'::jsonb;

Search Terms Response

The createSearchTerms() method returns a JSON string containing search terms with only the encryption indexes (without the full ciphertext). The response format depends on the configured indexes.

Standard Indexes Response

For columns configured with unique, ore, and/or match indexes:

{
    "hm": "f3ca71fd39ae9d3d1d1fc25141bcb6da...",
    "ob": null,
    "bf": [1124,2134,987,1456,743,2201],
    "i": {
        "t": "users",
        "c": "email"
    }
}

Response parameters:

Parameter	Type	Source	Description
hm	string|null	unique	HMAC index for exact equality queries and uniqueness constraints
ob	array|null	ore	Order-revealing encryption index for range queries
bf	array|null	match	Bloom filter index for full-text search queries
i	object	Always	Table and column identifier for this encrypted value: {"t":"table","c":"column"}

STE Vec Index Response

For columns configured with ste_vec indexes:

{
    "sv": [
        {
            "s": "dd4659b9c279af040dd05ce21b2a22f7...",
            "t": "22303061363334333330316661653633...",
            "r": "mBbLkCZcaJ2U|G333rRC>f;r}uFEp7Tg...",
            "pa": false
        },
        {
            "s": "df08a4c4157bdb5bf6fa9be89cf18d10...",
            "t": "22303063343133306135646334356130...",
            "r": "mBbLkCZcaJ2U|G333rRC>f;r}E&d@?`;...",
            "pa": false
        }
    ],
    "i": {
        "t": "users",
        "c": "contact"
    }
}

Response parameters:

Parameter	Type	Source	Description
sv	array|null	ste_vec	Structured text encryption vector for JSONB containment queries
sv[].s	string	ste_vec	Tokenized selector representing the encrypted JSON path to the value
sv[].t	string	ste_vec	Encrypted term value for equality and order-preserving queries
sv[].r	string	ste_vec	Base85-encoded ciphertext containing the encrypted record data
sv[].pa	boolean	ste_vec	Whether the parent JSON element is an array
i	object	Always	Table and column identifier for this encrypted value: {"t":"table","c":"column"}

Error Handling

Protect.php FFI operations may throw FFIException exceptions when errors occur during client, encryption, or decryption operations. Proper error handling ensures your application can gracefully handle configuration issues, network problems, or invalid data scenarios.

Exception Types

All FFI operations throw FFIException exceptions that contain descriptive error messages:

use CipherStash\Protect\FFI\Client;
use CipherStash\Protect\FFI\Exceptions\FFIException;

$client = new Client;

$config = [
    'v' => 2,
    'tables' => [
        'users' => [
            'email' => [
                'cast_as' => 'text',
                'indexes' => [
                    'unique' => (object) [],
                    'match' => (object) [],
                ],
            ],
        ],
    ],
];

$clientPtr = null;

try {
    $configJson = json_encode($config, JSON_THROW_ON_ERROR);
    $clientPtr = $client->newClient($configJson);

    $encryptResultJson = $client->encrypt(
        client: $clientPtr,
        plaintext: 'john@example.com',
        column: 'email',
        table: 'users',
    );

    $encryptResult = json_decode(json: $encryptResultJson, associative: true, flags: JSON_THROW_ON_ERROR);
    $ciphertext = $encryptResult['c']; // mBbKlk}G7QdaGiNj$dL7#+AOrA^}*VJx...
} catch (FFIException $e) {
    // Handle FFI errors
    // ...
} finally {
    if ($clientPtr !== null) {
        $client->freeClient($clientPtr);
    }
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.