From c0c44ebad2a47c02b78b8585fc7aad931ffcc1ab Mon Sep 17 00:00:00 2001 From: Connor MacDonald Date: Mon, 29 Jun 2026 12:16:25 -0400 Subject: [PATCH 1/3] DRIVERS-3472 add maxScramIterations URI option --- source/uri-options/tests/auth-options.json | 20 ++++++++++++++++++++ source/uri-options/tests/auth-options.yml | 17 +++++++++++++++++ source/uri-options/uri-options.md | 3 +++ 3 files changed, 40 insertions(+) diff --git a/source/uri-options/tests/auth-options.json b/source/uri-options/tests/auth-options.json index d7fa14a134..2f3469277d 100644 --- a/source/uri-options/tests/auth-options.json +++ b/source/uri-options/tests/auth-options.json @@ -28,6 +28,26 @@ "authMechanism": "SCRAM-SHA-1", "authSource": "authSourceDB" } + }, + { + "description": "maxScramIterations is parsed correctly", + "uri": "mongodb://example.com/?maxScramIterations=123456", + "valid": true, + "warning": false, + "hosts": null, + "auth": null, + "options": { + "maxScramIterations": 123456 + } + }, + { + "description": "maxScramIterations with value less than 4096 causes a warning", + "uri": "mongodb://example.com/?maxScramIterations=4095", + "valid": true, + "warning": true, + "hosts": null, + "auth": null, + "options": null } ] } diff --git a/source/uri-options/tests/auth-options.yml b/source/uri-options/tests/auth-options.yml index 4a46516f13..c8a5c8e22d 100644 --- a/source/uri-options/tests/auth-options.yml +++ b/source/uri-options/tests/auth-options.yml @@ -23,3 +23,20 @@ tests: options: authMechanism: "SCRAM-SHA-1" authSource: "authSourceDB" + - + description: "maxScramIterations is parsed correctly" + uri: "mongodb://example.com/?maxScramIterations=123456" + valid: true + warning: false + hosts: ~ + auth: ~ + options: + maxScramIterations: 123456 + - + description: "maxScramIterations with value less than 4096 causes a warning" + uri: "mongodb://example.com/?maxScramIterations=4095" + valid: true + warning: true + hosts: ~ + auth: ~ + options: ~ diff --git a/source/uri-options/uri-options.md b/source/uri-options/uri-options.md index 85a137671c..256d8c8bbf 100644 --- a/source/uri-options/uri-options.md +++ b/source/uri-options/uri-options.md @@ -78,6 +78,7 @@ to URI options apply here. | authMechanism | any string; valid values are defined in the [auth spec](../auth/auth.md#supported-authentication-methods) | None; default values for authentication exist for constructing authentication credentials per the [auth spec](../auth/auth.md#supported-authentication-methods), but there is no default for the URI option itself. | no | The authentication mechanism method to use for connection to the server | | authMechanismProperties | comma separated key:value pairs, e.g. "opt1:val1,opt2:val2" | no properties specified | no | Additional options provided for authentication (e.g. to enable hostname canonicalization for GSSAPI) | | authSource | any string | None; default values for authentication exist for constructing authentication credentials per the [auth spec](../auth/auth.md#supported-authentication-methods), but there is no default for the URI option itself. | no | The database that connections should authenticate against | +| maxScramIterations | integer greater than or equal to 4096 | 100000 | no | The maximum number of iterations permitted in SCRAM PBKDF2 | | compressors | comma separated list of strings, e.g. "snappy,zlib" | defined in [compression spec](../compression/OP_COMPRESSED.md#compressors) | no | The list of allowed compression types for wire protocol messages sent or received from the server | | connectTimeoutMS | non-negative integer; 0 means "no timeout" | 10,000 ms (unless a driver already has a different default) | no | Amount of time to wait for a single TCP socket connection to the server to be established before erroring; note that this applies to [SDAM hello and legacy hello operations](../mongodb-handshake/handshake.md) | | directConnection | "true" or "false" | defined in [SDAM spec](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#initial-topologytype) | no | Whether to connect to the deployment in Single topology. | @@ -184,6 +185,8 @@ changes. ## Changelog +- 2026-06-29: Add `maxScramIterations` URI option. + - 2024-05-08: Migrated from reStructuredText to Markdown. - 2023-08-21: Add serverMonitoringMode option. From 2714839d784af7ccc740c3c57bd62e16e083eca6 Mon Sep 17 00:00:00 2001 From: Connor MacDonald Date: Mon, 29 Jun 2026 12:32:01 -0400 Subject: [PATCH 2/3] DRIVERS-3472 enforce a maximum SCRAM iteration count --- source/auth/auth.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index efaea8779c..8b2debe1a0 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -634,8 +634,12 @@ that this be as secure and truly random as possible. For instance, Java provides SecureRandom class. SecureRandom is cryptographically generated while Random is just a pseudo-random generator with predictable outcomes. -Additionally, drivers MUST enforce a minimum iteration count of 4096 and MUST error if the authentication conversation -specifies a lower count. This mitigates downgrade attacks by a man-in-the-middle attacker. +Drivers MUST enforce a minimum iteration count of 4096 and MUST error if the authentication conversation specifies a +lower count. This mitigates downgrade attacks by a man-in-the-middle attacker. + +Drivers MUST enforce a maximum iteration count, defined by the `maxScramIterations` connection string option (default: +100000), and MUST error if the authentication conversation specifies a higher count. This mitigates client-side denial +of service attacks in which a malicious server causes CPU exhaustion by specifying an extremely high iteration count. Drivers MUST NOT advertise support for channel binding, as the server does not support it and legacy servers may fail authentication if drivers advertise support. I.e. the client-first-message MUST start with `n,`. @@ -703,8 +707,12 @@ The MongoDB SCRAM-SHA-256 mechanism works similarly to the SCRAM-SHA-1 mechanism - Passwords MUST be prepared with SASLprep, per RFC 5802. Passwords are used directly for key derivation ; they MUST NOT be digested as they are in SCRAM-SHA-1. -Additionally, drivers MUST enforce a minimum iteration count of 4096 and MUST error if the authentication conversation -specifies a lower count. This mitigates downgrade attacks by a man-in-the-middle attacker. +Drivers MUST enforce a minimum iteration count of 4096 and MUST error if the authentication conversation specifies a +lower count. This mitigates downgrade attacks by a man-in-the-middle attacker. + +Drivers MUST enforce a maximum iteration count, defined by the `maxScramIterations` connection string option (default: +100000), and MUST error if the authentication conversation specifies a higher count. This mitigates client-side denial +of service attacks in which a malicious server causes CPU exhaustion by specifying an extremely high iteration count. Drivers MUST add a top-level `options` field to the saslStart command, whose value is a document containing a field named `skipEmptyExchange` whose value is true. Older servers will ignore the `options` field and continue with the @@ -2034,6 +2042,12 @@ See the speculative authentication section in the [MongoDB Handshake spec](../mo For SCRAM-SHA-1 and SCRAM-SHA-256, test that the minimum iteration count is respected. This may be done via unit testing of an underlying SCRAM library. +### Maximum iteration count + +For SCRAM-SHA-1 and SCRAM-SHA-256, test that the maximum iteration count is respected. This may be done via unit testing +of an underlying SCRAM library. Ensure drivers use the `maxScramIterations` connection string option when set and fall +back to 100000 when unset. + ## Backwards Compatibility Drivers may need to remove support for association of more than one credential with a MongoClient, including @@ -2143,6 +2157,8 @@ practice to avoid this. (See ## Changelog +- 2026-06-29: Require SCRAM-SHA-1 and SCRAM-SHA-256 to enforce a maximum iteration count + - 2025-11-25: Remove redundant `*.mongodbgov.net` on `ALLOWED_HOSTS` - 2025-11-19: Extend `ALLOWED_HOSTS` with `*.mongo.com` and `*.mongodbgov.net` From 752a65d5bea0ab9cfd6f454170d7162dded1986c Mon Sep 17 00:00:00 2001 From: Connor MacDonald Date: Fri, 10 Jul 2026 14:18:34 -0400 Subject: [PATCH 3/3] DRIVERS-3472 test maxScramIterations=4096 --- source/uri-options/tests/auth-options.json | 11 +++++++++++ source/uri-options/tests/auth-options.yml | 9 +++++++++ 2 files changed, 20 insertions(+) diff --git a/source/uri-options/tests/auth-options.json b/source/uri-options/tests/auth-options.json index 2f3469277d..a4f94e72dc 100644 --- a/source/uri-options/tests/auth-options.json +++ b/source/uri-options/tests/auth-options.json @@ -40,6 +40,17 @@ "maxScramIterations": 123456 } }, + { + "description": "maxScramIterations of exactly 4096 does not cause a warning", + "uri": "mongodb://example.com/?maxScramIterations=4096", + "valid": true, + "warning": false, + "hosts": null, + "auth": null, + "options": { + "maxScramIterations": 4096 + } + }, { "description": "maxScramIterations with value less than 4096 causes a warning", "uri": "mongodb://example.com/?maxScramIterations=4095", diff --git a/source/uri-options/tests/auth-options.yml b/source/uri-options/tests/auth-options.yml index c8a5c8e22d..d1b5f5a330 100644 --- a/source/uri-options/tests/auth-options.yml +++ b/source/uri-options/tests/auth-options.yml @@ -32,6 +32,15 @@ tests: auth: ~ options: maxScramIterations: 123456 + - + description: "maxScramIterations of exactly 4096 does not cause a warning" + uri: "mongodb://example.com/?maxScramIterations=4096" + valid: true + warning: false + hosts: ~ + auth: ~ + options: + maxScramIterations: 4096 - description: "maxScramIterations with value less than 4096 causes a warning" uri: "mongodb://example.com/?maxScramIterations=4095"