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)
> 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.
- RFC2119 language is probably not appropriate in Abstract
- 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 ...
> 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.
> 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.
> 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.
- Furthermore, "Allocation Token" everywhere (with caps) would be a
better choice.
> 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)
> 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.
- 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.
> 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.
> 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 ;)
- Also, remove "detailed" from the <info> command text.
> 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...)
> 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"
> 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).
> <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.
> that serves as a marker to the server to return the
> <allocationToken:allocationToken> element, defined in Section 2.1, in
remove "defined in..."
> 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
> 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?
Add a note that this authorization is subject to local server policy.
> 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:"
> 3.1.3. EPP <transfer> Command
Rename to "EPP <transfer> Query Command", as described above.
> 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.
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..
> 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"..
"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"?
> 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.
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.
> 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?).
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.
> 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.
> 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.
> 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.
> 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"..
> 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 :)
> 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.
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
