mongodb-tls-certs

README

mongotls - easily generate TLS certificates and keys for MongoDB test environments

Overview

THe mongotls command allows you to generate TLS certificates, keys, keyfiles, and combination files for MongoDB test purposes.

PLEASE NOTE These certificates are not intended for production use or for any deployment that requires security controls.

Specifically, the command supports generating:

• Root CA certificates
• Intermediate CA certificates
• Server certificates
• Client certificates
• Signing certificates for OCSP responders
• Combination files, such as for CA certificate chains or for MongoDB certificateKeyFile files that include both the private key and certificate for a MongoDB server
• Keyfiles for MongoDB replica sets or for MongoDB local encryption-at-rest keys

Characteristics of these files are specified in a YAML file.

Running mongotls

The only option (other than --help) for the mongotls command is -f <config-file> to point to the YAML configuration file to be used. The default filename is mongodb-tls.yaml.

Example YAML configuration file

See the example file included with this project, which includes extensive comments. You may not need to explanation below; you may be able to copy and customize the example file based on the comments.

YAML file specifications

The YAML file has several sections: directories, extensions, certificates, combos, and keyfiles. Each is described separately below.

directories

The directories section has two possible YAML keys underneath it:

• public: <directory-path> (default tls) -- the directory path for files containing only TLS certificates, These files are created with 0644 permissions.
• private: <directory-path. (default tls/private) -- the directory path for files containing keys. These files are created with 0600 permissions.

Example:

directories:
  public: /etc/ssl/certificates
  private: /etc/ssl/tls/private

extensions

The extensions section has two possible YAML keys underneath it:

• key: <ext> (default key) -- the filename extension used when creating files containing only keys
• certificate: <ext> (default pem)

Example:

extensions:
  key: priv
  certificate: cer

subject

The subject section has defaults for the subject name components of the generated certificates. Any certificate that does not specify an O, OU, or CM will receive the default component.

• O:
• OU:
• CN:

certificates

The certificates section has one YAML key underneath it for each TLS private key and certificate generated by the command. The YAML key becomes the filename of each file, with the file extensions specified by the extensions section.

For example, the following generates a root CA certificate and key, and creates files called tls/foobar.key and tls/private/foobar.pem (assuming default values for the directories and extensions sections).

certificates:
  root-ca:
    type: rootCA
    # other options...

The YAML keys underneath the name of the certificate/key are the following:

• type: -- can be rootCA, intermediateCA, server, client, or OCSPSigning.
• subject: -- beginning of a section for the subject name. Can contain sub-keys O:, OU: and/or CN:.
• issuer: -- name of the CA to sign this certificate.
• hosts: -- list of hostnames and/or IP addresses for the SAN field of a server certificate.

combos

The combos section specifies creation of files containing multiple keys and certificates. Each YAML key underneath it is the name of a file to be created, following by a list of names of files to be included in that file.