Client-Side Encryption

libmongocrypt

Libmongocrypt is a C library used by the driver for client-side encryption. To use client-side encryption, you must install the libmongocrypt library on the machine running your Ruby program.

The easiest way to install this library is to install libmongocrypt-helper as follows:

gem install libmongocrypt-helper --pre

The version number of libmongocrypt-helper is the version of included libmongocrypt followed by the release number, e.g. 1.3.2.r1. Because Ruby considers any letters in the version number to indicate a pre-release version, the --pre flag is needed.

The driver will automatically load libmongocrypt-helper - no further configuration is needed.

Alternatively you can download a pre-built binary distribution of libmongocrypt and manually place the required shared object on your computer, as follows:

• Download a tarball of all libmongocrypt variations here.

• Extract the file you downloaded. You will see a list of directories, each corresponding to an operating system. Find the directory that matches your operating system and open it.

• Inside that folder, open the folder called "nocrypto." In either the lib or lb64 folder, you will find the libmongocrypt.so or libmongocrypt.dylib or libmongocrypt.dll file, depending on your OS.

• Move that file to wherever you want to keep it on your machine. You may delete the other files included in the tarball.

To build the binary from source:

• Follow the instructions in the README in the libmongocrypt GitHub repo.

Once you have the libmongocrypt binary on your machine, specify the path to the binary using the LIBMONGOCRYPT_PATH environment variable. It is recommended that you add this variable to your rc files. For example:

export LIBMONGOCRYPT_PATH=/path/to/your/libmongocrypt.so

Automatic Encryption Shared Library

The Automatic Encryption Shared Library is a dynamic library that enables your client application to perform automatic encryption. It is only required for automatic encryption, which is an enterprise-only feature. If you only intend to use explicit encryption, you may skip this step. The Automatic Encryption Shared Library provides the same functionality as mongocryptd (see below), but does not require you to spawn another process to perform automatic encryption.

For installation instructions, see the MongoDB manual.

When automatic encryption is enabled, libmongocrypt will look for the shared library in the system library path, or try to load the library from a particular place if :crypt_shared_lib_path option is provided when creating a client. If the library can be loaded, then the driver will not try to spawn mongocryptd daemon. The daemon will be still spawned if the shared library cannot be found.

It is also possible to require using the shared library by passing crypt_shared_lib_required: true option when creating a client. In this case, an error will be raised if the shared library cannot be loaded.

mongocryptd

Mongocryptd is an alternative to the Automatic Encryption Shared Library. Mongocryptd is a daemon that tells the driver which fields to encrypt in a given operation. It is only required for automatic encryption, which is an enterprise-only feature. If you only intend to use explicit encryption, you may skip this step.

Mongocryptd comes pre-packaged with enterprise builds of the MongoDB server (versions 4.2 and newer). For installation instructions, see the MongoDB manual.

In order to configure mongocryptd (for example, which port it listens on or the path used to spawn the daemon), it is necessary to pass different options to the Mongo::Client performing automatic encryption. See the :extra_options section of this tutorial for more information.

Local Master Key

A local master key is a 96-byte binary string. It should be persisted on your machine as an environment variable or in a text file.

Run the following code to generate a local master key using Ruby:

local_master_key = SecureRandom.random_bytes(96)
# => "\xB2\xBE\x8EN\xD4\x14\xC2\x13\xC3..." (a binary blob)

Remote Master Key

It is recommended that you use a remote Key Management Service to create and store your master key. To do so, follow steps of the "Set up a Remote Master Key" in the MongoDB Client-Side Encryption documentation.

For more information about creating a master key, see the Create a Master Key section of the MongoDB manual.

Create a Data Key Using a Local Master Key

If you have created a local master key, you may use it to generate a new data key with the following code snippet:

# A Mongo::Client instance that will be used to connect to the key vault
# collection. Replace the server address with the address of the MongoDB
# server where you would like to store your key vault collection.
key_vault_client = Mongo::Client.new(['localhost:27017'])
client_encryption = Mongo::ClientEncryption.new(
  key_vault_client,
  # Replace with the database and collection names for your key vault collection
  key_vault_namespace: 'encryption.__keyVault',
  kms_providers: {
    local: {
      key: local_master_key
    }
  }
)
data_key_id = client_encryption.create_data_key('local')
# => <BSON::Binary... type=ciphertext...>

See the Local Master Key section for more information about generating a new local master key.

Create a Data Key Using a Remote Master Key

If you have created an AWS KMS master key, note the access key ID and the secret access key of the IAM user that has permissions to use the key. Additionally, note the AWS region and the Amazon Resource Number (ARN) of your master key. You will use that information to generate a data key.

If you have created an Azure master key, note the tenant id, the client id, and the client secret of the application that has permissions to use the key. Additionally, note the key name, key version (if any), and key vault endpoint for your master key. You will use that information to generate a data key.

If you have created a GCP KMS master key, note the email and the private key, and the client secret of the application that has permissions to use the key. Additionally, note the project id, location, key ring, key name, and key version (if any) for your master key. You will use that information to generate a data key.

