Skip to content

Commit b573fe1

Browse files
mbroadstmbroadst
committed
refactor: translate modern tls options to ssl, update documentation
We now prefer the `tls` variants of SSL/TLS options. For now, we detect these and translate them internally to the old option names. Documentation has been updated to prefer these types, and mention that the `sslVariants` are deprecated NODE-2359
1 parent 806cd62 commit b573fe1

File tree

11 files changed

+229
-254
lines changed

11 files changed

+229
-254
lines changed

‎docs/guide/tutorials/connect/authentication.txt

Lines changed: 14 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,10 @@ In the following example, the connection string specifies the user ``dave``\ , p
2626

2727
// Connection URL
2828
const url = `mongodb://${user}:${password}@localhost:27017/?authMechanism=${authMechanism}`;
29-
29+
3030
// Create a new MongoClient
3131
const client = new MongoClient(url);
32-
32+
3333
// Function to connect to the server
3434
async function run() {
3535
try {
@@ -41,7 +41,7 @@ In the following example, the connection string specifies the user ``dave``\ , p
4141
await client.close();
4242
}
4343
}
44-
44+
4545
// Runs your code
4646
run();
4747

@@ -78,7 +78,7 @@ In the following example, the connection string specifies the user ``dave``\ , p
7878
await client.close();
7979
}
8080
}
81-
81+
8282
// Runs your code
8383
run();
8484

@@ -115,7 +115,7 @@ In the following example, the connection string specifies the user ``dave``\ , p
115115
await client.close();
116116
}
117117
}
118-
118+
119119
// Runs your code
120120
run();
121121

@@ -153,7 +153,7 @@ In the following example, the connection string specifies the user ``dave``\ , p
153153
await client.close();
154154
}
155155
}
156-
156+
157157
// Runs your code
158158
run();
159159

@@ -163,11 +163,11 @@ In the following example, the connection string specifies the user ``dave``\ , p
163163
X509
164164
----
165165

166-
With :manual:`X.509 </core/security-x.509>` mechanism, MongoDB uses the X.509 certificate presented during SSL negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
166+
With :manual:`X.509 </core/security-x.509>` mechanism, MongoDB uses the X.509 certificate presented during TLS negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
167167

168-
X.509 authentication requires the use of SSL connections with certificate validation and is available in MongoDB 2.6 and newer.
168+
X.509 authentication requires the use of TLS connections with certificate validation and is available in MongoDB 2.6 and newer.
169169

170-
To connect using the X.509 authentication mechanism, specify ``MONGODB-X509`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` , ``ssl=true``\ , and the username. Use ``enodeURIComponent`` to encode the username string.
170+
To connect using the X.509 authentication mechanism, specify ``MONGODB-X509`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` , ``tls=true``\ , and the username. Use ``enodeURIComponent`` to encode the username string.
171171

172172
In addition to the connection string, pass to the new ``MongoClient`` a connections options for the ``server`` with the X.509 certificate and other :doc:`TLS/SSL connections </tutorials/connect/tls>` options.
173173

@@ -176,19 +176,13 @@ In addition to the connection string, pass to the new ``MongoClient`` a connecti
176176
const { MongoClient } = require('mongodb');
177177
const fs = require('fs');
178178

179-
// Read the cert and key
180-
const cert = fs.readFileSync(`${__dirname}/ssl/x509/client.pem`);
181-
const key = fs.readFileSync(`${__dirname}/ssl/x509/client.pem`);
182-
183179
// User name
184180
const userName = encodeURIComponent('CN=client,OU=kerneluser,O=10Gen,L=New York City,ST=New York,C=US');
185-
const url = `mongodb://${userName}:${password}@server:27017?authMechanism=MONGODB-X509&ssl=true`;
181+
const url = `mongodb://${userName}:${password}@server:27017?authMechanism=MONGODB-X509&tls=true`;
186182

187183
// Create a new MongoClient
188184
const client = new MongoClient(url, {
189-
sslKey: key,
190-
sslCert: cert,
191-
sslValidate: false
185+
tlsCertificateKeyFile: `${__dirname}/certs/x509/client.pem`,
192186
});
193187

194188
// Function to connect to the server
@@ -202,7 +196,7 @@ In addition to the connection string, pass to the new ``MongoClient`` a connecti
202196
await client.close();
203197
}
204198
}
205-
199+
206200
// Runs your code
207201
run();
208202

