Skip to content

Commit 8686591

Browse files
vincentkamvincentkam
committed
CSHARP-2817: Ocsp Support
1 parent 22c09c9 commit 8686591

File tree

24 files changed

+1748
-56
lines changed

24 files changed

+1748
-56
lines changed

‎Docs/reference/content/reference/driver/ssl.md

Lines changed: 60 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -43,14 +43,66 @@ var settings = new MongoClientSettings
4343
{{% note class="important" %}}It is imperative that when loading a certificate with a password, the [PrivateKey]({{< msdnref "system.security.cryptography.x509certificates.x509certificate2.privatekey" >}}) property not be null. If the property is null, it means that your certificate does not contain the private key and will not be passed to the server.{{% /note %}}
4444

4545
### Certificate Revocation Checking
46-
The .NET Driver now **disables** certificate revocation checking by default, setting [`CheckCertificateRevocation`]({{< apiref "P_MongoDB_Driver_SslSettings_CheckCertificateRevocation">}}) in [`SslSettings`]({{< apiref "T_MongoDB_Driver_SslSettings" >}}) to `false` by default. Any applications relying on the older default of `true` now must explicitly set [`CheckCertificateRevocation`]({{< apiref "P_MongoDB_Driver_SslSettings_CheckCertificateRevocation">}}) to `true` in [`SslSettings`]({{< apiref "T_MongoDB_Driver_SslSettings" >}}) to re-enable certificate revocation checking.
4746