Please note that GCP private key can be in different formats. Ruby driver supports DER encoded RSA private key as base64 encoded string. For MRI Ruby the driver additionally support PEM encoded RSA private key.

If you have created a master key using a Key Management Interoperability Protocol (KMIP) compatible key management server, note the server host and port, and key id. You will use that information to generate a data key. You may also need certificate authority certificate(s), as well as and your client certificate and private key to authenticate to KMIP server.

# A Mongo::Client instance that will be used to connect to the key vault
# collection. Replace the server address with the address of the MongoDB
# server where you would like to store your key vault collection.
key_vault_client = Mongo::Client.new(['localhost:27017'])
client_encryption = Mongo::ClientEncryption.new(
  key_vault_client,
  # Replace with the database and collection names for your key vault collection
  key_vault_namespace: 'encryption.__keyVault',
  kms_providers: {
    aws: {
      access_key_id: 'IAM-ACCESS-KEY-ID',
      secret_access_key: 'IAM-SECRET-ACCESS-KEY'
    },
    azure: {
      tenant_id: 'AZURE-TENANT-ID',
      client_id: 'AZURE-CLIENT-ID',
      client_secret: 'AZURE-CLIENT-SECRET'
    },
    gcp: {
      email: 'GCP-EMAIL',
      # :private_key value should be GCP private key as base64 encoded
      # DER RSA private key, or PEM RSA private key, if you are using MRI Ruby.
      private_key: 'GCP-PRIVATE-KEY',
    },
    kmip: {
      # KMIP server endpoint may include port.
      endpoint: 'KMIP-SERVER-HOST'
    },
    # TLS options to connect to KMIP server.
    kms_tls_options: {
      kmip: {
        ssl_ca_cert: 'PATH-TO-CA-FILE',
        ssl_cert: 'PATH-TO-CLIENT-CERT-FILE',
        ssl_key: 'PATH-TO-CLIENT-KEY-FILE'
      }
    }
  }
)
aws_data_key_id = client_encryption.create_data_key(
  'aws',
  {
    master_key: {
      region: 'REGION-OF-YOUR-MASTER-KEY',
      key: 'ARN-OF-YOUR-MASTER-KEY'
    }
  }
)
# => <BSON::Binary... type=ciphertext...>
azure_data_key_id = client_encryption.create_data_key(
  'azure',
  {
    master_key: {
      key_vault_endpoint: 'AZURE-KEY-VAULT-ENDPOINT',
      key_name: 'AZURE-KEY-NAME'
    }
  }
)
# => <BSON::Binary... type=ciphertext...>
gcp_data_key_id = client_encryption.create_data_key(
  'gcp',
  {
    master_key: {
      project_id: 'GCP-PROJECT-ID',
      location: 'GCP-LOCATION',
      key_ring: 'GCP-KEY-RING',
      key_name: 'GCP-KEY-NAME',
    }
  }
)
# => <BSON::Binary... type=ciphertext...>

See the Remote Master Key section of this tutorial for more information about generating a new remote master key and finding the information you need to create data keys.

For more information about creating a data key, see the Create a Data Encryption Key section of the MongoDB manual.

For a list of possible KMS TLS options see create client reference. Mongo::ClientEncryption constructor accepts same ssl_ options as Mongo::Client.

:key_vault_client

The key vault client is a Mongo::Client instance that will be used to connect to the MongoDB collection containing your encryption data keys. For example, if your key vault was hosted on a MongoDB instance at localhost:30000:

key_vault_client = Mongo::Client.new(['localhost:30000'])
Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    key_vault_client: key_vault_client,
    # ... (Fill in other options here)
  }
)

If your data keys are stored in the same MongoDB instance that stores your encrypted data, you may leave this option blank, and the top-level client will be used to insert and fetch data keys.

:key_vault_namespace

The key vault namespace is a String in the format "database_name.collection_name", where database_name and collection_name are the name of the database and collection in which you would like to store your data keys. For example, if your data keys are stored in the encryption database in the __keyVault collection:

Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    key_vault_namespace: 'encryption.__keyVault',
    # ... (Fill in other options here)
  }
)

There is no default key vault namespace, and this option must be provided.

:kms_providers

A Hash that contains KMS provider names as keys, and provider options as values.

Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    key_vault_namespace: 'encryption.__keyVault',
    kms_providers: {
      aws: {
        access_key_id: 'IAM-ACCESS-KEY-ID',
        secret_access_key: 'IAM-SECRET-ACCESS-KEY'
      },
      azure: {
        tenant_id: 'AZURE-TENANT-ID',
        client_id: 'AZURE-CLIENT-ID',
        client_secret: 'AZURE-CLIENT-SECRET'
      },
      gcp: {
        email: 'GCP-EMAIL',
        # :private_key value should be GCP private key as base64 encoded
        # DER RSA private key, or PEM RSA private key, if you are using MRI Ruby.
        private_key: 'GCP-PRIVATE-KEY',
      },
      kmip: {
        # KMIP server endpoint may include port.
        endpoint: 'KMIP-SERVER-HOST'
      },
      # TLS options to connect to KMIP server.
      kms_tls_options: {
        kmip: {
          ssl_ca_cert: 'PATH-TO-CA-FILE',
          ssl_cert: 'PATH-TO-CLIENT-CERT-FILE',
          ssl_key: 'PATH-TO-CLIENT-KEY-FILE'
        }
      }
    }
  }
)

The client can retrieve AWS credentials from the environment or from EC2 or ECS metadata endpoints. To retrieve credentials automatically, specify an empty Hash as KMS provider options for AWS:

Mongo::Client.new(['localhost:27017'],
   auto_encryption_options: {
    key_vault_namespace: 'encryption.__keyVault',
    kms_providers: {
      aws: {}
    }
  }
)

See "Automatically Retrieving Credentials" for more detailed information about the credential retrieval.

The client can retrieve GCP credentials from the Google Compute Engine metadata endpoints. To retrieve credentials automatically, specify an empty Hash as KMS provider options for GCP:

Mongo::Client.new(['localhost:27017'],
   auto_encryption_options: {
    key_vault_namespace: 'encryption.__keyVault',
    kms_providers: {
      gcp: {}
    }
  }
)

:kms_tls_options

A Hash that contains KMP provider names as keys, and TLS options to connect to corresponding providers.

Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    key_vault_namespace: 'encryption.__keyVault',
    kms_providers: {
      kmip: {
        endpoint: 'KMIP-SERVER-HOST'
      }
    },
    kms_tls_options: {
      kmip: {
        ssl_ca_cert: 'PATH-TO-CA-FILE',
        ssl_cert: 'PATH-TO-CLIENT-CERT-FILE',
        ssl_key: 'PATH-TO-CLIENT-KEY-FILE'
      }
    }
  }
)

:schema_map

A schema map is a Hash with information about which fields to automatically encrypt and decrypt.

The code snippet at the top of this tutorial demonstrates creating a schema map using a Ruby Hash. While this will work, schema maps can grow quite large and it could be unweildy to include them in your Ruby code. Instead, it is recommended that you store them in a separate JSON (JavaScript Object Notation) file.

Before creating the JSON file, Base64-encode the UUID of the your data key.

Base64.encode64(data_key_id.data)
# => "sr6OTtQUwhPD..." (a base64-encoded string)

Then, create a new JSON file containing your schema map in the format defined by the JSON Schema Draft 4 standard syntax. You can read more about formatting your schema map in the Automatic Encryption Rules section of the MongoDB manual.

{
  "encryption_db.encryption_coll": {
    "properties": {
      "encrypted_field": {
        "encrypt": {
          "keyId": [{
            "$binary": {
              "base64": "YOUR-BASE64-ENCODED-DATA-KEY-ID",
              "subType": "04"
            }
          }],
          "bsonType": "string",
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
        }
      }
    },
    "bsonType": "object"
  }
}

When you intend to use your schema map, convert it to a Ruby Hash using the BSON::ExtJSON module in the bson Ruby gem.

schema_map = BSON::ExtJSON.parse(File.read('/path/to/your/file.json'))
# => { 'encryption_db.encryption_coll' => { ... } }
Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    schema_map: schema_map,
    # ... (Fill in other options here)
  }
)

:schema_map_path

It is also possible to load schema map from a file. Prepare the schema map as described above, save it to file, and then pass path to the file using :schema_map_path option.

Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    schema_map_path: '/path/to/your/file.json',
    # ... (Fill in other options here)
  }
)

:bypass_auto_encryption

The :bypass_auto_encryption option is a Boolean that specifies whether the Mongo::Client should skip encryption when writing to the database. If :bypass_auto_encryption is true, the client will still perform automatic decryption of any previously-encrypted data.

Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    bypass_auto_encryption: true,
    # ... (Fill in other options here)
  }
)

:extra_options

:extra_options is a Hash of options related to spawning mongocryptd. Every option in this Hash has a default value, so it is only necessary to provide the options whose defaults you want to override.

• :mongocryptd_spawn_args - This is an Array<String> containing arguments for spawning mongocryptd. The Ruby driver will pass these arguments to mongocryptd on spawning the daemon. Possible arguments are:

  • "--idleShutdownTimeoutSecs" - The number of seconds mongocryptd must remain idle before it shuts itself down. The default value is 60.

  • "--port" - The port at which mongocryptd will listen for connections. The default is 27020.

• :mongocryptd_uri - The URI that the driver will use to connect to mongocryptd. By default, this is "mongodb://localhost:27020".

• :mongocryptd_spawn_path - The path to the mongocryptd executable. The default is "mongocryptd".

• :mongocryptd_bypass_spawn - A Boolean indicating whether the driver should skip spawning mongocryptd.

For example, if you would like to run mongocryptd on port 30000, provide extra_options as follows:

  Mongo::Client.new(['localhost:27017],
  auto_encryption_options: {
    extra_options: {
      mongocryptd_spawn_args: ['--port=30000'],
      mongocryptd_uri: 'mongodb://localhost:30000',
    }
    # ... (Fill in other options here)
  }
)