Alex, Thanks for the detailed review and feedback. I provide my responses to your feedback embedded below. — JG
James Gould Distinguished Engineer [email protected] 703-948-3271 12061 Bluemont Way Reston, VA 20190 Verisign.com <http://verisigninc.com/> On 1/15/18, 9:01 AM, "regext on behalf of Alexander Mayrhofer" <[email protected] on behalf of [email protected]> wrote: All, i've done a review of the draft, and my comments are as follows: I like the draft, particularly of it's simplicity and the focused purposed. However, i find the text could be more precise in some spots, particularly as i don't think examples consitute normative specifications (even though most people cut&paste them into their implementations ;). While most of the document is pretty clear, the "update" section is - frankly - confusing and underspecified. I think the draft could also benefit from a few editorial changes. My suggestions are below, between quotes from the original text: best, Alex ---- snip snip 8< ---- > Abstract > > This document describes an Extensible Provisioning Protocol (EPP) Acronynms don't need to be expanded in Abstract (see NITS documents) Yes, it may not need to be expanded, but I would like the draft to be consistent with the other EPP extension RFCs (RFC 5731, RFC 5732, RFC 5733, RFC 3915, RFC 5910). > extension for including an allocation token or for allocating an > object like a domain name to the client. The allocation token MAY be > transferred out-of-band to a client to give them authorization to > allocate an object using one of the EPP transform commands including > create, update, and transfer. - Keep "Allocation Token" with caps all across the document. It's mixed across the doc, please uppercase everywhere. Sure, that can be fixed. - RFC2119 language is probably not appropriate in Abstract Agreed, the reference to “MAY” can be changed to “may”; although use of your revise abstract language below does not require the use of “may”. - I think the "for including an allocation token or for allocating .." is a bit confusing, the "gatekeeping functionality" is not described. Therefore i suggest the following text: ... for including an Allocation Token in query and transform commands. The Allocation Token is used as a credential that authorizes a client to request the allocation of a specific object from the server, using one of the EPP transform commands ... I like your text better, so I’ll revise the draft to use it. > 3.1. EPP Query Commands . . . . . . . . . . . . . . . . . . . 4 > 3.1.1. EPP <check> Command . . . . . . . . . . . . . . . . . 4 > 3.1.2. EPP <info> Command . . . . . . . . . . . . . . . . . 8 > 3.1.3. EPP <transfer> Command . . . . . . . . . . . . . . . 10 - I suggest naming this "EPP <transfer> Query Command", in order to make a clear distinction from the transform query command, like done in 5730. The RFC’s are somewhat inconsistent on the title for this section. I agree that the use of “EPP <transfer> Query Command” is more specific and in sync with some of the EPP RFCs, so I’ll change it. > 1. Introduction > > This document describes an extension mapping for version 1.0 of the > Extensible Provisioning Protocol (EPP) [RFC5730]. This mapping, an > extension to EPP object mappings like the EPP domain name mapping > [RFC5731], for passing an allocation token to one of the EPP > transform commands including create, update, and transfer. A client - There's something missing in front of ", for".. "allows for"? Also, "passing ... IN" rather then "TO"? it's passed to the server, not the command. I believe it is best to borrow some of your proposed abstract text as in “The mapping, …, supports passing an Allocation Token as a credential that authorizes a client to request the allocation of a specific object from the server, using one of the EPP transform commands including create, update, and transfer.” Do you believe this is better? > MUST pass an allocation token known to the server to be authorized to > use one of the supported EPP transform commands. It is up to server > policy which EPP transform commands and which objects support the > allocation token. The allocation token MAY be returned to an > authorized client for passing out-of-band to a client that uses it > with an EPP transform command. - "support the allocation token" is too "soft" for me. "require" would be better. Done - Furthermore, "Allocation Token" everywhere (with caps) would be a better choice. Done > 2.1. Allocation Token > > The Allocation Token is a simple XML "token" type. The exact format > of the Allocation Token is up to server policy. The server MUST have > the allocation token for each object to match against the allocation > token passed by the client to authorize the allocation of the object. - Do we have a definition of "allocation" somewhere? EPP only "creates" objects, and i understand the connotation of "allocation" of pre-reserved objects, but since it's at the basis of the document, we should define it (or refer to a definition) Agreed, a definition would help. How about adding a definition in the Introduction, as in the following? “Allocation is when a server assigns the sponsoring client of an object based on the use of an Allocation Token credential. Examples include allocating a registration based on a pre-eligibility Allocation Token, allocating a premium domain name registration based on an auction Allocation Token, allocating a registration based on a founders Allocation Token, and allocating an existing domain name held by the server or by a different sponsoring client based on an Allocation Token passed with an update or transfer command.” > The same <allocationToken:allocationToken> element is used for all of > the supported EPP transform commands as well as the info response. - The element is also used in the "check" command which is not a transfer command. Suggest shortening this to "for transporting the Allocation Token in all of the supported EPP commands." I understand the allocationToken:info element is also used, but in that case, no Token is transmitted. Done, I removed the word “transform” from “supported EPP transform commands” to be “supported EPP commands”. - Also, i suggest using "the same ... element type" here, since (although i'm not a native speaker) "element" sounds to me like the same element *instance*, which is certainly not true. Maybe simply remove the word “same” so it reads “The <allocationToken:allocationToken> element is used for …”. Do you agree? > If an invalid allocation token is passed the server MUST return an > EPP error result code of 2201. - What's "invalid"? i suggest using "When an Allocation Token passed to the server does not match the Allocation Token associated with the object...". This would exclude syntactical problems. My only concern with your text is that it is assumed that there is an Allocation Token pre-assigned to the object, which is not the case. I do agree that the 2201 error is associated with a mismatch of the Allocation Token and the object. How about changing the sentence to read “If the Allocation Token passed to the server does not apply to the object, the server MUST return an EPP error result code of 2201.”? > EPP provides three commands to retrieve object information: <check> > to determine if an object is known to the server, <info> to retrieve > detailed information associated with an object, and <transfer> to > retrieve object transfer status information. - This is not what 5730 defines for "<check>". It says "if an object can be provisioned". Let's stick to this rather trying to update RFC5730 ;) Done - Also, remove "detailed" from the <info> command text. Done > 3.1.1. EPP <check> Command > > This extension defines additional elements to extend the EPP <check> > command of an object mapping like [RFC5731]. > > This extension allow clients to check the availability of an object > with an allocation token, as described in Section 2.1. Clients can > check if an object can be created using the allocation token. The > allocation token is applied to all object names included in the EPP > <check> command. - I'm totally missing a description of the intended server behaviour here. This is probably the most important point of this section! Examples are not enough, we need normative text! eg. a description of: (assuming domain is available, but only with token) object requires Allocation Token, but not given in command: 1000, avail=0, reason "Allocation Token required" object requires allocation token, and correct token given: 1000, avail=1 object requires allocation token, incorrect token given: 1000, avail=0, reason "Allocation Token mismatch" object does not require allocation token, but still given: 1000, avail=1 If we don't specify that, we're down in Interop Hell. (see avail-discussion in Fee Extension...) Ok, I thought this was somewhat straight forward since there is no extension of the check response with its own “avail” attribute to describe, like is the case for the fee extension. To address your concern, how about revising the section “If the query was successful, the server replies with an <check> response providing availability status of queried object” to the text below that addresses the expected values of the “avail” attribute in the check response when the extension is or is not passed? If the query was successful, the server replies with the <check> response providing the availability status (e.g., “avail” attribute) of the queried object based on the following Allocation Token cases, where the object is otherwise available: 1. If an object requires an Allocation Token and the Allocation Token does apply to the object, then the server MUST return the availability status as available (e.g., “avail” attribute is “true”). 2. If an object requires an Allocation Token and the Allocation Token does not apply to the object or an object does not require an Allocation Token, then the server SHOULD return the availability status as unavailable (e.g., “avail” attribute is “false”). For case #2, passing the Allocation Token for an object that does not require it should be classified as a mismatch. There any many use cases for the passing of an Allocation Token, so my recommendation is to use SHOULD instead of MUST here. The example reason “Invalid domain-token pair” was replaced with the reason “Allocation Token mismatch”. The case of the check command when the extension is not passed is not covered, since that is completely up to server policy. For example, for the pre-eligibility Allocation Token use case, the Allocation Token may be required for all registrations, but the Registry would want to return the appropriate availability status to the client independent of passing the Allocation Token extension with the matching value. In this case, the protocol should not dictate the registry policy. > 3.1.2. EPP <info> Command > > This extension defines additional elements to extend the EPP <info> > command of an object mapping like [RFC5731]. > > The EPP <info> command allows a client to request information on an suggest "associated with" rather than "on" Done > existing object. Authorized clients MAY retrieve the allocation > token (Section 2.1) along with the other object information using the no need to refer to Section 2.1 here i think, if we use "Allocation Token" (in caps). Yes, but I believe it doesn’t hurt to include the reference or link in the case of HTML. > <allocationToken:info> element that identifies the extension > namespace. The <allocationToken:info> element is an empty element suggest to remove the "that identifies the extension namespace". That's defined elsewhere, and only clutters the text. Done > that serves as a marker to the server to return the > <allocationToken:allocationToken> element, defined in Section 2.1, in remove "defined in..." Done > the info response. If the client is not authorized to receive the > allocation token (Section 2.1), the server MUST return an EPP error remove section 2.1 Done > result code of 2201. If the client is authorized to receive the > allocation token (Section 2.1), but there is no allocation token > (Section 2.1) associated with the object, the server MUST return an > EPP error result code of 2303 object referencing the > <allocationToken:info> element. remove secton 2.1 references again. Plus, i don't get the "code of 2303 object referencing the .." part - remove it? Done, I removed the “object referencing the <allocationToken:info> element” from the sentence. Add a note that this authorization is subject to local server policy. Done, I added “The authorization is subject to server policy” to the end of the section. > If the query was successful, the server replies with an > <allocationToken:allocationToken> element, as described in > Section 2.1. "the server response contains" would be more precise. Again, remove the "as described in Section 2.1", or replace it with "as follows:" I believe that the reference should stay here, since the formal definition of the <allocationToken:allocationToken> element is defined in section 2.1. > 3.1.3. EPP <transfer> Command Rename to "EPP <transfer> Query Command", as described above. Done > This extension does not add any elements to the EPP <transfer> query > command or <transfer> response described in the [RFC5730]. add "query" to the "response" text here as well, to make it clear. Done Create Command: > The EPP <create> command provides a transform operation that allows a > client to create an object. In addition to the EPP command elements "an instance of an object" is the RFC5730 text.. Done > described in an object mapping like [RFC5731], the command MUST > contain a child <allocationToken:allocationToken> element, as defined > in Section 2.1, that identifies the extension namespace for the > client to be authorized to create and allocate the object. If the remove "as defined in section .... identifies... client".. Modified the sentence to include “the command MUST contain a child <allocationToken:allocationToken> element for the client to be authorized to create and allocate the object”. "create and allocate" here triggers my question from above - this will come up during IESG review if we don't define it, i fear.. remove the "create"? The definition of allocate was added to the introduction. In this case the create represents a registration (instantiate the object) and the allocate authorizes setting the sponsoring client with the use of the Allocation Token as the credential. > allocation token (Section 2.1) does not match the object's allocation > token (Section 2.1), the server MUST return an EPP error result code > of 2201.: suggest changing to "does not match the Allocation Token associated with the object", since there *is* no actual object before the create command. The text was revised to match the text in the Allocation Token section, which reads “If the Allocation Token does not apply to the object, the server MUST return an EPP error result code of 2201.”. Transfer: > The EPP <transfer> request command provides a transform operation > that allows a client to request the transfer of an object. In > addition to the EPP command elements described in an object mapping > like [RFC5731], the command MUST contain a child > <allocationToken:allocationToken> element, as defined in Section 2.1, > that identifies the extension namespace for the client to be remove the section 2.1 and namespace identification text. Done > authorized to transfer and allocate the object. If the allocation > token (Section 2.1) does not match the object's allocation token > (Section 2.1), the server MUST return an EPP error result code of > 2201. remove section 2.1 text, change to "associated with object", or "the respective Token stored at the server" (also in the other spots?). The language associated with the 2201 error has been revised to match the language of the create and the allocation token sections. In the transfer, we should also have text clarifying that this does *NOT* change the existing authInfo logic. At least i do hope so. Something like: Note that the Allocation Token does not replace the existing "authInfo" authorization methods specified in RFC5730, but rather provides an additional layer of credentials. The interworking between authInfo and Allocation Token verification is subject to local server policy. The use of “authInfo” is not defined in RFC 5730 but is in the object mappings (e.g., RFC 5731). Since the Allocation Token extension is object-agnostic, I believe it is best to provide generic language like the following: The authorization associated with the Allocation Token is in addition to and does not replace the authorization mechanism defined for the object's <transfer> request command. > 3.2.5. EPP <update> Command > This extension defines additional elements to extend an extension of > an empty EPP <update> command of an object mapping like [RFC5731]. > An example of an extension of an empty EPP <update> command is the > definition of the restore command within [RFC3915]. This confuses the hell out of me. I have no idea what the first sentence means, to be honest. Also, i understand the "release" is just a theoretical example? Since the namespace is not defined anywhere, neither is it's functionality mentioned? Therefore, i think this section needs either significant work to specify the "release" case properly (including the registration of namespace, definition of the XML schema, server behaviour, etc..) or the text must be changed in order to describe that the "release" case is just a non-normative example. The extension is meant to extend the definition of a new verb that has been handled in the past by extending an empty update as in the restore command of the RGP RFC. I am certainly not proposing in anyway the definition of a release command, but I can foresee the use of an allocation token to support the authorization of allocation using a different EPP verb. If this is too confusing and if no one else sees such a possibility, then the extension of the update can be removed. If the extension of the update remains, then the example using the fictitious release command can be removed, or the text can be changed in order to describe “release” as a non-normative example as you state. Since you’re the second one to get confused on this, we can simply remove the extension of the update. This was defined to support a potential future requirement. > An extension of an empty EPP <update> command defines a new verb that > transforms an object. In addition to the EPP command elements The introduction says that this is an object level extension. If we define a new verb, then we need to revisit the introduction as well. If you’re getting confused on the extension of an empty update to defined new verb, then I’m not sure modifying the introduction around the extension of the update will help out. If we remove the extension of the update, then all references would get removed. > described in an object mapping like [RFC5731], the command MUST > contain a child <allocationToken:allocationToken> element, as defined > in Section 2.1, that identifies the extension namespace for the > client to be authorized to allocate the object. If the allocation remove section 2.1 and namespace text. Done, the text matches the language in the create and transfer. > token (Section 2.1) does not match the object's allocation token > (Section 2.1), the server MUST return an EPP error result code of > 2201. same as above. "associated with" or "stored at server".. Done, the text matches the language in the create and the transfer. > Example use an extension of an empty <update> command to release a > domain object with an allocation token: As i said above. "To release a domain" is not a specification :) I got it. This comes down to whether or not the extension of the update is desired. I can give on this one based on getting this feedback more than once. > 5.2. EPP Extension Registry > > The EPP extension described in this document should be registered by > the IANA in the EPP Extension Registry described in [RFC7451]. The > details of the registration are as follows: suggest "The following registration the EPP Extensions Registry as described ... is requested" instead. I modified this to read “The following registration of the EPP Extension Registry, described in [RFC7451], is requested:” tia. On Fri, Jan 12, 2018 at 2:32 PM, James Galvin <[email protected]> wrote: > The document editors have indicated that the following document is ready for > submission to the IESG to be considered for publication as a Proposed > Standard: > > Allocation Token Extension for the Extensible Provisioning Protocol (EPP) > https://datatracker.ietf.org/doc/draft-ietf-regext-allocation-token-05 > > If any working group member objects to the publication of this document > please respond on the list by close of business everywhere, Friday, 26 > January 2018. If there are no objections the document will be submitted to > the IESG. > > During the last call the chairs are looking for a document shepherd for this > document. If you are interesting in being the document shepherd please let > the chairs know. The document editors can not be the document shepherd. > > Thanks, > > Antoin and Jim > WG Co-Chairs > > _______________________________________________ > regext mailing list > [email protected] > https://www.ietf.org/mailman/listinfo/regext _______________________________________________ regext mailing list [email protected] https://www.ietf.org/mailman/listinfo/regext _______________________________________________ regext mailing list [email protected] https://www.ietf.org/mailman/listinfo/regext
