diff --git a/docs/draft-ietf-dconn-domainconnect-04.clean.txt b/docs/draft-ietf-dconn-domainconnect-04.clean.txt index 879ed22..7029636 100644 --- a/docs/draft-ietf-dconn-domainconnect-04.clean.txt +++ b/docs/draft-ietf-dconn-domainconnect-04.clean.txt @@ -2047,6 +2047,11 @@ Table of Contents Table 8: URI template parameters of the apply call in the sync flow + Where an apply parameter carries text intended for display to the + user, the Service Provider MAY set its value to text localized to + match the user agent's language preference (e.g. the HTTP "Accept- + Language" header). + An example query string: GET @@ -2250,9 +2255,10 @@ Table of Contents "temporarily_unavailable". * "error_description" - OPTIONAL. A developer-oriented plain-text - description of the error. The DNS Provider SHOULD keep - descriptions vague where disclosure of internal account or domain - state would be inappropriate. + description of the error, intended for developers rather than the + end user and therefore RECOMMENDED to be in English. The DNS + Provider SHOULD keep descriptions vague where disclosure of + internal account or domain state would be inappropriate. As a RECOMMENDED convention, when the user explicitly cancels the operation and the DNS Provider uses "error=access_denied", the @@ -3449,6 +3455,9 @@ Change from draft-ietf-dconn-domainconnect-03 to -04 * Added dc-template-property, dc-unprefixed-property, and dc-vnd- property to Terminology. + * Clarified how the language of user-facing and developer-facing + protocol text relates to the user agent's language preference. + Change from draft-ietf-dconn-domainconnect-02 to -03 * Classified template record types as Fully Specified, Computed, or @@ -3722,9 +3731,9 @@ Normative References Informative References - [RFC8499] "Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS + [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", IETF, DOI 10.17487/RFC8499, RFC 8499, - January 2019, >.". + January 2019, . [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", IETF, DOI 10.17487/RFC6839, diff --git a/docs/draft-ietf-dconn-domainconnect-04.html b/docs/draft-ietf-dconn-domainconnect-04.html index abf17f1..f4e9081 100644 --- a/docs/draft-ietf-dconn-domainconnect-04.html +++ b/docs/draft-ietf-dconn-domainconnect-04.html @@ -4119,20 +4119,23 @@

-
-

An example query string:

+
+

Where an apply parameter carries text intended for display to the user, the Service Provider MAY set its value to text localized to match the user agent's language preference (e.g. the HTTP "Accept-Language" header).

+
+
+

An example query string:

-
+
GET
 
 https://web-connect.dnsprovider.example/v2/domainTemplates/providers/
 exampleservice.example/services/template1/apply?domain=example.com&
-IP=192.168.42.42&RANDOMTEXT=shm%3A1542108821%3AHello
+IP=192.168.42.42&RANDOMTEXT=shm%3A1542108821%3AHello
-
-

This call indicates that the Service Provider wishes to connect the domain example.com to the service using the template identified by the composite key of the provider (exampleservice.example) and the service template owned by them (template1). In this example, there are two variables in this template, "IP" and "RANDOMTEXT". These variables are passed as name/value pairs.

+
+

This call indicates that the Service Provider wishes to connect the domain example.com to the service using the template identified by the composite key of the provider (exampleservice.example) and the service template owned by them (template1). In this example, there are two variables in this template, "IP" and "RANDOMTEXT". These variables are passed as name/value pairs.

@@ -4308,7 +4311,7 @@

-
+

8.3.6. Template Apply Error Response @@ -4324,8 +4327,8 @@

