DRIVERS-3329: Configurable DNS domain validation for SRV records

source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md

@@ -37,7 +37,8 @@ mongodb+srv://{hostname}/{options}
 `{options}` refers to the optional elements from the [Connection String](../connection-string/connection-string-spec.md)
 specification following the `Host Information`. This includes the `Auth database` and `Connection Options`.
 
-For the purposes of this document, `{hostname}` will be divided using the following terminology. If an SRV `{hostname}`
+For the purposes of this document, `{hostname}` will be divided using the following terminology. If
+`srvAllowedHostsSuffix` has been configured, then that will act as the `{domainname}`. Otherwise, if an SRV `{hostname}`
 has:
 
 1. Three or more `.` separated parts, then the left-most part is the `{subdomain}` and the remaining portion is the
@@ -65,6 +66,15 @@ Only `{domainname}` is used during SRV record verification and `{subdomain}` is
 
 ### MongoClient Configuration
 
+#### srvAllowedHostsSuffix
+
+This option is used to validate hosts. If present, its value MUST be treated as the `{domainname}` for
+[DNS validation](#querying-dns). For example, `srvAllowedHostsSuffix=.mydomain.net`. If the value does not begin with a
+`.`, for example, `srvAllowedHostsSuffix=mydomain.net`, the `.` MUST be automatically prepended prior to validation. If
+this option is not present, the `{domainname}` MUST be inferred from the `{hostname}` (as described in
+[Connection String Format](#connection-string-format)). This option MUST only be configurable at the level of a
+`MongoClient`.
+
 #### srvMaxHosts
 
 This option is used to limit the number of mongos connections that may be created for sharded topologies. This option
@@ -84,9 +94,9 @@ requires a string value and defaults to "mongodb". This option MUST only be conf
 
 #### URI Validation
 
-The driver MUST report an error if either the `srvServiceName` or `srvMaxHosts` URI options are specified with a non-SRV
-URI (i.e. scheme other than `mongodb+srv`). The driver MUST allow specifying the `srvServiceName` and `srvMaxHosts` URI
-options with an SRV URI (i.e. `mongodb+srv` scheme).
+The driver MUST report an error if any of `srvServiceName`, `srvMaxHosts`, or `srvAllowedHostsSuffix` URI options are
+specified with a non-SRV URI (i.e. scheme other than `mongodb+srv`). The driver MUST allow specifying the
+`srvServiceName`, `srvMaxHosts`, and `srvAllowedHostsSuffix` URI options with an SRV URI (i.e. `mongodb+srv` scheme).
 
 If `srvMaxHosts` is a positive integer, the driver MUST throw an error in the following cases:
 
@@ -283,6 +293,8 @@ In the future we could consider using the priority and weight fields of the SRV
 
 ## ChangeLog
 
+- 2026-06-08: Add `srvAllowedHostsSuffix` MongoClient option.
+
 - 2024-09-24: Removed requirement for URI to have three '.' separated parts; these SRVs have stricter parent domain
     matching requirements for security. Create terminology section. Remove usage of term `{TLD}`. The `{hostname}` now
     refers to the entire hostname, not just the `{subdomain}`.

source/initial-dns-seedlist-discovery/tests/replica-set/srvAllowedHostsSuffix-mismatch.yml

@@ -0,0 +1,5 @@
+# DNS record for test12.test.build.10gen.cc returns localhost.build.10gen.cc which would not match test.build.10gen.cc
+uri: "mongodb+srv://test12.test.build.10gen.cc/?srvAllowedHostsSuffix=test.build.10gen.cc"
+seeds: []
+hosts: []
+error: true

source/initial-dns-seedlist-discovery/tests/replica-set/srvAllowedHostsSuffix-with_dot.yml

@@ -0,0 +1,7 @@
+uri: "mongodb+srv://test12.test.build.10gen.cc/?srvAllowedHostsSuffix=.build.10gen.cc"
+seeds:
+    - localhost.build.10gen.cc:27017
+options:
+    srvAllowedHostsSuffix: .build.10gen.cc
+    ssl: true
+ping: false

source/initial-dns-seedlist-discovery/tests/replica-set/srvAllowedHostsSuffix-without_dot_fail.yml

@@ -0,0 +1,5 @@
+# dot should be prepended to `srvAllowedHostsSuffix` causing the host to be .uild.10gen.cc which does not match any available DNS records
+uri: "mongodb+srv://test12.test.build.10gen.cc/?srvAllowedHostsSuffix=uild.10gen.cc"
+seeds: []
+hosts: []
+error: true

source/initial-dns-seedlist-discovery/tests/replica-set/srvAllowedHostsSuffix-without_dot_pass.yml

@@ -0,0 +1,7 @@
+uri: mongodb+srv://test12.test.build.10gen.cc/?srvAllowedHostsSuffix=build.10gen.cc
+seeds:
+  - localhost.build.10gen.cc:27017
+options:
+  srvAllowedHostsSuffix: build.10gen.cc
+  ssl: true
+ping: false

source/uri-options/uri-options.md

@@ -43,9 +43,9 @@ The driver MUST report an error if the `directConnection=true` URI option is spe
 The driver MUST report an error if the `directConnection=true` URI option is specified with an SRV URI, because the URI
 may resolve to multiple hosts. The driver MUST allow specifying `directConnection=false` URI option with an SRV URI.
 
-### srvServiceName and srvMaxHosts URI options
+### srvServiceName, srvMaxHosts, and srvAllowedHostsSuffix URI options
 
-For URI option validation pertaining to `srvServiceName` and `srvMaxHosts`, please see the
+For URI option validation pertaining to `srvServiceName`, `srvMaxHosts`, and `srvAllowedHostsSuffix`, please see the
 [Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#uri-validation)
 for details.
 
@@ -104,6 +104,7 @@ to URI options apply here.
 | serverSelectionTimeoutMS             | positive integer; a driver may also accept 0 to be used for a special case, provided that it documents the meaning                                                                        | defined in [server selection spec](../server-selection/server-selection.md#serverselectiontimeoutms)                                                                                                                         | no                                                                                                                                                                                                        | A timeout in milliseconds to block for server selection before raising an error                                                                                                                                                                                                                  |
 | serverSelectionTryOnce               | "true" or "false"                                                                                                                                                                         | defined in [server selection spec](../server-selection/server-selection.md#serverselectiontryonce)                                                                                                                           | required for single-threaded drivers                                                                                                                                                                      | Scan the topology only once after a server selection failure instead of repeatedly until the server selection times out                                                                                                                                                                          |
 | socketTimeoutMS                      | non-negative integer; 0 means no timeout                                                                                                                                                  | no timeout                                                                                                                                                                                                                   | no                                                                                                                                                                                                        | NOTE: This option is deprecated in favor of [timeoutMS](../client-side-operations-timeout/client-side-operations-timeout.md#timeoutms)<br><br>Amount of time spent attempting to send or receive on a socket before timing out; note that this only applies to application operations, not SDAM. |
+| srvAllowedHostsSuffix                | a valid DNS hostname suffix (e.g. ".mydomain.net")                                                                                                                                        | none; domain is inferred from the SRV hostname                                                                                                                                                                               | no                                                                                                                                                                                                        | A hostname suffix used to validate hosts returned via SRV lookup, replacing the domain inferred from the SRV hostname. Defined in the [Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvallowedhostssuffix).                          |
 | srvMaxHosts                          | non-negative integer; 0 means no maximum                                                                                                                                                  | defined in the [Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvmaxhosts)                                                                                        | no                                                                                                                                                                                                        | The maximum number of SRV results to randomly select when initially populating the seedlist or, during SRV polling, adding new hosts to the topology.                                                                                                                                            |
 | srvServiceName                       | a valid SRV service name according to [RFC 6335](https://datatracker.ietf.org/doc/html/rfc6335#section-5.1)                                                                               | "mongodb"                                                                                                                                                                                                                    | no                                                                                                                                                                                                        | the service name to use for SRV lookup in [initial DNS seedlist discovery](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvservicename) and [SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md)                        |
 | ssl                                  | "true" or "false"                                                                                                                                                                         | same as "tls"                                                                                                                                                                                                                | no                                                                                                                                                                                                        | alias of "tls"; required to ensure that Atlas connection strings continue to work                                                                                                                                                                                                                |
@@ -184,6 +185,8 @@ changes.
 
 ## Changelog
 
+- 2026-06-08: Add `srvAllowedHostsSuffix` option.
+
 - 2024-05-08: Migrated from reStructuredText to Markdown.
 
 - 2023-08-21: Add serverMonitoringMode option.