Grant Negotiation and Authorization Protocol
draft-ietf-gnap-core-protocol-20

[Ballot comment]
Thanks for addressing my concerns by either document changes or by clarifications to me why I was wrong :)

Please do not forget to talk to the RFC Editor about the "lots of blue links bleeding" in the document.

I have updated my Ballot to Yes

[Ballot discuss]
[updated on 08/03/2024, apologies for the delay)

First, let me thank you for a very clear document with the largest Security Considerations section I've ever seen and an extensive Privacy Considerations Section. I'll be using these as examples in the future :)

I have a a number of questions regarding the normative language in the document that I'm populating mostly in the comments, but I wanted to hightlight two
in the discuss section:

1) Section 2:

        access_token (object / array of objects):

        Describes the rights and properties associated with the requested
        access token. REQUIRED if requesting an access token. See
        Section 2.1.

I believe "access_token" should be "access"? The whole thing is an "access_token"
and the example shows an undocumented "access" field. It also matches the text
and structure of Section 2.1.1 if this was called "access". This also requires
updating section 11.2.2. If "access_token" is really meant here, the field
below is misnamed "access". I am a bit confused as Section 12 shows a lot
of implementations, so what am I missing here?


2) Section 13.28 on Exhaustion of Random Value Space

Why does this section not recommend using a KDF to produce random to prevent
exhaustion. Or if one believes that is dangerous as a default, to only do
this when it is running low on random? Even if reseeding a KDF every 5 minutes,
that is still a 99.999% reduction in required random ? Or if this is a really
bad idea, maybe add text to prevent people like me implementing it as "smart"? :)

[Ballot comment]
        Flag values MUST NOT be included more than once.

What is the action expected when it does appear more than once? Presumably
return an "invalid_request" error ?

Update [I-D.ietf-secevent-subject-identifiers] to [RFC9493]
Update [draft-ietf-uta-rfc6125bis-15] to [RFC9525]

        Possible values include id_token for an OpenID Connect ID Token

Is there a reason this is called "id_token" and not "openid_token" which
seems far more descriptive of what it is? I guess it is probably too late
to change this now :/

        If omitted, the AS SHOULD assume that subject information requests
        are about the current user and SHOULD require direct interaction
        or proof of presence before releasing information.

Why are these SHOULDs and not MUSTs? When can it be about a non-current user?
When can it omit requiring proo of presence?

        Client information MUST either be sent by value as an object or by reference as a string

This "MUST" really seems a "can be". I mean what other options are there than by value or by reference?

        MUST exercise caution

What normative caution is that? In other words, if an implementer writes a test case for each MUST and
SHOULD in the document, how does one test this "MUST"?

        it SHOULD return an invalid_client error (Section 3.6) or
        interpret the request as if the class_id were not present

I don't know how the parse the applicability of this SHOULD combined with the "or".

        MAY accept or reject the request

Similar here. What is the "not" clause of this MAY ?

        The client instance's key MAY be pre-registered with the AS
        ahead of time and associated with a set of policies and allowable
        actions pertaining to that client.

Here I also think a normative MAY does not make sense. It is a just a "the client can"?

        Additional fields sent during a request but not present in a
        pre-registered client instance record at the AS SHOULD NOT be
        added to the client's pre-registered record.

Why not MUST NOT?

        A client instance that is capable of talking to multiple AS's SHOULD use a different key

Why not MUST? if it prevents known attacks?

        The instance identifier MAY be assigned to a client instance at
        runtime through a grant response (Section 3.5) or MAY be obtained
        in another fashion, such as a static registration process at
        the AS.

This also seems the MAYs are really "can". Compare this for example with

        An individual AS can define its own policies and processes for
        deciding when and how to gather the necessary authorizations
        and consent

Why is "can" and not MAY used here?

        If the client instance is identified in this manner

What is "in this matter"? The text leading up to this sentence talks about a fatal error,
so I'm confused.

        Display name of the client software. RECOMMENDED.

Why is this recommended? Isn't this a privacy leak that could make it easier to find
vulnerable software?


        the AS SHOULD reject the request with an unknown_user error (Section 3.6).

Does the SHOULD bind to "reject" the the specific error "unknown_user" ? If it binds
to the reject, what is a reason to not reject a disallowed cross-user authorization ?

NITS:

Is the common spelling "mTLS" or "MTLS" ?

I find the double links used a bit weird, eg:

        Additional assertion formats are defined by the GNAP Assertion Formats Registry (Section 11.5).

