[Acme] AD review of draft-ietf-acme-authority-token-05

[Roman Danyliw <[e-mail]>]

Hi!

I performed an AD review of draft-ietf-acme-authority-token.  Thanks for writing this document in an extensible way (for additional token types).  Below is my detailed feedback.

** What is the intended status of this document? The document says Informational; the datatracker and the shepherd's report says Proposed Standard.  TnAuthlist is PS.  These four places need to be consistent.

** Are there implementations of this document?  The rough history in ACME seems to have been PS should have implementation experience.  Is the link to STIR decisive here (to make it PS)?

** ID-Nits reported the following issues with references being listed but not used:
  == Unused Reference: 'I-D.ietf-acme-service-provider' is defined on line
     455, but no explicit reference was found in the text

  == Unused Reference: 'I-D.ietf-acme-star' is defined on line 460, but no
     explicit reference was found in the text

  == Unused Reference: 'RFC7340' is defined on line 477, but no explicit
     reference was found in the text

  == Unused Reference: 'RFC8224' is defined on line 494, but no explicit
     reference was found in the text

  == Unused Reference: 'RFC8225' is defined on line 500, but no explicit
     reference was found in the text

** Additionally, on the topic of references, why are [I-D.ietf-acme-authority-token-tnauthlist] , [RFC7340] and [RFC8226] normative?

-- Section 1. [I-D.ietf-acme-telephone] is an expired draft that doesn't appear to be actively advanced.  Given that it primarily to show an example use case, it should likely be an informative, not normative, reference.

** In the introductory materials (abstract and/or Section 1), I would have benefited from an upfront statement that this document is describing an architecture for Authority Tokens, a particular token format, a new protocol for retrieving the token, and integration of this token into an ACME challenge.  In particular the existence of the new protocol (between the TA and the client) was not clear.

** The tkauth-type="atc" type doesn't seem to describe all of the required information described by Section 3.1 - 3.3 and Section 9 (Security Considerations) as being needed for a token format.  Specifically:

(a) Section 3.1.  Per "Definitions of a tkauth-type MUST specify how they manage the freshness of authority assignments", how is freshness of authority assignment handled in tkauth-type="atc"?

(b)  Section 3.2 suggests that tokens need to convey scope.  This scope seems to be identifier specific conveyed through the tkvalue.  However, the values of tkvalue is out of scope of this document.

(c) Section 3.3. suggests "To mitigate this, Authority Tokens contain a binding signed by an Authority".  Section 9 says "... all Authority Tokens MUST contain a field that identifies to the CA which ACME client requested the token from the authority; here that is the fingerprint specified in Section 4)."  However, Section 4 says, "For the purposes of the "atc" tkauth-type, the binding "fingerprint" is assumed to be a fingerprint of the ACME credential for the account used to request the certificate, but the specification of how the binding is generated is left to the identifier type profile for the Authority Token."  This seems to suggest that defining the binding computation is out scope of this document.

For the binding, I'm curious on how is it computed (on what input? How are algorithms/keys selected) and when does this need to occur?

Minimally, it seems that properties (b) and (c) can only be satisfied with the combination of this document and a particular "identifier profile".  Perhaps this section is spelling out requirements for both of those collectively?  If so, this should be explicitly stated (perhaps in the intro to Section 3, reminded in Sections 4 and 9).

** Editorially, decide on where the text will use AT and TA; Authority Token and Token Authority; or token and authority.  It would be clear if it was the fewest possible version of this key terms.

** Section 3.  Editorial.  The title "Challenges for an Authority Token" might be clearer if reworded given that ACME has "challenges" - perhaps s/Challenges for an Authority Token/ACME Authority Token Challenge/

** Section 3.  The text notes that authority tokens can be used for ACME challenges, but this document doesn't add a new challenge type to the "ACME Validation Methods" registry.  Section 6 provides an example using token-tnauthlist which seems to suggest a type="tkauth-01", but that isn't specified in draft-ietf-acme-token-tnauthlist or this document.

I also found it jarring to jump into the discussion of tkauth-type and token authority without a bit more context.  I recommend replacing the last paragraph as follows:

OLD
ACME challenges that support Authority Tokens ...

NEW

The ACME Authority Token Challenge, "tkauth-01", supports different token types.  The token type is determined by a new ACME challenge field, tkauth-type.  An IANA registry is used to manage the values of tkauth-type, see Section 8.*.  Additionally, this challenge also has a new "token-authority" field to designate a location where a token can be acquired.

** Section 3.1. Per "The IANA will maintain a registry of tkauth-types under a policy of Specification Required", move this text about registry policy to the IANA section

** Section 3.1.  Per "... future specifications must indicate how a token conveys to the CA the name(s) ...", is there a reason this isn't a normative MUST?

