Skip to content

Commit 223e65e

Browse files
mdb-admdb-ad
committed
suggestions
1 parent 0ffe96c commit 223e65e

File tree

4 files changed

+86
-133
lines changed

4 files changed

+86
-133
lines changed

‎source/client-side-encryption/client-side-encryption.md

Lines changed: 46 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1814,59 +1814,39 @@ metadata.
18141814
18151815
Data keys are stored in the MongoDB key vault collection with the following schema:
18161816
1817-
| | | |
1818-
| ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
1819-
| **Name** | **Type** | **Description** |
1820-
| \_id | UUID | A unique identifier for the key. |
1821-
| version | Int64 | A numeric identifier for the schema version of this document. Implicitly 0 if unset. |
1822-
| keyAltNames | Array of strings | Alternate names to search for keys by. Used for a per-document key scenario in support of GDPR scenarios. |
1823-
| keyMaterial | BinData | Encrypted data key material, BinData type General |
1824-
| creationDate | Date | The datetime the wrapped data key material was imported into the Key Database. |
1825-
| updateDate | Date | The datetime the wrapped data key material was last modified. On initial import, this value will be set to creationDate. |
1826-
| status | Int | 0 = enabled, 1 = disabled |
1827-
| masterKey | Document | Per provider master key definition, see below |
1817+
| | | | | \------------ | ---------------- |
1818+
\------------------------------------------------------------------------------------------------------------------------
1819+
| | **Name** | **Type** | **Description** | | \_id | UUID | A unique identifier for the key. | | version | Int64 | A
1820+
numeric identifier for the schema version of this document. Implicitly 0 if unset. | | keyAltNames | Array of strings |
1821+
Alternate names to search for keys by. Used for a per-document key scenario in support of GDPR scenarios. | |
1822+
keyMaterial | BinData | Encrypted data key material, BinData type General | | creationDate | Date | The datetime the
1823+
wrapped data key material was imported into the Key Database. | | updateDate | Date | The datetime the wrapped data key
1824+
material was last modified. On initial import, this value will be set to creationDate. | | status | Int | 0 = enabled, 1
1825+
= disabled | | masterKey | Document | Per provider master key definition, see below |
18281826
18291827
#### masterKey contents
18301828
1831-
| | | |
1832-
| -------- | -------- | --------------------------------------------------------------------- |
1833-
| **Name** | **Type** | **Description** |
1834-
| provider | "aws" | |
1835-
| key | String | AWS ARN. Only applicable for "aws" provider. |
1836-
| region | String | AWS Region that contains AWS ARN. Only applicable for "aws" provider. |
1837-
| endpoint | String | Alternate AWS endpoint (needed for FIPS endpoints) |
1838-
1839-
| | | |
1840-
| ---------------- | -------- | ------------------------------------------------------------- |
1841-
| **Name** | **Type** | **Description** |
1842-
| provider | "azure" | |
1843-
| keyVaultEndpoint | String | Required key vault endpoint. (e.g. "example.vault.azure.net") |
1844-
| keyName | String | Required key name. |
1845-
| keyVersion | String | Optional key version. |
1846-
1847-
| | | |
1848-
| ---------- | -------- | ---------------------------------------------------------------- |
1849-
| **Name** | **Type** | **Description** |
1850-
| provider | "gcp" | |
1851-
| projectId | String | Required project ID. |
1852-
| location | String | Required location name (e.g. "global") |
1853-
| keyRing | String | Required key ring name. |
1854-
| keyName | String | Required key name. |
1855-
| keyVersion | String | Optional key version. |
1856-
| endpoint | String | Optional, KMS URL, defaults to <https://cloudkms.googleapis.com> |
1857-
1858-
| | | |
1859-
| -------- | -------- | --------------- |
1860-
| **Name** | **Type** | **Description** |
1861-
| provider | "local" | |
1862-
1863-
| | | |
1864-
| --------- | -------- | -------------------------------------------------------------------------------------- |
1865-
| **Name** | **Type** | **Description** |
1866-
| provider | "kmip" | |
1867-
| endpoint | String | Optional. Defaults to kmip.endpoint from KMS providers. |
1868-
| delegated | Boolean | Optional. Defaults to false. |
1869-
| keyId | String | Required. keyId is the Unique Identifier to a 96 byte KMIP Secret Data managed object. |
1829+
| | | | | -------- | -------- | --------------------------------------------------------------------- | | **Name** |
1830+
**Type** | **Description** | | provider | "aws" | | | key | String | AWS ARN. Only applicable for "aws" provider. | |
1831+
region | String | AWS Region that contains AWS ARN. Only applicable for "aws" provider. | | endpoint | String |
1832+
Alternate AWS endpoint (needed for FIPS endpoints) |
1833+
1834+
| | | | | ---------------- | -------- | ------------------------------------------------------------- | | **Name** |
1835+
**Type** | **Description** | | provider | "azure" | | | keyVaultEndpoint | String | Required key vault endpoint. (e.g.
1836+
"example.vault.azure.net") | | keyName | String | Required key name. | | keyVersion | String | Optional key version. |
1837+
1838+
| | | | | ---------- | -------- | ---------------------------------------------------------------- | | **Name** |
1839+
**Type** | **Description** | | provider | "gcp" | | | projectId | String | Required project ID. | | location | String |
1840+
Required location name (e.g. "global") | | keyRing | String | Required key ring name. | | keyName | String | Required
1841+
key name. | | keyVersion | String | Optional key version. | | endpoint | String | Optional, KMS URL, defaults to
1842+
<https://cloudkms.googleapis.com> |
1843+
1844+
| | | | | -------- | -------- | --------------- | | **Name** | **Type** | **Description** | | provider | "local" | |
1845+
1846+
| | | | | \--------- | -------- | --------------------------------------------------------------------------------------
1847+
| | **Name** | **Type** | **Description** | | provider | "kmip" | | | endpoint | String | Optional. Defaults to
1848+
kmip.endpoint from KMS providers. | | delegated | Boolean | Optional. Defaults to false. | | keyId | String | Required.
1849+
keyId is the Unique Identifier to a 96 byte KMIP Secret Data managed object. |
18701850
18711851
Data keys are needed for encryption and decryption. They are identified in the intent-to-encrypt marking and ciphertext.
18721852
Data keys may be retrieved by querying the "\_id" with a UUID or by querying the "keyAltName" with a string.
@@ -1943,11 +1923,12 @@ encrypt : {
19431923

19441924
Each field is briefly described as follows:
19451925

1946-
| Name | Type | Description |
1947-
| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
1948-
| bsonType | string | The bsonType of the underlying encrypted field. |
1949-
| algorithm | string | "AEAD_AES_256_CBC_HMAC_SHA_512-Random" or <br>"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" |
1950-
| keyId | string or array of UUID | If string, it is a JSON pointer to a field with a scalar value <br>identifying a key by keyAltName.<br>If array, an array of eligible keys. |
1926+
| Name | Type | Description | | --------- | ----------------------- |
1927+
\-------------------------------------------------------------------------------------------------------------------------------------------
1928+
| | bsonType | string | The bsonType of the underlying encrypted field. | | algorithm | string |
1929+
"AEAD_AES_256_CBC_HMAC_SHA_512-Random" or <br>"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" | | keyId | string or array
1930+
of UUID | If string, it is a JSON pointer to a field with a scalar value <br>identifying a key by keyAltName.<br>If
1931+
array, an array of eligible keys. |
19511932

19521933
### libmongocrypt: Prohibitions and warnings
19531934

@@ -1996,46 +1977,16 @@ IV key and any given encryption operation will derive the IV from the IV key and
19961977
libmongocrypt determines whether or not the command requires encryption (i.e. is sent to mongocryptd) based on the table
19971978
below. Commands not listed in this table will result in an error returned by libmongocrypt.
19981979

1999-
| | |
2000-
| ------------------------ | ----------- |
2001-
| **Command** | **Action** |
2002-
| aggregate (collection) | AUTOENCRYPT |
2003-
| count | AUTOENCRYPT |
2004-
| distinct | AUTOENCRYPT |
2005-
| delete | AUTOENCRYPT |
2006-
| find | AUTOENCRYPT |
2007-
| findAndModify | AUTOENCRYPT |
2008-
| getMore | BYPASS |
2009-
| insert | AUTOENCRYPT |
2010-
| update | AUTOENCRYPT |
2011-
| authenticate | BYPASS |
2012-
| getnonce | BYPASS |
2013-
| logout | BYPASS |
2014-
| hello | BYPASS |
2015-
| legacy hello | BYPASS |
2016-
| abortTransaction | BYPASS |
2017-
| commitTransaction | BYPASS |
2018-
| endSessions | BYPASS |
2019-
| startSession | BYPASS |
2020-
| create | BYPASS |
2021-
| createIndexes | BYPASS |
2022-
| createSearchIndexes | BYPASS |
2023-
| drop | BYPASS |
2024-
| dropDatabase | BYPASS |
2025-
| dropIndexes | BYPASS |
2026-
| dropSearchIndex | BYPASS |
2027-
| killCursors | BYPASS |
2028-
| listCollections | BYPASS |
2029-
| listDatabases | BYPASS |
2030-
| listIndexes | BYPASS |
2031-
| renameCollection | BYPASS |
2032-
| explain | AUTOENCRYPT |
2033-
| ping | BYPASS |
2034-
| killAllSessions | BYPASS |
2035-
| killSessions | BYPASS |
2036-
| killAllSessionsByPattern | BYPASS |
2037-
| refreshSessions | BYPASS |
2038-
| updateSearchIndex | BYPASS |
1980+
| | | | ------------------------ | ----------- | | **Command** | **Action** | | aggregate (collection) | AUTOENCRYPT | |
1981+
count | AUTOENCRYPT | | distinct | AUTOENCRYPT | | delete | AUTOENCRYPT | | find | AUTOENCRYPT | | findAndModify |
1982+
AUTOENCRYPT | | getMore | BYPASS | | insert | AUTOENCRYPT | | update | AUTOENCRYPT | | authenticate | BYPASS | |
1983+
getnonce | BYPASS | | logout | BYPASS | | hello | BYPASS | | legacy hello | BYPASS | | abortTransaction | BYPASS | |
1984+
commitTransaction | BYPASS | | endSessions | BYPASS | | startSession | BYPASS | | create | BYPASS | | createIndexes |
1985+
BYPASS | | createSearchIndexes | BYPASS | | drop | BYPASS | | dropDatabase | BYPASS | | dropIndexes | BYPASS | |
1986+
dropSearchIndex | BYPASS | | killCursors | BYPASS | | listCollections | BYPASS | | listDatabases | BYPASS | |
1987+
listIndexes | BYPASS | | renameCollection | BYPASS | | explain | AUTOENCRYPT | | ping | BYPASS | | killAllSessions |
1988+
BYPASS | | killSessions | BYPASS | | killAllSessionsByPattern | BYPASS | | refreshSessions | BYPASS | |
1989+
updateSearchIndex | BYPASS |
20391990

20401991
All AUTOENCRYPT commands are sent to mongocryptd, even if there is no JSONSchema. This is to ensure that commands that
20411992
reference other collections (e.g. aggregate with `$lookup`) are handled properly.

‎source/client-side-encryption/etc/data/encryptedFields-prefix-suffix.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
"subType": "04"
88
}
99
},
10-
"path": "encrypted-textPreview",
10+
"path": "encryptedText",
1111
"bsonType": "string",
1212
"queries": [
1313
{

‎source/client-side-encryption/etc/data/encryptedFields-substring.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
"subType": "04"
88
}
99
},
10-
"path": "encrypted-textPreview",
10+
"path": "encryptedText",
1111
"bsonType": "string",
1212
"queries": [
1313
{

‎source/client-side-encryption/tests/README.md

Lines changed: 38 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3834,6 +3834,36 @@ class EncryptOpts {
38343834
}
38353835
```
38363836

3837+
Where prefix, suffix, or substring options are required, use the following:
3838+
3839+
1. Prefix
3840+
3841+
```typescript
3842+
class PrefixOpts {
3843+
strMaxQueryLength: 10,
3844+
strMinQueryLength: 2,
3845+
}
3846+
```
3847+
3848+
2. Suffix
3849+
3850+
```typescript
3851+
class SuffixOpts {
3852+
strMaxQueryLength: 10,
3853+
strMinQueryLength: 2,
3854+
}
3855+
```
3856+
3857+
3. Substring
3858+
3859+
```typescript
3860+
class SubstringOpts {
3861+
strMaxLength: 10,
3862+
strMaxQueryLength: 10,
3863+
strMinQueryLength: 2,
3864+
}
3865+
```
3866+
38373867
Use `encryptedClient` to insert the following document into `db.prefix-suffix`:
38383868

38393869
```javascript
@@ -3885,42 +3915,14 @@ class EncryptOpts {
38853915
}
38863916
```
38873917

3888-
1. Prefix
3889-
3890-
```typescript
3891-
class PrefixOpts {
3892-
strMaxQueryLength: 10,
3893-
strMinQueryLength: 2,
3894-
}
3895-
```
3896-
3897-
2. Suffix
3898-
3899-
```typescript
3900-
class SuffixOpts {
3901-
strMaxQueryLength: 10,
3902-
strMinQueryLength: 2,
3903-
}
3904-
```
3905-
3906-
3. Substring
3907-
3908-
```typescript
3909-
class SubstringOpts {
3910-
strMaxLength: 10,
3911-
strMaxQueryLength: 10,
3912-
strMinQueryLength: 2,
3913-
}
3914-
```
3915-
39163918
#### Case 1: can find a document by prefix
39173919

39183920
Use `clientEncryption.encrypt()` to encrypt the string `"foo"`. Store the resulting payload in `findPayload`.
39193921

39203922
Use `encryptedClient` to run a "find" operation on the `db.prefix-suffix` collection with the following filter:
39213923

39223924
```javascript
3923-
{ "$expr": { "$encStrStartsWith": {"input": "$encryptedText", "prefix": <findPayload>}, } }
3925+
{ $expr: { $encStrStartsWith: {input: '$encryptedText', prefix: <findPayload>}, } }
39243926
```
39253927

39263928
Assert the following document is returned:
@@ -3931,12 +3933,12 @@ Assert the following document is returned:
39313933

39323934
#### Case 2: can find a document by suffix
39333935

3934-
Use `clientEncryption.encrypt()` to encrypt the string `"foo"`. Store the resulting payload in `findPayload`.
3936+
Use `clientEncryption.encrypt()` to encrypt the string `"baz"`. Store the resulting payload in `findPayload`.
39353937

39363938
Use `encryptedClient` to run a "find" operation on the `db.prefix-suffix` collection with the following filter:
39373939

39383940
```javascript
3939-
{ "$expr": { "$encStrStartsWith": {"input": "$encryptedText", "prefix": <findPayload>}, } }
3941+
{ $expr: { $encStrEndsWith: {input: '$encryptedText', suffix: <findPayload>}, } }
39403942
```
39413943

39423944
Assert the following document is returned:
@@ -3947,12 +3949,12 @@ Assert the following document is returned:
39473949

39483950
#### Case 3: assert no document found by prefix
39493951

3950-
Use `clientEncryption.encrypt()` to encrypt the string `"foo"`. Store the resulting payload in `findPayload`.
3952+
Use `clientEncryption.encrypt()` to encrypt the string `"baz"`. Store the resulting payload in `findPayload`.
39513953

39523954
Use `encryptedClient` to run a "find" operation on the `db.prefix-suffix` collection with the following filter:
39533955

39543956
```javascript
3955-
{ "$expr": { "$encStrStartsWith": {"input": "$encryptedText", "prefix": <findPayload>}, } }
3957+
{ $expr: { $encStrStartsWith: {input: '$encryptedText', prefix: <findPayload>}, } }
39563958
```
39573959

39583960
Assert that no documents are returned.
@@ -3964,7 +3966,7 @@ Use `clientEncryption.encrypt()` to encrypt the string `"foo"`. Store the result
39643966
Use `encryptedClient` to run a "find" operation on the `db.prefix-suffix` collection with the following filter:
39653967

39663968
```javascript
3967-
{ "$expr": { "$encStrStartsWith": {"input": "$encryptedText", "suffix": <findPayload>}, } }
3969+
{ $expr: { $encStrEndsWith: {input: '$encryptedText', suffix: <findPayload>}, } }
39683970
```
39693971

39703972
Assert that no documents are returned.
@@ -3976,7 +3978,7 @@ Use `clientEncryption.encrypt()` to encrypt the string `"foo"`. Store the result
39763978
Use `encryptedClient` to run a "find" operation on the `db.substring` collection with the following filter:
39773979

39783980
```javascript
3979-
{ "$expr": { "$encStrStartsWith": {"input": "$encryptedText", "prefix": <findPayload>}, } }
3981+
{ $expr: { $encStrContains: {input: '$encryptedText', substring: <findPayload>}, } }
39803982
```
39813983

39823984
Assert the following document is returned:
@@ -3992,7 +3994,7 @@ Use `clientEncryption.encrypt()` to encrypt the string `"qux"`. Store the result
39923994
Use `encryptedClient` to run a "find" operation on the `db.substring` collection with the following filter:
39933995

39943996
```javascript
3995-
{ "$expr": { "$encStrStartsWith": {"input": "$encryptedText", "prefix": <findPayload>}, } }
3997+
{ $expr: { $encStrContains: {input: '$encryptedText', substring: <findPayload>}, } }
39963998
```
39973999

39984000
Assert that no documents are returned.

0 commit comments

Comments
 (0)