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, SSH keys, and combination files for MongoDB test purposes.

PLEASE NOTE These certificates and keys 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
• SSH key pairs for SSH access

Characteristics of these files are specified in a YAML file.

Running mongotls

Command options:

• -f <config-file>: specify the YAML configuration file to be used. The default filename is mongodb-tls.yaml.
• -erase: All files in the specified directories are removed before generating new files, Default behavior is to not erase files.
• -version: print version and exit.
• -help: print a summary of the available options.

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.

If a particular file specification has a directory path prefixed to it, then that directory path will be used instead of the defaults from the directories section.

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) -- the extension used when creating certificate files or combo files
• sshkey: <ext> (default blank) -- the extension used when creating private SSH key files
• sshpub: <ext> (dfault pub) -- the extension used when creating public SSH key files

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. The YAML key can include a slash character, indicating a specified directory path for the files.

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.
• rsabits -- size of the RSA private key, default is 2048.
• valid: -- number of days before certificate expires. Default is 90.
• 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.

keyfiles

The keyfiles section specifies keyfiles to be generated. For example, to generate a keyfile with filename "mykeyfile.key":

keyfiles: 
  mykeyfile:

sshkeypairs

The sshkeypairs section generates SSH private/public key pair in files, where the public key has a ".pub" extension. The optional "rsabits: N" specifies the RSA keylength (default 2048). For example, the following generates keypairs named "spencer.brown" and "joe.smith" (4096-bit RSA key) in the "tls/clients" directory.

sshkeypairs:
  tls/clients/spencer.brown:
  tls/clients/joe.smith:
    rsabits: 4096

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. Again, the filenames can include slash separators indicating specific directory paths.