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
Copy file name to clipboardExpand all lines: README.md
+25-64
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,7 @@
1
1
# Encrypt Query Language (EQL)
2
2
3
-
[](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/concepts/WHY.md)
-[How do I integrate CipherStash EQL with my application?](#how-do-i-integrate-cipherstash-eql-with-my-application)
43
41
-[Can I use EQL without the CipherStash Proxy?](#can-i-use-eql-without-the-cipherstash-proxy)
@@ -68,6 +66,10 @@ The simplest way to get up and running with EQL is to execute the install SQL fi
68
66
EQL relies on [CipherStash Proxy](https://github.com/cipherstash/encrypt-query-language/blob/main/PROXY.md) for low-latency encryption & decryption.
69
67
We plan to support direct language integration in the future.
70
68
69
+
## Documentation
70
+
71
+
You can read more about the EQL concepts and reference guides in the [documentation directory](https://github.com/cipherstash/encrypt-query-language/tree/main/docs).
72
+
71
73
## Getting started
72
74
73
75
Once the custom types and functions are installed, you can start using EQL in your queries.
@@ -121,7 +123,7 @@ When connected to the database directly, it is a no-op.
121
123
122
124
Encrypted data is stored as `jsonb` values in the database, regardless of the original data type.
123
125
124
-
You can read more about the data format [here][#data-format].
126
+
You can read more about the data format [here](docs/reference/PAYLOAD.md).
125
127
126
128
### Inserting Data
127
129
@@ -201,7 +203,7 @@ SELECT cs_add_index_v1(
201
203
);
202
204
```
203
205
204
-
You can read more about the index configuration options [here][https://github.com/cipherstash/encrypt-query-language/blob/main/docs/reference/INDEX.md].
206
+
You can read more about the index configuration options [here](docs/reference/INDEX.md).
205
207
206
208
**Example (Unique index):**
207
209
@@ -396,7 +398,7 @@ Data is stored in the database as:
396
398
"k": "sv",
397
399
"v": 1,
398
400
"sv": [
399
-
...ciphertext...
401
+
["ciphertext"]
400
402
]
401
403
}
402
404
```
@@ -429,59 +431,7 @@ Data is returned as:
429
431
### Advanced JSON queries
430
432
431
433
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. |
434
+
You can read more about the JSONB support in the [JSONB reference guide](docs/reference/JSON.md).
485
435
486
436
## Frequently Asked Questions
487
437
@@ -501,12 +451,23 @@ No, CipherStash Proxy is required to handle the encryption and decryption operat
501
451
Data is encrypted using CipherStash's cryptographic schemes and stored in the `cs_encrypted_v1` column as a JSONB payload.
502
452
Encryption and decryption are handled by CipherStash Proxy.
503
453
504
-
## Helper packages
454
+
## Helper packages and examples
505
455
506
456
We've created a few langague specific packages to help you interact with the payloads:
0 commit comments