You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/concepts/WHY.md)
Encrypt Query Language (EQL) is a set of abstractions for transmitting, storing, and interacting with encrypted data and indexes in PostgreSQL.
9
7
@@ -12,12 +10,13 @@ Store encrypted data alongside your existing data.
12
10
- Encrypted data is stored using a `jsonb` column type
13
11
- Query encrypted data with specialized SQL functions
14
12
- Index encrypted columns to enable searchable encryption
15
-
- Integrate with [CipherStash Proxy](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/tutorials/PROXY.md) for transparent encryption/decryption
13
+
- Integrate with [CipherStash Proxy](/docs/tutorials/PROXY.md) for transparent encryption/decryption
Encrypted data is stored as `jsonb` values in the database, regardless of the original data type.
120
+
Encrypted data is stored as `jsonb` values in the PostgreSQL database, regardless of the original data type.
123
121
124
-
You can read more about the data format [here][#data-format].
122
+
You can read more about the data format [here](docs/reference/PAYLOAD.md).
125
123
126
124
### Inserting Data
127
125
@@ -135,7 +133,7 @@ INSERT INTO users (encrypted_email) VALUES (
135
133
);
136
134
```
137
135
138
-
Data is stored in the database as:
136
+
Data is stored in the PostgreSQL database as:
139
137
140
138
```json
141
139
{
@@ -201,7 +199,7 @@ SELECT cs_add_index_v1(
201
199
);
202
200
```
203
201
204
-
You can read more about the index configuration options [here][https://github.com/cipherstash/encrypt-query-language/blob/main/docs/reference/INDEX.md].
202
+
You can read more about the index configuration options [here](docs/reference/INDEX.md).
205
203
206
204
**Example (Unique index):**
207
205
@@ -339,155 +337,15 @@ SELECT field, COUNT(*) FROM users GROUP BY field;
339
337
340
338
## JSON and JSONB support
341
339
342
-
EQL supports encrypting, decrypting, and searching JSON and JSONB objects.
343
-
344
-
### Configuring the index
345
-
346
-
Similar to how you configure indexes for text data, you can configure indexes for JSON and JSONB data.
347
-
The only difference is that you need to specify the `cast_as` parameter as `json` or `jsonb`.
348
-
349
-
```sql
350
-
SELECT cs_add_index_v1(
351
-
'users',
352
-
'encrypted_json',
353
-
'ste_vec',
354
-
'jsonb',
355
-
'{"prefix": "users/encrypted_json"}'-- The prefix is in the form of "table/column"
356
-
);
357
-
```
358
-
359
-
You can read more about the index configuration options [here](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/reference/INDEX.md).
360
-
361
-
### Inserting JSON data
362
-
363
-
When inserting JSON data, this works the same as inserting text data.
364
-
You need to wrap the JSON data in the appropriate EQL payload.
365
-
CipherStash Proxy will **encrypt** the data automatically.
366
-
367
-
**Example:**
368
-
369
-
Assuming you want to store the following JSON data:
We support a wide range of JSON/JSONB functions and operators.
432
-
You can read more about the JSONB support in the [JSONB reference guide](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/reference/JSON.md).
433
-
434
-
## EQL payload data format
435
-
436
-
Encrypted data is stored as `jsonb` with a specific schema:
437
-
438
-
-**Plaintext payload (client side):**
439
-
440
-
```json
441
-
{
442
-
"v": 1,
443
-
"k": "pt",
444
-
"p": "plaintext value",
445
-
"e": {
446
-
"t": "table_name",
447
-
"c": "column_name"
448
-
}
449
-
}
450
-
```
451
-
452
-
-**Encrypted payload (database side):**
453
-
454
-
```json
455
-
{
456
-
"v": 1,
457
-
"k": "ct",
458
-
"c": "ciphertext value",
459
-
"e": {
460
-
"t": "table_name",
461
-
"c": "column_name"
462
-
}
463
-
}
464
-
```
465
-
466
-
The format is defined as a [JSON Schema](./cs_encrypted_v1.schema.json).
467
-
468
-
It should never be necessary to directly interact with the stored `jsonb`.
469
-
CipherStash Proxy handles the encoding, and EQL provides the functions.
| s | Schema version | JSON Schema version of this json document. |
474
-
| v | Version | The configuration version that generated this stored value. |
475
-
| k | Kind | The kind of the data (plaintext/pt, ciphertext/ct, encrypting/et). |
476
-
| i.t | Table identifier | Name of the table containing encrypted column. |
477
-
| i.c | Column identifier | Name of the encrypted column. |
478
-
| p | Plaintext | Plaintext value sent by database client. Required if kind is plaintext/pt or encrypting/et. |
479
-
| q | For query | Specifies that the plaintext should be encrypted for a specific query operation. If `null`, source encryption and encryption for all indexes will be performed. Valid values are `"match"`, `"ore"`, `"unique"`, `"ste_vec"`, and `"ejson_path"`. |
480
-
| c | Ciphertext | Ciphertext value. Encrypted by Proxy. Required if kind is plaintext/pt or encrypting/et. |
481
-
| m | Match index | Ciphertext index value. Encrypted by Proxy. |
482
-
| o | ORE index | Ciphertext index value. Encrypted by Proxy. |
483
-
| u | Unique index | Ciphertext index value. Encrypted by Proxy. |
484
-
| sv | STE vector index | Ciphertext index value. Encrypted by Proxy. |
340
+
EQL supports encrypting entire JSON and JSONB data sets.
341
+
This warrants a separate section in the documentation.
342
+
You can read more about the JSONB support in the [JSONB reference guide](docs/reference/JSON.md).
485
343
486
344
## Frequently Asked Questions
487
345
488
346
### How do I integrate CipherStash EQL with my application?
489
347
490
-
Use CipherStash Proxy to intercept database queries and handle encryption and decryption automatically.
348
+
Use CipherStash Proxy to intercept PostgreSQL queries and handle encryption and decryption automatically.
491
349
The proxy interacts with the database using the EQL functions and types defined in this documentation.
492
350
493
351
Use the [helper packages](#helper-packages) to integate EQL functions into your application.
@@ -501,16 +359,23 @@ No, CipherStash Proxy is required to handle the encryption and decryption operat
501
359
Data is encrypted using CipherStash's cryptographic schemes and stored in the `cs_encrypted_v1` column as a JSONB payload.
502
360
Encryption and decryption are handled by CipherStash Proxy.
503
361
504
-
## Helper packages
362
+
## Helper packages and examples
505
363
506
364
We've created a few langague specific packages to help you interact with the payloads:
0 commit comments