Getting started with CipherStash Proxy

Getting started

Important

Prerequisites: Before you start you need to have this software installed:

Get up and running in local dev in < 5 minutes by creating an account in the CipherStash Dashboard, and using the credentials to start the containers:

1# Clone the Proxy repository
2git clone https://github.com/cipherstash/proxy
3
4# Navigate to the Proxy repository
5cd proxy
6
7# Follow the instructions in the Dashboard to create a workspace and get credentials
8# Copy the credentials to the `.env.proxy.docker` file
9
10# Start the containers
11docker compose up

This will start a PostgreSQL database on localhost:5432, and CipherStash Proxy on localhost:6432. There's an example table called users that you can use to start inserting and querying encrypted data with.

Note

In this example table we've chosen users' email, date of birth, and salary as examples of the kind of sensitive data that you might want to protect with encryption.

Step 1: Insert and read some data

Now let's connect to the Proxy via psql and run some queries:

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

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

Now insert and read some data via Proxy:

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

The INSERT statement inserts a record into the users table, and the SELECT statement 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 let's connect to the database directly via psql and see what the data actually looks like behind the scenes:

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

This establishes an interactive session directly with the database (note the change of host to postgres and port to 5432).

Now on this direct psql session, query the database directly:

1SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users;

You'll see the output is much larger, because the SELECT returns the raw encrypted data. The data is transparently encrypted and decrypted by Proxy in the INSERT and SELECT statements.

Step 2: Update the data with a WHERE clause

In your psql connection to Proxy:

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

Update the data we inserted in Step 1, and read it back:

1UPDATE users SET encrypted_dob = '1978-02-01' WHERE encrypted_email = '[email protected]';
2
3SELECT encrypted_dob FROM users WHERE encrypted_email = '[email protected]';

In the UPDATE statement, the = comparison operation in the WHERE clause is evaluated against encrypted data. In the SELECT statement, the encrypted_email value is transparently encrypted by Proxy, and compared in the database against the stored encrypted email value. In the SELECT statement, the SELECT returns 1978-02-01.

Back on the psql session connected directly to the database, verify the data is encrypted:

1SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users;

This SELECT shows the raw encrypted data — no plaintext to see.

Step 3: Search encrypted data with a WHERE clause

In your psql connection to Proxy:

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

Insert more records via Proxy, and query by email:

1INSERT INTO users (encrypted_email, encrypted_dob, encrypted_salary) VALUES ('[email protected]', '1991-03-06', '10');
2INSERT INTO users (encrypted_email, encrypted_dob, encrypted_salary) VALUES ('[email protected]', '2005-12-30', '1000');
3
4SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users WHERE encrypted_salary <= 100;

In the INSERT statement, the salary value is transparently encrypted by Proxy, and stored in the database in encrypted form. In the SELECT statement, the encrypted_salary value is transparently encrypted and compared in the database against the stored encrypted salary value. In the SELECT statement, the <= comparison operation in the WHERE clause is evaluated against encrypted data. In the SELECT statement, the SELECT returns alice and bob, but not carol.

Query users by email:

1SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users WHERE encrypted_email LIKE 'alice';

The literal string alice is transparently encrypted by Proxy, and compared in the database against the stored encrypted date value. The LIKE comparison operation is evaluated against encrypted data. The SELECT will only return alice.

Finally, query users by date:

1SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users WHERE encrypted_dob > '2000-01-01' ;

The literal date 2000-01-01 is transparently encrypted by Proxy, and compared in the database against the stored encrypted date value. The > comparison operation is evaluated against encrypted data. The SELECT will only return carol.

Back on the psql session connected directly to the database, verify the data is encrypted:

1SELECT encrypted_email, encrypted_dob, encrypted_salary FROM users;

This SELECT shows the raw encrypted data, no plaintext to see.

References