Appendix C - OpenSSL Client Certificates for Testing

Disclaimer

This page is provided for testing purposes only and the certificatesare 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 andmongodb-test-ia.key created inAppendix A - OpenSSL CA Certificate for Testing.

Procedure

The following procedure outlines the steps to create test certificatesfor MongoDB clients. For steps to create test certificates for MongoDBservers, see Appendix B - OpenSSL Server Certificates for Testing.

A. Create the OpenSSL Configuration File

  • Create a test configuration file openssl-test-client.cnf foryour client with the following content:
  1. # NOT FOR PRODUCTION USE. OpenSSL configuration file for testing.
  2.  
  3. [ req ]
  4. default_bits = 4096
  5. default_keyfile = myTestClientCertificateKey.pem    ## The default private key file name.
  6. default_md = sha256
  7. distinguished_name = req_dn
  8. req_extensions = v3_req
  9.  
  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.  
  18.  
  19. [ req_dn ]
  20. countryName = Country Name (2 letter code)
  21. countryName_default =
  22. countryName_min = 2
  23. countryName_max = 2
  24.  
  25. stateOrProvinceName = State or Province Name (full name)
  26. stateOrProvinceName_default = TestClientCertificateState
  27. stateOrProvinceName_max = 64
  28.  
  29. localityName = Locality Name (eg, city)
  30. localityName_default = TestClientCertificateLocality
  31. localityName_max = 64
  32.  
  33. organizationName = Organization Name (eg, company)
  34. organizationName_default = TestClientCertificateOrg
  35. organizationName_max = 64
  36.  
  37. organizationalUnitName = Organizational Unit Name (eg, section)
  38. organizationalUnitName_default = TestClientCertificateOrgUnit
  39. organizationalUnitName_max = 64
  40. commonName = Common Name (eg, YOUR name)
  41. commonName_max = 64
  • Optional. You can update the default Distinguished Name (DN)values. Ensure that client certificates differ from server certificateswith regards to at least one of the following attributes:Organization (O), the Organizational Unit (OU) or the DomainComponent (DC).

B. Generate the Test PEM File for Client

  • Create the test key file mongodb-test-client.key.
  1. openssl genrsa -out mongodb-test-client.key 4096
  • Create the test certificate signing requestmongodb-test-client.csr. When asked for Distinguished Namevalues, enter the appropriate values for your test certificate:

Important

The client certificate subject must differ to a server certificatesubject with regards to at least one of the following attributes:Organization (O), the Organizational Unit (OU) or the DomainComponent (DC).

  1. openssl req -new -key mongodb-test-client.key -out mongodb-test-client.csr -config openssl-test-client.cnf
  • Create the test client certificate mongodb-test-client.crt.
  1. openssl x509 -sha256 -req -days 365 -in mongodb-test-client.csr -CA mongodb-test-ia.crt -CAkey mongodb-test-ia.key -CAcreateserial -out mongodb-test-client.crt -extfile openssl-test-client.cnf -extensions v3_req
  • Create the test PEM file for the client.
  1. cat mongodb-test-client.crt mongodb-test-client.key > test-client.pem

You can use the test PEM file to configure the mongoshell for TLS/SSL testing. For example, to connect to amongod or a mongos:

For MongoDB 4.2 or greater, include the following options for the client:

  1. mongo --tls --host <serverHost> --tlsCertificateKeyFile test-client.pem  --tlsCAFile test-ca.pem

For MongoDB 4.0 and earlier, include the following options for the client:

  1. mongo --ssl --host <serverHost> --sslPEMKeyFile test-client.pem  --sslCAFile test-ca.pem
  • On macOS,
  • If you are testing with Keychain Access to manage certificates,create a PKCS 12 file to add to Keychain Access instead of a PEMfile:
  1. openssl pkcs12 -export -out test-client.pfx -inkey mongodb-test-client.key -in mongodb-test-client.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 as in the following example:

For MongoDB 4.2 or greater

  1. mongo --tls --tlsCertificateSelector subject="<TestClientCertificateCommonName>"

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

For MongoDB 4.0 and earlier

  1. mongo --ssl --sslCertificateSelector subject="<TestClientCertificateCommonName>"

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

See also