48-
Prior to v2.7.0, the driver enabled certificate revocation checking by default, in contrast to the `mongo` shell and other MongoDB drivers. This was also in contrast to .NET's defaults for `SslStream` (see .NET Framework documentation [here](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.authenticateasclient?view=netframework-4.7.2#System_Net_Security_SslStream_AuthenticateAsClient_System_String_) and .NET Standard documentation [here](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.authenticateasclient?view=netstandard-2.0#System_Net_Security_SslStream_AuthenticateAsClient_System_String_)).
47+
#### Default behavior
48+
The .NET Driver now **enables** certificate revocation checking by
49+
default, setting [`CheckCertificateRevocation`]({{< apiref
50+
"P_MongoDB_Driver_SslSettings_CheckCertificateRevocation">}}) in
51+
[`SslSettings`]({{< apiref "T_MongoDB_Driver_SslSettings" >}}) to
52+
`true` by default. This is in contrast to .NET's defaults for
53+
`SslStream` (see .NET Framework documentation
54+
[here](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.authenticateasclient?view=netframework-4.7.2#System_Net_Security_SslStream_AuthenticateAsClient_System_String_)
55+
and .NET Standard documentation
56+
[here](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.authenticateasclient?view=netstandard-2.0#System_Net_Security_SslStream_AuthenticateAsClient_System_String_)).
57+
Any applications relying on the older default of `false` now must
58+
explicitly set [`CheckCertificateRevocation`]({{< apiref
59+
"P_MongoDB_Driver_SslSettings_CheckCertificateRevocation">}}) to
60+
`false` in [`SslSettings`]({{< apiref "T_MongoDB_Driver_SslSettings"
61+
>}}) to disable certificate revocation checking. Alternatively,
62+
applications may also set `tlsDisableCertificateRevocationCheck=true`
63+
in their connection string. See
64+
[tlsDisableCertificateRevocationCheck](#tlsDisableCertificateRevocationCheck)
65+
for more information.
66+
67+
Prior to v2.7.0, the driver also enabled certificate revocation checking by
68+
default.
69+
70+
#### tlsDisableCertificateRevocationCheck
71+
The URI option, `tlsDisableCertificateRevocationCheck` controls
72+
whether or not to disable certificate revocation checking during a TLS
73+
handshake. Setting `tlsDisableCertificateRevocationCheck=true` is
74+
equivalent to setting [`CheckCertificateRevocation`]({{< apiref
75+
"P_MongoDB_Driver_SslSettings_CheckCertificateRevocation">}}) in
76+
[`SslSettings`]({{< apiref "T_MongoDB_Driver_SslSettings" >}}) to
77+
`false`.
78+
79+
### OCSP
80+
81+
#### Stapling
82+
Due to limitations in .NET, the driver currently only supports OCSP
83+
(Online Certificate Status Protocol) stapling on .NET Core ≥2.x on
84+
macOS.
85+
86+
On Windows, when a server has a Must-Staple certificate and does not
87+
staple, by default, the driver will continue to connect as long as the
88+
OCSP responder is still available and reports that the server's
89+
certificate is valid. This behavior differs from the mongo shell and
90+
from the MongoDB Python and Go drivers, which will fail to connect in
91+
when a server has a Must-Staple certificate and does not staple.
92+
93+
#### Hard-fail vs. soft-fail
94+
On Windows, due .NET's implementation of TLS, the driver utilizes
95+
"hard-fail" behavior in contrast to the "soft-fail" behavior exhibited
96+
by the mongo shell and MongoDB drivers such as Python and Go. This
97+
means that in the case that an OCSP responder is unavailable, the
98+
driver will fail to connect (i.e. hard-fail) instead of allowing the
99+
connection to continue (i.e. soft-fail).
100+
49101

50102
## TLS support
51103
### Overview
52104

53-
| OS | .NET Version | TLS1.1 | TLS1.2 | SNI | CRLs without OCSP |
105+
| OS | .NET Version | TLS1.1 | TLS1.2 | SNI | CRLs without OCSP |
54106
|---------|-----------------------|--------|--------|-----|-------------------|
55107
| Windows | | | | | |
56108
| | .NET Framework 4.5 | Yes | Yes | Yes | Yes |
@@ -65,7 +117,7 @@ Prior to v2.7.0, the driver enabled certificate revocation checking by default,
65117
| | .NET Core 1.1 | Yes | Yes | No | Yes |
66118
| | .NET Core 2.0 | Yes | Yes | No | Yes |
67119
| | .NET Core 2.1 | Yes | Yes | Yes | Yes |
68-
| OSX | | | | | |
120+
| macOS | | | | | |
69121
| | .NET Core 1.0 | Yes | Yes | No | Yes |
70122
| | .NET Core 1.1 | Yes | Yes | No | Yes |
71123
| | .NET Core 2.0 | Yes | Yes | Yes | No |
@@ -74,10 +126,10 @@ Prior to v2.7.0, the driver enabled certificate revocation checking by default,
74126

75127
#### Notes
76128
- SNI (Server Name Indication) is required for Atlas free tier.
77-
- .NET Core on OSX will fail to connect if **both** of the following conditions are met: (1) [certificate revocation checking]({{<relref "reference\driver\ssl.md#certificate-revocation-checking" >}}) is enabled, and (2) a server's certificate includes Certificate Revocation List (CRL) Distribution Points but does not include an Online Certificate Status Protocol (OCSP) extension.
78-
79-
- This is due to a limitation of the Apple Security Framework (see https://github.com/dotnet/corefx/issues/29064). Prior to version 2.0, .NET Core on OSX used OpenSSL, which does support CRLs without OCSP.
80-
- Connecting to Atlas on OSX with certificate revocation checking enabled will succeed since Atlas certificates include CRL Distribution Points as well as an OCSP extension.
129+
- .NET Core on macOS will fail to connect if **both** of the following conditions are met: (1) [certificate revocation checking]({{<relref "reference\driver\ssl.md#certificate-revocation-checking" >}}) is enabled, and (2) a server's certificate includes Certificate Revocation List (CRL) Distribution Points but does not include an Online Certificate Status Protocol (OCSP) extension.
130+
131+
- This is due to a limitation of the Apple Security Framework (see https://github.com/dotnet/corefx/issues/29064). Prior to version 2.0, .NET Core on macOS used OpenSSL, which does support CRLs without OCSP.
132+
- Connecting to Atlas on macOS with certificate revocation checking enabled will succeed since Atlas certificates include CRL Distribution Points as well as an OCSP extension.
81133

82134

83135
### Support for TLS v1.1 and newer

‎Docs/reference/content/upgrading.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,15 @@ title = "Upgrading"
1111

1212
## Breaking Changes
1313

14-
There should be no breaking changes in version 2.10.0 of the driver.
14+
# Backwards compatibility with driver version 2.7.0–2.10.x
15+
An application that is unable to contact the OCSP endpoints and/or CRL
16+
distribution points specified in a server's certificate may experience
17+
connectivity issues (e.g. if the application is behind a firewall with
18+
an outbound whitelist). This is because the driver needs to contact
19+
the OCSP endpoints and/or CRL distribution points specified in the
20+
server’s certificate and if these OCSP endpoints and/or CRL
21+
distribution points are not accessible, then the connection to the
22+
server may fail. In such a scenario, connectivity may be able to be
23+
restored by disabling certificate revocation checking by adding
24+
`tlsDisableCertificateRevocationCheck=true` to the application's connection
25+
string.

‎build.cake

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,10 @@ Task("Release")
4444
.IsDependentOn("Build")
4545
.IsDependentOn("Test")
4646
.IsDependentOn("Docs")
47-
.IsDependentOn("Package");
48-
47+
.IsDependentOn("Package");
48+
4949
Task("Restore")
50-
.Does(() =>
50+
.Does(() =>
5151
{
5252
DotNetCoreRestore(solutionFullPath);
5353
});
@@ -113,7 +113,7 @@ Task("Test")
113113
.DoesForEach(
114114
GetFiles("./**/*.Tests.csproj")
115115
.Where(name => !name.ToString().Contains("Atlas")),
116-
testProject =>
116+
testProject =>
117117
{
118118
var testWithDefaultGuidRepresentationMode = Environment.GetEnvironmentVariable("TEST_WITH_DEFAULT_GUID_REPRESENTATION_MODE");
119119
if (testWithDefaultGuidRepresentationMode != null)
@@ -144,7 +144,7 @@ Task("TestAllGuidRepresentations")
144144
GetFiles("./**/*.Tests.csproj")
145145
// .Where(name => name.ToString().Contains("Bson.Tests")) // uncomment to only test Bson
146146
.Where(name => !name.ToString().Contains("Atlas")),
147-
testProject =>
147+
testProject =>
148148
{
149149
var modes = new string[][]
150150
{
@@ -179,12 +179,12 @@ Task("TestAllGuidRepresentations")
179179
);
180180
}
181181
});
182-
182+
183183
Task("TestAtlasConnectivity")
184184
.IsDependentOn("Build")
185185
.DoesForEach(
186186
GetFiles("./**/AtlasConnectivity.Tests.csproj"),
187-
testProject =>
187+
testProject =>
188188
{
189189
DotNetCoreTest(
190190
testProject.FullPath,
@@ -197,6 +197,26 @@ Task("TestAtlasConnectivity")
197197
);
198198
});
199199

200+
Task("TestOcsp")
201+
.IsDependentOn("Build")
202+
.DoesForEach(
203+
GetFiles("./**/MongoDB.Driver.Tests.csproj"),
204+
testProject =>
205+
{
206+
DotNetCoreTest(
207+
testProject.FullPath,
208+
new DotNetCoreTestSettings {
209+
NoBuild = true,
210+
NoRestore = true,
211+
Configuration = configuration,
212+
213+
ArgumentCustomization = args => args
214+
.Append("--filter FullyQualifiedName~OcspIntegrationTests")
215+
.Append("-- RunConfiguration.TargetPlatform=x64")
216+
}
217+
);
218+
});
219+
200220
Task("Docs")
201221
.IsDependentOn("ApiDocs")
202222
.IsDependentOn("RefDocs");

‎evergreen/add-certs.sh

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,13 @@
33
set -o xtrace # Write all commands first to stderr
44
set -o errexit # Exit the script with an error if any of the commands fail
55

6+
OCSP_TLS_SHOULD_SUCCEED=${OCSP_TLS_SHOULD_SUCCEED:-nil}
7+
OCSP_ALGORITHM=${OCSP_ALGORITHM:-nil}
8+
69
if [[ "$OS" =~ Windows|windows ]]; then
710
certutil.exe -addstore "Root" ${DRIVERS_TOOLS}/.evergreen/x509gen/ca.pem
11+
12+
if [ "$OCSP_TLS_SHOULD_SUCCEED" != "nil" ] && [ "$OCSP_ALGORITHM" != "nil" ]; then
13+
certutil.exe -addstore "Root" ${DRIVERS_TOOLS}/.evergreen/ocsp/${OCSP_ALGORITHM}/ca.pem
14+
fi
815
fi

0 commit comments

Comments
 (0)