Skip to content

Commit 4b4d525

Browse files
blink1073blink1073
committed
Rename source/ocsp-support/ocsp-support.rst to source/ocsp-support/ocsp-support.md
1 parent df091d7 commit 4b4d525

File tree

2 files changed

+265
-0
lines changed

2 files changed

+265
-0
lines changed

‎source/ocsp-support/ocsp-support.rst‎ renamed to ‎source/ocsp-support/ocsp-support.md‎

File renamed without changes.

‎source/ocsp-support/tests/README.rst‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
======================
2+
OCSP Support Test Plan
3+
======================
4+
5+
.. contents::
6+
7+
----------
8+
9+
Introduction
10+
=============
11+
12+
The prose tests defined in this file are platform-independent tests that
13+
drivers can use to prove their conformance to the OCSP Support
14+
specification. These tests MUST BE implemented by all drivers.
15+
16+
Additional YAML and JSON tests have also been added to the `URI
17+
Options Tests <../../uri-options/tests/README.md>`__. Specifically,
18+
the `TLS Options Test <../../uri-options/tests/tls-options.yml>`__ has
19+
been updated with additional tests for the new URI options
20+
``tlsDisableOCSPEndpointCheck`` and ``tlsDisableCertificateRevocationCheck``.
21+
22+
Tests involving the new URI options MUST BE implemented by drivers
23+
that are able to support those new URI options (see `MongoClient
24+
Configuration <../ocsp-support#MongoClient-Configuration>`__).
25+
26+
Testing Invalid Configurations
27+
==============================
28+
29+
The following tests only apply to drivers that expose an option to
30+
enable/disable certificate revocation checking on a per MongoClient
31+
basis.
32+
33+
1. Create a MongoClient with ``tlsInsecure=true``.
34+
35+
2. Enable certificate revocation checking on the MongoClient.
36+
37+
3. Ensure that an error is thrown noting that revocation checking cannot
38+
be used in combination with ``tlsInsecure=true``.
39+
40+
The following test only applies to drivers that expose an option to
41+
enable/disable certificate revocation checking on a per MongoClient
42+
basis and implement support for ``tlsAllowInvalidCertificates``.
43+
44+
1. Create a MongoClient with ``tlsAllowInvalidCertificates=true``.
45+
46+
2. Enable certificate revocation checking on the MongoClient
47+
48+
3. Ensure that an error is thrown noting that revocation checking cannot
49+
be used in combination with ``tlsAllowInvalidCertificates=true``.
50+
51+
Integration Tests: Permutations to Be Tested
52+
============================================
53+
54+
For integration tests, we will test all combinations of URI options that
55+
influence a driver’s OCSP behavior with both validity states of the
56+
server’s certificate (configured with the mock OCSP responder). We will
57+
also test the case where an OCSP responder is unavailable and two
58+
malicious server cases.
59+
60+
Drivers that do not default to enabling OCSP MUST enable OCSP for
61+
these tests.
62+
63+
+----------------------------------------+-----------------------------------------+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------+--------------------------------------------------------------------+
64+
| **URI options** | **Test 1\:** | **Test 2\:** | **Test 3\:** | **Test 4\:** | **Soft Fail Test\:** | **Malicious Server Test 1\:** | **Malicious Server Test 2\: No OCSP Responder + server w/ Must-** |
65+
| | **Valid cert + server that staples** | **Revoked cert + server that staples** | **Valid cert + server that does not staple** | **Revoked cert + server that does not staple** | **No OCSP Responder + server that does not staple** | **Revoked cert + server w/ Must- Staple cert that does not staple** | **Staple cert that does not staple** |
66+
+========================================+=========================================+===========================================+=================================================+===================================================+=====================================================+=======================================================================+====================================================================+
67+
| ``tls=true`` | OK | FAIL | OK | FAIL | OK\* | FAIL\* | FAIL\* |
68+
+----------------------------------------+-----------------------------------------+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------+--------------------------------------------------------------------+
69+
| | ``tls=true`` | OK | OK | OK | OK | OK | OK | OK |
70+
| | ``&tlsInsecure=true`` | | | | | | | |
71+
+----------------------------------------+-----------------------------------------+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------+--------------------------------------------------------------------+
72+
| | ``tls=true`` | OK | OK | OK | OK | OK | OK | OK |
73+
| | ``&tlsAllowInvalidCertificates=true``| | | | | | | |
74+
+----------------------------------------+-----------------------------------------+-------------------------------------------+-------------------------------------------------+---------------------------------------------------+-----------------------------------------------------+-----------------------------------------------------------------------+--------------------------------------------------------------------+
75+
76+
See
77+
`Required Server Versions <../ocsp-support.rst#required-server-versions>`__
78+
to determine which versions of the server can be used for each column.
79+
80+
Note: From the perspective of a driver that does not support OCSP
81+
stapling, the following sets of tests should be identical: {Test 1, Test
82+
3}, {Test 2, Test 4, Malicious Server Test 1}, and {Soft Fail Test,
83+
Malicious Server Test 2}. For drivers with full control over their OCSP behavior, both malicious
84+
server tests are identical as well. However, it does no harm to test these
85+
extra cases and may help reveal unexpected behavior.
86+
87+
\*: Drivers that cannot pass these tests due to limitations in their
88+
TLS library’s implementation of OCSP will need to document these
89+
failures as described under `Documentation Requirements
90+
<../ocsp-support.rst#documentation-requirements>`__. Additionally,
91+
drivers that fail the "Soft Fail Test" will need to change any
92+
applicable defaults as described under `MongoClient Configuration
93+
<../ocsp-support.rst#mongoclient-configuration>`__
94+
95+
Mock OCSP Responder Testing Suite
96+
==================================
97+
98+
The certificates and scripts needed for testing OCSP are part of
99+
`driver-evergreen-tools
100+
<https://github.com/mongodb-labs/drivers-evergreen-tools>`__ in
101+
``.evergreen/ocsp``. The ``rsa`` and ``ecdsa`` directories contain
102+
the certificates and scripts needed to test with RSA and ECDSA
103+
certificates, respectively.
104+
105+
Both of the above directories contain four scripts: ``mock-valid.sh``,
106+
``mock-revoked.sh``, ``mock-delegate-valid.sh``, and
107+
``mock-delegate-revoked.sh``.
108+
109+
``mock-valid.sh`` starts up a mock OCSP responder that uses the
110+
issuing CA's certificate. This responder will report that every
111+
certificate is valid.
112+
113+
``mock-revoked.sh`` starts up a mock OCSP responder that uses the
114+
issuing CA's certificate. This responder will report that every
115+
certificate is revoked.
116+
117+
``mock-delegate-valid-valid.sh`` starts up a mock OCSP responder that
118+
uses a delegate certificate. This responder will report that every
119+
certificate is valid.
120+
121+
``mock-delegate-revoked.sh`` starts up a mock OCSP that uses a
122+
delegate certificate. This responder will report that every
123+
certificate is revoked.
124+
125+
mongo-orchestration configurations
126+
----------------------------------
127+
128+
The mongo-orchestration configurations needed for testing can be found
129+
at ``.evergreen/orchestration/configs/servers/``.
130+
131+
RSA Tests
132+
^^^^^^^^^^
133+
134+
Tests that specify that a server should staple MUST use
135+
``rsa-basic-tls-ocsp-mustStaple.json``. Tests that specify that a
136+
server should not staple MUST use
137+
``rsa-basic-tls-ocsp-disableStapling.json``. The malicious server
138+
tests MUST use ``rsa-basic-tls-ocsp-mustStaple-disableStapling.json``.
139+
140+
ECDSA Tests
141+
^^^^^^^^^^^^
142+
143+
Tests that specify that a server should staple MUST use
144+
``ecdsa-basic-tls-ocsp-mustStaple.json``. Tests that specify that a
145+
server should not staple MUST use
146+
``ecdsa-basic-tls-ocsp-disableStapling.json``. The malicious server
147+
tests MUST use
148+
``ecdsa-basic-tls-ocsp-mustStaple-disableStapling.json``.
149+
150+
Test Procedure
151+
==============
152+
153+
Each column that utilizes an OCSP responder represents four tests:
154+
155+
1. A test with RSA certificates and an OCSP responder that uses the
156+
issuing CA's certificate
157+
2. A test with RSA certificates and an OCSP responder that uses a
158+
delegate certificate
159+
3. A test with ECDSA certificates and an OCSP responder that uses the
160+
issuing CA's certificate
161+
4. A test with ECDSA certificates and an OCSP responder that uses a
162+
delegate certificate
163+
164+
Each column that does not utilize an OCSP responder (i.e. "Soft Fail
165+
Test" and "Malicious Server Test 2") represent two tests:
166+
167+
1. A test with RSA certificates
168+
2. A test with ECDSA certificates
169+
170+
Each test MUST BE its own Evergreen task in order to
171+
minimize the impact of OCSP caching. OCSP caching can exist at the
172+
OS-level, user-level and/or application-level; having separate
173+
Evergreen tasks should help minimize the impact of user-level and
174+
application-level caching since Evergreen performs some cleanup
175+
between test runs.
176+
177+
Since each test column represents four tests, and each test is run as
178+
a separate Evergreen task, each Evergreen task SHOULD set a
179+
``batchtime`` of 14 days to reduce how often these tests run (this
180+
will not affect patch builds).
181+
182+
Any OCSP caches that persist between test runs (e.g. the OS-level OCSP
183+
cache) MUST be cleared before configuring a certificate chain. This is
184+
important because the Evergreen instance that is running a driver’s test
185+
may have a cached response from a previous test run (Evergreen instances
186+
are generally reused between test runs), and this cached result could
187+
lead the driver or server to read stale data. See the
188+
`Appendix <../ocsp-support.rst#os-level-ocsp-cache-manipulation>`__
189+
for instructions on how to clear OS-level OCSP caches.
190+
191+
For each test, ensure that the mock OCSP responder is configured to
192+
use the correct certificate and to report the expected revocation
193+
status for that certificate (see `Mock OCSP Responder Testing Suite`_
194+
for configuration details)
195+
and that a ``mongod`` is running with the correct certificate
196+
chain. The mock OCSP responder MUST BE started before the ``mongod``
197+
as the ``mongod`` expects that a responder will be available upon
198+
startup. Again, each test MUST BE its own Evergreen task in order to
199+
minimize the impact of user-level and application-level OCSP caching
200+
201+
To assert whether a test passes or fails, drivers SHOULD create a
202+
MongoClient with the options specified under “URI options”, connect to a
203+
server and attempt to issue a ping command. The success or failure (due
204+
to a TLS error) of the ping command should correlate with the expected
205+
test result.
206+
207+
Drivers may wish to use a smaller value for ``serverSelectionTimeoutMS`` to
208+
speed up tests (otherwise server selection will spin for the entire
209+
duration even after a driver encounters a TLS error early).
210+
211+
Testing on Linux
212+
----------------
213+
214+
Drivers MUST test on Linux platforms that have server support for OCSP stapling.
215+
216+
- `SERVER-51364 <https://jira.mongodb.org/browse/SERVER-51364>`__ disables OCSP stapling on the server for Ubuntu 18.04.
217+
- `SERVER-56848 <https://jira.mongodb.org/browse/SERVER-56848>`__ is a known bug with Go clients and versions of RHEL 8 before 8.3.
218+
219+
Consider using RHEL 7.0 or Ubuntu 20.04 as alternative platforms.
220+
221+
Testing on Windows and macOS
222+
-----------------------------
223+
224+
Until `SPEC-1589 <http://jira.mongodb.org/browse/SPEC-1589>`__ and
225+
`SPEC-1645 <https://jira.mongodb.org/browse/SPEC-1645>`__ are
226+
resolved, drivers can only test with ECDSA certificates on Linux and
227+
thus, on Windows and macOS, drivers can only test with RSA
228+
certificates. Therefore, when testing on Windows and macOS, each
229+
column in the test matrix that utilizes an OCSP responder represents
230+
only two tests:
231+
232+
1. A test with RSA certificates and an OCSP responder that uses the
233+
issuing CA's certificate
234+
2. A test with RSA certificates and an OCSP responder that uses a
235+
delegate certificate
236+
237+
Additionally, because the Windows and macOS ``mongod`` do not support
238+
stapling when a client connects, the following sets of tests will be
239+
identical even if a driver supports stapled OCSP: {Test 1, Test 3} and
240+
{Test 2, Test 4}. Therefore, when testing on Windows and macOS, a
241+
driver MAY skip Test 1 and Test 2 if desired. A driver MAY also simply
242+
choose to run all the tests in the table, irrespective of OS, in order
243+
to simplify the testing procedure.
244+
245+
Changelog
246+
==========
247+
248+
**2021-11-??**: Clarify that not all Linux platforms support server stapling.
249+
250+
**2020-07-01**: Clarify that drivers that do not enable OCSP by
251+
default MUST enable OCSP for the tests.
252+
253+
**2020-03-20**: Clarify that the mock OCSP responder must be started
254+
before the mongod.
255+
256+
**2020-03-11**: Reduce and clarify Windows testing requirements.
257+
258+
**2020-03-05**: Add tests for tlsDisableCertificateRevocationCheck to
259+
URI Options tests. Move/add OCSP URI options default tests to separate file.
260+
261+
**2021-02-27**: Add delegate responders and ECDSA certificate testing.
262+
263+
**2020-02-26**: Add additional URI Options Tests.
264+
265+
**2020-01-16**: Initial commit.

0 commit comments

Comments
 (0)