[DOCS-10488] SSL/TLS x.509 certificate creation guidelines Created: 05/Jul/17  Updated: 30/Oct/23  Resolved: 04/Sep/18

Status: Closed
Project: Documentation
Component/s: Server
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Improvement Priority: Major - P3
Reporter: Ricardo Lorenzo Assignee: Kay Kim (Inactive)
Resolution: Fixed Votes: 2
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to DOCS-10776 MongoDB server SSL certificate and ex... Closed
is related to DOCS-6351 Be more explicit in the type of certi... Closed
is related to DOCS-6352 Specify structure of SSL certificate Closed
is related to DOCS-9180 Document required CN / subjectAltName... Closed
is related to DOCS-4436 Add a section to the docs showing how... Closed
Participants:
Days since reply: 5 years, 23 weeks, 1 day ago
Epic Link: DOCSP-1769

 Description   

We usually don’t provide full OpenSSL certificate creation or sign steps as this is an off topic that is usually addressed by the security administrator in each organisation. However, due the large amount of issues and support tickets in relation to this topic which can be easily resolved by following a correct procedure, I would like to see the following procedure available in the official documentation.

As everyone knows, any x.509 certificate should meet the standards and recommendations. One of the relevant things to consider is the certificate purpose (please take a look at the extended key usage section from the RFC 5280 for clarification).

Please find the following configuration and commands as an example of the correct OpenSSL steps to create a valid certificate.

OpenSSL configuration

# For the CA policy
[ policy_match ]
countryName = match
stateOrProvinceName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
 
[ req ]
default_bits        = 4096
default_keyfile     = server-key.pem
default_md      = sha1
distinguished_name  = req_dn
req_extensions = v3_req
x509_extensions = v3_ca # The extentions to add to the self signed cert
 
[ v3_req ]
subjectKeyIdentifier  = hash
basicConstraints = CA:FALSE
keyUsage = critical, digitalSignature, keyEncipherment
nsComment = "OpenSSL Generated Certificate"
extendedKeyUsage  = serverAuth, clientAuth
 
[ req_dn ]
countryName = Country Name (2 letter code)
countryName_default = IE
countryName_min = 2
countryName_max = 2
 
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Dublin
stateOrProvinceName_max = 64
 
localityName = Locality Name (eg, city)
localityName_default = Dublin
localityName_max = 64
 
organizationName = Organization Name (eg, company)
organizationName_default = MongoDB
organizationName_max = 64
 
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName_default = Support
organizationalUnitName_max = 64
 
commonName = Common Name (eg, YOUR name)
commonName_max = 64
 
[ v3_ca ]
# Extensions for a typical CA
 
subjectKeyIdentifier=hash
basicConstraints = critical,CA:true
authorityKeyIdentifier=keyid:always,issuer:always
 
# Key usage: this is typical for a CA certificate. However since it will
# prevent it being used as an test self-signed certificate it is best
# left out by default.
keyUsage = critical,keyCertSign,cRLSign

Authority creation

openssl genrsa -out mongodb-ca.key 4096
openssl req -new -x509 -days 1826 -key mongodb-ca.key -out mongodb-ca.crt -config openssl.cnf

Intermediate authority creation

It is optional to have an intermediate authority for signing the server certificates. However, it is a good practice in terms of security and certificate management.

openssl genrsa -out mongodb-ia.key 4096
openssl req -new -key mongodb-ia.key -out mongodb-ia.csr -config openssl.cnf
openssl x509 -req -days 730 -in mongodb-ia.csr -CA mongodb-ca.crt -CAkey mongodb-ca.key -set_serial 01 -out mongodb-ia.crt -extfile openssl.cnf -extensions v3_ca

Final CA PEM file

cat mongodb-ca.crt > mongodb-ca.pem
cat mongodb-ia.crt >> mongodb-ca.pem

Server certificate creation

After modifying or copying the OpenSSL configuration file, the following should be added to the v3_req section. Please note that this needs to be done for each of the servers.

[ v3_req ]
...
subjectAltName = @alt_names
 
[ alt_names ]
DNS.1 = server1.mongodb.com
DNS.2 = server1
DNS.3 = ip-192-168-44-31

The DNS names should match the server names. According to RFC 6125, hostname verification should be done against the certificate’s subjectAlternativeName’s dNSName field and not the CN (please take a look at https://tools.ietf.org/html/rfc6125#section-1.5).

openssl genrsa -out mongodb-server1.mongodb.com.key 4096
openssl req -new -key mongodb-server1.mongodb.com.key -out mongodb-server1.mongodb.com.csr -config openssl.cnf
openssl x509 -req -days 365 -in mongodb-server1.mongodb.com.csr -CA mongodb-ia.crt -CAkey mongodb-ia.key -CAcreateserial -out mongodb-server1.mongodb.com.crt -extfile openssl.cnf -extensions v3_req

Server PEM file (certificate and key) creation

cat mongodb-server1.mongodb.com.crt > mongodb-server1.mongodb.com.pem
cat mongodb-server1.mongodb.com.key >> mongodb-server1.mongodb.com.pem

The same procedure can be used to create a client certificate. The following is an example of the x.509 fields from the server certificate.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 18362953150530396348 (0xfed650996c8120bc)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=IE, ST=Dublin, L=Dublin, O=MongoDB, OU=Support, CN=MongoDB Support IA
        Validity
            Not Before: Dec 31 08:18:33 2015 GMT
            Not After : Dec 31 08:18:33 2016 GMT
        Subject: C=IE, ST=Dublin, L=Dublin, O=MongoDB, OU=Support, CN=mongodb-server1.mongodb.com
        ...
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
                E1:61:F7:BB:47:03:B3:1D:7A:CB:28:6A:01:80:4C:ED:DE:38:E8:28
            X509v3 Basic Constraints: 
                CA:FALSE
            X509v3 Key Usage: critical
                Digital Signature, Key Encipherment
            Netscape Comment: 
                OpenSSL Generated Certificate
            X509v3 Extended Key Usage: 
                TLS Web Server Authentication, TLS Web Client Authentication
            X509v3 Subject Alternative Name: 
                DNS:server1.mongodb.com, DNS:server1, DNS:ip-192-168-44-31
    ...

This kind of certificates should work well.



 Comments   
Comment by Githook User [ 04/Sep/18 ]

Author:

{'name': 'kay', 'email': 'kay.kim@10gen.com', 'username': 'kay-kim'}

Message: DOCS-10488: add redirects
Branch: master
https://github.com/mongodb/docs/commit/f006d04c7dade1465085857c25815c94762858b4

Comment by Githook User [ 04/Sep/18 ]

Author:

{'name': 'kay', 'email': 'kay.kim@10gen.com', 'username': 'kay-kim'}

Message: DOCS-10488: appendix test openssl certificates
Branch: master
https://github.com/mongodb/docs/commit/364d08c57150a71c0923c2ea326ed3bc3a0da66d

Comment by Kay Kim (Inactive) [ 02/Feb/18 ]

sorry, this got off track for 3.6, but back on it now

Comment by Ricardo Lorenzo [ 05/Jul/17 ]

Thanks kay.kim

Generated at Thu Feb 08 08:00:40 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.