This makes the text "GNAP Assertion Formats Registry" a link as well as "Section 11.5" and the links
are to the same thing. I think only making the "Section 11.5" a link would improve the readability
by preventing very long links (which also look like they could be links to outside the document.
It also sometimes uses "Section X" and sometimes "(Section X)". There are paragraphs that are half
blue due to this method of using linking. I really personally like [link] to be clearly within the
same document - currently the links without brackets appear to be external links even though they are not.

If a number of examples follow each other, such as in Section 2.5, the text:

        In this non-normative example,

it becomes very confusing. If one has been scrolling, it is not clear if the text applies to the example above
or below the text. Maybe instead write "In the following non-normative example" ?

Section 3.3.4:

uri (string):

        The interaction URI that the client instance will direct the RO
        to. This URI MUST be short enough to be communicated to the end
        user by the client instance. It is RECOMMENDED that this URI be
        short enough for an end user to type in manually.

This worried me a bit as short URLs are mostly done by large wealthy corporations,
or via URL shorteners. The last one being a risk redirect. One char off could get
you a malicious page that looks like the real thing. Typing in even a short URI
by a user seems a security risk? I guess QR codes would negate these though.

        It is RECOMMENDED that this code be no more than eight characters
        in length. REQUIRED.

How about 0? or 1 :P
As in, I think you are saying "a minimum of 8 and RECOMMENDED not more" ?

Section 3.3 and 3.4 seem to omit the "This non-normative example" preamble
that other sections have used.

Section 3.6


        If the AS determines that the request cannot be completed for
        any reason, it responds to the client instance with an error
        field in the response message. This field is either an object
        or a string.When returned as an object, the object contains the
        following fields:

        code (string):

        A single ASCII error code defining the error. REQUIRED.

Why is "code" not named "error_code" or "error_string" ? (error_code to
me feels numeric but I might just be too old). Again it is probably too
late to change this?

The error codes also return very specific error failure mode that could
help an attacker. Would it perhaps make sense to limit these to one "request_denied" ?
I know this is an issue of "easier debugging" vs "making attacks harder" issue.

Are the error code descriptions flexible? Eg can they be changed based on the known
user's language preference? Are these descriptions static mandatory strings (which
is not clear to me that they are)

Section 4.1.2 and 4.1.3 contain a lot of duplicate text. I think it would be clearer
to reference it and highlight the differences (if any). Now one needs to stare at
trying to find differences.

Section 5:

        The new continue response MUST include a continuation access
        token as well, and this token SHOULD be a new access token,
        invalidating the previous access token.

Why SHOULD and not MUST?

Section 5.4:

        If the request is successfully revoked, the AS responds with
        status code HTTP 204 (No Content).

What should be returned if this fails?

Section 6.2:

The first SHOULD and MUST seem to not both be possible ?

[Ballot comment]
===

My own review isn't done yet, but forwarding some comments from Orie Steele, incoming ART Area Director:

"""
The AS is uniquely defined by the grant endpoint URI, which the absolute URI where grant requests are started by clients.
"""

Suggested change "which is the absolute URI" (missing is?).

"""
Grant:

(verb): to permit an instance of client software to receive some attributes at a specific time and valid for a specific duration and/or to exercise some set of delegated rights to access a protected resource;

(noun): the act of granting permission to a client instance.

"""

I wonder if these definitions can be shortened to the following without loss of generality?

"""
Grant:
(verb): to permit an instance of client software to receive attributes or to access protected resources.
(noun): an expression of attributes or permissions given to an instance of client software.
"""
...
"""
Some promises can be conditional of some previous interactions (e.g. repeated requests).
"""

Suggested change: Some promises can be conditioned on previous interactions (e.g. repeated requests).

"""
In may cases, this happens through a front-channel interaction through the end user's browser.
"""

Suggested change: In many cases,...

In section-2.1.1

"""
A unique name chosen by the client instance to refer to the resulting access token.
"""

Is this meant to be a machine facing string, or a human facing one?
Are there unicode consideration that apply to this field, similar to https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-sfbis-05#section-3.3.8 ?

Put another way, is deceptive text a security consideration for this field?

"""
Each object is a subject identifier as defined by [[I-D.ietf-secevent-subject-identifiers](https://datatracker.ietf.org/doc/html/draft-ietf-secevent-subject-identifiers-18)].
"""

Suggest to update reference to: https://datatracker.ietf.org/doc/html/rfc9493


"""
If the identified end user does not match the RO present at the AS during an interaction step, and the AS is not explicitly allowing a cross-user authorization, the AS SHOULD reject the request with an unknown_user error.
"""

Why not MUST?

Section 2.5.3.1 Indicate Desired Interaction Locales

It would have been good to have gotten an i18n review based on this section.

I recommend a reference to https://datatracker.ietf.org/doc/html/rfc5895 regarding international domain names, to ensure that language considerations in URLs are also addressed.

In section 3, an informative or normative reference for DID should be provided.

In section 3.4


"""
value (string):
The assertion value as the JSON string serialization of the assertion. REQUIRED.
"""

The example starts with "eyj...", is this value meant to also be base64url encoded?

It seems like this might also be a JWT, in which case, its not a JSON string, its a string of base64url encoded JSON strings separated by periods.

A less elided example might be helpful here.

Section 4.1.2 rightly warns of deceptive / indistinguishable unicode, you might consider a citation to https://datatracker.ietf.org/doc/rfc8264/

Section 5.3

"""
  The AS SHOULD check that this presented user information is
  consistent with any user information previously presented by the
  client instance or otherwise associated with this grant request.
"""

What happens if this check is not performed or the information does not match?

References to ietf-httpbis-message-signatures should be updated to https://datatracker.ietf.org/doc/html/rfc9421

In section 7.3.3

+jwsd is introduced, but there is no corrosponding registered Structured Syntax Suffixes in https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml or in the document.

Similarly  `typ: gnap-binding+...` implies a registered media type of `application/gnap-binding+...`

`gnap-binding-rotation` is also present but not requested to be registered via IANA media types registry.

In section 11, you may wish to comment on if expired drafts are acceptable references for specification required, so that experts have guidance on this topic.

In 11, I wonder if it is truly necessary to request 16 registries from IANA, given the initial entries for some of the registries contain only a single reference.

[Ballot discuss]
Thank you for the work on this document.

Holding a DISCUSS for Orie Steele (incoming ART AD) who caught this:

DISCUSS:

This document appears to required registered media types of the form:

application/gnap-binding+jwsd
application/gnap-binding-rotation+jwsd

These are inline with the JWT BCP:  https://datatracker.ietf.org/doc/html/rfc8725#name-use-explicit-typing

However, they are not currently requested for registration, as either standalone media types, or as Structured Syntax Suffixes.

I believe this can easily be addressed, by requesting registrations in the appropriate iana registries:

- https://www.iana.org/assignments/media-types/media-types.xhtml
- https://www.iana.org/assignments/media-type-structured-suffix/media-type-structured-suffix.xhtml

[Ballot discuss]
I have a a number of questions regarding the normative language in the document that I'm populating in the comments section shortly. I think this adds up to a DISCUSS level.

Section 2:

        access_token (object / array of objects):

        Describes the rights and properties associated with the requested
        access token. REQUIRED if requesting an access token. See
        Section 2.1.

I believe "access_token" should be "access". The whole thing is an "access_token"
and the example shows an undocumented "access" field. It also matches the text
and structure of Section 2.1.1 if this was called "access".

[Ballot comment]
# Internet AD comments for draft-ietf-gnap-core-protocol-18
CC @ekline

* comment syntax:
  - https://github.com/mnot/ietf-comments/blob/main/format.md

* "Handling Ballot Positions":
  - https://ietf.org/about/groups/iesg/statements/handling-ballot-positions/

## Nits

### S1.2

* "which the absolute" -> "which is the absolute", I think

### S13.9

* "able capture of" -> "able to capture", I think

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

IANA has completed its review of draft-ietf-gnap-core-protocol-16. If any part of this review is inaccurate, please let us know.

The IANA understands that, upon approval of this document, there are eighteen actions which we must complete.

First, in the HTTP Authentication Schemes registry in the Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry group located at:

https://www.iana.org/assignments/http-authschemes/

a single new registration will be made as follows:

Authentication Scheme Name: GNAP
Reference: [ RFC-to-be; Section 7.2 ]
Notes:

Second, a new registry group will be created called "Grant Negotiation and Authorization Protocol" with a reference to [ RFC-to-be ].

All of the remaining actions for IANA - upon approval of this document - are the creation of new registries in this newly created registry group. For each new registry, and each new registration, the reference for the IANA action will be [ RFC-to-be ].

We had also recently proposed in an early review for IETF 118 to prepend "GNAP" to each of the 16 new registries being created. We would need this to be reflected in the names of the registries in the document, as we will use the names used there when creating these registries.

