Skip to content

Commit acf59ea

Browse files
jmikolaalcaeus
jmikola
and
alcaeus
authored
PHPLIB-913: Database::createEncryptedCollection() helper (#1050)
* Docs for Database::createEncryptedCollection() * Revise docs and require $options since encryptedFields is required * Add example for creating new Client with auto encryption * Permit coding standard deviations in CSFLE prose tests * Extract Database methods to CreateEncryptedCollection operation * Functional tests for CreateEncryptedCollection::createDataKeys() * Test that createDataKey() doesn't modify encryptedFields object option * Require replica sets for CreateEncryptedCollectionFunctionalTest * Add reference links to CreateCollection operation docs Co-authored-by: Andreas Braun <[email protected]>
1 parent c1d32ac commit acf59ea

File tree

4 files changed

+207
-0
lines changed

4 files changed

+207
-0
lines changed

‎source/includes/apiargs-MongoDBDatabase-method-createEncryptedCollection-param.yaml

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
source:
2+
file: apiargs-common-param.yaml
3+
ref: $collectionName
4+
replacement:
5+
subject: "encrypted collection"
6+
action: " to create"
7+
---
8+
arg_name: param
9+
name: $clientEncryption
10+
type: :php:`MongoDB\\Driver\\ClientEncryption <mongodb-driver-clientencryption>`
11+
description: |
12+
The ClientEncryption object used to create data keys.
13+
interface: phpmethod
14+
operation: ~
15+
optional: false
16+
---
17+
arg_name: param
18+
name: $kmsProvider
19+
type: string
20+
description: |
21+
KMS provider (e.g. "local", "aws") that will be used to encrypt new data keys.
22+
This corresponds to the ``$kmsProvider`` parameter for
23+
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`.
24+
interface: phpmethod
25+
operation: ~
26+
optional: false
27+
---
28+
arg_name: param
29+
name: $masterKey
30+
type: array|null
31+
description: |
32+
KMS-specific key options that will be used to encrypt new data keys. This
33+
corresponds to the ``masterKey`` option for
34+
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`.
35+
36+
If ``$kmsProvider`` is "local", this should be ``null``.
37+
interface: phpmethod
38+
operation: ~
39+
optional: false
40+
---
41+
source:
42+
file: apiargs-common-param.yaml
43+
ref: $options
44+
optional: false
45+
post: |
46+
The ``encryptedFields`` option is required.
47+
...

‎source/reference/class/MongoDBDatabase.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Methods
4848
/reference/method/MongoDBDatabase-aggregate
4949
/reference/method/MongoDBDatabase-command
5050
/reference/method/MongoDBDatabase-createCollection
51+
/reference/method/MongoDBDatabase-createEncryptedCollection
5152
/reference/method/MongoDBDatabase-drop
5253
/reference/method/MongoDBDatabase-dropCollection
5354
/reference/method/MongoDBDatabase-getDatabaseName

‎source/reference/exception-classes.txt

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,21 @@ MongoDB\\Exception\\BadMethodCallException
3030

3131
----
3232

33+
MongoDB\\Exception\\CreateEncryptedCollectionException
34+
------------------------------------------------------
35+
36+
.. phpclass:: MongoDB\\Exception\\CreateEncryptedCollectionException
37+
38+
Thrown by :phpmethod:`MongoDB\\Database::createEncryptedCollection()` if any
39+
error is encountered while creating data keys or creating the collection. The
40+
original exception and modified ``encryptedFields`` option can be accessed
41+
via the ``getPrevious()`` and ``getEncryptedFields()`` methods, respectively.
42+
43+
This class extends the library's :phpclass:`RuntimeException
44+
<MongoDB\\Exception\\RuntimeException>` class.
45+
46+
----
47+
3348
MongoDB\\Exception\\InvalidArgumentException
3449
--------------------------------------------
3550

‎source/reference/method/MongoDBDatabase-createEncryptedCollection.txt

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
==============================================
2+
MongoDB\\Database::createEncryptedCollection()
3+
==============================================
4+
5+
.. versionadded:: 1.16
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. note::
16+
17+
Queryable Encryption is in public preview and available for evaluation
18+
purposes. It is not yet recommended for production deployments as breaking
19+
changes may be introduced. See the
20+
`Queryable Encryption Preview <https://www.mongodb.com/blog/post/mongodb-releases-queryable-encryption-preview/>`_
21+
blog post for more information.
22+
23+
Definition
24+
----------
25+
26+
.. phpmethod:: MongoDB\\Database::createEncryptedCollection()
27+
28+
Explicitly creates an encrypted collection.
29+
30+
.. code-block:: php
31+
32+
function createEncryptedCollection(string $collectionName, MongoDB\Driver\ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options): array
33+
34+
This method will automatically create data keys for any encrypted fields
35+
where ``keyId`` is ``null``. Data keys will be created using
36+
:php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`
37+
and the provided ``$kmsProvider`` and ``$masterKey`` parameters. A copy of
38+
the modified ``encryptedFields`` option will be returned in addition to the
39+
result from creating the collection.
40+
41+
This method does not affect any auto encryption settings on existing
42+
:phpclass:`MongoDB\\Client` objects. Users must configure auto encryption
43+
after creating the encrypted collection with ``createEncryptedCollection()``.
44+
45+
This method has the following parameters:
46+
47+
.. include:: /includes/apiargs/MongoDBDatabase-method-createEncryptedCollection-param.rst
48+
49+
The ``$options`` parameter supports the same options as
50+
:phpmethod:`MongoDB\\Database::createCollection()`. The ``encryptedFields``
51+
option is required.
52+
53+
Return Values
54+
-------------
55+
56+
A tuple (i.e. two-element array) containing the result document from the
57+
:manual:`create </reference/command/create>` command (an array or object
58+
according to the ``typeMap`` option) and the modified ``encryptedFields``
59+
option.
60+
61+
Errors/Exceptions
62+
-----------------
63+
64+
:phpclass:`MongoDB\\Exception\\CreateEncryptedCollectionException` if any error
65+
is encountered creating data keys or the collection. The original exception and
66+
modified ``encryptedFields`` option can be accessed via the ``getPrevious()``
67+
and ``getEncryptedFields()`` methods, respectively.
68+
69+
.. include:: /includes/extracts/error-invalidargumentexception.rst
70+
71+
Example
72+
-------
73+
74+
The following example creates an encrypted ``users`` collection in the ``test``
75+
database. The ``ssn`` field within the ``users`` collection will be defined as
76+
an encrypted string field.
77+
78+
.. code-block:: php
79+
80+
<?php
81+
82+
// 96-byte master key used to encrypt/decrypt data keys
83+
define('LOCAL_MASTERKEY', '...');
84+
85+
$client = new MongoDB\Client;
86+
87+
$clientEncryption = $client->createClientEncryption([
88+
'keyVaultNamespace' => 'keyvault.datakeys',
89+
'kmsProviders' => [
90+
'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
91+
],
92+
);
93+
94+
[$result, $encryptedFields] = $client->test->createEncryptedCollection(
95+
'users',
96+
$clientEncryption,
97+
'local',
98+
null,
99+
[
100+
'encryptedFields' => [
101+
'fields' => [
102+
['path' => 'ssn', 'bsonType' => 'string', 'keyId' => null],
103+
],
104+
],
105+
]
106+
);
107+
108+
If the encrypted collection was successfully created, ``$result`` will contain
109+
the response document from the ``create`` command and
110+
``$encryptedFields['fields'][0]['keyId']`` will contain a
111+
:php:`MongoDB\\BSON\\Binary <class.mongodb-bson-binary>` object with subtype 4
112+
(i.e. UUID).
113+
114+
The modified ``encryptedFields`` option can then be used to construct a new
115+
:phpclass:`MongoDB\\Client` with auto encryption enabled.
116+
117+
.. code-block:: php
118+
119+
<?php
120+
121+
$encryptedClient = new MongoDB\Client(
122+
null, // Connection string
123+
[], // Additional connection string options
124+
[
125+
'autoEncryption' => [
126+
'keyVaultNamespace' => 'keyvault.datakeys',
127+
'kmsProviders' => [
128+
'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
129+
],
130+
'encryptedFieldsMap' => [
131+
'test.users' => $encryptedFields,
132+
],
133+
],
134+
]
135+
);
136+
137+
See Also
138+
--------
139+
140+
- :phpmethod:`MongoDB\\Database::createCollection()`
141+
- :phpmethod:`MongoDB\\Client::createClientEncryption()`
142+
- :php:`MongoDB\\Driver\\ClientEncryption::createDataKey() <mongodb-driver-clientencryption.createdatakey>`
143+
- :manual:`create </reference/command/create>` command reference in the MongoDB
144+
manual

0 commit comments

Comments
 (0)