Appendix B - OpenSSL Server Certificates for Testing

Disclaimer

This page is provided for testing purposes only and thecertificates are for testing purposes only.

The following tutorial provides some basic steps for creatingtest x.509 certificates:

  • Do not use these certificates for production. Instead, follow yoursecurity policies.
  • For information on OpenSSL, refer to the official OpenSSL docs.Although this tutorial uses OpenSSL, the material should not betaken as an authoritative reference on OpenSSL.

Prerequisite

The procedure outlined on this page uses the test intermediate authoritycertificate and key mongodb-test-ia.crt and mongodb-test-ia.keycreated in Appendix A - OpenSSL CA Certificate for Testing .

Procedure

The following procedure outlines the steps to create test certificatesfor MongoDB servers. For steps to create test certificates for MongoDBclients, see Appendix C - OpenSSL Client Certificates for Testing.

A. Create the OpenSSL Configuration File

  • Create a test configuration file openssl-test-server.cnf foryour server with the following content:
  1. # NOT FOR PRODUCTION USE. OpenSSL configuration file for testing.
  2.  
  3.  
  4. [ req ]
  5. default_bits = 4096
  6. default_keyfile = myTestServerCertificateKey.pem    ## The default private key file name.
  7. default_md = sha256
  8. distinguished_name = req_dn
  9. req_extensions = v3_req
  10.  
  11. [ v3_req ]
  12. subjectKeyIdentifier  = hash
  13. basicConstraints = CA:FALSE
  14. keyUsage = critical, digitalSignature, keyEncipherment
  15. nsComment = "OpenSSL Generated Certificate for TESTING only.  NOT FOR PRODUCTION USE."
  16. extendedKeyUsage  = serverAuth, clientAuth
  17. subjectAltName = @alt_names
  18.  
  19. [ alt_names ]
  20. DNS.1 =         ##TODO: Enter the DNS names. The DNS names should match the server names.
  21. DNS.2 =         ##TODO: Enter the DNS names. The DNS names should match the server names.
  22. IP.1 =          ##TODO: Enter the IP address. SAN matching by IP address is available starting in MongoDB 4.2
  23. IP.2 =          ##TODO: Enter the IP address. SAN matching by IP address is available starting in MongoDB 4.2
  24.  
  25. [ req_dn ]
  26. countryName = Country Name (2 letter code)
  27. countryName_default = TestServerCertificateCountry
  28. countryName_min = 2
  29. countryName_max = 2
  30.  
  31. stateOrProvinceName = State or Province Name (full name)
  32. stateOrProvinceName_default = TestServerCertificateState
  33. stateOrProvinceName_max = 64
  34.  
  35. localityName = Locality Name (eg, city)
  36. localityName_default = TestServerCertificateLocality
  37. localityName_max = 64
  38.  
  39. organizationName = Organization Name (eg, company)
  40. organizationName_default = TestServerCertificateOrg
  41. organizationName_max = 64
  42.  
  43. organizationalUnitName = Organizational Unit Name (eg, section)
  44. organizationalUnitName_default = TestServerCertificateOrgUnit
  45. organizationalUnitName_max = 64
  46.  
  47. commonName = Common Name (eg, YOUR name)
  48. commonName_max = 64
  • In the [alt_names] section, enter the appropriateDNS names and/or IP addresses for the MongoDB server. You canspecify multiple DNS names a MongoDB server.

For OpenSSL SAN identifiers, MongoDB supports:

  • DNS names and/or
  • IP address fields (Starting in MongoDB 4.2)
    • Optional. You can update the default Distinguished Name (DN)values.

Tip

  • Specify a non-empty value for at least one of the followingattributes: Organization (O), the Organizational Unit(OU), or the Domain Component (DC).

  • When creating test server certificates for internal membershipauthentication, the following attributes, if specified, must matchexactly across the member certificates: Organization (O),Organizational Unit (OU), the Domain Component (DC).

For more information on requirements for internal membershipauthentication, see membership authentication.

B. Generate the Test PEM File for Server

Important

Before proceeding, ensure that you have entered theappropriate DNS names in the [alt_names] section of theconfiguration file openssl-test-server.cnf.

  • Create the test key file mongodb-test-server1.key.
  1. openssl genrsa -out mongodb-test-server1.key 4096
  • Create the test certificate signing request mongodb-test-server1.csr.

When asked for Distinguished Name values, enter the appropriatevalues for your test certificate:

  • Specify a non-empty value for at least one of the followingattributes: Organization (O), the Organizational Unit(OU), or the Domain Component (DC).
  • When creating test server certificates for internal membershipauthentication, the following attributes, if specified, must matchexactly across the member certificates: Organization (O),Organizational Unit (OU), the Domain Component (DC).
  1. openssl req -new -key mongodb-test-server1.key -out mongodb-test-server1.csr -config openssl-test-server.cnf
  • Create the test server certificate mongodb-test-server1.crt.
  1. openssl x509 -sha256 -req -days 365 -in mongodb-test-server1.csr -CA mongodb-test-ia.crt -CAkey mongodb-test-ia.key -CAcreateserial -out mongodb-test-server1.crt -extfile openssl-test-server.cnf -extensions v3_req
  • Create the test PEM file for the server.
  1. cat mongodb-test-server1.crt mongodb-test-server1.key > test-server1.pem

You can use the test PEM file when configuring amongod or a mongos for TLS/SSLtesting. For example:

For MongoDB 4.2 or greater

  1. mongod --tlsMode requireTLS --tlsCertificateKeyFile test-server1.pem  --tlsCAFile test-ca.pem

Although still available, —sslMode,—sslPEMKeyFile, and—sslCAFile are deprecated asof MongoDB 4.2.

For MongoDB 4.0 and earlier

  1. mongod --sslMode requireSSL --sslPEMKeyFile test-server1.pem  --sslCAFile test-ca.pem
  • On macOS,
  • If you are testing with Keychain Access to managecertificates, create a pkcs-12 file to add to Keychain Accessinstead of a PEM file:
  1. openssl pkcs12 -export -out test-server1.pfx -inkey mongodb-test-server1.key -in mongodb-test-server1.crt -certfile mongodb-test-ia.crt

Once added to Keychain Access, instead of specifying the certificate keyfile, you can use the —tlsCertificateSelector to specify the certificate to use. Ifthe CA file is also in Keychain Access, you can omit—tlsCAFile as well.

For MongoDB 4.2 or greater

  1. mongod --tlsMode requireTLS --tlsCertificateSelector subject="<TestServerCertificateCommonName>"

Although still available, —sslModeand —sslCertificateSelector are deprecated as of MongoDB 4.2.

For MongoDB 4.0 and earlier

  1. mongod --sslMode requireSSL --sslCertificateSelector subject="<TestServerCertificateCommonName>"

For adding certificates to Keychain Access, refer to yourofficial documentation for Keychain Access.

See also