Third, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Grant Request Parameters. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
------+----+------------
access_token object [ RFC-to-be; Section 2.1.1 ]
access_token array of objects [ RFC-to-be; Section 2.1.2 ]
subject object [ RFC-to-be; Section 2.2 ]
client object [ RFC-to-be; Section 2.3 ]
client string [ RFC-to-be; Section 2.3.1 ]
user object [ RFC-to-be; Section 2.4 ]
user string [ RFC-to-be; Section 2.4.1 ]
interact object [ RFC-to-be; Section 2.5 ]
interact_ref string [ RFC-to-be; Section 5.1 ]

Fourth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Access Token Flags. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Allowed Use Reference
-------+-------------------+-------------------------------------------
bearer Request, Response [ RFC-to-be; Section 2.1.1; Section 3.2.1 ]
durable Response [ RFC-to-be; Section 3.2.1 ]

Fifth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Subject Information Request Fields. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
-----+-----+------------
sub_id_formats array of strings [ RFC-to-be; Section 2.2 ]
assertion_formats array of strings [ RFC-to-be; Section 2.2 ]
sub_ids array of objects [ RFC-to-be; Section 2.2 ]

Sixth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Assertion Formats. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Reference
-----+------------
id_token [ RFC-to-be; Section 2.2; Section 3.4 ]
saml2 [ RFC-to-be; Section 2.2; Section 3.4 ]

Seventh, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Client Instance Fields. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
-----+----+------------
key object [ RFC-to-be; Section 7.1 ]
key string [ RFC-to-be; Section 7.1.1 ]
class_id string [ RFC-to-be; Section 2.3 ]
display object [ RFC-to-be; Section 2.3.2 ]

Eighth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Client Instance Display Fields. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
------+----+---------------
name string [ RFC-to-be; Section 2.3.2 ]
uri string [ RFC-to-be; Section 2.3.2 ]
logo_uri string [ RFC-to-be; Section 2.3.2 ]

Ninth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Interaction Start Modes. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Mode Type Reference
-----+----+---------------
redirect string [ RFC-to-be; Section 2.5.1.1 ]
app string [ RFC-to-be; Section 2.5.1.2 ]
user_code string [ RFC-to-be; Section 2.5.1.3 ]
user_code_uri string [ RFC-to-be; Section 2.5.1.4 ]

Tenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Interaction Finish Methods. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Mode Reference
-----+------------
redirect [ RFC-to-be; Section 2.5.2.1 ]
push [ RFC-to-be; Section 2.5.2.2 ]

Eleventh, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Interaction Hints. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There is an initial registration in the new registry as follows:

Mode Reference
-----+-------------
ui_locales [ RFC-to-be; Section 2.5.3 ]

Twelveth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Grant Response Parameters. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
------+----+------------
continue object [ RFC-to-be; Section 3.1 ]
acces_token object [ RFC-to-be; Section 3.2.1 ]
acces_token array of objects [ RFC-to-be; Section 3.2.2 ]
interact object [ RFC-to-be; Section 3.3 ]
subject object [ RFC-to-be; Section 3.4 ]
instance_id string [ RFC-to-be; Section 3.5 ]
error object [ RFC-to-be; Section 3.6 ]

Thirteenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Interaction Mode Responses. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Reference
-----+------------
redirect [ RFC-to-be; Section 3.3 ]
app [ RFC-to-be; Section 3.3 ]
user_code [ RFC-to-be; Section 3.3 ]
user_code_uri [ RFC-to-be; Section 3.3 ]
finish [ RFC-to-be; Section 3.3 ]
expires_in [ RFC-to-be; Section 3.3 ]

Fourteenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Subject Information Response Fields. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
------+----+--------------
sub_ids array of objects [ RFC-to-be; Section 3.4 ]
assertions array of objects [ RFC-to-be; Section 3.4 ]
updated_at string [ RFC-to-be; Section 3.4 ]

Fifteenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Error Codes. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Error Reference
----+-----------
invalid_request [ RFC-to-be; Section 3.6 ]
invalid_client [ RFC-to-be; Section 3.6 ]
invalid_interaction [ RFC-to-be; Section 3.6 ]
invalid_flag [ RFC-to-be; Section 3.6 ]
invalid_rotation [ RFC-to-be; Section 3.6 ]
key_rotation_not_supported [ RFC-to-be; Section 3.6 ]
invalid_continuation [ RFC-to-be; Section 3.6 ]
user_denied [ RFC-to-be; Section 3.6 ]
request_denied [ RFC-to-be; Section 3.6 ]
unknown_interaction [ RFC-to-be; Section 3.6 ]
too_fast [ RFC-to-be; Section 3.6 ]
too_many_attempts [ RFC-to-be; Section 3.6 ]

Sixteenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Key Proofing Methods. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Method Type Reference
-------+-----+-----------------------------
httpsig string [ RFC-to-be; Section 7.3.1 ]
httpsig object [ RFC-to-be; Section 7.3.1 ]
mtls string [ RFC-to-be; Section 7.3.2 ]
jwsd string [ RFC-to-be; Section 7.3.3 ]
jws string [ RFC-to-be; Section 7.3.4 ]

Seventeenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Key Formats. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Format Reference
------+-------------
jwk [ RFC-to-be; Section 7.1 ]
cert [ RFC-to-be; Section 7.1 ]
cert#S256 [ RFC-to-be; Section 7.1 ]

Eighteenth, in the newly created registry group called "Grant Negotiation and Authorization Protocol," a new registry will be created called Authorization Server Discovery Fields. Future assignments and modifications to existing assignment are to be made through the Specification Required registration policy as defined in RFC 8126.

There are initial registrations in the new registry as follows:

Name Type Reference
-----+-----+----------
grant_request_endpoint string [ RFC-to-be; Section 9 ]
interaction_start_modes_supported array of strings [ RFC-to-be; Section 9 ]
interaction_finish_methods_supported array of strings [ RFC-to-be; Section 9 ]
key_proofs_supported array of strings [ RFC-to-be; Section 9 ]
sub_id_formats_supported array of strings [ RFC-to-be; Section 9 ]
assertion_formats_supported array of strings [ RFC-to-be; Section 9 ]
key_rotation_supported boolean [ RFC-to-be; Section 9 ]

We understand that these eighteen actions are the only ones required to be completed upon approval of this document.

NOTE: The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Sr. Specialist

The following Last Call announcement was sent out (ends 2023-11-21):

From: The IESG
To: IETF-Announce
CC: draft-ietf-gnap-core-protocol@ietf.org, gnap-chairs@ietf.org, rdd@cert.org, txauth@ietf.org, yaronf.ietf@gmail.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Grant Negotiation and Authorization Protocol) to Proposed Standard


The IESG has received a request from the Grant Negotiation and Authorization
Protocol WG (gnap) to consider the following document: - 'Grant Negotiation
and Authorization Protocol'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2023-11-21. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  GNAP defines a mechanism for delegating authorization to a piece of
  software, and conveying the results and artifacts of that delegation
  to the software.  This delegation can include access to a set of APIs
  as well as subject information passed directly to the software.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-gnap-core-protocol/



No IPR declarations have been submitted directly on this I-D.

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

There is working group consensus on this document.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

No.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

Yes, multiple implementations exist. See https://www.ietf.org/archive/id/draft-ietf-gnap-core-protocol-14.html#name-implementation-status

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

GNAP lives in the same general space is OAuth, and over the years several people from the OAuth community have been involved. This includes the authors who are also active in the OAuth WG. Also, the document relies on technology from the SecEvent WG and from httpbis (message signatures). Since some of the same people are involved on both sides, no further review is called for.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

N/A.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

All issues have been addressed, in particular the Security Area list.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard. This is a protocol specification with several existing implementations, including some in production.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes, and the authors confirmed the BCP has been followed.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes. N/A.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

There are still some non-ASCII characters in the document, the authors are figuring out how to get rid of them.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

Reviewed, and I believe the distinction is correct.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

There are two normative references to non-IETF documents which are known stable: SAML and OpenID Connect.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

The document defines numerous IANA registries (Sec. 11). The name and DE guidance seem reasonable.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

All 16 registries require a DE.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

There is working group consensus on this document.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

No.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

Yes, multiple implementations exist. See https://www.ietf.org/archive/id/draft-ietf-gnap-core-protocol-14.html#name-implementation-status

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

GNAP lives in the same general space is OAuth, and over the years several people from the OAuth community have been involved. This includes the authors who are also active in the OAuth WG. Also, the document relies on technology from the SecEvent WG and from httpbis (message signatures). Since some of the same people are involved on both sides, no further review is called for.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

N/A.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

N/A.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

N/A.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

All issues have been addressed, in particular the Security Area list.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed Standard. This is a protocol specification with several existing implementations, including some in production.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes, and the authors confirmed the BCP has been followed.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes. N/A.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

There are still some non-ASCII characters in the document, the authors are figuring out how to get rid of them.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

Reviewed, and I believe the distinction is correct.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

N/A.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

There are two normative references to non-IETF documents which are known stable: SAML and OpenID Connect.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

The document defines numerous IANA registries (Sec. 11). The name and DE guidance seem reasonable.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

All 16 registries require a DE.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://wiki.ietf.org/group/ops/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://wiki.ietf.org/group/iesg/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/