--- 1/draft-ietf-regext-epp-fees-18.txt 2019-10-11 13:13:06.326581652 -0700 +++ 2/draft-ietf-regext-epp-fees-19.txt 2019-10-11 13:13:06.394583372 -0700 @@ -1,20 +1,20 @@ Registration Protocols Extensions R. Carney Internet-Draft GoDaddy Inc. Intended status: Standards Track G. Brown -Expires: March 11, 2020 CentralNic Group plc +Expires: April 13, 2020 CentralNic Group plc J. Frakes - September 8, 2019 + October 11, 2019 Registry Fee Extension for the Extensible Provisioning Protocol (EPP) - draft-ietf-regext-epp-fees-18 + draft-ietf-regext-epp-fees-19 Abstract Given the expansion of the DNS namespace, and the proliferation of novel business models, it is desirable to provide a method for Extensible Provisioning Protocol (EPP) clients to query EPP servers for the fees and credits and provide expected fees and credits for certain commands and objects. This document describes an EPP extension mapping for registry fees. @@ -26,21 +26,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on March 11, 2020. + This Internet-Draft will expire on April 13, 2020. Copyright Notice Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -59,21 +59,21 @@ 3.1. Client Commands . . . . . . . . . . . . . . . . . . . . . 4 3.2. Currency Codes . . . . . . . . . . . . . . . . . . . . . 5 3.3. Validity Periods . . . . . . . . . . . . . . . . . . . . 5 3.4. Fees and Credits . . . . . . . . . . . . . . . . . . . . 6 3.4.1. Refunds . . . . . . . . . . . . . . . . . . . . . . . 7 3.4.2. Grace Periods . . . . . . . . . . . . . . . . . . . . 7 3.4.3. Correlation between Refundability and Grace Periods . 7 3.4.4. Applicability . . . . . . . . . . . . . . . . . . . . 7 3.5. Account Balance . . . . . . . . . . . . . . . . . . . . . 8 3.6. Credit Limit . . . . . . . . . . . . . . . . . . . . . . 8 - 3.7. Classification of Objects . . . . . . . . . . . . . . . . 8 + 3.7. Classification of Objects . . . . . . . . . . . . . . . . 9 3.8. Phase and Subphase Attributes . . . . . . . . . . . . . . 9 3.9. Reason . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. Server Handling of Fee Information . . . . . . . . . . . . . 11 5. EPP Command Mapping . . . . . . . . . . . . . . . . . . . . . 12 5.1. EPP Query Commands . . . . . . . . . . . . . . . . . . . 12 5.1.1. EPP Command . . . . . . . . . . . . . . . . . 12 5.1.2. EPP Transfer Query Command . . . . . . . . . . . . . 16 5.2. EPP Transform Commands . . . . . . . . . . . . . . . . . 18 5.2.1. EPP Command . . . . . . . . . . . . . . . . 18 5.2.2. EPP Command . . . . . . . . . . . . . . . . 20 @@ -83,39 +83,40 @@ 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 27 6.1. Fee Extension Schema . . . . . . . . . . . . . . . . . . 27 7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 8.1. XML Namespace . . . . . . . . . . . . . . . . . . . . . . 32 8.2. EPP Extension Registry . . . . . . . . . . . . . . . . . 32 9. Implementation Status . . . . . . . . . . . . . . . . . . . . 33 9.1. RegistryEngine EPP Service . . . . . . . . . . . . . . . 33 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 34 11. Change History . . . . . . . . . . . . . . . . . . . . . . . 34 - 11.1. Change from 17 to 18 . . . . . . . . . . . . . . . . . . 34 - 11.2. Change from 16 to 17 . . . . . . . . . . . . . . . . . . 34 - 11.3. Change from 15 to 16 . . . . . . . . . . . . . . . . . . 34 - 11.4. Change from 14 to 15 . . . . . . . . . . . . . . . . . . 35 - 11.5. Change from 13 to 14 . . . . . . . . . . . . . . . . . . 35 - 11.6. Change from 12 to 13 . . . . . . . . . . . . . . . . . . 35 - 11.7. Change from 11 to 12 . . . . . . . . . . . . . . . . . . 35 - 11.8. Change from 10 to 11 . . . . . . . . . . . . . . . . . . 35 - 11.9. Change from 09 to 10 . . . . . . . . . . . . . . . . . . 35 - 11.10. Change from 08 to 09 . . . . . . . . . . . . . . . . . . 35 - 11.11. Change from 07 to 08 . . . . . . . . . . . . . . . . . . 36 - 11.12. Change from 06 to 07 . . . . . . . . . . . . . . . . . . 36 - 11.13. Change from 05 to 06 . . . . . . . . . . . . . . . . . . 36 - 11.14. Change from 04 to 05 . . . . . . . . . . . . . . . . . . 36 - 11.15. Change from 03 to 04 . . . . . . . . . . . . . . . . . . 36 - 11.16. Change from 02 to 03 . . . . . . . . . . . . . . . . . . 36 - 11.17. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 37 - 11.18. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 37 - 11.19. Change from draft-brown-00 to draft-ietf-regext-fees-00 37 + 11.1. Change from 18 to 19 . . . . . . . . . . . . . . . . . . 34 + 11.2. Change from 17 to 18 . . . . . . . . . . . . . . . . . . 34 + 11.3. Change from 16 to 17 . . . . . . . . . . . . . . . . . . 34 + 11.4. Change from 15 to 16 . . . . . . . . . . . . . . . . . . 35 + 11.5. Change from 14 to 15 . . . . . . . . . . . . . . . . . . 35 + 11.6. Change from 13 to 14 . . . . . . . . . . . . . . . . . . 35 + 11.7. Change from 12 to 13 . . . . . . . . . . . . . . . . . . 35 + 11.8. Change from 11 to 12 . . . . . . . . . . . . . . . . . . 35 + 11.9. Change from 10 to 11 . . . . . . . . . . . . . . . . . . 35 + 11.10. Change from 09 to 10 . . . . . . . . . . . . . . . . . . 35 + 11.11. Change from 08 to 09 . . . . . . . . . . . . . . . . . . 35 + 11.12. Change from 07 to 08 . . . . . . . . . . . . . . . . . . 36 + 11.13. Change from 06 to 07 . . . . . . . . . . . . . . . . . . 36 + 11.14. Change from 05 to 06 . . . . . . . . . . . . . . . . . . 36 + 11.15. Change from 04 to 05 . . . . . . . . . . . . . . . . . . 36 + 11.16. Change from 03 to 04 . . . . . . . . . . . . . . . . . . 36 + 11.17. Change from 02 to 03 . . . . . . . . . . . . . . . . . . 37 + 11.18. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 37 + 11.19. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 37 + 11.20. Change from draft-brown-00 to draft-ietf-regext-fees-00 37 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 12.1. Normative References . . . . . . . . . . . . . . . . . . 37 12.2. Informative References . . . . . . . . . . . . . . . . . 38 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 1. Introduction Historically, domain name registries have applied a simple fee structure for billable transactions, namely a basic unit price applied to domain , , and RGP [RFC3915] @@ -192,22 +193,23 @@ o "create" indicating a command as defined in [RFC5730]; o "delete" indicating a command as defined in [RFC5730]; o "renew" indicating a command as defined in [RFC5730]; o "update" indicating a command as defined in [RFC5730]; o "transfer" indicating a command as defined in [RFC5730]; o If the server supports the Registry Grace Period Mapping [RFC3915], then the server MUST also support the "restore" value as defined in [RFC3915]; - o "custom" indicating a custom command that uses the "customName" - attribute to define the custom operation. + o "custom" indicating a custom command that MUST set the + "customName" attribute with custom command name. The possible set + of custom command name values is up to server policy. The element MAY have an OPTIONAL "phase" attribute specifying a launch phase as described in [RFC8334]. It may also contain an OPTIONAL "subphase" attribute identifying the custom or sub-phase as described in [RFC8334]. 3.2. Currency Codes The element is used to indicate which currency fees are charged in. This value of this element MUST be a three-character @@ -224,60 +226,63 @@ and server via an out-of-band channel. However, the element MUST be present in responses. Servers SHOULD NOT perform a currency conversion if a client uses an incorrect currency code. Servers SHOULD return a 2004 "Parameter value range" error instead. 3.3. Validity Periods When querying for fee information using the command, the - element is used to indicate the units to be added to the - registration period of objects by the , and - commands. This element is derived from the - element described in [RFC5731]. + element is used to indicate the period measured in years + or months, with the appropriate units specified using the "unit" + attribute to be added to the registration period of objects by the + , and commands. This element is derived + from the element described in [RFC5731]. The element is OPTIONAL in commands, if omitted, the server MUST determine the fee(s) using the server default period. The element MUST be present in responses. 3.4. Fees and Credits Servers which implement this extension will include elements in responses which provide information about the fees and/or credits associated with a given billable transaction. A fee will result in subtracting from the Account Balance (described in Section 3.5) and a credit will result in adding to the Account Balance (described in Section 3.5). The and elements are used to provide this information. The presence of a element in a response indicates a debit against the client's account balance; a element indicates a credit. A element MUST - have a non-negative value. A element MUST have a - negative value. + have a zero or greater (non-negative) value. A element + MUST have a negative value. A server MAY respond with multiple and elements in the same response. In such cases, the net fee or credit applicable to the transaction is the arithmetic sum of the values of each of the and/or elements. This amount applies to the total additional validity period applied to the object - (where applicable) rather than to any incremental unit. + (where applicable). The following attributes are defined for the element. These are described in detail below: description: an OPTIONAL attribute which provides a human-readable description of the fee. Servers should provide documentation on the possible values of this attribute, and their meanings. An OPTIONAL - "lang" attribute MAY be present to identify the language of the - returned text and has a default value of "en" (English). + "lang" attribute MAY be present, per the language structure in + [RFC5646], to identify the language of the returned text and has a + default value of "en" (English). If the "description" attribute is + not present, the "lang" attribute can be ignored. refundable: an OPTIONAL boolean attribute indicating whether the fee is refundable if the object is deleted. grace-period: an OPTIONAL attribute which provides the time period during which the fee is refundable. applied: an OPTIONAL attribute indicating when the fee will be deducted from the client's account. @@ -433,25 +438,26 @@ If the client contains a subphase attribute (or phase/ subphase combination) not supported by server the server MUST respond with a 2004 "Parameter value range" error. 3.9. Reason The element is used to provide server specific text in an effort to better explain why a command did not complete as the client expected. An OPTIONAL "lang" attribute MAY be present to - identify the language of the returned text and has a default value of - "en" (English). + identify the language, per the language structure in [RFC5646], of + the returned text and has a default value of "en" (English). The element can be used within the server response - element or within the element. + element or within the element. See section + 5.1.1 for details on the "check data" element. If the server cannot calculate the relevant fees, because the object, command, currency, period, class or some combination is invalid per server policy, the server has two ways of handling error processing of element(s): 1. Fast-fail - The server, upon error identification, MAY stop processing elements and return to the client a containing the and a element detailing the reason for failure. @@ -490,37 +496,38 @@ commands. Servers must provide clear documentation to clients about the circumstances in which this extension must be used. The server MUST return avail="0" in its response to a command for any object in the command that does not include the extension for which the server would likewise fail a domain command when no extension is provided for that same object. If a server receives a command from a client, which results - in no possible fee combination but where a fee is required, the - server MUST set the "avail" attribute of the element to - false and provide a . + in no possible fee combination, the server MUST set the "avail" + attribute of the element to false (0) and provide a + . If a server receives a command from a client, which results in an ambiguous result (i.e. multiple possible fee combinations) the server MUST reject the command with a 2003 "Required parameter missing" error. If a server receives a command from a client, which does not include the fee extension data elements required by the server for that command, then the server MUST respond with a 2003 "Required parameter missing" error. - If the currency or total fee provided by the client is less than the - server's own calculation of the fee for that command, then the server - MUST reject the command with a 2004 "Parameter value range" error. + If the total fee provided by the client is less than the server's own + calculation of the fee or the server determines the currency is + inappropriate for that command, then the server MUST reject the + command with a 2004 "Parameter value range" error. 5. EPP Command Mapping A detailed description of the EPP syntax and semantics can be found in [RFC5730]. 5.1. EPP Query Commands This extension does not add any elements to the EPP or commands or responses. @@ -530,21 +537,21 @@ This extension defines a new command called the Fee Check Command that defines additional elements for the EPP command to provide fee information along with the availability information of the EPP command. The command MAY contain an element which MAY contain a element. The element MAY contain one element and MUST contain one or more elements. - The element(s) contain(s) a "name" attribute (see + The element(s) MUST contain(s) a "name" attribute (see Section 3.1), an OPTIONAL "phase" attribute, and an OPTIONAL "subphase" attribute (see Section 3.8). The element(s) MAY have the following child elements: o An OPTIONAL element (as described in Section 3.3). Example command: C: C: @@ -569,67 +576,68 @@ C: C: C: ABC-12345 C: C: When the server receives a command that includes the extension elements described above, its response MUST contain an element, which MUST contain a child element. The element MUST contain a - element and a for each element referenced in the client - command. + element and a element for each object referenced in the + client command. - Each element MUST contain the following child elements: + Each (check data) element MUST contain the following child + elements: o A element, which MUST match an element referenced in the client command. o An OPTIONAL element (as described in Section 3.7). o A element matching each (unless the "avail" attribute of the if false) that appeared in the corresponding of the client command. This element MAY have the OPTIONAL "standard" attribute, with a default value of "0" (or "false"), which indicates whether the fee matches the fee of the "standard" classification (see section 3.7). This element MAY have the OPTIONAL "phase" and "subphase" attributes, which - SHOULD match the same attributes in the corresponding - element of the client command if sent by the client. + will match the same attributes in the corresponding + element of the client command if sent by the client. The element also has an OPTIONAL "avail" attribute which is a boolean. If the value of this attribute evaluates to false, this indicates that the server cannot calculate the relevant fees, because the object, command, currency, period, class or some combination is invalid per server policy. If "avail" is false then the or the element MUST contain a element (as described in Section 3.9) and the server MAY eliminate some or all of the element(s). The element(s) MAY have the following child elements: o An OPTIONAL element (as described in Section 3.3), - which contains the same unit that appeared in the - element of the command. If the value of the preceding + which contains the same unit, if present, that appeared in the + element of the command. If the value of the parent element is "restore", this element MUST NOT be included, otherwise it MUST be included. If no appeared in the client command (and the command is not "restore") then the server MUST return its default period value. o Zero or more elements (as described in Section 3.4). o Zero or more elements (as described in Section 3.4). o An OPTIONAL element (as described in Section 3.9). - If the "avail" attribute of the element is true and if no - elements are present in a element, this + If the "avail" attribute of the element is true (1) and if + no elements are present in a element, this indicates that no fee will be assessed by the server for this command. - If the "avail" attribute is true, then the element MUST - NOT contain a element. + If the "avail" attribute of the element is true (1), then + the element MUST NOT contain a element. Example response: S: S: S: S: S: Command completed successfully S: S: @@ -759,24 +767,24 @@ S: S: S: Command completed successfully; action pending S: S: S: S: example.com S: pending S: ClientX - S: 2000-06-08T22:00:00.0Z + S: 2019-06-08T22:00:00.0Z S: ClientY - S: 2000-06-13T22:00:00.0Z - S: 2002-09-08T22:00:00.0Z + S: 2019-06-13T22:00:00.0Z + S: 2021-09-08T22:00:00.0Z S: S: S: S: S: USD S: 1 S: 5.00 S: S: S: @@ -794,23 +802,20 @@ response, when the extension is included in the command service extensions. When submitting a command to the server, the client MAY include in the element a element which includes the following child elements: o An OPTIONAL element (as described in Section 3.2); o One or more elements (as described in Section 3.4). - The server MUST fail the command if the provided - by the client is less than the server fee. - When the command has been processed successfully, and the client included the extension in the command service extensions, and a fee was assessed by the server for the transaction, the server MUST include in the section of the EPP response a element, which contains the following child elements: o A element (as described in Section 3.2); o Zero or more elements (as described in Section 3.4); o Zero or more elements (as described in Section 3.4); @@ -854,22 +859,22 @@ S: S: S: S: S: Command completed successfully S: S: S: S: example.com - S: 1999-04-03T22:00:00.0Z - S: 2001-04-03T22:00:00.0Z + S: 2019-04-03T22:00:00.0Z + S: 2021-04-03T22:00:00.0Z S: S: S: S: S: USD S: 5.00 @@ -956,21 +961,21 @@ Example command: C: C: C: C: C: C: example.com - C: 2000-04-03 + C: 2019-04-03 C: 5 C: C: C: C: C: USD C: 5.00 C: C: C: ABC-12345 @@ -981,21 +986,21 @@ S: S: S: S: S: Command completed successfully S: S: S: S: example.com - S: 2005-04-03T22:00:00.0Z + S: 2024-04-03T22:00:00.0Z S: S: S: S: S: USD S: 5.00 S: 1000.00 S: @@ -1065,24 +1070,24 @@ S: S: S: Command completed successfully; action pending S: S: S: S: example.com S: pending S: ClientX - S: 2000-06-08T22:00:00.0Z + S: 2019-06-08T22:00:00.0Z S: ClientY - S: 2000-06-13T22:00:00.0Z - S: 2002-09-08T22:00:00.0Z + S: 2019-06-13T22:00:00.0Z + S: 2021-09-08T22:00:00.0Z S: S: S: S: S: USD S: 5.00 S: S: @@ -1287,21 +1292,21 @@ - + and "description" attribute detailed in section 3.4. -11.4. Change from 14 to 15 +11.5. Change from 14 to 15 Updated schema, moving the "standard" attribute of the "commandDataType" inside the block. -11.5. Change from 13 to 14 +11.6. Change from 13 to 14 Moved RFC 7451 reference from Normative to Informative section. -11.6. Change from 12 to 13 +11.7. Change from 12 to 13 Updated XML namespace and schema registration to be "epp" scoped - global replace of XML namespace from urn:ietf:params:xml:ns:fee-1.0 to urn:ietf:params:xml:ns:epp:fee-1.0 and the XML schema registration from urn:ietf:params:xml:schema:fee-1.0 to urn:ietf:params:xml:schema:epp:fee-1.0. -11.7. Change from 11 to 12 +11.8. Change from 11 to 12 Updated references to current version of documents and moved the "standard" attribute from the check command (commandType) to the check response (commandDataType). -11.8. Change from 10 to 11 +11.9. Change from 10 to 11 Updated document per Working Group Last Call comments. Made minor textual changes throughout for enhanced clarity per WGLC comments. -11.9. Change from 09 to 10 +11.10. Change from 09 to 10 Updated document per Working Group Last Call comments. Updated schema to version 1.0 in anticipation of standardization, no changes were made to the latest, 0.25, schema. Made minor textual changes throughout for enhanced clarity per WGLC comments. -11.10. Change from 08 to 09 +11.11. Change from 08 to 09 Updated scheme to version 0.25 to allow tighter checking on by splitting the client and server definitions, moved the class element from the command to the object level and added an optional standard attribute to the command element. Also updated section 3.1 for clarity on name attribute; updated section 3.9 for clarity on uses of ; removed second paragraph in section 5.2.1 as it was duplicative of second to last paragraph in 4.0; and updated section 5.1.1 to add section references. -11.11. Change from 07 to 08 +11.12. Change from 07 to 08 Updated section 3.8 and 5.1.1 to provide clarity on server processing and response of various scenarios (i.e. "quiet" period processing). -11.12. Change from 06 to 07 +11.13. Change from 06 to 07 Updated section 3.8 and 4.0 to provide clarity on server processing and response of various scenarios. -11.13. Change from 05 to 06 +11.14. Change from 05 to 06 Updated scheme to version 0.23 to allow the return of no element(s) if an error situation occurs. Edited section 3.8 extensively after input from interim meeting and REGEXT F2F meeting at IETF-99. Added normative reference for draft-ietf- eppext-launchphase. -11.14. Change from 04 to 05 +11.15. Change from 04 to 05 Updated scheme to version 0.21 to support the lang attribute for the reason element of the objectCDType and the commandType types as well as to add the update command to the commandEnum type. Updated section 3.1 to include language for the custom command. Added section 3.9 to provide a description of the element. Fixed typos and added clarification text on when client fee is less than server fee in section 4. Additionally, I added description pointers to appropriate Section 3 definitions for element clarity throughout the document. -11.15. Change from 03 to 04 +11.16. Change from 03 to 04 Updated scheme to version 0.19 to correct typos and to replace the commandTypeValue type with the commandEnum type and customName attribute for stricter validation. Updated various text for grammar and clarity. Added text to section 4 clarifying the response when the client provided no fee extension but the server was expecting the extension. -11.16. Change from 02 to 03 +11.17. Change from 02 to 03 Updated scheme to version 0.17 to simplify the check command syntax. Moved fee avail to objectCDType to allow fast failing on error situations. Removed the objectCheckType as it was no longer being used. Updated examples to reflect these scheme changes. Added language for server failing a if the passed by the client is less than the server fee. -11.17. Change from 01 to 02 +11.18. Change from 01 to 02 Updated scheme to version 0.15 to fix errors in CommandType, objectCDType, transformCommandType and transformResultType definitions. -11.18. Change from 00 to 01 +11.19. Change from 00 to 01 Added Roger Carney as author to finish draft. Moved Formal Syntax section to main level numbering. Various grammar, typos, and administrative edits for clarity. Removed default value for the "applied" attribute of so that it can truly be optional. Added support for the command to return a element as well. Modified default response on the command for the optional when it was not provided in the command, leaving it to the server to provide the default period value. Extensive edits were done to the command, the response and to the fee extension schema (checkType, objectCheckType, objectIdentifierType, objectCDType, commandType) to support requesting and returning multiple transformation fees in a single call. Added section on Phase/Subphase to provide more context on the uses. -11.19. Change from draft-brown-00 to draft-ietf-regext-fees-00 +11.20. Change from draft-brown-00 to draft-ietf-regext-fees-00 Updated to be REGEXT WG document. 12. References 12.1. Normative References [ISO4217:2015] International Organization for Standardization, "Codes for the representation of currencies", August 2015,