** Section 3.1.  Per "The protocols used to request an Authority Token MUST convey to the Token Authority the identifier type and value from the ACME challenge ...", the language of "from the ACEM challenge" suggests only a workflow where the token is requested after engagement with the ACME server.  However, Section 3.2 suggests that a client might get the token before engaging the ACME server.  Maybe s/from the ACME challenge/from or what will be used in the ACME challenge/

** Section 3.2.  Editorial. Somewhere earlier in the text state "Authority Token (AT)", as no text currently establishes this acronym.

** Section 3.2.  Editorial. Consistently use "Authority Token", s/to a client a Token/to a client an Authority Token/

** Section 3.2.  Per "an Authority Token could attest to all of the resources that the client is eligible to receive certificates for", couldn't this leaks information to a CA, if that single CA is not responsible for all of the scopes?

** Section 3.2. Editorial. Consistently use "Token Authority" instead of "Authority" to make it clear were aren't saying "Certificate Authority"

** Section 3.3.  Editorial. I found it confusing to use "binding" and both a noun and a verb:
-- "To mitigate this, Authority Tokens contain a binding signed by an Authority ..."
-- "Binding an Authority Token to a particular ACME account ..."

** Section 4.  Editorial.

OLD
This draft registers a tkauth-type of "atc", for the Authority Token
   Challenge.   Here the "atc" tkauth-type signifies a standard JWT token
   [RFC7519] using a JWS-defined signature string [RFC7515]. This may
   be used for any number of different identifier types given in ACME
   challenges.  The "atc" element (defined below) lists the identifier
   type used by tokens based on ATC .  The use of "atc" is restricted to
   JWTs, if non-JWT tokens were desired for ACME challenges, a different
   tkauth-type should be defined for them.

NEW
This draft specifies a tkauth-type of "atc" which is a standard JWT token [RFC7519] using a JWS-defined signature string [RFC7115].  The "atc" tkauth-type MAY be used for any number of different ACME identifier types in the ACME challenge.  A new JWT claim, "atc", is defined below and lists the identifier type used in this Authority Token.  The "atc" tkauth-type is restricted to the JWTs; if a non-JWT token format is desired for the ACME Authority Token Challenge, a different tkauth-type should be specified and registered in the "xxx" registry defined in Section 8.*

** Section 4.  Editorial. ATC is used but never explicitly defined as being "Authority Token Challenge (ATC)".

** Section 4.  What would be the circumstance where the x5u/iss would not equal the token-authority?

** Section 4.  Why is "The JWT payload must also contain a ...", not a normative MUST?

** Section 4.  Should the values of tktype be constrained to the IANA "ACME Identifier Types" registry?

** Section 4.  This text should explicitly say that "tkvalue" semantics are outside the scope of this document.

** Section 4. s/"atc" element/"atc" claim/

** Section 4.  The example in this section is missing the full payload/protected /signature structure to show the actual binding provided by the server

** Section 5.  This token acquisition protocol seems underspecified:
-- How does the client authenticate/do authorization with the HTTPS server?

-- Is there any semantics to the resource locator to make for an interoperable/discoverable URI?

-- Does the client get to request a scope?

** Section 5. Editorial. s/a Authority Token/an Authority Token/

** Section 5.1.  It might be useful to show a full server response example given a particular client request

** Section 5.1
After an HTTPS-level challenge to verify the identity of the client
   and subsequently making an authorization decision , in the success
   case the Token Authority returns a 200 OK with a body of type
   "application/json"  containing the Authority Token.

-- What is an "HTTPS-level challenge"?

-- It seems like a few words are missing describing the server's behavior to describe what happens between client sending the JSON "atc" blob and returning an authority token?  Should there be text about signing? The server validating the scope in a some identifier specific way?

-- How is error handling managed with the HTTP error code?  The TnAuthlist draft actually specifies this behavior more that this base document.

-- Section 5.  Shouldn't a successful response from a Token Authority return a body of type "application/jwt" if an "authority token" is being returned per Section 4?

** Section 6.  This section seems underspecified with only the use of an example.  It provides no normative text on using the authority token in the ACME challenge.  For example, what type should be used (tkauth-01)?  What is the cardinality of tk-auth-type, token-authority, token?

** Section 8.  This text registers "atc" as an ACME identifier.  When and how is that used?  I thought that identifier profiles specified an identifier and that the atc what the challenge/verification type.

** Section 8.  Is there a reason that the "atc" claim from Section 4 not being registered in the "JSON Web Token Claims" registry?

** Section 8.  Per the registry of "token types", there don't seem to be enough details here:
-- Is the intent for the registry to be called (in lower case) "token types".  Shouldn't it be something like "ACME Authority Token Challenge Types"?

-- What columns are in that registry?  Please be explicit, if it is Label and Reference.

Regards,
Roman