Skip to content

Commit 11e7964

Browse files
jmikolajmikola
committed
PHPLIB-1176: Various improvements for In-Use Encryption tutorial
Adds additional non-enterprise examples from the PyMongo tutorial: "Explicit Encryption with Automatic Decryption" and "Explicit Queryable Encryption". Examples are now broken out into separate files, which can be tested via ExamplesTest. Renames "Client-Side Encryption" to "In-Use Encryption" (PHPLIB-997). This will warrant adding a redirect from "/tutorial/client-side-encryption/" to "/tutorial/encryption/" in the related docs-php-library project. Also adds docs for crypt_shared and mongocryptd (PHPLIB-985).
1 parent b8af536 commit 11e7964

14 files changed

+818
-369
lines changed

‎docs/examples/create_data_key.php

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?php
2+
3+
use MongoDB\BSON\Binary;
4+
use MongoDB\Client;
5+
use MongoDB\Driver\ClientEncryption;
6+
7+
require __DIR__ . '/../../vendor/autoload.php';
8+
9+
$uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
10+
11+
// Generate a secure local key to use for this script
12+
$localKey = new Binary(random_bytes(96));
13+
14+
/* Create a client with no encryption options. Additionally, create a
15+
* ClientEncryption object to manage data keys. */
16+
$client = new Client($uri);
17+
18+
$clientEncryption = $client->createClientEncryption([
19+
'keyVaultNamespace' => 'encryption.__keyVault',
20+
'kmsProviders' => [
21+
'local' => ['key' => $localKey],
22+
],
23+
]);
24+
25+
/* Create an encryption key. This would typically be done during application
26+
* deployment. To store the key ID for later use, you can use serialize() or
27+
* var_export(). */
28+
$keyId = $clientEncryption->createDataKey('local');
29+
30+
print_r($keyId);
31+
32+
// Encrypt a value using the key that was just created
33+
$encryptedValue = $clientEncryption->encrypt('mySecret', [
34+
'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
35+
'keyAltName' => 'myDataKey',
36+
]);
37+
38+
print_r($encryptedValue);

‎docs/examples/csfle-automatic_encryption-local_schema.php

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<?php
2+
3+
use MongoDB\BSON\Binary;
4+
use MongoDB\Client;
5+
use MongoDB\Driver\ClientEncryption;
6+
7+
require __DIR__ . '/../../vendor/autoload.php';
8+
9+
$uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
10+
11+
// Generate a secure local key to use for this script
12+
$localKey = new Binary(random_bytes(96));
13+
14+
/* Create a client with no encryption options. Additionally, create a
15+
* ClientEncryption object to manage data keys. */
16+
$client = new Client($uri);
17+
18+
$clientEncryption = $client->createClientEncryption([
19+
'keyVaultNamespace' => 'encryption.__keyVault',
20+
'kmsProviders' => [
21+
'local' => ['key' => $localKey],
22+
],
23+
]);
24+
25+
/* Create an encryption key. Alternatively, this key ID could be read from a
26+
* configuration file. */
27+
$keyId = $clientEncryption->createDataKey('local');
28+
29+
// Create a client with automatic encryption enabled
30+
$autoEncryptionOpts = [
31+
'keyVaultNamespace' => 'encryption.__keyVault',
32+
'kmsProviders' => ['local' => ['key' => $localKey]],
33+
];
34+
35+
$encryptedClient = new Client($uri, [], ['autoEncryption' => $autoEncryptionOpts]);
36+
37+
/* Drop and create the collection. Specify a validator option to enforce a
38+
* server-side JSON schema. */
39+
$collectionOpts = [
40+
'validator' => [
41+
'$jsonSchema' => [
42+
'bsonType' => 'object',
43+
'properties' => [
44+
'encryptedField' => [
45+
'encrypt' => [
46+
'keyId' => [$keyId],
47+
'bsonType' => 'string',
48+
'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
49+
],
50+
],
51+
],
52+
],
53+
],
54+
];
55+
56+
$encryptedClient->selectDatabase('test')->dropCollection('coll');
57+
$encryptedClient->selectDatabase('test')->createCollection('coll', $collectionOpts);
58+
$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
59+
60+
/* Using the encrypted client, insert and find a document. The encrypted field
61+
* will be automatically encrypted and decrypted. */
62+
$encryptedCollection->insertOne([
63+
'_id' => 1,
64+
'encryptedField' => 'mySecret',
65+
]);
66+
67+
print_r($encryptedCollection->findOne(['_id' => 1]));
68+
69+
/* Using the client configured without encryption, find the same document and
70+
* observe that the field is not automatically decrypted. Additionally, the JSON
71+
* schema will prohibit inserting a document with an unencrypted field value. */
72+
$unencryptedCollection = $client->selectCollection('test', 'coll');
73+
74+
print_r($unencryptedCollection->findOne(['_id' => 1]));

