DRIVERS-2539 Replace DataKeyOpts with masterKey in `CreateEncrypt…

…edCollection` (#1377)

* add CEC test case with `aws`

* replace CEC DataKeyOpts with masterKey

* update Last Modified and Changelog

* add aws to clientEncryptionOptions in test

source/client-side-encryption/client-side-encryption.rst

@@ -4,7 +4,7 @@ Client Side Encryption
 
 :Status: Accepted
 :Minimum Server Version: 4.2 (CSFLE), 6.0 (Queryable Encryption)
-:Last Modified: 2023-01-31
+:Last Modified: 2023-02-01
 :Version: 1.12.0
 
 .. _lmc-c-api: https://github.com/mongodb/libmongocrypt/blob/master/src/mongocrypt.h.in
@@ -952,9 +952,10 @@ Create Encrypted Collection Helper
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To support automatic generation of encryption data keys, a helper
-`CreateEncryptedCollection(CE, database, collName, collOpts, kmsProvider, dkOpts)`
+`CreateEncryptedCollection(CE, database, collName, collOpts, kmsProvider, masterKey)`
 is defined, where `CE` is a ClientEncryption_ object, `kmsProvider` is a
-KMSProviderName_ and `dkOpts` is a DataKeyOpts_. It has the following behavior:
+KMSProviderName_ and `masterKey` is equivalent to the `masterKey` defined in DataKeyOpts_.
+It has the following behavior:
 
 - If `collOpts` contains an ``"encryptedFields"`` property, then `EF` is the value
   of that property.  Otherwise, report an error that there are no ``encryptedFields``
@@ -969,6 +970,7 @@ KMSProviderName_ and `dkOpts` is a DataKeyOpts_. It has the following behavior:
     - Otherwise, if `F` has a ``"keyId"`` named element `K` and `K` is a
       ``null`` value:
 
+      - Create a DataKeyOpts_ named `dkOpts` with the `masterKey` argument.
       - Let `D` be the result of ``CE.createDataKey(kmsProvider, dkOpts)``.
       - If generating `D` resulted in an error `E`, the entire
         `CreateEncryptedCollection` must now fail with error `E`. Return the
@@ -1036,7 +1038,7 @@ ClientEncryption
       // create a collection with encrypted fields, automatically allocating and assigning new data encryption
       // keys. It returns a handle to the new collection, as well as a document consisting of the generated
       // "encryptedFields" options. Refer to "Create Encrypted Collection Helper"
-      createEncryptedCollection(database: Database, collName: string, collOpts, kmsProvider: KMSProviderName, dkOpts: DataKeyOpts): [Collection, Document];
+      createEncryptedCollection(database: Database, collName: string, collOpts, kmsProvider: KMSProviderName, masterKey: Optional<Document>): [Collection, Document];
 
       // Creates a new key document and inserts into the key vault collection.
       // Returns the _id of the created document as a UUID (BSON binary subtype 0x04).
@@ -2712,6 +2714,7 @@ explicit session parameter as described in the
 Changelog
 =========
 
+:2023-02-01: Replace ``DataKeyOpts`` with ``masterKey`` in ``createEncryptedCollection``.
 :2023-01-31: ``createEncryptedCollection`` does not check AutoEncryptionOptions for the encryptedFieldsMap.
 :2023-01-30: Return ``encryptedFields`` on ``CreateCollection`` error.
 :2023-01-26: Use GetEncryptedFields_ in more helpers.

source/client-side-encryption/tests/README.rst

@@ -2506,9 +2506,24 @@ options::
       keyVaultNamespace: "keyvault.datakeys",
       kmsProviders: {
          local: { key: base64Decode(LOCAL_MASTERKEY) },
+         aws: {
+            accessKeyId: <set from environment>,
+            secretAccessKey: <set from environment>
+         },
       },
    }
 
+Run each test case with each of these KMS providers: ``aws``, ``local``. The KMS provider name is referred to as ``kmsProvider``.
+When testing ``aws``, use the following as the ``masterKey`` option:
+
+.. code:: javascript
+
+   {
+      region: "us-east-1",
+      key: "arn:aws:kms:us-east-1:579766882180:key/89fcc2c4-08b0-4bd9-9f25-e30687b580d0"
+   }
+
+When testing ``local``, set ``masterKey`` to ``null``.
 
 Case 1: Simple Creation and Validation
 ``````````````````````````````````````
@@ -2535,7 +2550,7 @@ rejects an attempt to insert plaintext in an encrypted fields.
          }
       }
 
-2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, "local", null)`
+2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, kmsProvider, masterKey)`
    to obtain a new collection `Coll`. Expect success.
 3. Attempt to insert the following document into `Coll`::
 
@@ -2559,7 +2574,7 @@ missing.
 
 1. Create a new empty create-collection options `Opts`. (i.e. it must not
    contain any ``encryptedFields`` options.)
-2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, "local", null)`.
+2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, kmsProvider, masterKey)`.
 3. Expect the invocation to fail with an error indicating that
    ``encryptedFields`` is not defined for the collection, and expect that no
    collection was created within the database. It would be *incorrect* for
@@ -2592,7 +2607,7 @@ when attempting to create a collection with such invalid settings.
          }
       }
 
-2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, "local", null)`.
+2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, kmsProvider, masterKey)`.
 3. Expect an error from the server indicating a validation error at
    ``create.encryptedFields.fields.keyId``, which must be a UUID and not a
    boolean value.
@@ -2615,7 +2630,7 @@ with encrypted value.
          }
       }
 
-2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, "local", null)`
+2. Invoke `CreateEncryptedCollection(CE, DB, "testing1", Opts, kmsProvider, masterKey)`
    to obtain a new collection `Coll` and data key `key1`. Expect success.
 3. Use `CE` to explicitly encrypt the string "123-45-6789" using
    algorithm `Unindexed` and data key `key1`. Refer result as `encryptedPayload`.