@@ -244,7 +238,7 @@ The following example connects to MongoDB using Kerberos for UNIX.
244238
await client.close();
245239
}
246240
}
247-
241+
248242
// Runs your code
249243
run();
250244

@@ -284,7 +278,7 @@ To connect using the LDAP authentication mechanism, specify ``authMechanism=PLAI
284278
await client.close();
285279
}
286280
}
287-
281+
288282
// Runs your code
289283
run();
290284

‎docs/guide/tutorials/connect/connect.txt

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ To connect to a :manual:`replica set </core/replication-introduction/>` ,
2929
include a seedlist of replica set members and the name of the replica set in the
3030
:manual:`URI connection string </reference/connection-string/>` .
3131

32-
In the following example, the connection string specifies two of the replica set members running on ``localhost:27017`` and ``localhost:27018`` and the name of the replica set (\ ``foo``\ ).
32+
In the following example, the connection string specifies two of the replica set members running on ``localhost:27017`` and ``localhost:27018`` and the name of the replica set (\ ``foo``\ ).
3333

3434
.. literalinclude:: /includes/connect-to-replicaset.js
3535
:language: js
@@ -62,18 +62,13 @@ For example, you can specify TLS/SSL and authentication setting.
6262
const { MongoClient } = require('mongodb');
6363
const fs = require('fs');
6464

65-
// Read the certificate authority
66-
const ca = [fs.readFileSync(`${__dirname} + /ssl/ca.pem`)];
67-
const cert = fs.readFileSync(`${__dirname} + /ssl/client.pem`);
68-
6965
// Connection URL
70-
const url = 'mongodb://dave:password@localhost:27017?authMechanism=DEFAULT&authSource=db&ssl=true';
66+
const url = 'mongodb://dave:password@localhost:27017?authMechanism=DEFAULT&authSource=db&tls=true';
7167

7268
// Create a client, passing in additional options
7369
const client = new MongoClient(url, {
74-
sslValidate: true,
75-
sslCA: ca,
76-
sslCert: cert
70+
tlsCAFile: path.resolve(__dirname + '/certs/ca.pem'),
71+
tlsCertificateKeyFile: `${__dirname}/certs/client.pem`
7772
});
7873

7974
// Function to connect to the server

‎docs/guide/tutorials/connect/tls.txt

Lines changed: 48 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ The Node.js driver supports TLS/SSL connections to MongoDB that support TLS/SSL
77
No Certificate Validation
88
-------------------------
99

10-
If the MongoDB instance does not perform any validation of the certificate chain, include the ``ssl=true`` in the :manual:`URI ConnectionString </reference/connection-string/>` .
10+
If the MongoDB instance does not perform any validation of the certificate chain, include the ``tls=true`` in the :manual:`URI ConnectionString </reference/connection-string/>` .
1111

1212
.. code-block:: js
1313

1414
const { MongoClient } = require('mongodb');
1515

1616
// Connection URL
17-
const url = 'mongodb://localhost:27017?ssl=true';
17+
const url = 'mongodb://localhost:27017?tls=true';
1818

1919
// Create a new MongoClient
2020
const client = new MongoClient(url);
@@ -39,54 +39,38 @@ Validate Server Certificate
3939

4040
If the MongoDB instance presents a certificate, to validate the server's certificate, pass the following when creating a ``MongoClient``\ :
4141

42-
* A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``ssl=true`` setting,
42+
* A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``tls=true`` setting,
4343

44-
* A connections options with the certificate for the Certificate Authority (\ ``sslCA``\ ) and the ``sslValidate`` setting set to ``true``
44+
* A connections options with the certificate for the Certificate Authority (\ ``tlsCAFile``\ )
4545

4646
.. code-block:: js
4747

4848
const { MongoClient } = require('mongodb');
49-
const fs = require('fs');
50-
51-
// Connection URL
52-
const url = 'mongodb://localhost:27017?ssl=true';
5349

