From f27364c6f0821faf38f1e827e09776bf3142c5a5 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Thu, 8 Aug 2024 17:03:25 -0400 Subject: [PATCH 01/27] feat(DRIVERS-2922): loosen options parser restrictions lint clarify fix capitalization --- .../initial-dns-seedlist-discovery.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 0e3da0797a..d045ee72a5 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -82,8 +82,7 @@ It is an error to specify more than one host name in a connection string with th MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. A driver MUST verify that in addition to the `{hostname}`, the `{domainname}` consists of at least two parts: the domain -name, and a TLD. Drivers MUST raise an error and MUST NOT contact the DNS server to obtain SRV (or TXT records) if the -full URI does not consist of at least three parts. +name, and a TLD. In the case that an SRV or TXT record does not have three parts prior to DNS resolution, drivers MUST NOT throw an error. If `mongodb+srv` is used, a driver MUST implicitly also enable TLS. Clients can turn this off by passing `tls=false` in either the Connection String, or options passed in as parameters in code to the MongoClient constructor (or equivalent From 238538229cfeb60967d1ddb43af550766c2b7eb3 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Wed, 14 Aug 2024 11:19:26 -0400 Subject: [PATCH 02/27] add test criteria --- .../initial-dns-seedlist-discovery.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index d045ee72a5..6b0736285c 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -81,8 +81,7 @@ parse error and MUST NOT do DNS resolution or contact hosts. It is an error to specify more than one host name in a connection string with the `mongodb+srv` protocol, and the driver MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. -A driver MUST verify that in addition to the `{hostname}`, the `{domainname}` consists of at least two parts: the domain -name, and a TLD. In the case that an SRV or TXT record does not have three parts prior to DNS resolution, drivers MUST NOT throw an error. +In the case that an hostname does not have a `{hostname}` and a `{domainname}` (consisting of a domain name and a TLD) prior to DNS resolution, drivers MUST NOT throw an error. If `mongodb+srv` is used, a driver MUST implicitly also enable TLS. Clients can turn this off by passing `tls=false` in either the Connection String, or options passed in as parameters in code to the MongoClient constructor (or equivalent @@ -199,11 +198,28 @@ mongodb://mongodb1.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true&replic ## Test Plan +### Spec Tests See README.md in the accompanying [test directory](tests). Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the [Connection String Spec tests](../connection-string/tests). +### Prose Tests +* Test #1: The driver should not throw an error when given a SRV record that only contains the name of the domain and the TLD. + + * Stub external DNS resolution to always pass (ex: `dns.lookup`). + + * Assert that creating a client with the uri `mongodb+srv//mongodb.localhost` does not cause an error. + + * Assert that connecting the client from 2. to the server does not cause an error. + +* Test #2: The driver should not throw an error when given a SRV record that only contains the TLD. + * Stub external DNS resolution to always pass (ex: `dns.lookup`). + + * Assert that creating a client with the uri `mongodb+srv//localhost` does not cause an error. + + * Assert that connecting the client from 2. to the server does not cause an error. + ## Motivation Several of our users have asked for this through tickets: From 18737431b21be4b12728ef5079598c15969b08ac Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Wed, 14 Aug 2024 11:32:47 -0400 Subject: [PATCH 03/27] grammar fix --- .../initial-dns-seedlist-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 6b0736285c..61fd4c16d5 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -211,14 +211,14 @@ Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the * Assert that creating a client with the uri `mongodb+srv//mongodb.localhost` does not cause an error. - * Assert that connecting the client from 2. to the server does not cause an error. + * Assert that connecting the client to the server does not cause an error. * Test #2: The driver should not throw an error when given a SRV record that only contains the TLD. * Stub external DNS resolution to always pass (ex: `dns.lookup`). * Assert that creating a client with the uri `mongodb+srv//localhost` does not cause an error. - * Assert that connecting the client from 2. to the server does not cause an error. + * Assert that connecting the client to the server does not cause an error. ## Motivation From fbacddbb715a36c749f2fe35fcc0057ad47248d2 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Thu, 15 Aug 2024 13:56:50 -0400 Subject: [PATCH 04/27] wording fix --- .../initial-dns-seedlist-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 61fd4c16d5..3c5ddd3e68 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -205,7 +205,7 @@ Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the [Connection String Spec tests](../connection-string/tests). ### Prose Tests -* Test #1: The driver should not throw an error when given a SRV record that only contains the name of the domain and the TLD. +* Test #1: The driver should not throw an error when given a valid SRV record that only contains the name of the domain and the TLD. * Stub external DNS resolution to always pass (ex: `dns.lookup`). @@ -213,7 +213,7 @@ Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the * Assert that connecting the client to the server does not cause an error. -* Test #2: The driver should not throw an error when given a SRV record that only contains the TLD. +* Test #2: The driver should not throw an error when given a valid SRV record that only contains the TLD. * Stub external DNS resolution to always pass (ex: `dns.lookup`). * Assert that creating a client with the uri `mongodb+srv//localhost` does not cause an error. From b052a3adf4b86cdfaab8dd88d70f7e86ea04195d Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 20 Aug 2024 15:52:55 -0400 Subject: [PATCH 05/27] temp commit - changing terminology --- .../initial-dns-seedlist-discovery.md | 40 ++++++++----------- .../tests/README.md | 16 ++++++++ 2 files changed, 33 insertions(+), 23 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 3c5ddd3e68..117882b60f 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -31,7 +31,7 @@ step before it considers the connection string and SDAM specifications. In this host names is replaced with a single host name. The format is: ``` -mongodb+srv://{hostname}.{domainname}/{options} +mongodb+srv://{subdomain}.{domainname}/{options} ``` `{options}` refers to the optional elements from the [Connection String](../connection-string/connection-string-spec.md) @@ -81,7 +81,15 @@ parse error and MUST NOT do DNS resolution or contact hosts. It is an error to specify more than one host name in a connection string with the `mongodb+srv` protocol, and the driver MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. -In the case that an hostname does not have a `{hostname}` and a `{domainname}` (consisting of a domain name and a TLD) prior to DNS resolution, drivers MUST NOT throw an error. +Prior to DNS resolution. `{hostname}` format can follow any of the following formats: +* `{subdomain}`.`{second-level domain}`.`{top-level domain}` +* `{second-level domain}`.`{top-level domain}` +* `{top-level domain}` + +For the purposes of this document, `{domainname}` refers to all parts of the host that are not the `{subdomain}`. + + +Node: If `mongodb+srv` is used, a driver MUST implicitly also enable TLS. Clients can turn this off by passing `tls=false` in either the Connection String, or options passed in as parameters in code to the MongoClient constructor (or equivalent @@ -89,10 +97,10 @@ API for each driver), but not through a TXT record (discussed in a later section #### Querying DNS -In this preprocessing step, the driver will query the DNS server for SRV records on `{hostname}.{domainname}`, prefixed +In this preprocessing step, the driver will query the DNS server for SRV records on the hostname, prefixed with the SRV service name and protocol. The SRV service name is provided in the `srvServiceName` URI option and defaults to `mongodb`. The protocol is always `tcp`. After prefixing, the URI should look like: -`_{srvServiceName}._tcp.{hostname}.{domainname}`. This DNS query is expected to respond with one or more SRV records. +`_{srvServiceName}._tcp.{hostname}`. This DNS query is expected to respond with one or more SRV records. The priority and weight fields in returned SRV records MUST be ignored. @@ -116,7 +124,7 @@ randomization. ### Default Connection String Options -As a second preprocessing step, a Client MUST also query the DNS server for TXT records on `{hostname}.{domainname}`. If +As a second preprocessing step, a Client MUST also query the DNS server for TXT records on `{subdomain}.{domainname}`. If available, a TXT record provides default connection string options. The maximum length of a TXT record string is 255 characters, but there can be multiple strings per TXT record. A Client MUST support multiple TXT record strings and concatenate them as if they were one single string in the order they are defined in each TXT record. The order of @@ -146,7 +154,7 @@ the Connection String spec. ### CNAME not supported -The use of DNS CNAME records is not supported. Clients MUST NOT check for a CNAME record on `{hostname}.{domainname}`. A +The use of DNS CNAME records is not supported. Clients MUST NOT check for a CNAME record on `{subdomain}.{domainname}`. A system's DNS resolver could transparently handle CNAME, but because of how clients validate records returned from SRV queries, use of CNAME could break validation. Seedlist discovery therefore does not recommend or support the use of CNAME records in concert with SRV or TXT records. @@ -204,22 +212,6 @@ See README.md in the accompanying [test directory](tests). Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the [Connection String Spec tests](../connection-string/tests). -### Prose Tests -* Test #1: The driver should not throw an error when given a valid SRV record that only contains the name of the domain and the TLD. - - * Stub external DNS resolution to always pass (ex: `dns.lookup`). - - * Assert that creating a client with the uri `mongodb+srv//mongodb.localhost` does not cause an error. - - * Assert that connecting the client to the server does not cause an error. - -* Test #2: The driver should not throw an error when given a valid SRV record that only contains the TLD. - * Stub external DNS resolution to always pass (ex: `dns.lookup`). - - * Assert that creating a client with the uri `mongodb+srv//localhost` does not cause an error. - - * Assert that connecting the client to the server does not cause an error. - ## Motivation Several of our users have asked for this through tickets: @@ -269,6 +261,8 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog +- 2024-08-20: Removed requirement for URI to have three '.' separated parts + - 2024-03-06: Migrated from reStructuredText to Markdown. - 2022-10-05: Revise spec front matter and reformat changelog. @@ -320,4 +314,4 @@ In the future we could consider using the priority and weight fields of the SRV - 2017-09-01: Updated test plan with YAML tests, and moved prose tests for URI\ parsing into invalid-uris.yml in the - Connection String Spec tests. + Connection String Spec tests. \ No newline at end of file diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 50a77cb3f8..8b82705f0b 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -3,6 +3,22 @@ This directory contains platform-independent tests that drivers can use to prove their conformance to the Initial DNS Seedlist Discovery spec. +### Prose Tests +* Test #1: The driver should not throw an error when given a valid SRV record that only contains the name of the domain and the TLD. + + * Stub external DNS resolution to always pass (ex: `dns.lookup`). + + * Assert that creating a client with the uri `mongodb+srv//mongodb.localhost` does not cause an error. + + * Assert that connecting the client to the server does not cause an error. + +* Test #2: The driver should not throw an error when given a valid SRV record that only contains the TLD. + * Stub external DNS resolution to always pass (ex: `dns.lookup`). + + * Assert that creating a client with the uri `mongodb+srv//localhost` does not cause an error. + + * Assert that connecting the client to the server does not cause an error. + ## Test Setup The tests in the `replica-set` directory MUST be executed against a three-node replica set on localhost ports 27017, From 73f7dac4f1d339663be220c64bba9fffe18f61cd Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 20 Aug 2024 16:30:19 -0400 Subject: [PATCH 06/27] change terminology --- .../initial-dns-seedlist-discovery.md | 12 ++++++------ .../tests/README.md | 18 ++++-------------- 2 files changed, 10 insertions(+), 20 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 117882b60f..22f7e9b611 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -82,11 +82,11 @@ It is an error to specify more than one host name in a connection string with th MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. Prior to DNS resolution. `{hostname}` format can follow any of the following formats: -* `{subdomain}`.`{second-level domain}`.`{top-level domain}` -* `{second-level domain}`.`{top-level domain}` -* `{top-level domain}` +* `{subdomain}`.`{second-level domain}`.`{top-level domain}` (ex: `{blogs.mongodb.com}`) +* `{second-level domain}`.`{top-level domain}` (ex: `{mongodb.localhost}`) +* `{top-level domain}` (ex: `{localhost}`) -For the purposes of this document, `{domainname}` refers to all parts of the host that are not the `{subdomain}`. +For the purposes of this document, `{domainname}` refers to all parts of the hostname, excluding the `{subdomain}`. Node: @@ -124,7 +124,7 @@ randomization. ### Default Connection String Options -As a second preprocessing step, a Client MUST also query the DNS server for TXT records on `{subdomain}.{domainname}`. If +As a second preprocessing step, a Client MUST also query the DNS server for TXT records on `{hostname}`. If available, a TXT record provides default connection string options. The maximum length of a TXT record string is 255 characters, but there can be multiple strings per TXT record. A Client MUST support multiple TXT record strings and concatenate them as if they were one single string in the order they are defined in each TXT record. The order of @@ -154,7 +154,7 @@ the Connection String spec. ### CNAME not supported -The use of DNS CNAME records is not supported. Clients MUST NOT check for a CNAME record on `{subdomain}.{domainname}`. A +The use of DNS CNAME records is not supported. Clients MUST NOT check for a CNAME record on `{hostname}`. A system's DNS resolver could transparently handle CNAME, but because of how clients validate records returned from SRV queries, use of CNAME could break validation. Seedlist discovery therefore does not recommend or support the use of CNAME records in concert with SRV or TXT records. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 8b82705f0b..f42a7b2be6 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -4,20 +4,10 @@ This directory contains platform-independent tests that drivers can use to prove Seedlist Discovery spec. ### Prose Tests -* Test #1: The driver should not throw an error when given a valid SRV record that only contains the name of the domain and the TLD. - - * Stub external DNS resolution to always pass (ex: `dns.lookup`). - - * Assert that creating a client with the uri `mongodb+srv//mongodb.localhost` does not cause an error. - - * Assert that connecting the client to the server does not cause an error. - -* Test #2: The driver should not throw an error when given a valid SRV record that only contains the TLD. - * Stub external DNS resolution to always pass (ex: `dns.lookup`). - - * Assert that creating a client with the uri `mongodb+srv//localhost` does not cause an error. - - * Assert that connecting the client to the server does not cause an error. +When given a valid SRV with +1. Only one domain level (ex: `{localhost}`) +2. Only two domain levels (ex: `{mongo.local}`) + ## Test Setup From 726d576c864c16a589ac6af91ad78449e4b3a7ce Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 20 Aug 2024 17:00:38 -0400 Subject: [PATCH 07/27] update changelog --- .../initial-dns-seedlist-discovery.md | 2 +- source/initial-dns-seedlist-discovery/tests/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 22f7e9b611..f9a5078c77 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -261,7 +261,7 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog -- 2024-08-20: Removed requirement for URI to have three '.' separated parts +- 2024-08-20: Removed requirement for URI to have three '.' separated parts. Replace usage of 'TLD' with 'top-level domain'. `{hostname}` now refers to the entire hostname, not just the `{subdomain}`. - 2024-03-06: Migrated from reStructuredText to Markdown. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index f42a7b2be6..d71b4864a5 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -4,10 +4,10 @@ This directory contains platform-independent tests that drivers can use to prove Seedlist Discovery spec. ### Prose Tests -When given a valid SRV with +When given a valid SRV with 1. Only one domain level (ex: `{localhost}`) 2. Only two domain levels (ex: `{mongo.local}`) - +Parse the connection string without throwing a parse related error. ## Test Setup From 81f43dab41bbeeece067632fa5a90decc0e4178d Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 20 Aug 2024 17:43:46 -0400 Subject: [PATCH 08/27] add in prose test ref --- .../initial-dns-seedlist-discovery.md | 48 +++++++++++-------- .../tests/README.md | 5 +- 2 files changed, 30 insertions(+), 23 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index f9a5078c77..69f0c7c0b1 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -82,12 +82,12 @@ It is an error to specify more than one host name in a connection string with th MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. Prior to DNS resolution. `{hostname}` format can follow any of the following formats: -* `{subdomain}`.`{second-level domain}`.`{top-level domain}` (ex: `{blogs.mongodb.com}`) -* `{second-level domain}`.`{top-level domain}` (ex: `{mongodb.localhost}`) -* `{top-level domain}` (ex: `{localhost}`) -For the purposes of this document, `{domainname}` refers to all parts of the hostname, excluding the `{subdomain}`. +- `{subdomain}`.`{second-level domain}`.`{top-level domain}` (ex: `{blogs.mongodb.com}`) +- `{second-level domain}`.`{top-level domain}` (ex: `{mongodb.localhost}`) +- `{top-level domain}` (ex: `{localhost}`) +For the purposes of this document, `{domainname}` refers to all parts of the hostname, excluding the `{subdomain}`. Node: @@ -97,10 +97,10 @@ API for each driver), but not through a TXT record (discussed in a later section #### Querying DNS -In this preprocessing step, the driver will query the DNS server for SRV records on the hostname, prefixed -with the SRV service name and protocol. The SRV service name is provided in the `srvServiceName` URI option and defaults -to `mongodb`. The protocol is always `tcp`. After prefixing, the URI should look like: -`_{srvServiceName}._tcp.{hostname}`. This DNS query is expected to respond with one or more SRV records. +In this preprocessing step, the driver will query the DNS server for SRV records on the hostname, prefixed with the SRV +service name and protocol. The SRV service name is provided in the `srvServiceName` URI option and defaults to +`mongodb`. The protocol is always `tcp`. After prefixing, the URI should look like: `_{srvServiceName}._tcp.{hostname}`. +This DNS query is expected to respond with one or more SRV records. The priority and weight fields in returned SRV records MUST be ignored. @@ -124,12 +124,12 @@ randomization. ### Default Connection String Options -As a second preprocessing step, a Client MUST also query the DNS server for TXT records on `{hostname}`. If -available, a TXT record provides default connection string options. The maximum length of a TXT record string is 255 -characters, but there can be multiple strings per TXT record. A Client MUST support multiple TXT record strings and -concatenate them as if they were one single string in the order they are defined in each TXT record. The order of -multiple character strings in each TXT record is guaranteed. A Client MUST NOT allow multiple TXT records for the same -host name and MUST raise an error when multiple TXT records are encountered. +As a second preprocessing step, a Client MUST also query the DNS server for TXT records on `{hostname}`. If available, a +TXT record provides default connection string options. The maximum length of a TXT record string is 255 characters, but +there can be multiple strings per TXT record. A Client MUST support multiple TXT record strings and concatenate them as +if they were one single string in the order they are defined in each TXT record. The order of multiple character strings +in each TXT record is guaranteed. A Client MUST NOT allow multiple TXT records for the same host name and MUST raise an +error when multiple TXT records are encountered. Information returned within a TXT record is a simple URI string, just like the `{options}` in a connection string. @@ -154,10 +154,10 @@ the Connection String spec. ### CNAME not supported -The use of DNS CNAME records is not supported. Clients MUST NOT check for a CNAME record on `{hostname}`. A -system's DNS resolver could transparently handle CNAME, but because of how clients validate records returned from SRV -queries, use of CNAME could break validation. Seedlist discovery therefore does not recommend or support the use of -CNAME records in concert with SRV or TXT records. +The use of DNS CNAME records is not supported. Clients MUST NOT check for a CNAME record on `{hostname}`. A system's DNS +resolver could transparently handle CNAME, but because of how clients validate records returned from SRV queries, use of +CNAME could break validation. Seedlist discovery therefore does not recommend or support the use of CNAME records in +concert with SRV or TXT records. ## Example @@ -206,7 +206,12 @@ mongodb://mongodb1.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true&replic ## Test Plan -### Spec Tests +### Prose Tests + +See README.md in the accompanying [test directory](tests). + +### Spec Tests + See README.md in the accompanying [test directory](tests). Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the @@ -261,7 +266,8 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog -- 2024-08-20: Removed requirement for URI to have three '.' separated parts. Replace usage of 'TLD' with 'top-level domain'. `{hostname}` now refers to the entire hostname, not just the `{subdomain}`. +- 2024-08-20: Removed requirement for URI to have three '.' separated parts. Replace usage of 'TLD' with 'top-level + domain'. `{hostname}` now refers to the entire hostname, not just the `{subdomain}`. - 2024-03-06: Migrated from reStructuredText to Markdown. @@ -314,4 +320,4 @@ In the future we could consider using the priority and weight fields of the SRV - 2017-09-01: Updated test plan with YAML tests, and moved prose tests for URI\ parsing into invalid-uris.yml in the - Connection String Spec tests. \ No newline at end of file + Connection String Spec tests. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index d71b4864a5..401ba29c1a 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -4,10 +4,11 @@ This directory contains platform-independent tests that drivers can use to prove Seedlist Discovery spec. ### Prose Tests + When given a valid SRV with + 1. Only one domain level (ex: `{localhost}`) -2. Only two domain levels (ex: `{mongo.local}`) -Parse the connection string without throwing a parse related error. +2. Only two domain levels (ex: `{mongo.local}`) Parse the connection string without throwing a parse related error. ## Test Setup From d3630899865a6f6660587ac0bd5be384d0a4d555 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 23 Aug 2024 19:06:54 -0400 Subject: [PATCH 09/27] add parent matching requirements --- .../initial-dns-seedlist-discovery.md | 36 +++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 69f0c7c0b1..ca1653b71e 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -81,20 +81,30 @@ parse error and MUST NOT do DNS resolution or contact hosts. It is an error to specify more than one host name in a connection string with the `mongodb+srv` protocol, and the driver MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. -Prior to DNS resolution. `{hostname}` format can follow any of the following formats: - -- `{subdomain}`.`{second-level domain}`.`{top-level domain}` (ex: `{blogs.mongodb.com}`) -- `{second-level domain}`.`{top-level domain}` (ex: `{mongodb.localhost}`) -- `{top-level domain}` (ex: `{localhost}`) - -For the purposes of this document, `{domainname}` refers to all parts of the hostname, excluding the `{subdomain}`. - Node: If `mongodb+srv` is used, a driver MUST implicitly also enable TLS. Clients can turn this off by passing `tls=false` in either the Connection String, or options passed in as parameters in code to the MongoClient constructor (or equivalent API for each driver), but not through a TXT record (discussed in a later section). +#### Terminology + +For the purposes of this document, `{hostname}` will be divided using the following terminology. + +If an SRV `{hostname}` has: + +- 3 or more `.` separated parts: + - the left-most part is the `{subdomain}` + - the remaining portion is the `{domain}` + - examples: + - `{cluster_1.tests.mongodb.co.uk}` + - `{hosts_34.example.com}` +- have 1 or 2 `.` separated part(s): + - the `{hostname}` is equivalent to the `{domain}` + - examples: + - `{localhost}` + - `{mongodb.local}` + #### Querying DNS In this preprocessing step, the driver will query the DNS server for SRV records on the hostname, prefixed with the SRV @@ -108,10 +118,14 @@ If the DNS result returns no SRV records, or no records at all, or a DNS error h indicating that the URI could not be used to find hostnames. The error SHALL include the reason why they could not be found. -A driver MUST verify that the host names returned through SRV records have the same parent `{domainname}`. Drivers MUST -raise an error and MUST NOT initiate a connection to any returned host name which does not share the same +A driver MUST verify that the host names returned through SRV records end with the original SRV's `{domainname}`. +Drivers MUST raise an error and MUST NOT initiate a connection to any returned host name which does not share the same `{domainname}`. +In the case that the SRV record has less than three `.` separated parts, the returned address MUST NOT be identical to +the original `{hostname}`. The next major version should the host names returned through all SRVs require to end with +the entire `{hostname}`. + The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. If `srvMaxHosts` is zero or greater than or equal to the number of hosts in the DNS result, the driver MUST populate the @@ -175,7 +189,7 @@ _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27317 mongodb1. _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27017 mongodb2.mongodb.com. ``` -The returned host names (`mongodb1.mongodb.com` and `mongodb2.mongodb.com`) must share the same parent domain name +The returned host names (`mongodb1.mongodb.com` and `mongodb2.mongodb.com`) must end with the same domain name (`mongodb.com`) as the provided host name (`server.mongodb.com`). The driver also needs to request the DNS server for the TXT records on `server.mongodb.com`. This could return: From 914487962c9bdf5fc61a951d39108cbf719c65ca Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 23 Aug 2024 19:11:12 -0400 Subject: [PATCH 10/27] update changelod --- .../initial-dns-seedlist-discovery.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index ca1653b71e..6835dba095 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -280,8 +280,10 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog -- 2024-08-20: Removed requirement for URI to have three '.' separated parts. Replace usage of 'TLD' with 'top-level - domain'. `{hostname}` now refers to the entire hostname, not just the `{subdomain}`. +- 2024-08-20: Removed requirement for URI to have three '.' separated parts; these SRVs have stricter parent domain + matching requirements for security. SRVs with three or more parts should have stricter matching requirements in next + major version. Create terminology section. Remove usage of term `{TLD}`. The `{hostname}` now refers to the entire + hostname, not just the `{subdomain}`. - 2024-03-06: Migrated from reStructuredText to Markdown. From da904905259f4b584020b1c84751441e6c287584 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 3 Sep 2024 15:24:53 -0400 Subject: [PATCH 11/27] added in new prose test requirements + fixed formatting --- .../tests/README.md | 24 ++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 401ba29c1a..3ec0e82d77 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -5,10 +5,28 @@ Seedlist Discovery spec. ### Prose Tests -When given a valid SRV with +1. When given the following valid SRVs, parse the connection string without throwing a parse related error. -1. Only one domain level (ex: `{localhost}`) -2. Only two domain levels (ex: `{mongo.local}`) Parse the connection string without throwing a parse related error. + a. Only one domain level (ex: `mongodb+srv://localhost`). + + b. Only two domain levels (ex: `mongodb+srv://mongo.local`). + +
+ +2. When given an SRV that does NOT end with the original SRV's `{domainname}`, throw a runtime error. + + For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error. + + Run this test for the following test cases: SRVs with one, two, and three `.` separated parts. + +
+ +3. When given an SRV with less than three `.` separated parts that returns identical address to the original + `{hostname}`, throw a runtime error. + + For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error. + + Run this test for both cases: one and two `.` separated parts. ## Test Setup From ff800b4f7a8b143a53e1d69e0be83b640a2095e7 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 3 Sep 2024 17:50:59 -0400 Subject: [PATCH 12/27] requested changes --- .vscode/settings.json | 5 ++ .../initial-dns-seedlist-discovery.md | 55 +++++++++++-------- .../tests/README.md | 24 ++++---- 3 files changed, 50 insertions(+), 34 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..dba0a6b5b3 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cSpell.words": [ + "domainname" + ] +} \ No newline at end of file diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 6835dba095..18b89fc706 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -9,9 +9,9 @@ ______________________________________________________________________ Presently, seeding a driver with an initial list of ReplicaSet or MongoS addresses is somewhat cumbersome, requiring a comma-delimited list of host names to attempt connections to. A standardized answer to this problem exists in the form -of SRV records, which allow administrators to configure a single domain to return a list of host names. Supporting this -feature would assist our users by decreasing maintenance load, primarily by removing the need to maintain seed lists at -an application level. +of SRV records, which allow administrators to configure a single hostname to return a list of host names. Supporting +this feature would assist our users by decreasing maintenance load, primarily by removing the need to maintain seed +lists at an application level. This specification builds on the [Connection String](../connection-string/connection-string-spec.md) specification. It adds a new protocol scheme and modifies how the @@ -37,6 +37,30 @@ mongodb+srv://{subdomain}.{domainname}/{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}` +has: + +1. Three or more `.` separated parts, then the left-most part is the `{subdomain}` and the remaining portion is the + `{domainname}`. + + - Examples: + - `{hostname}` = `cluster_1.tests.mongodb.co.uk` + + - `{subdomain}` = `cluster_1` + - `{domainname}` = `tests.mongodb.co.uk` + + - `{hostname}` = `hosts_34.example.com` + + - `{subdomain}` = `hosts_34` + - `{domainname}` = `example.com` + +2. One or two `.` separated part(s), then the `{hostname}` is equivalent to the `{domainname}`, and there is no + subdomain. + + - Examples: + - `{hostname}` = `{domainname}` = `localhost` + - `{hostname}` = `{domainname}` = `mongodb.local` + ### MongoClient Configuration #### srvMaxHosts @@ -87,24 +111,6 @@ If `mongodb+srv` is used, a driver MUST implicitly also enable TLS. Clients can either the Connection String, or options passed in as parameters in code to the MongoClient constructor (or equivalent API for each driver), but not through a TXT record (discussed in a later section). -#### Terminology - -For the purposes of this document, `{hostname}` will be divided using the following terminology. - -If an SRV `{hostname}` has: - -- 3 or more `.` separated parts: - - the left-most part is the `{subdomain}` - - the remaining portion is the `{domain}` - - examples: - - `{cluster_1.tests.mongodb.co.uk}` - - `{hosts_34.example.com}` -- have 1 or 2 `.` separated part(s): - - the `{hostname}` is equivalent to the `{domain}` - - examples: - - `{localhost}` - - `{mongodb.local}` - #### Querying DNS In this preprocessing step, the driver will query the DNS server for SRV records on the hostname, prefixed with the SRV @@ -122,9 +128,10 @@ A driver MUST verify that the host names returned through SRV records end with t Drivers MUST raise an error and MUST NOT initiate a connection to any returned host name which does not share the same `{domainname}`. -In the case that the SRV record has less than three `.` separated parts, the returned address MUST NOT be identical to -the original `{hostname}`. The next major version should the host names returned through all SRVs require to end with -the entire `{hostname}`. +In the case that the SRV record has less than three `.` separated parts, the returned address MUST must end with the +SRV's entire `{hostname}` and MUST NOT be identical to the original `{hostname}`. The next major version MUST no longer +allow an SRV record, with any number of parts, to return address that doesn't end with the SRVs' entire `{hostname}`. +Drivers MUST document this in a prior minor release. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 3ec0e82d77..d4fccb6ae4 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -5,28 +5,32 @@ Seedlist Discovery spec. ### Prose Tests -1. When given the following valid SRVs, parse the connection string without throwing a parse related error. +For the following prose tests, it is assumed drivers are be able to stub DNS results to easily test invalid DNS +resolution results. - a. Only one domain level (ex: `mongodb+srv://localhost`). +1. When given the following valid SRVs, the pre-DNS SRV validation step not cause any errors. - b. Only two domain levels (ex: `mongodb+srv://mongo.local`). + a. Only one domain level: `mongodb+srv://localhost`. + + b. Only two domain levels: `mongodb+srv://mongo.local`.
-2. When given an SRV that does NOT end with the original SRV's `{domainname}`, throw a runtime error. +2. For the following steps, run each of these cases: SRVs with one, two, and three `.` separated parts. - For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error. + When given an SRV that does NOT end with the original SRV's domain name, throw a runtime error. - Run this test for the following test cases: SRVs with one, two, and three `.` separated parts. + For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error, since + the returned address does not end with `mongodb.com`.
-3. When given an SRV with less than three `.` separated parts that returns identical address to the original - `{hostname}`, throw a runtime error. +3. For the following steps, run each of these cases: SRVs with one, and two `.` separated parts. - For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error. + When given an SRV that returns identical address to the original hostname, throw a runtime error. - Run this test for both cases: one and two `.` separated parts. + For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since it is + identical to the original hostname. ## Test Setup From b26afc2797929134184fa261c87fd036e50a721f Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Wed, 4 Sep 2024 15:32:42 -0400 Subject: [PATCH 13/27] requested changes 2 --- .../initial-dns-seedlist-discovery.md | 8 +++--- .../tests/README.md | 26 ++++++++----------- 2 files changed, 15 insertions(+), 19 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 18b89fc706..4c836f0773 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -128,10 +128,10 @@ A driver MUST verify that the host names returned through SRV records end with t Drivers MUST raise an error and MUST NOT initiate a connection to any returned host name which does not share the same `{domainname}`. -In the case that the SRV record has less than three `.` separated parts, the returned address MUST must end with the -SRV's entire `{hostname}` and MUST NOT be identical to the original `{hostname}`. The next major version MUST no longer -allow an SRV record, with any number of parts, to return address that doesn't end with the SRVs' entire `{hostname}`. -Drivers MUST document this in a prior minor release. +In the case that the SRV record has less than three `.` separated parts, the returned address MUST end with the SRV's +entire `{hostname}` and MUST NOT be identical to the original `{hostname}`. The next major version MUST no longer allow +an SRV record, with any number of parts, to return address that doesn't end with the SRVs' entire `{hostname}`. Drivers +MUST document this in a prior minor release. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index d4fccb6ae4..c9c4d1477b 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -8,29 +8,25 @@ Seedlist Discovery spec. For the following prose tests, it is assumed drivers are be able to stub DNS results to easily test invalid DNS resolution results. -1. When given the following valid SRVs, the pre-DNS SRV validation step not cause any errors. +#### 1. When given the following valid SRVs, the pre-DNS SRV validation step not cause any errors. - a. Only one domain level: `mongodb+srv://localhost`. +a. Only one domain level: `mongodb+srv://localhost`. - b. Only two domain levels: `mongodb+srv://mongo.local`. +b. Only two domain levels: `mongodb+srv://mongo.local`. -
+#### 2. For the following steps, run each of these cases: SRVs with one, two, and three `.` separated parts. -2. For the following steps, run each of these cases: SRVs with one, two, and three `.` separated parts. +When given an SRV that does NOT end with the original SRV's domain name, throw a runtime error. - When given an SRV that does NOT end with the original SRV's domain name, throw a runtime error. +For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error, since the +returned address does not end with `mongodb.com`. - For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error, since - the returned address does not end with `mongodb.com`. +#### 3. For the following steps, run each of these cases: SRVs with one, and two `.` separated parts. -
+When given an SRV that returns identical address to the original hostname, throw a runtime error. -3. For the following steps, run each of these cases: SRVs with one, and two `.` separated parts. - - When given an SRV that returns identical address to the original hostname, throw a runtime error. - - For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since it is - identical to the original hostname. +For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since it is identical +to the original hostname. ## Test Setup From a02975318dbd24b6f3a849580c98cdfec8ce6405 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Thu, 5 Sep 2024 13:31:21 -0400 Subject: [PATCH 14/27] uniform formatting + fix typo --- .../tests/README.md | 30 ++++++++++++------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index c9c4d1477b..9aae27f263 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -3,30 +3,40 @@ This directory contains platform-independent tests that drivers can use to prove their conformance to the Initial DNS Seedlist Discovery spec. -### Prose Tests +## Prose Tests For the following prose tests, it is assumed drivers are be able to stub DNS results to easily test invalid DNS resolution results. -#### 1. When given the following valid SRVs, the pre-DNS SRV validation step not cause any errors. +### 1. Allow SRVs with less than 3 `.` separated parts -a. Only one domain level: `mongodb+srv://localhost`. +For the following test, run each of these cases: SRVs with one and two `.` separated parts. -b. Only two domain levels: `mongodb+srv://mongo.local`. +When running validation on an SRV string before DNS resolution, do not throw a error due to number of SRV parts. -#### 2. For the following steps, run each of these cases: SRVs with one, two, and three `.` separated parts. +For example, `mongodb+srv://localhost` is a valid SRV string with one part/one domain level, and +`mongodb+srv://mongo.local` is a valid SRV string with two parts/two domain levels. -When given an SRV that does NOT end with the original SRV's domain name, throw a runtime error. +### 2. Throw when return address does not end with SRV domain + +For the following test, run each of these cases: SRVs with one, two, and three `.` separated parts. + +When given a returned address that does NOT end with the original SRV's domain name, throw a runtime error. For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error, since the returned address does not end with `mongodb.com`. -#### 3. For the following steps, run each of these cases: SRVs with one, and two `.` separated parts. +Importantly, the domain of an SRV with one or two parts is its entire hostname. For example, the domain of +`mongodb+srv://mySite.com` is `mySite.com`. If this SRV resolves to `evil.com`, this should prompt an error. + +### 3. Throw when return address is identical to SRV hostname + +For the following test, run each of these cases: SRVs with one and two `.` separated parts. -When given an SRV that returns identical address to the original hostname, throw a runtime error. +When given a returned address that is identical to the original hostname, throw a runtime error. -For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since it is identical -to the original hostname. +For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since the returned +address is identical to the original hostname. ## Test Setup From 43785b2f5b7edfac2f81f51672c492f1c81c61f8 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 6 Sep 2024 11:36:47 -0400 Subject: [PATCH 15/27] team review requested changes --- .../initial-dns-seedlist-discovery.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 4c836f0773..51dcfb657a 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -9,7 +9,7 @@ ______________________________________________________________________ Presently, seeding a driver with an initial list of ReplicaSet or MongoS addresses is somewhat cumbersome, requiring a comma-delimited list of host names to attempt connections to. A standardized answer to this problem exists in the form -of SRV records, which allow administrators to configure a single hostname to return a list of host names. Supporting +of SRV records, which allow administrators to configure a single SRV record to return a list of host names. Supporting this feature would assist our users by decreasing maintenance load, primarily by removing the need to maintain seed lists at an application level. @@ -31,7 +31,7 @@ step before it considers the connection string and SDAM specifications. In this host names is replaced with a single host name. The format is: ``` -mongodb+srv://{subdomain}.{domainname}/{options} +mongodb+srv://{hostname}/{options} ``` `{options}` refers to the optional elements from the [Connection String](../connection-string/connection-string-spec.md) @@ -105,8 +105,6 @@ parse error and MUST NOT do DNS resolution or contact hosts. It is an error to specify more than one host name in a connection string with the `mongodb+srv` protocol, and the driver MUST raise a parse error and MUST NOT do DNS resolution or contact hosts. -Node: - If `mongodb+srv` is used, a driver MUST implicitly also enable TLS. Clients can turn this off by passing `tls=false` in either the Connection String, or options passed in as parameters in code to the MongoClient constructor (or equivalent API for each driver), but not through a TXT record (discussed in a later section). @@ -129,9 +127,9 @@ Drivers MUST raise an error and MUST NOT initiate a connection to any returned h `{domainname}`. In the case that the SRV record has less than three `.` separated parts, the returned address MUST end with the SRV's -entire `{hostname}` and MUST NOT be identical to the original `{hostname}`. The next major version MUST no longer allow -an SRV record, with any number of parts, to return address that doesn't end with the SRVs' entire `{hostname}`. Drivers -MUST document this in a prior minor release. +entire `{hostname}` and MUST have at least one more domain level than the `{hostname}`. The next major version MUST no +longer allow an SRV record, with any number of parts, to return an address that doesn't end with the SRVs' entire +`{hostname}`. Drivers MUST document this in a prior minor release. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. From be32cbbb1d35856caf2e5c6deec27647bf5f099d Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 6 Sep 2024 11:38:46 -0400 Subject: [PATCH 16/27] team review requested changes --- .vscode/settings.json | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index dba0a6b5b3..0000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "cSpell.words": [ - "domainname" - ] -} \ No newline at end of file From cf83c95043db59b8407f5cc1a9fef81e71c5bda3 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 13 Sep 2024 15:15:19 -0400 Subject: [PATCH 17/27] team review requested changes 2 --- .../initial-dns-seedlist-discovery.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 51dcfb657a..82d1777b5d 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -122,14 +122,14 @@ If the DNS result returns no SRV records, or no records at all, or a DNS error h indicating that the URI could not be used to find hostnames. The error SHALL include the reason why they could not be found. -A driver MUST verify that the host names returned through SRV records end with the original SRV's `{domainname}`. -Drivers MUST raise an error and MUST NOT initiate a connection to any returned host name which does not share the same +A driver MUST verify that the host names returned through SRV records share the original SRV's `{domainname}`. Drivers +MUST raise an error and MUST NOT initiate a connection to any returned host name which does not share the same `{domainname}`. -In the case that the SRV record has less than three `.` separated parts, the returned address MUST end with the SRV's -entire `{hostname}` and MUST have at least one more domain level than the `{hostname}`. The next major version MUST no -longer allow an SRV record, with any number of parts, to return an address that doesn't end with the SRVs' entire -`{hostname}`. Drivers MUST document this in a prior minor release. +In the case that the SRV record name has less than three `.` separated parts, the returned address' `{domainname}` MUST +be the SRV's entire `{hostname}` and MUST have at least one more domain level than the `{hostname}`. The next major +version MUST no longer allow an SRV record, with any number of parts, to return an address that doesn't contain the +SRVs' entire `{hostname}`. Drivers MUST document this in a prior minor release. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. @@ -194,7 +194,7 @@ _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27317 mongodb1. _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27017 mongodb2.mongodb.com. ``` -The returned host names (`mongodb1.mongodb.com` and `mongodb2.mongodb.com`) must end with the same domain name +The returned host names (`mongodb1.mongodb.com` and `mongodb2.mongodb.com`) must share the same domain name (`mongodb.com`) as the provided host name (`server.mongodb.com`). The driver also needs to request the DNS server for the TXT records on `server.mongodb.com`. This could return: From 6d953e3e7fadc71f6af97744301dd92bb008d38e Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 13 Sep 2024 18:02:31 -0400 Subject: [PATCH 18/27] update deprecation comment --- .../initial-dns-seedlist-discovery.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 82d1777b5d..f7aab9686f 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -122,14 +122,10 @@ If the DNS result returns no SRV records, or no records at all, or a DNS error h indicating that the URI could not be used to find hostnames. The error SHALL include the reason why they could not be found. -A driver MUST verify that the host names returned through SRV records share the original SRV's `{domainname}`. Drivers -MUST raise an error and MUST NOT initiate a connection to any returned host name which does not share the same -`{domainname}`. - -In the case that the SRV record name has less than three `.` separated parts, the returned address' `{domainname}` MUST -be the SRV's entire `{hostname}` and MUST have at least one more domain level than the `{hostname}`. The next major -version MUST no longer allow an SRV record, with any number of parts, to return an address that doesn't contain the -SRVs' entire `{hostname}`. Drivers MUST document this in a prior minor release. +A driver MUST verify that the host names returned through SRV records share the original SRV's `{domainname}`. In +addition, SRV records with less than three `.` separated parts, the returned hostname MUST have at least one more domain +level SRV record hostname. Drivers MUST raise an error and MUST NOT initiate a connection to any returned hostname which +does not fulfill these requirements. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. @@ -194,7 +190,7 @@ _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27317 mongodb1. _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27017 mongodb2.mongodb.com. ``` -The returned host names (`mongodb1.mongodb.com` and `mongodb2.mongodb.com`) must share the same domain name +The returned host names (`mongodb1.mongodb.com` and `mongodb2.mongodb.com`) must share the same domainname (`mongodb.com`) as the provided host name (`server.mongodb.com`). The driver also needs to request the DNS server for the TXT records on `server.mongodb.com`. This could return: @@ -286,9 +282,8 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog - 2024-08-20: Removed requirement for URI to have three '.' separated parts; these SRVs have stricter parent domain - matching requirements for security. SRVs with three or more parts should have stricter matching requirements in next - major version. Create terminology section. Remove usage of term `{TLD}`. The `{hostname}` now refers to the entire - hostname, not just the `{subdomain}`. + matching requirements for security. Create terminology section. Remove usage of term `{TLD}`. The `{hostname}` now + refers to the entire hostname, not just the `{subdomain}`. - 2024-03-06: Migrated from reStructuredText to Markdown. From 9db03a721c626f71fe1e75e4c284781b99df543d Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 13 Sep 2024 18:03:33 -0400 Subject: [PATCH 19/27] typo --- .../initial-dns-seedlist-discovery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index f7aab9686f..a73ef0d98c 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -124,8 +124,8 @@ found. A driver MUST verify that the host names returned through SRV records share the original SRV's `{domainname}`. In addition, SRV records with less than three `.` separated parts, the returned hostname MUST have at least one more domain -level SRV record hostname. Drivers MUST raise an error and MUST NOT initiate a connection to any returned hostname which -does not fulfill these requirements. +level than the SRV record hostname. Drivers MUST raise an error and MUST NOT initiate a connection to any returned +hostname which does not fulfill these requirements. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. From f4175e9278e9eaf9358cde8ceb0861d4cd8eb296 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Fri, 20 Sep 2024 16:57:26 -0400 Subject: [PATCH 20/27] clarify subdomain --- .../initial-dns-seedlist-discovery.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index c886e775ad..77bfd6d293 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -61,6 +61,8 @@ has: - `{hostname}` = `{domainname}` = `localhost` - `{hostname}` = `{domainname}` = `mongodb.local` +Only `{domainname}` is used during SRV record verification and `{subdomain}` is ignored. + ### MongoClient Configuration #### srvMaxHosts @@ -229,7 +231,6 @@ See README.md in the accompanying [test directory](tests/README.md). See README.md in the accompanying [test directory](tests/README.md). - Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the [Connection String Spec tests](../connection-string/tests/README.md). From 54a55552b041fd58bbfe04f495ae9a3c5065b1f3 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Mon, 23 Sep 2024 10:28:15 -0400 Subject: [PATCH 21/27] add in Shanes test --- .../initial-dns-seedlist-discovery/tests/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 9aae27f263..fa42969da1 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -38,6 +38,20 @@ When given a returned address that is identical to the original hostname, throw For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since the returned address is identical to the original hostname. +### 4. Throw when return address does not contain `.` separating shared part of domain + +For the following test, run each of these cases: SRVs with one, two, and three `.` separated parts. + +When given a returned address that does not share the domain name of the SRV record because its missing a `.`, throw a +runtime error. + +For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `cluster.testmongodb.com` would be a valid +resolution if there was a `.` between `test` and `mongo`. Since the `.` is missing, the driver should throw a runtime +error. + +For the same reason, the SRV `mongodb+srv://mongo.local` resolving to `my_hostmongo.local` should also trigger a runtime +error. + ## Test Setup The tests in the `replica-set` directory MUST be executed against a three-node replica set on localhost ports 27017, From 0a90e7c815b4443119e807b8b8e498685b9da46a Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 24 Sep 2024 14:59:46 -0400 Subject: [PATCH 22/27] update changelog date --- .../initial-dns-seedlist-discovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 77bfd6d293..4cc7d26062 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -283,7 +283,7 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog -- 2024-08-20: Removed requirement for URI to have three '.' separated parts; these SRVs have stricter parent domain +- 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}`. From e1f6d67758471748dc19cc036af640d9e4d36623 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 24 Sep 2024 15:29:32 -0400 Subject: [PATCH 23/27] add in specific cases --- .../tests/README.md | 41 +++++++++---------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index fa42969da1..2847a45ecc 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -10,47 +10,44 @@ resolution results. ### 1. Allow SRVs with less than 3 `.` separated parts -For the following test, run each of these cases: SRVs with one and two `.` separated parts. - When running validation on an SRV string before DNS resolution, do not throw a error due to number of SRV parts. -For example, `mongodb+srv://localhost` is a valid SRV string with one part/one domain level, and -`mongodb+srv://mongo.local` is a valid SRV string with two parts/two domain levels. +For this test, run each of the following cases: -### 2. Throw when return address does not end with SRV domain +- `mongodb+srv://localhost` +- `mongodb+srv://mongo.local` -For the following test, run each of these cases: SRVs with one, two, and three `.` separated parts. +### 2. Throw when return address does not end with SRV domain When given a returned address that does NOT end with the original SRV's domain name, throw a runtime error. -For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` should prompt an error, since the -returned address does not end with `mongodb.com`. +For this test, run each of the following cases: -Importantly, the domain of an SRV with one or two parts is its entire hostname. For example, the domain of -`mongodb+srv://mySite.com` is `mySite.com`. If this SRV resolves to `evil.com`, this should prompt an error. +- the SRV `mongodb+srv://localhost` resolving to `local_host` +- the SRV `mongodb+srv://mongo.local` resolving to `evil.local` +- the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` + +Remember, the domain of an SRV with one or two `.` separated parts is the SRVs entire hostname. ### 3. Throw when return address is identical to SRV hostname -For the following test, run each of these cases: SRVs with one and two `.` separated parts. +When given a returned address that is identical to the SRV hostname and the SRV hostname has less than three `.` +separated parts, throw a runtime error. -When given a returned address that is identical to the original hostname, throw a runtime error. +For this test, run each of the following cases: -For example, the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` should prompt an error since the returned -address is identical to the original hostname. +- the SRV `mongodb+srv://localhost` resolving to `localhost` +- the SRV `mongodb+srv://mongo.local` resolving to `mongo.local` ### 4. Throw when return address does not contain `.` separating shared part of domain -For the following test, run each of these cases: SRVs with one, two, and three `.` separated parts. - -When given a returned address that does not share the domain name of the SRV record because its missing a `.`, throw a +When given a returned address that does NOT share the domain name of the SRV record because its missing a `.`, throw a runtime error. -For example, the SRV `mongodb+srv://blogs.mongodb.com` resolving to `cluster.testmongodb.com` would be a valid -resolution if there was a `.` between `test` and `mongo`. Since the `.` is missing, the driver should throw a runtime -error. +For this test, run each of the following cases: -For the same reason, the SRV `mongodb+srv://mongo.local` resolving to `my_hostmongo.local` should also trigger a runtime -error. +- the SRV `mongodb+srv://mongo.local` resolving to `my_hostmongo.local` +- the SRV `mongodb+srv://blogs.mongodb.com` resolving to `cluster.testmongodb.com` ## Test Setup From fbc8b293abdcaa942f0a3726ab4860b44f797029 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 24 Sep 2024 15:46:57 -0400 Subject: [PATCH 24/27] fix test cases --- source/initial-dns-seedlist-discovery/tests/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 2847a45ecc..68002d1cc9 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -23,8 +23,8 @@ When given a returned address that does NOT end with the original SRV's domain n For this test, run each of the following cases: -- the SRV `mongodb+srv://localhost` resolving to `local_host` -- the SRV `mongodb+srv://mongo.local` resolving to `evil.local` +- the SRV `mongodb+srv://localhost` resolving to `localhost.mongodb` +- the SRV `mongodb+srv://mongo.local` resolving to `test_1.evil.local` - the SRV `mongodb+srv://blogs.mongodb.com` resolving to `blogs.evil.com` Remember, the domain of an SRV with one or two `.` separated parts is the SRVs entire hostname. @@ -46,7 +46,7 @@ runtime error. For this test, run each of the following cases: -- the SRV `mongodb+srv://mongo.local` resolving to `my_hostmongo.local` +- the SRV `mongodb+srv://mongo.local` resolving to `test_1.my_hostmongo.local` - the SRV `mongodb+srv://blogs.mongodb.com` resolving to `cluster.testmongodb.com` ## Test Setup From d6581078ff528f101a87d17261f5ac6fcde5b91e Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 24 Sep 2024 16:05:32 -0400 Subject: [PATCH 25/27] fix tests --- source/initial-dns-seedlist-discovery/tests/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 68002d1cc9..618d193e2c 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -46,6 +46,7 @@ runtime error. For this test, run each of the following cases: +- the SRV `mongodb+srv://localhost` resolving to `test_1.cluster_1localhost` - the SRV `mongodb+srv://mongo.local` resolving to `test_1.my_hostmongo.local` - the SRV `mongodb+srv://blogs.mongodb.com` resolving to `cluster.testmongodb.com` From c4bb2b4183cac1aff9d72452036d61d3b6efed50 Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 24 Sep 2024 16:05:55 -0400 Subject: [PATCH 26/27] fix tests --- source/initial-dns-seedlist-discovery/tests/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 618d193e2c..972322881d 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -12,8 +12,6 @@ resolution results. When running validation on an SRV string before DNS resolution, do not throw a error due to number of SRV parts. -For this test, run each of the following cases: - - `mongodb+srv://localhost` - `mongodb+srv://mongo.local` From 63f99bb5983824c7cff0bc09f67f3f4be245d4ba Mon Sep 17 00:00:00 2001 From: Aditi Khare Date: Tue, 24 Sep 2024 16:15:18 -0400 Subject: [PATCH 27/27] grammar fix --- .../initial-dns-seedlist-discovery.md | 6 +++--- source/initial-dns-seedlist-discovery/tests/README.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 4cc7d26062..0c01577ca9 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -125,9 +125,9 @@ indicating that the URI could not be used to find hostnames. The error SHALL inc found. A driver MUST verify that the host names returned through SRV records share the original SRV's `{domainname}`. In -addition, SRV records with less than three `.` separated parts, the returned hostname MUST have at least one more domain -level than the SRV record hostname. Drivers MUST raise an error and MUST NOT initiate a connection to any returned -hostname which does not fulfill these requirements. +addition, SRV records with fewer than three `.` separated parts, the returned hostname MUST have at least one more +domain level than the SRV record hostname. Drivers MUST raise an error and MUST NOT initiate a connection to any +returned hostname which does not fulfill these requirements. The driver MUST NOT attempt to connect to any hosts until the DNS query has returned its results. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 972322881d..99a1e8e3f0 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -8,7 +8,7 @@ Seedlist Discovery spec. For the following prose tests, it is assumed drivers are be able to stub DNS results to easily test invalid DNS resolution results. -### 1. Allow SRVs with less than 3 `.` separated parts +### 1. Allow SRVs with fewer than 3 `.` separated parts When running validation on an SRV string before DNS resolution, do not throw a error due to number of SRV parts. @@ -29,7 +29,7 @@ Remember, the domain of an SRV with one or two `.` separated parts is the SRVs e ### 3. Throw when return address is identical to SRV hostname -When given a returned address that is identical to the SRV hostname and the SRV hostname has less than three `.` +When given a returned address that is identical to the SRV hostname and the SRV hostname has fewer than three `.` separated parts, throw a runtime error. For this test, run each of the following cases: @@ -39,7 +39,7 @@ For this test, run each of the following cases: ### 4. Throw when return address does not contain `.` separating shared part of domain -When given a returned address that does NOT share the domain name of the SRV record because its missing a `.`, throw a +When given a returned address that does NOT share the domain name of the SRV record because it's missing a `.`, throw a runtime error. For this test, run each of the following cases: