Skip to content

Commit 364d08c

Browse files
kay-kimkay-kim
committed
DOCS-10488: appendix test openssl certificates
1 parent 43d62d7 commit 364d08c

File tree

5 files changed

+548
-0
lines changed

5 files changed

+548
-0
lines changed

‎source/appendix/security.txt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
========
2+
Appendix
3+
========
4+
5+
.. default-domain:: mongodb
6+
7+
8+
.. toctree::
9+
:titlesonly:
10+
11+
/appendix/security/appendixA-openssl-ca
12+
/appendix/security/appendixB-openssl-server
13+
/appendix/security/appendixC-openssl-client

‎source/appendix/security/appendixA-openssl-ca.txt

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
.. _appendix-ca-certificate:
2+
3+
===============================================
4+
Appendix A - OpenSSL CA Certificate for Testing
5+
===============================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. admonition:: Testing Purposes Only
10+
:class: warning
11+
12+
The following tutorial provides some guidelines for creating
13+
test x.509 certificates:
14+
15+
- Do not use these certificates for production. Instead, follow your
16+
security policies.
17+
18+
- For information on OpenSSL, refer to the official OpenSSL docs.
19+
Although this tutorial uses OpenSSL, the material should not be
20+
taken as an authoritative reference on OpenSSL.
21+
22+
Procedures
23+
----------
24+
25+
The following procedures outlines the steps to create a test CA PEM
26+
file. The procedure creates both the CA PEM file and an intermediate
27+
authority certificate and key files to sign server/client test
28+
certificates.
29+
30+
A. Create the OpenSSL Configuration File
31+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32+
33+
#. Create a configuration file ``openssl-test-ca.cnf`` with the
34+
following content:
35+
36+
.. code-block:: cfg
37+
:emphasize-lines: 29,34,38,42,46
38+
39+
# NOT FOR PRODUCTION USE. OpenSSL configuration file for testing.
40+
41+
# For the CA policy
42+
[ policy_match ]
43+
countryName = match
44+
stateOrProvinceName = match
45+
organizationName = match
46+
organizationalUnitName = optional
47+
commonName = supplied
48+
emailAddress = optional
49+
50+
[ req ]
51+
default_bits = 4096
52+
default_keyfile = myTestCertificateKey.pem ## The default private key file name.
53+
default_md = sha256 ## Use SHA-256 for Signatures
54+
distinguished_name = req_dn
55+
req_extensions = v3_req
56+
x509_extensions = v3_ca # The extentions to add to the self signed cert
57+
58+
[ v3_req ]
59+
subjectKeyIdentifier = hash
60+
basicConstraints = CA:FALSE
61+
keyUsage = critical, digitalSignature, keyEncipherment
62+
nsComment = "OpenSSL Generated Certificate for TESTING only. NOT FOR PRODUCTION USE."
63+
extendedKeyUsage = serverAuth, clientAuth
64+
65+
[ req_dn ]
66+
countryName = Country Name (2 letter code)
67+
countryName_default =
68+
countryName_min = 2
69+
countryName_max = 2
70+
71+
stateOrProvinceName = State or Province Name (full name)
72+
stateOrProvinceName_default = TestCertificateStateName
73+
stateOrProvinceName_max = 64
74+
75+
localityName = Locality Name (eg, city)
76+
localityName_default = TestCertificateLocalityName
77+
localityName_max = 64
78+
79+
organizationName = Organization Name (eg, company)
80+
organizationName_default = TestCertificateOrgName
81+
organizationName_max = 64
82+
83+
organizationalUnitName = Organizational Unit Name (eg, section)
84+
organizationalUnitName_default = TestCertificateOrgUnitName
85+
organizationalUnitName_max = 64
86+
87+
commonName = Common Name (eg, YOUR name)
88+
commonName_max = 64
89+
90+
[ v3_ca ]
91+
# Extensions for a typical CA
92+
93+
subjectKeyIdentifier=hash
94+
basicConstraints = critical,CA:true
95+
authorityKeyIdentifier=keyid:always,issuer:always
96+
97+
#. *Optional*. You can update the default Distinguished Name (DN)
98+
values.
99+
100+
B. Generate the Test CA PEM File
101+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102+
103+
#. Create the CA key file :file:`mongodb-test-ca.key`.
104+
105+
.. code-block:: sh
106+
107+
openssl genrsa -out mongodb-test-ca.key 4096
108+
109+
.. tip::
110+
111+
This private key is used to generate valid certificates for the
112+
CA. Although this private key, like all files in this appendix,
113+
is intended for testing purposes only, you should engage in good
114+
security practices and secure this key file.
115+
116+
#. Create the CA certificate :file:`mongod-test-ca.crt` using the
117+
generated key file. When asked for Distinguished Name values, enter
118+
the appropriate values for your test CA certificate.
119+
120+
.. code-block:: sh
121+
122+
openssl req -new -x509 -days 1826 -key mongodb-test-ca.key -out mongodb-test-ca.crt -config openssl-test-ca.cnf
123+
124+
#. Create the private key for the intermediate certificate.
125+
126+
.. code-block:: sh
127+
128+
openssl genrsa -out mongodb-test-ia.key 4096
129+
130+
.. tip::
131+
132+
This private key is used to generate valid certificates for the
133+
intermediate authority. Although this private key, like all files
134+
in this appendix, is intended for testing purposes only, you
135+
should engage in good security practices and secure this key file.
136+
137+
#. Create the certificate signing request for the intermediate
138+
certificate. When asked for Distinguished Name values, enter the
139+
appropriate values for your test Intermediate Authority certificate.
140+
141+
.. code-block:: sh
142+
143+
openssl req -new -key mongodb-test-ia.key -out mongodb-test-ia.csr -config openssl-test-ca.cnf
144+
145+
#. Create the intermediate certificate :file:`mongodb-test-ia.crt`.
146+
147+
.. code-block:: sh
148+
149+
openssl x509 -sha256 -req -days 730 -in mongodb-test-ia.csr -CA mongodb-test-ca.crt -CAkey mongodb-test-ca.key -set_serial 01 -out mongodb-test-ia.crt -extfile openssl-test-ca.cnf -extensions v3_ca
150+
151+
#. Create the test CA PEM file from the test CA certificate :file:`mongod-test-ca.crt` and
152+
test intermediate certificate :file:`mongodb-test-ia.crt`.
153+
154+
.. code-block:: sh
155+
156+
cat mongodb-test-ca.crt mongodb-test-ia.crt > test-ca.pem
157+
158+
You can use the test PEM file when configuring :binary:`~bin.mongod`,
159+
:binary:`~bin.mongod`, or :binary:`~bin.mongo` for TLS/SSL testing.
160+
161+
You can use the test intermediate authority to sign the test
162+
certificates for both the server(s) and client(s). A single authority
163+
must issue the certificates for both the client and the server.
164+
165+
166+
167+
.. seealso::
168+
169+
- :ref:`appendix-server-certificate`
170+
- :ref:`appendix-client-certificate`

‎source/appendix/security/appendixB-openssl-server.txt

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
.. _appendix-server-certificate:
2+
3+
====================================================
4+
Appendix B - OpenSSL Server Certificates for Testing
5+
====================================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. admonition:: Testing Purposes Only
10+
:class: warning
11+
12+
The following tutorial provides some basic steps for creating
13+
test x.509 certificates:
14+
15+
- Do not use these certificates for production. Instead, follow your
16+
security policies.
17+
18+
- For information on OpenSSL, refer to the official OpenSSL docs.
19+
Although this tutorial uses OpenSSL, the material should not be
20+
taken as an authoritative reference on OpenSSL.
21+
22+
Prerequisite
23+
------------
24+
25+
The procedure outlined on this page uses the intermediate authority
26+
certificate and key :file:`mongodb-test-ia.crt` and :file:`mongodb-test-ia.key`
27+
created in :doc:`/appendix/security/appendixA-openssl-ca` .
28+
29+
Procedure
30+
---------
31+
32+
The following procedure outlines the steps to create test certificates
33+
for MongoDB servers. For steps to create test certificates for MongoDB
34+
clients, see :doc:`/appendix/security/appendixC-openssl-client`.
35+
36+
A. Create the OpenSSL Configuration File
37+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38+
39+
#. Create a test configuration file ``openssl-test-server.cnf`` for
40+
your server with the following content:
41+
42+
.. code-block:: cfg
43+
:emphasize-lines: 20-21,25,30,34,38,42
44+
45+
# NOT FOR PRODUCTION USE. OpenSSL configuration file for testing.
46+
47+
[ req ]
48+
default_bits = 4096
49+
default_keyfile = myTestServerCertificateKey.pem ## The default private key file name.
50+
default_md = sha256
51+
distinguished_name = req_dn
52+
req_extensions = v3_req
53+
54+
[ v3_req ]
55+
subjectKeyIdentifier = hash
56+
basicConstraints = CA:FALSE
57+
keyUsage = critical, digitalSignature, keyEncipherment
58+
nsComment = "OpenSSL Generated Certificate for TESTING only. NOT FOR PRODUCTION USE."
59+
extendedKeyUsage = serverAuth, clientAuth
60+
subjectAltName = @alt_names
61+
62+
[ alt_names ]
63+
DNS.1 = ##TODO: Enter the DNS names. The DNS names should match the server names.
64+
DNS.2 = ##TODO: Enter the DNS names. The DNS names should match the server names.
65+
66+
[ req_dn ]
67+
countryName = Country Name (2 letter code)
68+
countryName_default =
69+
countryName_min = 2
70+
countryName_max = 2
71+
72+
stateOrProvinceName = State or Province Name (full name)
73+
stateOrProvinceName_default = TestServerCertificateState
74+
stateOrProvinceName_max = 64
75+
76+
localityName = Locality Name (eg, city)
77+
localityName_default = TestServerCertificateLocality
78+
localityName_max = 64
79+
80+
organizationName = Organization Name (eg, company)
81+
organizationName_default = TestServerCertificateOrg
82+
organizationName_max = 64
83+
84+
organizationalUnitName = Organizational Unit Name (eg, section)
85+
organizationalUnitName_default = TestServerCertificateOrgUnit
86+
organizationalUnitName_max = 64
87+
88+
commonName = Common Name (eg, YOUR name)
89+
commonName_max = 64
90+
91+
#. In the ``[alt_names]`` section, enter the appropriate
92+
DNS names specific for the MongoDB server. You can
93+
specify multiple DNS names a MongoDB server.
94+
95+
#. *Optional*. You can update the default Distinguished Name (DN)
96+
values.
97+
98+
.. tip::
99+
100+
- Specify a non-empty value for at least one of the following
101+
attributes: Organization (``O``), the Organizational Unit
102+
(``OU``), or the Domain Component (``DC``).
103+
104+
- When creating test server certificates for internal membership
105+
authentication, the following attributes, if specified, must match
106+
exactly across the member certificates: Organization (``O``),
107+
Organizational Unit (``OU``), the Domain Component (``DC``).
108+
109+
B. Generate the Test PEM File for Server
110+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111+
112+
.. important::
113+
114+
Before proceeding, ensure that you have entered the
115+
appropriate DNS names in the ``[alt_names]`` section of the
116+
configuration file ``openssl-test-server.cnf``.
117+
118+
#. Create the test key file :file:`mongodb-test-server1.key`.
119+
120+
.. code-block:: sh
121+
122+
openssl genrsa -out mongodb-test-server1.key 4096
123+
124+
#. Create the test certificate signing request :file:`mongodb-test-server1.csr`.
125+
126+
When asked for Distinguished Name values, enter the appropriate
127+
values for your test certificate:
128+
129+
- Specify a non-empty value for at least one of the following
130+
attributes: Organization (``O``), the Organizational Unit
131+
(``OU``), or the Domain Component (``DC``).
132+
133+
- When creating test server certificates for internal membership
134+
authentication, the following attributes, if specified, must match
135+
exactly across the member certificates: Organization (``O``),
136+
Organizational Unit (``OU``), the Domain Component (``DC``).
137+
138+
.. code-block:: sh
139+
140+
openssl req -new -key mongodb-test-server1.key -out mongodb-test-server1.csr -config openssl-test-server.cnf
141+
142+
#. Create the test server certificate :file:`mongodb-test-server1.crt`.
143+
144+
.. code-block:: sh
145+
146+
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
147+
148+
#. Create the test PEM file for the server.
149+
150+
.. code-block:: sh
151+
152+
cat mongodb-test-server1.crt mongodb-test-server1.key > test-server1.pem
153+
154+
You can use the test PEM file when configuring a
155+
:binary:`~bin.mongod` or a :binary:`~bin.mongos` for TLS/SSL
156+
testing; e.g.
157+
158+
.. code-block:: javascript
159+
160+
mongod --sslMode requireSSL --sslPEMKeyFile test-server1.pem --sslCAFile test-ca.pem
161+
162+
163+
On macOS,
164+
If you are testing with Keychain Access to manage
165+
certificates, create a pkcs-12 file to add to Keychain Access
166+
instead of a PEM file:
167+
168+
.. code-block:: sh
169+
170+
openssl pkcs12 -export -out test-server1.pfx -inkey mongodb-test-server1.key -in mongodb-test-server1.crt -certfile mongodb-test-ia.crt
171+
172+
Once added to Keychain Access, instead of specifying the PEM Key
173+
file, you can use the :option:`--sslCertificateSelector <mongod
174+
--sslCertificateSelector>` to specify the certificate to use. If
175+
the CA pem file is also in Keychain Access, you can omit
176+
``--sslCAFile`` as well.
177+
178+
.. code-block:: javascript
179+
180+
mongod --sslMode requireSSL --sslCertificateSelector subject="TestServerCertificateCommonName"
181+
182+
For adding certificates to Keychain Access, refer to your
183+
official documentation for Keychain Access.
184+
185+
.. seealso::
186+
187+
- :ref:`appendix-ca-certificate`
188+
189+
- :ref:`appendix-client-certificate`
190+
191+
- :ref:`x509-member-certificate`

0 commit comments

Comments
 (0)