54-
// Read the certificate authority
55-
const sslCA = [fs.readFileSync(`${__dirname}/ssl/ca.pem`)];
56-
57-
const client = new MongoClient(url, {
58-
sslValidate: true,
59-
sslCA
50+
const client = new MongoClient('mongodb://localhost:27017?tls=true', {
51+
tlsCAFile: `${__dirname}/certs/ca.pem`)
6052
});
6153

6254
Disable Hostname Verification
6355
-----------------------------
6456

6557
By default, the driver ensures that the hostname included in the
66-
server's SSL certificate(s) matches the hostname(s) provided in the URI connection string. If you need to disable the hostname verification, but otherwise validate the server's certificate, pass to the new ``MongoClient``\ :
58+
server's TLS certificate(s) matches the hostname(s) provided in the URI connection string. If you need to disable the hostname verification, but otherwise validate the server's certificate, pass to the new ``MongoClient``\ :
6759

6860

69-
*
70-
A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``ssl=true`` setting,
61+
*
62+
A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``tls=true`` setting,
7163

72-
*
73-
A connections options with the certificate for the Certificate Authority (\ ``sslCA``\ ) and the ``sslValidate`` setting set to ``true`` but ``checkServerIdentity`` set to ``false``.
64+
*
65+
A connections options with the certificate for the Certificate Authority (\ ``tlsCAFile``\ ) but ``tlsAllowInvalidHostnames`` set to ``true``.
7466

7567
.. code-block:: js
7668

7769
const { MongoClient } = require('mongodb');
78-
const fs = require('fs');
7970

80-
// Connection URL
81-
const url = 'mongodb://localhost:27017?ssl=true';
82-
83-
// Read the certificate authority
84-
const sslCA = [fs.readFileSync(`${__dirname}/ssl/ca.pem`)];
85-
86-
const client = new MongoClient(url, {
87-
sslValidate: true,
88-
checkServerIdentity: false,
89-
sslCA
71+
const client = new MongoClient('mongodb://localhost:27017?tls=true', {
72+
tlsCAFile: `${__dirname}/certs/ca.pem`),
73+
tlsAllowInvalidHostnames: true
9074
});
9175

9276
Validate Server Certificate and Present Valid Certificate
@@ -96,61 +80,41 @@ If the MongoDB server performs certificate validation, the client must pass its
9680
certificate to the server. To pass the client's certificate as well as to validate the server's certificate, pass to the new ``MongoClient``\ :
9781

9882

99-
*
100-
A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``ssl=true`` setting,
83+
*
84+
A :manual:`URI ConnectionString </reference/connection-string/>` that includes ``tls=true`` setting,
10185

102-
*
103-
A connections options with the ``sslValidate`` setting set to ``true``\ , the certificate for the Certificate Authority (\ ``sslCA``\ ), the client's certificate (\ ``sslCert``\ ) and private key file (\ ``sslKey``\ ). If the client's key file is encrypted, include the password (\ ``sslPass``\ ).
86+
*
87+
A connections options with the certificate for the Certificate Authority (\ ``tlsCAFile``\ ), the client's certificate (\ ``tlsCertificateKeyFile``\ ). If the client's key file is encrypted, include the password (\ ``tlsCertificateKeyFilePassword``\ ).
10488

10589
.. code-block:: js
10690

10791
const { MongoClient } = require('mongodb');
10892
const fs = require('fs');
10993

110-
// Connection URL
111-
const url = 'mongodb://localhost:27017?ssl=true';
112-
113-
// Read the certificates
114-
const sslCA = [fs.readFileSync(`${__dirname}/ssl/ca.pem`)];
115-
const sslCert = fs.readFileSync(`${__dirname}/ssl/client.pem`);
116-
const sslKey = fs.readFileSync(`${__dirname}/ssl/client.pem`);
117-
118-
const client = new MongoClient(url, {
119-
sslValidate: true,
120-
sslCA,
121-
sslCert,
122-
sslKey,
123-
sslPass: '10gen'
94+
const client = new MongoClient('mongodb://localhost:27017?tls=true', {
95+
tlsCAFile: `${__dirname}/certs/ca.pem`),
96+
tlsCertificateKeyFile: `${__dirname}/certs/client.pem`,
97+
tlsCertificateKeyFilePassword: '10gen'
12498
});
12599

126100
Connect with X.509
127101
------------------
128102

129-
:manual:`X.509 </core/security-x.509>` authentication requires the use of TLS/SSL connections with certificate validation. MongoDB uses the X.509 certificate presented during SSL negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
103+
:manual:`X.509 </core/security-x.509>` authentication requires the use of TLS/SSL connections with certificate validation. MongoDB uses the X.509 certificate presented during TLS negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.
130104

131-
To connect using the X.509 authentication mechanism, specify ``MONGODB-X509`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` , ``ssl=true``\ , and the username. Use ``enodeURIComponent`` to encode the username string.
105+
To connect using the X.509 authentication mechanism, specify ``MONGODB-X509`` as the mechanism in the :manual:`URI ConnectionString </reference/connection-string/>` , ``tls=true``\ , and the username. Use ``enodeURIComponent`` to encode the username string.
132106

133107
In addition to the connection string, pass to the new ``MongoClient``
134108
a connections options with the X.509 certificate and other :doc:`TLS/SSL connections </tutorials/connect/tls>` options.
135109

136110
.. code-block:: js
137111

138112
const { MongoClient } = require('mongodb');
139-
const fs = require('fs');
140113

141-
// User name
142114
const userName = 'CN=client,OU=kerneluser,O=10Gen,L=New York City,ST=New York,C=US';
143-
144-
// Connection URL
145-
const url = `mongodb://${encodeURIComponent(userName)}@server:27017?authMechanism=MONGODB-X509&ssl=true`;
146-
147-
// Read the cert and key
148-
const sslCert = fs.readFileSync(`${__dirname}/ssl/x509/client.pem`);
149-
const sslKey = fs.readFileSync(`${__dirname}/ssl/x509/client.pem`);
150-
115+
const url = `mongodb://${encodeURIComponent(userName)}@server:27017?authMechanism=MONGODB-X509&tls=true`;
151116
const client = new MongoClient(url, {
152-
sslCert,
153-
sslKey
117+
tlsCertificateKeyFile: `${__dirname}/certs/x509/client.pem`
154118
});
155119

156120
TLS/SSL Options
@@ -165,35 +129,31 @@ The following TLS/SSL options are available.
165129
- Type
166130
- Default
167131
- Description
168-
* - ``ssl``
132+
* - ``tls``
169133
- boolean
170134
- ``false``
171-
- Use tls/ssl connection. See :manual:`tls </reference/connection-string/#urioption.tls>`
172-
* - ``sslValidate``
135+
- Use TLS connections.
136+
* - ``tlsInsecure``
173137
- boolean
174138
- ``false``
175-
- Validate mongod server certificate against ca. Is equivalent to :manual:`tlsInsecure </reference/connection-string/#urioption.tlsInsecure>`
176-
* - ``sslCA``
177-
- Buffer[]|string[]
178-
-
179-
- Array of valid certificates for Certificate Authority either as Buffers or Strings.
180-
* - ``sslCRL``
181-
- Buffer[]|string[]
182-
-
183-
- Certificate Revocation Lists. See `tls.createSecureContext <https://nodejs.org/dist/latest-v10.x/docs/api/tls.html#tls_tls_createsecurecontext_options>`_
184-
* - ``sslCert``
185-
- Buffer|string
186-
-
187-
- String or buffer containing the client certificate.
188-
* - ``sslKey``
189-
- Buffer|string
190-
-
191-
- String or buffer containing the certificate private key we wish to present
192-
* - ``sslPass``
139+
- Relax TLS constraints as much as possible (e.g. allowing invalid certificates or hostname mismatches); drivers must document the exact constraints which are relaxed by this option being true
140+
* - ``tlsCAFile``
141+
- string[]
142+
-
143+
- Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection
144+
* - ``tlsCertificateKeyFile``
145+
- string
146+
-
147+
- Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated
148+
* - ``tlsCertificateKeyFilePassword``
193149
- Buffer|string
194-
-
150+
-
195151
- String or buffer containing the client certificate password.
196-
* - ``checkServerIdentity``
197-
- function/boolean
198-
- true
199-
- If a function, overrides built-in `tls.checkServerIdentity <https://nodejs.org/dist/latest-v10.x/docs/api/tls.html#tls_tls_checkserveridentity_hostname_cert>`_. See `tls.connect <https://nodejs.org/dist/latest-v10.x/docs/api/tls.html#tls_tls_connect_options_callback>`_. If ``false``, automatically verifies all certificates and servernames.
152+
* - ``tlsAllowInvalidCertificates``
153+
- boolean
154+
- false
155+
- Specifies whether or not the driver should error when the server’s TLS certificate is invalid
156+
* - ``tlsAllowInvalidHostnames``
157+
- boolean
158+
- false
159+
- Specifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate

‎docs/reference/content/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ If you'd like to use the MongoDB driver with ESNext features such as Promises an
3939

4040
Advanced features for the driver.
4141

42-
* [SSL]({{< relref "tutorials/connect/ssl.md" >}})
42+
* [TLS]({{< relref "tutorials/connect/tls.md" >}})
4343
* [Logging]({{< relref "reference/management/logging.md" >}})
4444
* [APM]({{< relref "reference/management/apm.md" >}})
4545
* [Topology monitoring]({{< relref "reference/management/sdam-monitoring.md" >}})

0 commit comments

Comments
 (0)