Uploaded image for project: 'MongoDB Shell'
  1. MongoDB Shell
  2. MONGOSH-1316

Automatically create Queryable Encryption keys

    • 3
    • Iteration Unicornfish, Iteration Velvet Crab
    • Needed
    • Hide

      Description:
      With this change, mongosh surfaces the createEncryptedCollection helper on both Database and ClientEncryption instances. The createEncryptedCollection helper will 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 list of the generated "encryptedFields".

      Once a connection is established with relevant Queryable encryption options, the helper can be accessed directly on the Database instance `db` or using the ClientEncryption instance `db.getClientEncryption()`.

      Signatures:
      1. db.createEncryptedCollection(collname, collectionOptions)
      2. db.getMongo().getClientEncryption(databasename, collname, collectionOptions)
      // Note-1: unlike the option 1, in option 2 we need to provide the name of the database
      // Note-2: collectionOptions must include provider and createCollectionOptions keys.

      Example:
      const keyVaultNamespace = "keyvault.namespace";
      const kmsProviderName = "valid-kms-provider-string" // local, aws, etc;
      const secureClient = Mongo("uri", {
      keyVaultNamespace: keyVaultNamespace,
      kmsProviders: { [kmsProvider]:

      { ...kmsProvideroptions }

      }
      });
      const secureDB = secureClient.getDB("some-database");

      // Using Database instance
      secureDB.createEncryptedCollection("some-collection", {
      provider: kmsProviderName, // required
      createCollectionOptions: { // required
      encryptedFields: {
      fields: [

      { path: "field-name", bsonType: "valid-bson-type", keyId: null }

      ]
      }
      },
      masterKey:

      { // optional, needed only if kms provider is Azure, GCP or AWS ... }
      });

      // or using ClientEncryption instance
      secureClient.getClientEncryption().createEncryptedCollection("some-database", "some-collection", {
      provider: kmsProviderName, // required
      createCollectionOptions: { // required
      encryptedFields: {
      fields: [{ path: "field-name", bsonType: "valid-bson-type", keyId: null }]
      }
      },
      masterKey: { // optional, needed only if kms provider is Azure, GCP or AWS ... }

      });

      Required Changes:
      1. https://www.mongodb.com/docs/manual/reference/method/#database : This page should add Database.createEncryptedCollection method to the list.
      2. https://www.mongodb.com/docs/mongodb-shell/reference/methods/#database-methods : This page should add Database.createEncryptedCollection method to the list.
      3. Database.createEncryptedCollection accepts two parameters

      • first is the name of the collection
      • second is collection creation options which is similar to Database.createCollection options but should definitely include two keys
      • provider: the name of the kms provider
      • createCollectionOptions: an object that should contain a list of fields to be encrypted under the path "encryptedFields.fields"
      • masterKey: An optional object specifying how to get the master key when kms provider is either AWS, GCP or Azure
        4. https://www.mongodb.com/docs/manual/reference/method/#client-side-field-level-encryption : This page should add ClientEncryption.createEncryptedCollection method
        5. https://www.mongodb.com/docs/mongodb-shell/reference/methods/#client-side-field-level-encryption-methods : This page should add ClientEncryption.createEncryptedCollection method
        6. ClientEncryption.createEncryptedCollection accepts three parameters
      • first is the name of the database
      • second is the name of the collection
      • third is collection creation options which is similar to Database.createCollection options but should definitely include two keys
      • provider: the name of the kms provider
      • createCollectionOptions: an object that should contain a list of fields to be encrypted under the path "encryptedFields.fields"
      • masterKey: An optional object specifying how to get the master key when kms provider is either AWS, GCP or Azure
      Show
      Description: With this change, mongosh surfaces the createEncryptedCollection helper on both Database and ClientEncryption instances. The createEncryptedCollection helper will 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 list of the generated "encryptedFields". Once a connection is established with relevant Queryable encryption options, the helper can be accessed directly on the Database instance `db` or using the ClientEncryption instance `db.getClientEncryption()`. Signatures: 1. db.createEncryptedCollection(collname, collectionOptions) 2. db.getMongo().getClientEncryption(databasename, collname, collectionOptions) // Note-1: unlike the option 1, in option 2 we need to provide the name of the database // Note-2: collectionOptions must include provider and createCollectionOptions keys. Example: const keyVaultNamespace = "keyvault.namespace"; const kmsProviderName = "valid-kms-provider-string" // local, aws, etc; const secureClient = Mongo("uri", { keyVaultNamespace: keyVaultNamespace, kmsProviders: { [kmsProvider] : { ...kmsProvideroptions } } }); const secureDB = secureClient.getDB("some-database"); // Using Database instance secureDB.createEncryptedCollection("some-collection", { provider: kmsProviderName, // required createCollectionOptions: { // required encryptedFields: { fields: [ { path: "field-name", bsonType: "valid-bson-type", keyId: null } ] } }, masterKey: { // optional, needed only if kms provider is Azure, GCP or AWS ... } }); // or using ClientEncryption instance secureClient.getClientEncryption().createEncryptedCollection("some-database", "some-collection", { provider: kmsProviderName, // required createCollectionOptions: { // required encryptedFields: { fields: [{ path: "field-name", bsonType: "valid-bson-type", keyId: null }] } }, masterKey: { // optional, needed only if kms provider is Azure, GCP or AWS ... } }); Required Changes: 1. https://www.mongodb.com/docs/manual/reference/method/#database : This page should add Database.createEncryptedCollection method to the list. 2. https://www.mongodb.com/docs/mongodb-shell/reference/methods/#database-methods : This page should add Database.createEncryptedCollection method to the list. 3. Database.createEncryptedCollection accepts two parameters first is the name of the collection second is collection creation options which is similar to Database.createCollection options but should definitely include two keys provider: the name of the kms provider createCollectionOptions: an object that should contain a list of fields to be encrypted under the path "encryptedFields.fields" masterKey: An optional object specifying how to get the master key when kms provider is either AWS, GCP or Azure 4. https://www.mongodb.com/docs/manual/reference/method/#client-side-field-level-encryption : This page should add ClientEncryption.createEncryptedCollection method 5. https://www.mongodb.com/docs/mongodb-shell/reference/methods/#client-side-field-level-encryption-methods : This page should add ClientEncryption.createEncryptedCollection method 6. ClientEncryption.createEncryptedCollection accepts three parameters first is the name of the database second is the name of the collection third is collection creation options which is similar to Database.createCollection options but should definitely include two keys provider: the name of the kms provider createCollectionOptions: an object that should contain a list of fields to be encrypted under the path "encryptedFields.fields" masterKey: An optional object specifying how to get the master key when kms provider is either AWS, GCP or Azure

      We should expose this feature from NODE-4433 once the driver implements it.

            Assignee:
            himanshu.singh@mongodb.com Himanshu Singh
            Reporter:
            anna.henningsen@mongodb.com Anna Henningsen
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: