Configure Transport Layer Security (TLS)

Overview

In this guide, you can learn how to use the Transport Layer Security (TLS) protocol to secure your connection to a MongoDB deployment.

To connect to a MongoDB deployment using TLS, you must perform the following steps:

• Enable a TLS connection in Mongo::Client.

• Specify the client TLS certificate.

• Specify the Certificate Authority (CA) certificate to verify the server's TLS certificate.

To learn how to configure your MongoDB deployment for TLS, see the TLS configuration guide in the MongoDB Server manual.

Enable TLS

You can enable TLS for the connection to your MongoDB deployment in the following ways:

• Set the ssl option to true in a new Mongo:Client object.

• Set the tls option to true in your connection string.

client = Mongo::Client.new(["<hostname>:<port>"], 
  ssl: true,
  ssl_cert: 'path/to/client.crt',
  ssl_key: 'path/to/client.key',
  ssl_ca_cert: 'path/to/ca.crt'
)

client = Mongo::Client.new(["<hostname>:<port>"],
  ssl: true,
  ssl_cert: 'path/to/client.pem',
  ssl_key: 'path/to/client.pem',
  ssl_ca_cert: 'path/to/ca.crt',
)

client = Mongo::Client.new(
  "mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=path%2fto%2fclient.pem&tlsCAFile=path%2fto%2fca.crt")

Specify Client TLS Certificates

The Ruby driver provides multiple options for you to specify the TLS certificate, key, and CA certificate with different data or object types.

Modify the TLS Context

If your TLS configuration requires customization, you can set TLS context hooks by adding a native Ruby Proc object to the Mongo.tls_context_hooks array. Add the Proc object to the array before you create any Mongo::Client instances.

The following code example enables the AES256-SHA cipher as the only cipher to be used for TLS:

Mongo.tls_context_hooks.push(
  Proc.new { |context|
    context.ciphers = ["AES256-SHA"]
  }
)

The Ruby driver TLS context options are based on native Ruby handling of SSL. To learn more about the TLS context options available, see the Ruby documentation for SSLContext.

OCSP Verification

If the certificate provided by the server contains an OCSP endpoint URI, the driver issues an Online Certificate Status Protocol (OCSP) request to the specified endpoint by default to verify the validity of the certificate.

To disable the OCSP endpoint check, set the :ssl_verify_ocsp_endpoint Ruby option to false or set the tlsDisableOCSPEndpointCheck URI option to true when creating a client.

Allow Insecure TLS

When TLS is enabled, the Ruby driver automatically verifies the certificate that the server presents. When testing your code, you can disable this verification. This is known as insecure TLS.

When insecure TLS is enabled, the driver requires only that the server present an X.509 certificate. The driver accepts a certificate even if any of the following are true:

• The hostname of the server and the subject name (or subject alternative name) on the certificate don't match.

• The certificate is expired or not yet valid.

• The certificate doesn't have a trusted root certificate in the chain.

• The certificate purpose isn't valid for server identification.

To enable insecure TLS, set the sslVerify client option or the tlsInsecure URI option to true:

client = Mongo::Client.new(["<hostname>:<port>"],
  ssl: true,
  ssl_verify: false
)

client = Mongo::Client.new('mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true')

You can similarly set the following options to disable verification for the certificate or hostname:

API Documentation

For more information about any of the types and methods discussed in this guide, see the following API documentation:

• Mongo::Client

• tls_context_hooks