From 4348595ff0b05cc243aafafefccdfe29c9bee96b Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Mon, 11 Dec 2023 13:00:34 +1100 Subject: [PATCH 1/5] Fix TLS certificate documentation for mongoose v8 --- docs/guides.md | 2 +- docs/migrating_to_8.md | 10 +++++++ docs/tutorials/ssl.md | 66 +++++++++++++++++++++--------------------- 3 files changed, 44 insertions(+), 34 deletions(-) diff --git a/docs/guides.md b/docs/guides.md index 379c48dd0f..9cc835fdb0 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -41,7 +41,7 @@ integrating Mongoose with external tools and frameworks. * [Transactions](transactions.html) * [MongoDB Driver Deprecation Warnings](deprecations.html) * [Testing with Jest](jest.html) -* [SSL Connections](tutorials/ssl.html) +* [TLS/SSL Connections](tutorials/ssl.html) * [MongoDB Client Side Field Level Encryption](field-level-encryption.html) ## Other Guides diff --git a/docs/migrating_to_8.md b/docs/migrating_to_8.md index 9d664b1316..02267bfe73 100644 --- a/docs/migrating_to_8.md +++ b/docs/migrating_to_8.md @@ -71,6 +71,16 @@ There's a few noteable changes in MongoDB Node driver v6 that affect Mongoose: 1. The `ObjectId` constructor no longer accepts strings of length 12. In Mongoose 7, `new mongoose.Types.ObjectId('12charstring')` was perfectly valid. In Mongoose 8, `new mongoose.Types.ObjectId('12charstring')` throws an error. +1. Deprecated SSL options have been removed + + - `sslCA` -> `tlsCAFile` + - `sslCRL` -> `tlsCRLFile` + - `sslCert` -> `tlsCertificateKeyFile` + - `sslKey` -> `tlsCertificateKeyFile` + - `sslPass` -> `tlsCertificateKeyFilePassword` + - `sslValidate` -> `tlsAllowInvalidCertificates` + - `tlsCertificateFile` -> `tlsCertificateKeyFile` +

Removed findOneAndRemove()

In Mongoose 7, `findOneAndRemove()` was an alias for `findOneAndDelete()` that Mongoose supported for backwards compatibility. diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index 43be1971b7..4e4a771c79 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -1,6 +1,6 @@ -# SSL Connections +# TSL/SSL Connections -Mongoose supports connecting to [MongoDB clusters that require SSL connections](https://www.mongodb.com/docs/manual/tutorial/configure-ssl/). Setting the `ssl` option to `true` in [`mongoose.connect()`](../api/mongoose.html#mongoose_Mongoose-connect) or your connection string is enough to connect to a MongoDB cluster using SSL: +Mongoose supports connecting to [MongoDB clusters that require TLS/SSL connections](https://www.mongodb.com/docs/manual/tutorial/configure-ssl/). Setting the either the `tls` or `ssl` option to `true` in [`mongoose.connect()`](../api/mongoose.html#mongoose_Mongoose-connect) or your connection string is enough to connect to a MongoDB cluster using TLS/SSL: ```javascript mongoose.connect('mongodb://127.0.0.1:27017/test', { ssl: true }); @@ -12,8 +12,7 @@ mongoose.connect('mongodb://127.0.0.1:27017/test?ssl=true'); The `ssl` option defaults to `false` for connection strings that start with `mongodb://`. However, the `ssl` option defaults to `true` for connection strings that start with `mongodb+srv://`. So if you are using an srv connection string to connect to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), SSL is enabled by default. -If you try to connect to a MongoDB cluster that requires SSL without enabling the `ssl` option, `mongoose.connect()` -will error out with the below error: +If you try to connect to a MongoDB cluster that requires TLS/SSL without enabling the `tls`/`ssl` option, `mongoose.connect()` will error out with the below error: ```no-highlight MongooseServerSelectionError: connection to 127.0.0.1:27017 closed @@ -21,22 +20,21 @@ MongooseServerSelectionError: connection to 127.0.0.1:27017 closed ... ``` -## SSL Validation +## TLS/SSL Validation -By default, Mongoose validates the SSL certificate against a [certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) to ensure the SSL certificate is valid. To disable this validation, set the `sslValidate` option -to `false`. +By default, Mongoose validates the TLS/SSL certificate against a [certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) to ensure the TLS/SSL certificate is valid. To disable this validation, set the `tlsAllowInvalidCertificates` (or `tlsInsecure`) option to `true`. ```javascript mongoose.connect('mongodb://127.0.0.1:27017/test', { - ssl: true, - sslValidate: false + tls: true, + tlsAllowInvalidCertificates: true, }); ``` -In most cases, you should not disable SSL validation in production. However, `sslValidate: false` is often helpful -for debugging SSL connection issues. If you can connect to MongoDB with `sslValidate: false`, but not with -`sslValidate: true`, then you can confirm Mongoose can connect to the server and the server is configured to use -SSL correctly, but there's some issue with the SSL certificate. +In most cases, you should not disable TLS/SSL validation in production. However, `tlsAllowInvalidCertificates: true` is often helpful +for debugging SSL connection issues. If you can connect to MongoDB with `tlsAllowInvalidCertificates: true`, but not with +`tlsAllowInvalidCertificates: false`, then you can confirm Mongoose can connect to the server and the server is configured to use +TLS/SSL correctly, but there's some issue with the certificate. For example, a common issue is the below error message: @@ -45,17 +43,16 @@ MongooseServerSelectionError: unable to verify the first certificate ``` This error is often caused by [self-signed MongoDB certificates](https://medium.com/@rajanmaharjan/secure-your-mongodb-connections-ssl-tls-92e2addb3c89) or other situations where the certificate sent by the MongoDB -server is not registered with an established certificate authority. The solution is to set the `sslCA` option, which essentially sets a list of allowed SSL certificates. +server is not registered with an established certificate authority. The solution is to set the `tlsCAFile` option, which essentially sets a list of allowed SSL certificates. ```javascript await mongoose.connect('mongodb://127.0.0.1:27017/test', { - ssl: true, - sslValidate: true, + tls: true, // For example, see https://medium.com/@rajanmaharjan/secure-your-mongodb-connections-ssl-tls-92e2addb3c89 // for where the `rootCA.pem` file comes from. // Please note that, in Mongoose >= 5.8.3, `sslCA` needs to be // the **path to** the CA file, **not** the contents of the CA file - sslCA: `${__dirname}/rootCA.pem` + tlsCAFile: `${__dirname}/rootCA.pem`, }); ``` @@ -66,7 +63,7 @@ MongooseServerSelectionError: Hostname/IP does not match certificate's altnames: ``` The SSL certificate's [common name](https://knowledge.digicert.com/solution/SO7239.html) **must** line up with the host name -in your connection string. If the SSL certificate is for `hostname2.mydomain.com`, your connection string must connect to `hostname2.mydomain.com`, not any other hostname or IP address that may be equivalent to `hostname2.mydomain.com`. For replica sets, this also means that the SSL certificate's common name must line up with the [machine's `hostname`](../connections.html#replicaset-hostnames). +in your connection string. If the SSL certificate is for `hostname2.mydomain.com`, your connection string must connect to `hostname2.mydomain.com`, not any other hostname or IP address that may be equivalent to `hostname2.mydomain.com`. For replica sets, this also means that the SSL certificate's common name must line up with the [machine's `hostname`](../connections.html#replicaset-hostnames). To disable this validation, set the `tlsAllowInvalidHostnames` option to `true`. ## X.509 Authentication @@ -75,40 +72,43 @@ If you're using [X.509 authentication](https://www.mongodb.com/docs/drivers/node ```javascript // Do this: const username = 'myusername'; -await mongoose.connect(`mongodb://${encodeURIComponent(username)}@127.0.0.1:27017/test`, { - ssl: true, - sslValidate: true, - sslCA: `${__dirname}/rootCA.pem`, - authMechanism: 'MONGODB-X509' -}); +await mongoose.connect( + `mongodb://${encodeURIComponent(username)}@127.0.0.1:27017/test`, + { + tls: true, + tlsCAFile: `${__dirname}/rootCA.pem`, + authMechanism: 'MONGODB-X509', + } +); // Not this: await mongoose.connect('mongodb://127.0.0.1:27017/test', { - ssl: true, - sslValidate: true, - sslCA: `${__dirname}/rootCA.pem`, + tls: true, + tlsCAFile: `${__dirname}/rootCA.pem`, authMechanism: 'MONGODB-X509', - auth: { username } + auth: { username }, }); ``` ## X.509 Authentication with MongoDB Atlas -With MongoDB Atlas, X.509 certificates are not Root CA certificates and will not work with the `sslCA` parameter as self-signed certificates would. If the `sslCA` parameter is used an error similar to the following would be raised: +With MongoDB Atlas, X.509 certificates are not Root CA certificates and will not work with the `tlsCAFile` parameter as self-signed certificates would. If the `tlsCAFile` parameter is used an error similar to the following would be raised: ```no-highlight MongoServerSelectionError: unable to get local issuer certificate ``` -To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`. The connection string already specifies the `authSource` and `authMechanism`, and the DNS `TXT` record would supply the parameter and value for `sslValidate`, however they're included below as `connect()` options for completeness: +To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`. The connection string already specifies the `authSource` and `authMechanism`, however they're included below as `connect()` options for completeness: ```javascript -const url = 'mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509'; +const url = + 'mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509'; await mongoose.connect(url, { - sslValidate: true, + tls: true, + // location of a local .pem file that contains both the client's certificate and key, e.g. tlsCertificateKeyFile: '/path/to/certificate.pem', authMechanism: 'MONGODB-X509', - authSource: '$external' + authSource: '$external', }); ``` From 1359c445c18c1e0a308001d9a8c960b75357ed81 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Mon, 11 Dec 2023 14:00:28 +1100 Subject: [PATCH 2/5] Update TLS header in sidenav --- docs/layout.pug | 2 +- docs/tutorials/ssl.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/layout.pug b/docs/layout.pug index be171657ca..16dd2cf925 100644 --- a/docs/layout.pug +++ b/docs/layout.pug @@ -62,7 +62,7 @@ html(lang='en') - if ([`${versions.versionedPath}/docs/connections`, `${versions.versionedPath}/docs/tutorials/ssl`].some(path => outputUrl.startsWith(path))) ul.pure-menu-list li.pure-menu-item.sub-item - a.pure-menu-link(href=`${versions.versionedPath}/docs/tutorials/ssl.html`, class=outputUrl === `${versions.versionedPath}/docs/tutorials/ssl.html` ? 'selected' : '') SSL Connections + a.pure-menu-link(href=`${versions.versionedPath}/docs/tutorials/ssl.html`, class=outputUrl === `${versions.versionedPath}/docs/tutorials/ssl.html` ? 'selected' : '') TLS/SSL Connections li.pure-menu-item.sub-item a.pure-menu-link(href=`${versions.versionedPath}/docs/models.html`, class=outputUrl === `${versions.versionedPath}/docs/models.html` ? 'selected' : '') Models - if ([`${versions.versionedPath}/docs/models`, `${versions.versionedPath}/docs/change-streams`].some(path => outputUrl.startsWith(path))) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index 4e4a771c79..92422417bd 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -1,4 +1,4 @@ -# TSL/SSL Connections +# TLS/SSL Connections Mongoose supports connecting to [MongoDB clusters that require TLS/SSL connections](https://www.mongodb.com/docs/manual/tutorial/configure-ssl/). Setting the either the `tls` or `ssl` option to `true` in [`mongoose.connect()`](../api/mongoose.html#mongoose_Mongoose-connect) or your connection string is enough to connect to a MongoDB cluster using TLS/SSL: From a3e4e3285d59e85ee5f944468ef8b7acb62d5567 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Mon, 11 Dec 2023 14:12:30 +1100 Subject: [PATCH 3/5] Restore line lengths fixed by prettier --- docs/tutorials/ssl.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index 92422417bd..e744a021c0 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -72,14 +72,11 @@ If you're using [X.509 authentication](https://www.mongodb.com/docs/drivers/node ```javascript // Do this: const username = 'myusername'; -await mongoose.connect( - `mongodb://${encodeURIComponent(username)}@127.0.0.1:27017/test`, - { - tls: true, - tlsCAFile: `${__dirname}/rootCA.pem`, - authMechanism: 'MONGODB-X509', - } -); +await mongoose.connect(`mongodb://${encodeURIComponent(username)}@127.0.0.1:27017/test`, { + tls: true, + tlsCAFile: `${__dirname}/rootCA.pem`, + authMechanism: 'MONGODB-X509', +}); // Not this: await mongoose.connect('mongodb://127.0.0.1:27017/test', { @@ -101,11 +98,10 @@ MongoServerSelectionError: unable to get local issuer certificate To connect to a MongoDB Atlas cluster using X.509 authentication the correct option to set is `tlsCertificateKeyFile`. The connection string already specifies the `authSource` and `authMechanism`, however they're included below as `connect()` options for completeness: ```javascript -const url = - 'mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509'; +const url = 'mongodb+srv://xyz.mongodb.net/test?authSource=%24external&authMechanism=MONGODB-X509'; await mongoose.connect(url, { tls: true, - // location of a local .pem file that contains both the client's certificate and key, e.g. + // location of a local .pem file that contains both the client's certificate and key tlsCertificateKeyFile: '/path/to/certificate.pem', authMechanism: 'MONGODB-X509', authSource: '$external', From d7dd6c09407070bfb549ff23be7fcdc89b3d6ce0 Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Mon, 11 Dec 2023 14:25:56 +1100 Subject: [PATCH 4/5] Remove unused comment --- docs/tutorials/ssl.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index e744a021c0..6bcd4d605d 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -50,8 +50,6 @@ await mongoose.connect('mongodb://127.0.0.1:27017/test', { tls: true, // For example, see https://medium.com/@rajanmaharjan/secure-your-mongodb-connections-ssl-tls-92e2addb3c89 // for where the `rootCA.pem` file comes from. - // Please note that, in Mongoose >= 5.8.3, `sslCA` needs to be - // the **path to** the CA file, **not** the contents of the CA file tlsCAFile: `${__dirname}/rootCA.pem`, }); ``` From ea64e171eb833a1846d40e6e854827189168451d Mon Sep 17 00:00:00 2001 From: Andrew Welch Date: Wed, 13 Dec 2023 14:10:38 +1100 Subject: [PATCH 5/5] Use tls property over ssl - use `tls: true` for likelihood of ssl: true being removed - confirm tls is enabled by mongodb+srv:// https://www.mongodb.com/docs/manual/reference/connection-string/ --- docs/tutorials/ssl.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/ssl.md b/docs/tutorials/ssl.md index 6bcd4d605d..cbea425344 100644 --- a/docs/tutorials/ssl.md +++ b/docs/tutorials/ssl.md @@ -1,16 +1,16 @@ # TLS/SSL Connections -Mongoose supports connecting to [MongoDB clusters that require TLS/SSL connections](https://www.mongodb.com/docs/manual/tutorial/configure-ssl/). Setting the either the `tls` or `ssl` option to `true` in [`mongoose.connect()`](../api/mongoose.html#mongoose_Mongoose-connect) or your connection string is enough to connect to a MongoDB cluster using TLS/SSL: +Mongoose supports connecting to [MongoDB clusters that require TLS/SSL connections](https://www.mongodb.com/docs/manual/tutorial/configure-ssl/). Setting the `tls` option to `true` in [`mongoose.connect()`](../api/mongoose.html#mongoose_Mongoose-connect) or your connection string is enough to connect to a MongoDB cluster using TLS/SSL: ```javascript -mongoose.connect('mongodb://127.0.0.1:27017/test', { ssl: true }); +mongoose.connect('mongodb://127.0.0.1:27017/test', { tls: true }); // Equivalent: -mongoose.connect('mongodb://127.0.0.1:27017/test?ssl=true'); +mongoose.connect('mongodb://127.0.0.1:27017/test?tls=true'); ``` -The `ssl` option defaults to `false` for connection strings that start with `mongodb://`. However, -the `ssl` option defaults to `true` for connection strings that start with `mongodb+srv://`. So if you are using an srv connection string to connect to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), SSL is enabled by default. +The `tls` option defaults to `false` for connection strings that start with `mongodb://`. However, +the `tls` option defaults to `true` for connection strings that start with `mongodb+srv://`. So if you are using an srv connection string to connect to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), TLS/SSL is enabled by default. If you try to connect to a MongoDB cluster that requires TLS/SSL without enabling the `tls`/`ssl` option, `mongoose.connect()` will error out with the below error: