Getting started with Proxy

Clone the repo

Start by cloning the Proxy repo:

git clone https://github.com/cipherstash/proxy
cd proxy

Set up credentials

CipherStash Proxy runs inside a Docker container, so it cannot use the host's device-based authentication directly. For local development, create a client key in the CipherStash Dashboard and save the credentials to .env.proxy.docker:

CS_WORKSPACE_CRN=<your workspace CRN>
CS_CLIENT_ID=<client ID>
CS_CLIENT_KEY=<client key>
CS_CLIENT_ACCESS_KEY=<access key>

You can find your workspace CRN in Settings for your workspace. Create a client key under Clients and an access key under Access Keys.

For production Proxy deployments, see Going to production to set up application client key credentials.

Start the containers

docker compose up

This starts a PostgreSQL database on localhost:5432 and CipherStash Proxy on localhost:6432. The repo includes an example users table for inserting and querying encrypted data.

Insert and read some data

Connect to the Proxy via psql and run some queries:

docker compose exec proxy psql postgres://cipherstash:3ncryp7@localhost:6432/cipherstash

This establishes an interactive session with the database, via CipherStash Proxy.

Insert and read some data via Proxy:

INSERT INTO users (encrypted_email, encrypted_dob, encrypted_salary)
VALUES ('[email protected]', '1970-01-01', '100');

SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users;

The INSERT inserts a record into the users table, and the SELECT reads the same record back. Notice that it looks like nothing happened: the data in the INSERT was unencrypted, and the data in the SELECT is also unencrypted.

Now connect to the database directly via psql and see what the data actually looks like:

docker compose exec proxy psql postgres://cipherstash:3ncryp7@postgres:5432/cipherstash

Query the database directly:

SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users;

The output is significantly larger because the SELECT returns the raw encrypted data. The data is transparently encrypted and decrypted by Proxy.

Update data with a WHERE clause

In your psql connection to Proxy, update the data and read it back:

UPDATE users SET encrypted_dob = '1978-02-01'
WHERE encrypted_email = '[email protected]';

SELECT encrypted_dob FROM users
WHERE encrypted_email = '[email protected]';

The = comparison operation in the WHERE clause is evaluated against encrypted data. The SELECT returns 1978-02-01.

Search encrypted data

Insert more records via Proxy and search them:

INSERT INTO users (encrypted_email, encrypted_dob, encrypted_salary)
VALUES ('[email protected]', '1991-03-06', '10');

INSERT INTO users (encrypted_email, encrypted_dob, encrypted_salary)
VALUES ('[email protected]', '2005-12-30', '1000');

-- Range query on encrypted salary
SELECT encrypted_email, encrypted_dob, encrypted_salary
FROM users WHERE encrypted_salary <= 100;

-- Pattern match on encrypted email
SELECT encrypted_email, encrypted_dob, encrypted_salary
FROM users WHERE encrypted_email LIKE 'alice';

-- Range query on encrypted date
SELECT encrypted_email, encrypted_dob, encrypted_salary
FROM users WHERE encrypted_dob > '2000-01-01';

All comparison operations are evaluated against encrypted data. The literal values are transparently encrypted by Proxy before being compared in the database.