‎docs/examples/csfle-automatic_encryption-server_side_schema.php

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<?php
2+
3+
use MongoDB\BSON\Binary;
4+
use MongoDB\Client;
5+
use MongoDB\Driver\ClientEncryption;
6+
7+
require __DIR__ . '/../../vendor/autoload.php';
8+
9+
$uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
10+
11+
// Generate a secure local key to use for this script
12+
$localKey = new Binary(random_bytes(96));
13+
14+
/* Create a client with no encryption options. Additionally, create a
15+
* ClientEncryption object to manage data keys. */
16+
$client = new Client($uri);
17+
18+
$clientEncryption = $client->createClientEncryption([
19+
'keyVaultNamespace' => 'encryption.__keyVault',
20+
'kmsProviders' => [
21+
'local' => ['key' => $localKey],
22+
],
23+
]);
24+
25+
/* Create an encryption key. Alternatively, this key ID could be read from a
26+
* configuration file. */
27+
$keyId = $clientEncryption->createDataKey('local');
28+
29+
// Create a client with automatic encryption enabled
30+
$autoEncryptionOpts = [
31+
'keyVaultNamespace' => 'encryption.__keyVault',
32+
'kmsProviders' => ['local' => ['key' => $localKey]],
33+
];
34+
35+
$encryptedClient = new Client($uri, [], ['autoEncryption' => $autoEncryptionOpts]);
36+
37+
/* Drop and create the collection. Specify a validator option to enforce a
38+
* server-side JSON schema. */
39+
$collectionOpts = [
40+
'validator' => [
41+
'$jsonSchema' => [
42+
'bsonType' => 'object',
43+
'properties' => [
44+
'encryptedField' => [
45+
'encrypt' => [
46+
'keyId' => [$keyId],
47+
'bsonType' => 'string',
48+
'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
49+
],
50+
],
51+
],
52+
],
53+
],
54+
];
55+
56+
$encryptedClient->selectDatabase('test')->dropCollection('coll');
57+
$encryptedClient->selectDatabase('test')->createCollection('coll', $collectionOpts);
58+
$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
59+
60+
/* Using the encrypted client, insert and find a document. The encrypted field
61+
* will be automatically encrypted and decrypted. */
62+
$encryptedCollection->insertOne([
63+
'_id' => 1,
64+
'encryptedField' => 'mySecret',
65+
]);
66+
67+
print_r($encryptedCollection->findOne(['_id' => 1]));
68+
69+
/* Using the client configured without encryption, find the same document and
70+
* observe that the field is not automatically decrypted. Additionally, the JSON
71+
* schema will prohibit inserting a document with an unencrypted field value. */
72+
$unencryptedCollection = $client->selectCollection('test', 'coll');
73+
74+
print_r($unencryptedCollection->findOne(['_id' => 1]));

‎docs/examples/csfle-explicit_encryption.php

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<?php
2+
3+
use MongoDB\BSON\Binary;
4+
use MongoDB\Client;
5+
use MongoDB\Driver\ClientEncryption;
6+
7+
require __DIR__ . '/../../vendor/autoload.php';
8+
9+
$uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
10+
11+
// Generate a secure local key to use for this script
12+
$localKey = new Binary(random_bytes(96));
13+
14+
/* Create a client with no encryption options. Additionally, create a
15+
* ClientEncryption object to manage data keys. */
16+
$client = new Client($uri);
17+
18+
$clientEncryption = $client->createClientEncryption([
19+
'keyVaultNamespace' => 'encryption.__keyVault',
20+
'kmsProviders' => [
21+
'local' => ['key' => $localKey],
22+
],
23+
]);
24+
25+
/* Create an encryption key. Alternatively, this key ID could be read from a
26+
* configuration file. */
27+
$keyId = $clientEncryption->createDataKey('local');
28+
29+
// Select and drop a collection to use for this example
30+
$collection = $client->selectCollection('test', 'coll');
31+
$collection->drop();
32+
33+
// Insert a document with a manually encrypted field
34+
$encryptedValue = $clientEncryption->encrypt('mySecret', [
35+
'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
36+
'keyId' => $keyId,
37+
]);
38+
39+
$collection->insertOne(['encryptedField' => $encryptedValue]);
40+
41+
/* Query for the document. The field will not be automatically decrypted
42+
* because the client was not configured with an autoEncryption driver option.
43+
* Manually decrypt the field value using the ClientEncryption object. */
44+
$document = $collection->findOne();
45+
46+
print_r($document->encryptedField);
47+
print_r($clientEncryption->decrypt($document->encryptedField));

‎docs/examples/csfle-explicit_encryption_automatic_decryption.php

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<?php
2+
3+
use MongoDB\BSON\Binary;
4+
use MongoDB\Client;
5+
use MongoDB\Driver\ClientEncryption;
6+
7+
require __DIR__ . '/../../vendor/autoload.php';
8+
9+
$uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
10+
11+
// Generate a secure local key to use for this script
12+
$localKey = new Binary(random_bytes(96));
13+
14+
// Create a client with automatic encryption disabled
15+
$autoEncryptionOpts = [
16+
'keyVaultNamespace' => 'encryption.__keyVault',
17+
'kmsProviders' => ['local' => ['key' => $localKey]],
18+
'bypassAutoEncryption' => true,
19+
];
20+
21+
$client = new Client($uri, [], ['autoEncryption' => $autoEncryptionOpts]);
22+
23+
// Create a ClientEncryption object to manage data keys
24+
$clientEncryption = $client->createClientEncryption([
25+
'keyVaultNamespace' => 'encryption.__keyVault',
26+
'kmsProviders' => [
27+
'local' => ['key' => $localKey],
28+
],
29+
]);
30+
31+
/* Create an encryption key. Alternatively, this key ID could be read from a
32+
* configuration file. */
33+
$keyId = $clientEncryption->createDataKey('local');
34+
35+
// Select and drop a collection to use for this example
36+
$collection = $client->selectCollection('test', 'coll');
37+
$collection->drop();
38+
39+
// Insert a document with a manually encrypted field
40+
$encryptedValue = $clientEncryption->encrypt('mySecret', [
41+
'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
42+
'keyId' => $keyId,
43+
]);
44+
45+
$collection->insertOne(['encryptedField' => $encryptedValue]);
46+
47+
/* Query for the document. The field will still be automatically decrypted
48+
* because the client was configured with an autoEncryption driver option. */
49+
$document = $collection->findOne();
50+
51+
print_r($document->encryptedField);

‎docs/examples/key_alt_name.php

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
use MongoDB\BSON\Binary;
4+
use MongoDB\Client;
5+
use MongoDB\Driver\ClientEncryption;
6+
7+
require __DIR__ . '/../../vendor/autoload.php';
8+
9+
$uri = getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/';
10+
11+
// Generate a secure local key to use for this script
12+
$localKey = new Binary(random_bytes(96));
13+
14+
/* Create a client with no encryption options. Additionally, create a
15+
* ClientEncryption object to manage data keys. */
16+
$client = new Client($uri);
17+
18+
$clientEncryption = $client->createClientEncryption([
19+
'keyVaultNamespace' => 'encryption.__keyVault',
20+
'kmsProviders' => [
21+
'local' => ['key' => $localKey],
22+
],
23+
]);
24+
25+
// Create an encryption key with an alternate name
26+
$clientEncryption->createDataKey('local', ['keyAltNames' => ['myDataKey']]);
27+
28+
// Encrypt a value, using the "keyAltName" option instead of "keyId"
29+
$encryptedValue = $clientEncryption->encrypt('mySecret', [
30+
'algorithm' => ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC,
31+
'keyAltName' => 'myDataKey',
32+
]);
33+
34+
print_r($encryptedValue);

0 commit comments

Comments
 (0)