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
Encrypt Query Language (EQL) is a set of abstractions for transmitting, storing & interacting with encrypted data and indexes in PostgreSQL.
8
+
Encrypt Query Language (EQL) is a set of abstractions for transmitting, storing, and interacting with encrypted data and indexes in PostgreSQL.
9
9
10
-
EQL provides a data format for transmitting and storing encrypted data & indexes, and database types & functions to interact with the encrypted material.
10
+
EQL provides a data format for transmitting and storing encrypted data and indexes, as well as database types and functions to interact with the encrypted material.
11
11
12
12
## Table of Contents
13
13
@@ -27,9 +27,9 @@ EQL provides a data format for transmitting and storing encrypted data & indexes
27
27
28
28
## Installation
29
29
30
-
The simplest and fastest way to get up and running with EQL from scratch is to execute the install SQL file directly in your database.
30
+
The simplest and fastest way to get up and running with EQL is to execute the install SQL file directly in your database.
31
31
32
-
1. Download the [cipherstash-encrypt-dsl.sql](./release/cipherstash-encrypt-dsl.sql) file
2. Run the following command to install the custom types and functions:
34
34
35
35
```bash
@@ -42,17 +42,17 @@ Once the custom types and functions are installed, you can start using EQL in yo
42
42
43
43
1. Create a table with a column of type `cs_encrypted_v1` which will store your encrypted data.
44
44
1. Use EQL functions to add indexes for the columns you want to encrypt.
45
-
- Indexes are used by Cipherstash Proxy to understand what cryptography schemes are required for your use case.
46
-
1. Initialize Cipherstash Proxy for cryptographic operations.
47
-
-The Proxy will dynamically encrypt data on the way in and decrypt data on the way out based on the indexes you have defined.
45
+
- Indexes are used by CipherStash Proxy to understand what cryptography schemes are required for your use case.
46
+
1. Initialize CipherStash Proxy for cryptographic operations.
47
+
- Proxy will dynamically encrypt data on the way in and decrypt data on the way out, based on the indexes you've defined.
48
48
1. Insert data into the defined columns using a specific payload format.
49
-
-The payload format is defined in the [data format](#data-format)section.
50
-
1. Query the data using the EQL functions defined in the [querying data with EQL](#querying-data-with-eql) section.
49
+
-See [data format](#data-format)for the payload format.
50
+
1. Query the data using the EQL functions defined in [querying data with EQL](#querying-data-with-eql).
51
51
- No modifications are required to simply `SELECT` data from your encrypted columns.
52
-
-In order to perform `WHERE` and `ORDER BY` queries, you must wrap the queries in the EQL functions defined in the [querying data with EQL](#querying-data-with-eql) section.
52
+
-To perform `WHERE` and `ORDER BY` queries, wrap the queries in the EQL functions defined in [querying data with EQL](#querying-data-with-eql).
53
53
1. Integrate with your application via the [helper packages](#helper-packages) to interact with the encrypted data.
54
54
55
-
You can find a full getting started guide in the [GETTINGSTARTED.md](GETTINGSTARTED.md)file.
55
+
Read [GETTINGSTARTED.md](GETTINGSTARTED.md)for more detail.
56
56
57
57
## Encrypted columns
58
58
@@ -73,11 +73,11 @@ In some instances, especially when using langugage specific ORMs, EQL also suppo
73
73
74
74
### Configuring the column
75
75
76
-
In order for CipherStash Proxy to encrypt and decrypt the data, you can initialize the column in the database using the `cs_add_column_v1` function.
76
+
So that CipherStash Proxy can encrypt and decrypt the data, initialize the column in the database using the `cs_add_column_v1` function.
77
77
This function takes the following parameters:
78
78
79
-
-`table_name`: The name of the table containing the encrypted column.
80
-
-`column_name`: The name of the encrypted column.
79
+
-`table_name`: the name of the table containing the encrypted column.
80
+
-`column_name`: the name of the encrypted column.
81
81
82
82
This function will **not** enable searchable encryption, but will allow you to encrypt and decrypt data.
83
83
See [querying data with EQL](#querying-data-with-eql) for more information on how to enable searchable encryption.
When inserting data into the encrypted column, you must wrap the plaintext in the appropriate EQL payload.
112
+
When inserting data into the encrypted column, wrap the plaintext in the appropriate EQL payload.
113
113
These statements must be run through the CipherStash Proxy in order to **encrypt** the data.
114
114
115
115
**Example:**
@@ -137,7 +137,7 @@ All the data stored in the database is fully encrypted and secure.
137
137
138
138
### Reading data
139
139
140
-
When querying data, you must wrap the encrypted column in the appropriate EQL payload.
140
+
When querying data, wrap the encrypted column in the appropriate EQL payload.
141
141
These statements must be run through the CipherStash Proxy in order to **decrypt** the data.
142
142
143
143
**Example:**
@@ -346,7 +346,7 @@ Extract a field from a JSONB object in a `SELECT` statement:
346
346
SELECT cs_ste_value_v1(attrs, 'DQ1rbhWJXmmqi/+niUG6qw') FROM users;
347
347
```
348
348
349
-
The above is the equivalent to this SQL query:
349
+
Which is the equivalent to the following SQL query:
350
350
351
351
```sql
352
352
SELECT attrs->'login_count' FROM users;
@@ -361,7 +361,7 @@ Select rows that match a field in a JSONB object:
361
361
SELECT * FROM users WHERE cs_ste_term_v1(attrs, 'DQ1rbhWJXmmqi/+niUG6qw') > 'QAJ3HezijfTHaKrhdKxUEg';
362
362
```
363
363
364
-
The above is the equivalent to this SQL query:
364
+
Which is the equivalent to the following SQL query:
365
365
366
366
```sql
367
367
SELECT * FROM users WHERE attrs->'login_count' > 10;
@@ -418,20 +418,20 @@ The default Match index options are:
418
418
}
419
419
```
420
420
421
-
- `tokenFilters`: a list of filters to apply to normalise tokens before indexing.
421
+
- `tokenFilters`: a list of filters to apply to normalize tokens before indexing.
422
422
- `tokenizer`: determines how input text is split into tokens.
423
423
- `m`: The size of the backing [bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) in bits. Defaults to `2048`.
424
424
- `k`: The maximum number of bits set in the bloom filter per term. Defaults to `6`.
425
425
426
-
**Token Filters**
426
+
**Token filters**
427
427
428
-
There are currently only two token filters available `downcase` and `upcase`. These are used to normalise the text before indexing and are also applied to query terms. An empty array can also be passed to `tokenFilters` if no normalisation of terms is required.
428
+
There are currently only two token filters available: `downcase` and `upcase`. These are used to normalise the text before indexing and are also applied to query terms. An empty array can also be passed to `tokenFilters` if no normalisation of terms is required.
429
429
430
430
**Tokenizer**
431
431
432
432
There are two `tokenizer`s provided: `standard` and `ngram`.
433
-
The `standard` simply splits text into tokens using this regular expression: `/[ ,;:!]/`.
434
-
The `ngram` tokenizer splits the text into n-grams and accepts a configuration object that allows you to specify the `tokenLength`.
433
+
`standard` simply splits text into tokens using this regular expression: `/[ ,;:!]/`.
434
+
`ngram` splits the text into n-grams and accepts a configuration object that allows you to specify the `tokenLength`.
@@ -628,15 +628,15 @@ Cipherstash proxy handles the encoding, and EQL provides the functions.
628
628
| i.c | Column identifier | Name of the encrypted column. |
629
629
| p | Plaintext | Plaintext value sent by database client. Required if kind is plaintext/pt or encrypting/et. |
630
630
| 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"`, `"ejson_path"`, and `"websearch_to_match"`. |
631
-
| c | Ciphertext | Ciphertext value. Encrypted by proxy. Required if kind is plaintext/pt or encrypting/et. |
632
-
| m | Match index | Ciphertext index value. Encrypted by proxy. |
633
-
| o | ORE index | Ciphertext index value. Encrypted by proxy. |
634
-
| u | Unique index | Ciphertext index value. Encrypted by proxy. |
635
-
| sv | STE vector index | Ciphertext index value. Encrypted by proxy. |
631
+
| c | Ciphertext | Ciphertext value. Encrypted by Proxy. Required if kind is plaintext/pt or encrypting/et. |
632
+
| m | Match index | Ciphertext index value. Encrypted by Proxy. |
633
+
| o | ORE index | Ciphertext index value. Encrypted by Proxy. |
634
+
| u | Unique index | Ciphertext index value. Encrypted by Proxy. |
635
+
| sv | STE vector index | Ciphertext index value. Encrypted by Proxy. |
636
636
637
637
## Helper packages
638
638
639
-
We have created a few langague specific packages to help you interact with the payloads:
639
+
We've created a few langague specific packages to help you interact with the payloads:
640
640
641
641
- [@cipherstash/eql](https://github.com/cipherstash/encrypt-query-language/tree/main/languages/javascript/packages/eql): This is a TypeScript implementation of EQL.
642
642
- [github.com/cipherstash/goeql](https://github.com/cipherstash/goeql): This is a Go implementation of EQL
@@ -645,10 +645,10 @@ We have created a few langague specific packages to help you interact with the p
645
645
646
646
To cut a [release](https://github.com/cipherstash/encrypt-query-language/releases) of EQL:
647
647
648
-
1. Draft a [new release](https://github.com/cipherstash/encrypt-query-language/releases/new) on GitHub
649
-
1. Choose a tag, and create a new one with the prefix `eql-` followed by a [semver](https://semver.org/) (for example, `eql-1.2.3`)
650
-
1. Generate the release notes
651
-
1. Optionally set the release to be the latest (you can set a release to be latest later on if you are testing out a release first)
652
-
1. Click the `Publish release` button
648
+
1. Draft a [new release](https://github.com/cipherstash/encrypt-query-language/releases/new) on GitHub.
649
+
1. Choose a tag, and create a new one with the prefix `eql-` followed by a [semver](https://semver.org/) (for example, `eql-1.2.3`).
650
+
1. Generate the release notes.
651
+
1. Optionally set the release to be the latest (you can set a release to be latest later on if you are testing out a release first).
652
+
1. Click `Publish release`.
653
653
654
-
This will trigger a run of the [Release EQL](https://github.com/cipherstash/encrypt-query-language/actions/workflows/release-eql.yml) workflow, which will build and attach artifacts to the release.
654
+
This will trigger the [Release EQL](https://github.com/cipherstash/encrypt-query-language/actions/workflows/release-eql.yml) workflow, which will build and attach artifacts to the release.
0 commit comments