PHPLIB-492: Create tutorial for client side encryption #716
Conversation
docs/tutorial/fle.txt
Outdated
|
|
||
| Auto encryption is an enterprise only feature. | ||
|
|
||
| The following example assumes the key and schema have already been created in |
There was a problem hiding this comment.
Should there be an example of creating the key and schema? I assume this differs from the second example where we use a schemaMap.
There was a problem hiding this comment.
Added key and schema creation using $jsonValidator to the example. I would also suggest that the example in the Java documentation is improved the same way, as that's where this example was copied from.
docs/tutorial/fle.txt
Outdated
| use MongoDB\Driver\ClientEncryption; | ||
|
|
||
| $localKey = new Binary('<binary key data>', Binary::TYPE_GENERIC); | ||
| $keyId = new Binary('<UUID of encryption key', Binary::TYPE_UUID); |
There was a problem hiding this comment.
Should we add a comment above this to make the connection to ClientEncryption::createDataKey()? I believe we only show that being called in the previous schemaMap example, which is also for the enterprise, automatic encryption. That all seems a bit odd, as ClientEncryption seems like it's only useful for the explicit encryption but we end up using createDataKey alone for automatic encryption as well.
There was a problem hiding this comment.
I've changed the example and added creating an encryption key using createDataKey, so there is no confusion as to where this is coming from. However, this might lead users to believe that they should create a new encryption key anytime they want to encrypt data, which might not be desirable. We may want to address this in the tutorial if we indeed don't recommend doing this.
There was a problem hiding this comment.
@kevinAlbs I assume we don't expect users to create new data keys each time they need to invoke encryption. Do we expect them to use this method once and then either (a) directly query the key vault collection for future use or (b) save the ID and then hard-code it into their application/environment? I read through most of ClientEncryption and related references to keyId but I don't see much elaboration on this.
@alcaeus in the meantime, perhaps we can just use createDataKey but leave a multi-line comment explaining that users can alternatively fetch a key from the key vault themselves (and will probably want to do so if they've previously created a data key suitable for use).
There was a problem hiding this comment.
I assume we don't expect users to create new data keys each time they need to invoke encryption.
Yes, but they may be creating keys on the fly as part of their application. E.g. if they're creating a per-user data key.
Do we expect them to use this method once and then either (a) directly query the key vault collection for future use or (b) save the ID and then hard-code it into their application/environment?
That is one way. But they may also associate one or more keyAltNames based on other data (e.g. a user identifier) so would not need to query or hard code the ID.
There was a problem hiding this comment.
alternative name is a good point. I've added an example to show how this is used and also explained that encryption keys shouldn't be created every time a value is encrypted. I hope this clarifies the solution.
| key. To reference keys in your software, you can use the keyAltName attribute | ||
| specified when creating the key. The following example creates an encryption key | ||
| with an alternative name, which could be done when deploying the application. | ||
| The software then emcrypts data by referencing the key by its alternative name. |
There was a problem hiding this comment.
Ah, missed this earlier but "emcrypts" is a typo. May want to run spell-check on this file if you've not already.
|
Merged manually in 02bd585. |
https://jira.mongodb.org/browse/PHPLIB-492
https://jira.mongodb.org/browse/PHPLIB-517