"error" - REQUIRED on error. The value MUST be one of the error codes defined in Section 4.1.2.1 of [RFC6749]: "invalid_request", "unauthorized_client", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", or "temporarily_unavailable".
  • -
    -

    "error_description" - OPTIONAL. A developer-oriented plain-text description of the error. The DNS Provider SHOULD keep descriptions vague where disclosure of internal account or domain state would be inappropriate.

    +
    +

    "error_description" - OPTIONAL. A developer-oriented plain-text description of the error, intended for developers rather than the end user and therefore RECOMMENDED to be in English. The DNS Provider SHOULD keep descriptions vague where disclosure of internal account or domain state would be inappropriate.

    As a RECOMMENDED convention, when the user explicitly cancels the operation and the DNS Provider uses "error=access_denied", the "error_description" value MAY carry the prefix "user_cancel" to allow the Service Provider to distinguish user cancellation from other denial reasons.

    @@ -6116,13 +6119,13 @@

    • -
    +

    Change History

    This section is to be removed before publishing as an RFC.

    -
    +

    Change from draft-ietf-dconn-domainconnect-03 to -04 @@ -6141,6 +6144,8 @@

  • Added the IANA "Domain Connect Template Properties" registry in Domain Connect Template Properties Registry.
  • Added dc-template-property, dc-unprefixed-property, and dc-vnd-property to Terminology. +
    • +
  • Clarified how the language of user-facing and developer-facing protocol text relates to the user agent's language preference.

    • @@ -6433,7 +6438,7 @@

    -
    +

    Informative References @@ -6441,7 +6446,7 @@

    [RFC8499]
    -"Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", IETF, DOI 10.17487/RFC8499, RFC 8499, January 2019, >.".
    +Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", IETF, DOI 10.17487/RFC8499, RFC 8499, , <https://www.rfc-editor.org/info/rfc8499>.
    [RFC6839]
    diff --git a/docs/draft-ietf-dconn-domainconnect-04.pdf b/docs/draft-ietf-dconn-domainconnect-04.pdf index b4d6f24..8e020ab 100644 Binary files a/docs/draft-ietf-dconn-domainconnect-04.pdf and b/docs/draft-ietf-dconn-domainconnect-04.pdf differ diff --git a/docs/draft-ietf-dconn-domainconnect-04.txt b/docs/draft-ietf-dconn-domainconnect-04.txt index 76e3837..77d31a2 100644 --- a/docs/draft-ietf-dconn-domainconnect-04.txt +++ b/docs/draft-ietf-dconn-domainconnect-04.txt @@ -2481,6 +2481,11 @@ Internet-Draft Domain Connect July 2026 Table 8: URI template parameters of the apply call in the sync flow + Where an apply parameter carries text intended for display to the + user, the Service Provider MAY set its value to text localized to + match the user agent's language preference (e.g. the HTTP "Accept- + Language" header). + An example query string: GET @@ -2509,11 +2514,6 @@ Internet-Draft Domain Connect July 2026 a. Take all apply parameters except "sig" and "key". - b. URL-encode each parameter name and value per [RFC3986]. - - c. Sort the parameters in ascending lexicographic order of the - URL-encoded parameter name. - @@ -2522,6 +2522,11 @@ Kowalik, et al. Expires 4 January 2027 [Page 45] Internet-Draft Domain Connect July 2026 + b. URL-encode each parameter name and value per [RFC3986]. + + c. Sort the parameters in ascending lexicographic order of the + URL-encoded parameter name. + d. Concatenate them as name=value pairs joined by "&". 2. Sign the canonical input string using the private key @@ -2564,11 +2569,6 @@ Internet-Draft Domain Connect July 2026 specific parameters, apply parameter names are governed by the following reservation rules: - * Parameter names beginning with "dc." are reserved for parameters - defined by future standards-track extensions that normatively - require this document as their base. Implementations MUST NOT use - the "dc." prefix for private parameters. - @@ -2578,6 +2578,11 @@ Kowalik, et al. Expires 4 January 2027 [Page 46] Internet-Draft Domain Connect July 2026 + * Parameter names beginning with "dc." are reserved for parameters + defined by future standards-track extensions that normatively + require this document as their base. Implementations MUST NOT use + the "dc." prefix for private parameters. + * Parameter names beginning with "vnd." are reserved for vendor- specific and private-use parameters. A vendor SHOULD further namespace such parameters with a vendor identifier (e.g. @@ -2622,11 +2627,6 @@ Internet-Draft Domain Connect July 2026 "syncPubKeyDomain" is set, the DNS Provider MUST perform the following steps and MUST reject the request if any step fails: - 1. *Check for required parameters* - The request MUST carry both - "sig" and "key" parameters. - - - Kowalik, et al. Expires 4 January 2027 [Page 47] @@ -2634,6 +2634,9 @@ Kowalik, et al. Expires 4 January 2027 [Page 47] Internet-Draft Domain Connect July 2026 + 1. *Check for required parameters* - The request MUST carry both + "sig" and "key" parameters. + 2. *Retrieve the public key* - Query DNS for TXT records at the host formed by prepending the "key" parameter value as a label to "syncPubKeyDomain" (see Section 6.4). If no such records are @@ -2682,9 +2685,6 @@ Internet-Draft Domain Connect July 2026 - - - Kowalik, et al. Expires 4 January 2027 [Page 48] Internet-Draft Domain Connect July 2026 @@ -2723,9 +2723,10 @@ Internet-Draft Domain Connect July 2026 "temporarily_unavailable". * "error_description" - OPTIONAL. A developer-oriented plain-text - description of the error. The DNS Provider SHOULD keep - descriptions vague where disclosure of internal account or domain - state would be inappropriate. + description of the error, intended for developers rather than the + end user and therefore RECOMMENDED to be in English. The DNS + Provider SHOULD keep descriptions vague where disclosure of + internal account or domain state would be inappropriate. As a RECOMMENDED convention, when the user explicitly cancels the operation and the DNS Provider uses "error=access_denied", the @@ -2740,7 +2741,6 @@ Internet-Draft Domain Connect July 2026 - Kowalik, et al. Expires 4 January 2027 [Page 49] Internet-Draft Domain Connect July 2026 @@ -4168,6 +4168,9 @@ Internet-Draft Domain Connect July 2026 * Added dc-template-property, dc-unprefixed-property, and dc-vnd- property to Terminology. + * Clarified how the language of user-facing and developer-facing + protocol text relates to the user agent's language preference. + Change from draft-ietf-dconn-domainconnect-02 to -03 * Classified template record types as Fully Specified, Computed, or @@ -4192,9 +4195,6 @@ Change from draft-ietf-dconn-domainconnect-02 to -03 Template Definition; phishing warnings are now default behavior, see Template Variable Phishing. - * Clarified one-host-one-key rule in Public Key Publication. - - Kowalik, et al. Expires 4 January 2027 [Page 75] @@ -4202,6 +4202,8 @@ Kowalik, et al. Expires 4 January 2027 [Page 75] Internet-Draft Domain Connect July 2026 + * Clarified one-host-one-key rule in Public Key Publication. + * Added Media Type Registration for application/ domainconnect-template+json in IANA Considerations. @@ -4251,8 +4253,6 @@ Change from draft-ietf-dconn-domainconnect-00 to -01 - - Kowalik, et al. Expires 4 January 2027 [Page 76] Internet-Draft Domain Connect July 2026 @@ -4489,9 +4489,9 @@ Internet-Draft Domain Connect July 2026 Informative References - [RFC8499] "Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS + [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", IETF, DOI 10.17487/RFC8499, RFC 8499, - January 2019, >.". + January 2019, . [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", IETF, DOI 10.17487/RFC6839, diff --git a/docs/draft-ietf-dconn-domainconnect-04.xml b/docs/draft-ietf-dconn-domainconnect-04.xml index 3288d2d..162779f 100644 --- a/docs/draft-ietf-dconn-domainconnect-04.xml +++ b/docs/draft-ietf-dconn-domainconnect-04.xml @@ -942,7 +942,9 @@ serviceName,instanceId,redirect_uri,properties*}{&sig,key}]]> URI template parameters of the apply call in the sync flow
    PropertyRequest ParameterDescription
    URL Sync UXurlSyncUX(REQUIRED) The base URL of the DNS Provider synchronous UX endpoint, taken from the "urlSyncUX" field of the settings endpoint response (see ).
    This MUST be a valid URI with scheme "https"
    Service Provider IdproviderId(REQUIRED) Identifier of the Service Provider of the template to be applied. The value MUST conform to the dc-id syntax (see ).
    Service IdserviceId(REQUIRED) Identifier of the template to be applied. The value MUST conform to the dc-id syntax (see ).
    Domaindomain(REQUIRED) The domain name being configured. This is the Zone Apex (the registered domain or delegated zone). The value MUST conform to the domain-name syntax (see ).
    Hosthost(OPTIONAL) The host name of the Sub Domain within the zone identified by "domain".
    When present, the value MUST be a single name conforming to domain-name (see ) or an empty string.
    Redirect URIredirect_uri(OPTIONAL) The location to direct the user agent to upon successful authorization or upon error.
    The value MUST be an absolute URI conforming to .
    Statestate(OPTIONAL) A random and unique string passed along to prevent CSRF, or to pass back state.
    The value MUST conform to the "state" syntax (see ).
    Name/Value Pairsproperties(REQUIRED) Variable values to be substituted into the template. Each parameter name MUST correspond to a variable name defined in the template and MUST conform to the variable-name syntax (see ).
    Each parameter value MUST conform to the dc-prop-value syntax (see ), using the DNS presentation format .
    The parameter value corresponds to the value that will be used when applying the template.
    Provider NameproviderName(OPTIONAL) Additional display text for the template "providerName", provided by the caller. If "sharedProviderName" is not set in the template, this parameter MUST NOT be set. Note: this used to be controlled by the "shared" attribute in the template, which has been deprecated.
    The value MUST conform to the dc-display-name syntax (see ).
    Service NameserviceName(OPTIONAL) Additional display text for the template "serviceName", provided by the caller. If "sharedServiceName" is not set in the template, this parameter MUST NOT be set.
    The value MUST conform to the dc-display-name syntax (see ).
    Group IDgroupId(OPTIONAL) Specifies the subset of groups from the template to apply.
    The value MUST conform to the dc-id-list syntax (see ).
    Signaturesig(OPTIONAL) A digital signature of the canonical query string. The value MUST conform to the dc-sig syntax (see ):
    a standard base64-encoded signature, URL-encoded when carried in the query string.
    See the below for the signing procedure.
    Keykey(OPTIONAL) The DNS host label within the syncPubKeyDomain at which the public key TXT record is published.
    The value MUST conform to the dc-key-label syntax (see ): a single DNS label, either a plain ACE-form label or an RFC 8552 underscore-prefixed label.
    See the below.
    -An example query string: +Where an apply parameter carries text intended for display to the user, the Service Provider MAY set its value to text localized to match the user agent's language preference (e.g. the HTTP "Accept-Language" header). + +An example query string: -This call indicates that the Service Provider wishes to connect the domain example.com to the service using the template identified by the composite key of the provider (exampleservice.example) and the service template owned by them (template1). In this example, there are two variables in this template, "IP" and "RANDOMTEXT". These variables are passed as name/value pairs. +This call indicates that the Service Provider wishes to connect the domain example.com to the service using the template identified by the composite key of the provider (exampleservice.example) and the service template owned by them (template1). In this example, there are two variables in this template, "IP" and "RANDOMTEXT". These variables are passed as name/value pairs.
    Signing Procedure @@ -1035,14 +1037,14 @@ SHgJq9%2FXoMTTw%3D%3D&key=_dcpubkeyv1]]> The Service Provider SHOULD verify the outcome via DNS regardless of how the flow terminates (see ).
    -
    Template Apply Error Response +
    Template Apply Error Response If the DNS Provider cannot complete the apply operation - for example because authentication failed, the user does not control the domain, the domain is suspended, or the user explicitly canceled - the DNS Provider MUST signal an error. If "redirect_uri" is present and the open-redirect constraint is satisfied, the DNS Provider MUST redirect the user agent to the "redirect_uri" with the following parameters appended: -
    • "error" - REQUIRED on error. The value MUST be one of the error codes defined in Section 4.1.2.1 of : "invalid_request", "unauthorized_client", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", or "temporarily_unavailable".
      • -
    • "error_description" - OPTIONAL. A developer-oriented plain-text description of the error. The DNS Provider SHOULD keep descriptions vague where disclosure of internal account or domain state would be inappropriate.
       +
      • "error" - REQUIRED on error. The value MUST be one of the error codes defined in Section 4.1.2.1 of : "invalid_request", "unauthorized_client", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", or "temporarily_unavailable".
        • +
      • "error_description" - OPTIONAL. A developer-oriented plain-text description of the error, intended for developers rather than the end user and therefore RECOMMENDED to be in English. The DNS Provider SHOULD keep descriptions vague where disclosure of internal account or domain state would be inappropriate.
         As a RECOMMENDED convention, when the user explicitly cancels the operation and the DNS Provider uses "error=access_denied", the "error_description" value MAY carry the prefix "user_cancel" to allow the Service Provider to distinguish user cancellation from other denial reasons.
      • "state" - If a "state" parameter was present in the request, it MUST be echoed back unchanged as "state=" on the redirect URI.
        • @@ -1613,17 +1615,18 @@ r2.example.com. TXT v=spf1 include:_spf.newsletter.example ~all
      • Arnt Gulbrandsen
    -
    Change History +
    Change History -
    Change from draft-ietf-dconn-domainconnect-03 to -04 +
    Change from draft-ietf-dconn-domainconnect-03 to -04 -
    • Added to , reserving the "dc." and "vnd." prefixes and the unprefixed grandfathered parameter names.
      • +
      • Added to , reserving the "dc." and "vnd." prefixes and the unprefixed grandfathered parameter names.
      • Reserved built-in and grandfathered apply parameter names as forbidden variable-name identifiers in .
      • Added dc-apply-param, dc-predefined-param, dc-dot-param, and dc-vnd-param to .
      • Added and the "crit" property to .
      • Added the "templateSpecVersion" property to .
      • Added the IANA "Domain Connect Template Properties" registry in .
      • Added dc-template-property, dc-unprefixed-property, and dc-vnd-property to .
        • +
      • Clarified how the language of user-facing and developer-facing protocol text relates to the user agent's language preference.
    @@ -1753,13 +1756,9 @@ r2.example.com. TXT v=spf1 include:_spf.newsletter.example ~all IETF Media Type Specifications and Registration Procedures This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. IETF HTTP Semantics Hypertext Transfer ProtocolHTTPHTTP semanticsHTTP contentHTTP methodHTTP status code The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. - + Informative References - - - Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", IETF, DOI 10.17487/RFC8499, RFC 8499, January 2019, >. - - + IETF DNS Terminology vocabularydomain name system The Domain Name System (DNS) is defined in literally dozens of different RFCs. The terminology used by implementers and developers of DNS protocols, and by operators of DNS systems, has sometimes changed in the decades since the DNS was first defined. This document gives current definitions for many of the terms used in the DNS in a single document. This document obsoletes RFC 7719 and updates RFC 2308. IETF Additional Media Type Structured Syntax Suffixes structured syntax suffixmedia type A content media type name sometimes includes partitioned meta- information distinguished by a structured syntax to permit noting an attribute of the media as a suffix to the name. This document defines several structured syntax suffixes for use with media type registrations. In particular, it defines and registers the "+json", "+ber", "+der", "+fastinfoset", "+wbxml" and "+zip" structured syntax suffixes, and provides a media type structured syntax suffix registration form for the "+xml" structured syntax suffix. This document is not an Internet Standards Track specification; it is published for informational purposes. Domain Connect Specification, Version 2.3 Rev. 67 diff --git a/draft-ietf-dconn-domainconnect-04.adoc b/draft-ietf-dconn-domainconnect-04.adoc index b8688e1..e2b1e2a 100644 --- a/draft-ietf-dconn-domainconnect-04.adoc +++ b/draft-ietf-dconn-domainconnect-04.adoc @@ -1542,6 +1542,8 @@ The value MUST conform to the `dc-key-label` syntax (see <>): a sin See the <> below. |======================================================================= +Where an apply parameter carries text intended for display to the user, the Service Provider MAY set its value to text localized to match the user agent's language preference (e.g. the HTTP `"Accept-Language"` header). + An example query string: [source] @@ -1658,7 +1660,7 @@ If `"redirect_uri"` is present and the open-redirect constraint is satisfied, th * `"error"` — REQUIRED on error. The value MUST be one of the error codes defined in Section 4.1.2.1 of <>: `"invalid_request"`, `"unauthorized_client"`, `"access_denied"`, `"unsupported_response_type"`, `"invalid_scope"`, `"server_error"`, or `"temporarily_unavailable"`. -* `"error_description"` — OPTIONAL. A developer-oriented plain-text description of the error. The DNS Provider SHOULD keep descriptions vague where disclosure of internal account or domain state would be inappropriate. + +* `"error_description"` — OPTIONAL. A developer-oriented plain-text description of the error, intended for developers rather than the end user and therefore RECOMMENDED to be in English. The DNS Provider SHOULD keep descriptions vague where disclosure of internal account or domain state would be inappropriate. + + As a RECOMMENDED convention, when the user explicitly cancels the operation and the DNS Provider uses `"error=access_denied"`, the `"error_description"` value MAY carry the prefix `"user_cancel"` to allow the Service Provider to distinguish user cancellation from other denial reasons. @@ -2487,6 +2489,7 @@ The authors wish to thank the following persons for their feedback and suggestio - Added the `"templateSpecVersion"` property to <>. - Added the IANA "Domain Connect Template Properties" registry in <>. - Added `dc-template-property`, `dc-unprefixed-property`, and `dc-vnd-property` to <>. +- Clarified how the language of user-facing and developer-facing protocol text relates to the user agent's language preference. [toc=exclude,numbered=false] === Change from draft-ietf-dconn-domainconnect-02 to -03