2.5.1. Interaction start modes are specified by a string, which consists of <del> the start mode on its own, or by a JSON object with one required field and any number of optional parameters defined by the mode: </del>  <del> Individual modes MAY define additional parameters to be required in the object. </del>  This specification defines the following interaction start modes: Any keys presented by the client instance to the AS or RS MUST be validated as part of the request in which they are presented.  The type of binding used is indicated by the "proof" parameter of the key <del> object in key-format.  This parameter is formally specified by an object with at least the following member: </del>  <del> Individual methods MAY define additional parameters as members in this object. </del>  Values for the "method" defined by this specification are as follows: Additional proofing methods are defined by the IANA-key-proof- methods. <del> For example, the "httpsig" method can be specified with its parameters as: </del>  <del> If additional parameters are not required or used for a specific method, the method MAY be passed as a string instead of an object. For example, the "mtls" method with no additional parameters could be sent by the client instance as: </del>  <del> The AS would map this to the equivalent expanded form as follows: </del>  All key binding methods used by this specification MUST cover all relevant portions of the request, including anything that would 7.3.1. <del> This method is indicated by the method value "httpsig".  The signer creates an HTTP Message Signature as described in I-D.ietf-httpbis- message-signatures.  This method defines the following parameters: </del>  <del> The covered components of the signature MUST include the following: </del>  When the message contains a request body, the covered components MUST also include the following: 7.3.2. <del> This method is indicated by the method value "mtls".  This method defines no additional parameters.  The signer presents its TLS client certificate during TLS negotiation with the verifier. </del>  In this example, the certificate is communicated to the application through the "Client-Cert" header from a TLS reverse proxy, leading to 7.3.3. <del> This method is indicated by the method value "jwsd".  This method defines no additional parameters.  A JWS RFC7515 object is created as follows: </del>  To protect the request, the JOSE header of the signature contains the following claims: 7.3.4. <del> This method is indicated by the method value "jws".  This method defines no additional parameters.  A JWS RFC7515 object is created as follows: </del>  To protect the request, the JWS header contains the following claims.

This reformats the object-type key proofs to be defined in terms of types, in parallel with interaction start methods. Now instead of default field values, you can have either an object with parameters or a string with strictly specified behavior. This should be less susceptible to confusion than the previous definition which allowed partial objects and implied a large set of possible combinations that the receiver would have to deal with.
To edit notification comments on pull requests, go to your .
Makes sense, it's aligned with the behaviour of the rest of the doc

2.5.1. Interaction start modes are specified by a string, which consists of  <ins> the start mode name on its own, or by a JSON object with one required field and any number of parameters defined by the mode. </ins>  <ins> Individual modes defined as objects MAY define additional parameters to be required in the object. </ins> This specification defines the following interaction start modes: Any keys presented by the client instance to the AS or RS MUST be validated as part of the request in which they are presented.  The type of binding used is indicated by the "proof" parameter of the key  <ins> object in key-format.  Key proof methods are specified either by a string, which consists of the key proof method name on its own, or by a JSON object with one required field and any number of optional parameters defined by the method: </ins>  <ins> Individual methods defined as objects MAY define additional parameters as members in this object. </ins> Values for the "method" defined by this specification are as follows: Additional proofing methods are defined by the IANA-key-proof- methods.  <ins> In cases where a method's parameters can be set to omitted or set to default values, methods MAY be defined as both an object and a string.  For example, the "httpsig" method can be specified as an object with its parameters explicitly declared, such as: </ins>  <ins> The "httpsig" method also defines defines default behavior when it is passed as a string form: </ins>  <ins> This is explicitly defined as the signature algorithm specified by the associated key material and the content digest is calculated using sha-512. </ins> All key binding methods used by this specification MUST cover all relevant portions of the request, including anything that would 7.3.1.  <ins> This method is indicated by the method value "httpsig" and can be declared in either object form or string form. </ins>  <ins> When the proof method is specified in object form, the following parameters are defined: This example uses the ECDSA signing algorithm over the P384 curve and the SHA-256 hashing algorithm for the content digest. When the proof method is specified in string form, the signing algorithm MUST be derived from the key material (such as using the JWS algorithm in a JWK formatted key), and the content digest algorithm MUST be "sha-512". When using this method, the signer creates an HTTP Message Signature as described in I-D.ietf-httpbis-message-signatures.  The covered components of the signature MUST include the following: </ins> When the message contains a request body, the covered components MUST also include the following: 7.3.2.  <ins> This method is indicated by the method value "mtls" in string form. The signer presents its TLS client certificate during TLS negotiation with the verifier. </ins> In this example, the certificate is communicated to the application through the "Client-Cert" header from a TLS reverse proxy, leading to 7.3.3.  <ins> This method is indicated by the method value "jwsd" in string form. The signer creates a JWS RFC7515 object as follows: </ins> To protect the request, the JOSE header of the signature contains the following claims: 7.3.4.  <ins> This method is indicated by the method value "jws" in string form. The signer creates a JWS RFC7515 object as follows: </ins> To protect the request, the JWS header contains the following claims.


identity protocol and associated schema are outside the scope of this specification.  Extensions to this specification MAY define additional response properties in the IANA-subject-response.

To edit notification comments on pull requests, go to your .
This issue is based on a formal security analysis of the GNAP specification, which we are working on as a group in the Institute for Information Security at the University of Stuttgart, extending previous analysis work done by Florian Helmschmidt (). One of the security properties that we have been working to prove that the GNAP specification satisfies is security with respect to authentication. This security property states that an attacker should not be able to log in at an honest (protocol-following) client instance using the account of an honest end user at an honest AS. We were unable to prove that GNAP satisfies this property because of missing details about the use of GNAP as an authentication protocol, in particular about how a client instance identifies end user accounts. It is currently unclear how exactly GNAP can be used as an authentication protocol. While it seems that a realistic implementation based on the specification is most likely secure, there exist possible interpretations of the specification that are problematic. Most notably, if a client instance chooses to use the subject information returned by the AS as a sole identifier of end user accounts, the following flow is possible, in which an attacker is able to log in as an honest (protocol-following) user at an honest client, provided only that the honest user has an account at an attacker client that uses the same AS. ! Note that in this diagram, while the attacker is shown as three separate components (Attacker Client, Attacker User, and Attacker AS), we assume that there is only one attacker, which can share information between these different roles. This attack combines two flows. In the first flow, an honest end user attempts to log in using an attacker-controlled client with the identity u at an honest AS (HAS). As a result of this login flow (which is specification-compliant), the attacker client is sent the subject identifier u. In a subsequent flow, the attacker can initiate a grant with an honest client using an attacker-controlled AS (AAS), which can then return this same subject identifier u to the client. At this point, the attacker has successfully logged in at the honest client with the identity u. This flow presents a clear problem, in that an attacker is able to log in as an honest user at an honest client. Note that the first portion of this flow, where the honest user logs in at an attacker client, may be unnecessary if subject information is sufficiently guessable (e.g. if it follows the email identifier format). The simplest resolution to this problem is to clarify in the specification that client instances should not rely solely on subject information returned by an AS to identify a user account. For instance, the pair (subject information, AS) is sufficient to uniquely identify a user account at the client, since subject information uniquely identifies a user at the AS. Practically, the information identifying the AS should likely be a domain of the AS, or perhaps the URI of one of its endpoints. With this change, in order for an end user to be logged in at an honest client instance using an account managed by an honest AS, the subject information identifying that account must have been sent directly from this honest AS to the client. ! By modifying the client to use both the identity u and the AS at which it requested subject information to identify an account, this attack can be avoided. With this change, upon receiving the subject identifier u from AAS, the client logs in the attacker as (u, AAS), an account which, if it exists, has access to it managed by AAS, rather than HAS. This is related to URL This proposed change also resolves an issue with session integrity for authentication, in which an honest end user can end up logged in at an honest client as an attacker account managed by an honest AS. This attack is similar to that presented in URL The proposed change avoids this attack by limiting which accounts an attacker AS can authorize logins for to those which it manages, preventing a form of "privilege escalation" where a single attacker AS can provide access to accounts which it does not manage. In the case of authorization, presented in URL, this corresponds to the check performed by the RS to ensure that the AS at which it performs token introspection is responsible for access to the resources for which it provides access rights. If GNAP is to be used as an authentication protocol, its specification should be more explicit about what identifying information is needed to identify an end user at the CI. While reasonable implementations of the GNAP specification are unlikely to encounter this issue, it is possible to give an implementation that complies with the specification, but nevertheless has serious security issues. With this change, we are able to show both an authentication property (an attacker should not be able to log in to an honest client using the account of an honest user at an honest AS) and a session integrity property for authentication (an honest end user should not get logged in at an honest client with any other user's account at an honest AS).
Related to , but could probably use additional text in the specification. Even though GNAP is not on its own intended to be an authentication protocol, I think that clarifying that all subject information provided to a client instance needs to be taken in the context in which it was issued is a reasonable clarification, both in terms of the normative processing of the subject information as well as a security consideration. This is a common practice in federation requirements, see :
Not sure about the reference, or then specify precisely the part that's relevant

identity protocol and associated schema are outside the scope of this specification. <ins> The client instance MUST interpret all subject information in the context of the AS that the subject information is received from, as is discussed in Section 6 of SP80063C.  For example, one AS could return an email identifier of "user@example" for one account, and a different AS could return that same email identifier of "user@example" for a completely different account.  A client instance talking to both AS's needs to differentiate between these two accounts by accounting for the AS source of each identifier. </ins> Extensions to this specification MAY define additional response properties in the IANA-subject-response.


12. implementation by David Skyberg.  https://github.com/dskyberg/gnap <del> [2].  Prototype implementation of AS and Client in Rust.  MIT license. </del>  from Interledger Foundation. https://github.com/interledger/rafiki <del> [3] Production implementation of AS in JavaScript.  Apache 2.0 </del>  license. implementation by Aaron Parecki. https://github.com/aaronpk/gnap- <del> client-php [4] Prototype implementation of web application client and </del>  CLI client in PHP, with common support library.  CC0 license. <del> from SUNET. https://github.com/SUNET/sunet-auth-server [5] Production </del>  implementation of AS in Python.  BSD license.  from Bespoke Engineering, implementation by Justin Richer. <del> https://github.com/bspk/oauth.xyz-java [6].  Advanced prototype implementation of AS, Client, and RS in Java, with common support library.  Prototype implementation of SPA Client in pure JavaScript. </del>  Apache 2.0 license. 13. [2] https://github.com/dskyberg/gnap <del> [3] https://github.com/interledger/rafiki </del>  <del> [4] https://github.com/aaronpk/gnap-client-php </del>  <del> [5] https://github.com/SUNET/sunet-auth-server </del>  <del> [6] https://github.com/bspk/oauth.xyz-java </del>

To edit notification comments on pull requests, go to your .
NAME and NAME -- please check these additions to the implementation section.

12. implementation by David Skyberg.  https://github.com/dskyberg/gnap  <ins> [2] Prototype implementation of AS and client in Rust.  MIT license. from Interop Alliance, implementation by Dmitri Zagidulin. https://github.com/interop-alliance/gnap-client-js [3] Prototype implementation of client in JavaScript.  MIT License. </ins> from Interledger Foundation. https://github.com/interledger/rafiki  <ins> [4] Production implementation of AS in JavaScript.  Apache 2.0 </ins> license. implementation by Aaron Parecki. https://github.com/aaronpk/gnap-  <ins> client-php [5] Prototype implementation of web application client and </ins> CLI client in PHP, with common support library.  CC0 license.  <ins> from SUNET. https://github.com/SUNET/sunet-auth-server [6] Production </ins> implementation of AS in Python.  BSD license. <ins> from SecureKey. https://verified.me/ [7] Production implementation of AS, client and RS.  Proprietary license. </ins> from Bespoke Engineering, implementation by Justin Richer.  <ins> https://github.com/bspk/oauth.xyz-java [8] Advanced prototype implementation of AS, client, and RS in Java, with common support library.  Prototype implementation of SPA client in JavaScript. </ins> Apache 2.0 license. 13. [2] https://github.com/dskyberg/gnap  <ins> [3] https://github.com/interop-alliance/gnap-client-js [4] https://github.com/interledger/rafiki [5] https://github.com/aaronpk/gnap-client-php </ins>  <ins> [6] https://github.com/SUNET/sunet-auth-server </ins>  <ins> [7] https://verified.me/ </ins>  <ins> [8] https://github.com/bspk/oauth.xyz-java </ins>


access token, the client instance MUST present both the new key and previous key in the access token rotation request.  The client instance makes an HTTP POST as a JSON object with the following <del> fields: </del>  The "proof" method and parameters for the new key MUST be the same as those established for the previous key. <del> The client instance MUST prove possession of both keys simultaneously in the rotation request.  The means of doing so varies depending on the proofing method in use.  For example, the HTTP Message Signatures proofing method uses multiple signatures in the request as described in httpsig-rotate, as shown in this example. </del>  An attempt to change the "proof" method or parameters, including an attempt to rotate the key of a bearer token (which has no key), MUST Signature Algorithm is applied using the following RSA key (presented here in JWK format):  7.3.1. This method is indicated by the method value "httpsig" and can be new key. For example, the following request to the token management endpoint <del> for rotating a token value contains both the old and new keys in the request.  The message is first signed using the old key and the resulting signature is placed in "sig1": </del>  The signer then creates a new signature using the new key using the signature value as its input to the signature base.  Since the When keys are rotated, there could be a delay in the propagation of that rotation to various components in the AS's ecosystem.  The AS <del> can define its own policy regarding the timeout of the "previous_key", either making it immediately obsolete or allowing for a limited grace period during which both the "previous_key" and the current key can be used for signing requests.  Such a grace period can be useful when there are multiple running copies of the client that are coordinated with each other.  For example, the client </del>  software could be deployed as a cloud service with multiple orchestrated nodes.  Each of these copies is deployed using the same key and therefore all the nodes represent the same client instance to Narrowly restricting the exposure opportunities for exploit at the AS in terms of time, place, and method makes exploit significantly more difficult, especially if the exception happens only once.  For <del> example, the AS can reject requests from the "previous_key" (or any previous one before it) to cause rotation to a new key, or at least ensure that the rotation happens to the same known key. </del>  See also the related considerations for token values in security- network-management.

To edit notification comments on pull requests, go to your .
The "previous_key" element added in is not necessary in practice because the AS should always be able to look up the current key value based on the access token, and the signature using the previous key proves possession of that key separate from any presentation of the key value or reference.
Makes sense

access token, the client instance MUST present both the new key and previous key in the access token rotation request.  The client instance makes an HTTP POST as a JSON object with the following  <ins> field: </ins> The "proof" method and parameters for the new key MUST be the same as those established for the previous key.  <ins> The client instance MUST prove possession of both the currently-bound key and the newly-requested key simultaneously in the rotation request.  Specifically, the signature from the previous key MUST cover the value or reference of the new key, and the signature of the new key MUST cover the signature value of the old key.  The means of doing so varies depending on the proofing method in use.  For example, the HTTP Message Signatures proofing method uses multiple signatures in the request as described in httpsig-rotate, as shown in this example. </ins> An attempt to change the "proof" method or parameters, including an attempt to rotate the key of a bearer token (which has no key), MUST Signature Algorithm is applied using the following RSA key (presented here in JWK format): <ins> Key proofing methods SHOULD define a mechanism to allow the rotation of keys discussed in rotate-access-token-key.  Key rotation mechanisms MUST define a way for presenting proof of two keys simultaneously with the following attributes: The value of or reference to the new key material MUST be signed by the existing key.  Generally speaking, this amounts to using the existing key to sign the body of the message. The signature of the old key MUST be signed by the new key. Generally speaking, this means including the signature value of the old key under the coverage of the new key. </ins> 7.3.1. This method is indicated by the method value "httpsig" and can be new key. For example, the following request to the token management endpoint  <ins> for rotating a token value contains both the new key in the request. The message is first signed using the old key and the resulting signature is placed in "sig1": </ins> The signer then creates a new signature using the new key using the signature value as its input to the signature base.  Since the When keys are rotated, there could be a delay in the propagation of that rotation to various components in the AS's ecosystem.  The AS  <ins> can define its own policy regarding the timeout of the previously- bound key, either making it immediately obsolete or allowing for a limited grace period during which both the previously-bound key and the current key can be used for signing requests.  Such a grace period can be useful when there are multiple running copies of the client that are coordinated with each other.  For example, the client </ins> software could be deployed as a cloud service with multiple orchestrated nodes.  Each of these copies is deployed using the same key and therefore all the nodes represent the same client instance to Narrowly restricting the exposure opportunities for exploit at the AS in terms of time, place, and method makes exploit significantly more difficult, especially if the exception happens only once.  For  <ins> example, the AS can reject requests from the previously-bound key (or any previous one before it) to cause rotation to a new key, or at least ensure that the rotation happens to the same known key. </ins> See also the related considerations for token values in security- network-management.


Other message components MAY also be included.  If the signer's key presented is a JWK, the "keyid" parameter of the signature MUST be set to the "kid" value of the JWK, the signing algorithm used MUST be the JWS algorithm denoted by the key's "alg"

To edit notification comments on pull requests, go to your .
From the HTTP message sig spec : "tag: An application-specific tag for the signature as a String value. This value is used by applications to help identify signatures relevant for specific applications or protocols." Fair enough, but does a MUST requirement improve the security of the protocol ?
Yes, because it prevents cross-protocol confusion attacks. Where an attacker tries to use a signed HTTP message from another protocol in GNAP, or vice versa.
This was recently added to HTTP Signatures. Please add a standard value for GNAP messages.
LGTM

Other message components MAY also be included. <ins> The signer MUST include the "tag" signature parameter with the value "gnap", and the verifier MUST verify that the parameter exists with this value.  The signer MUST include the "created" signature parameter with a timestamp of when the signature was created, and the verifier MUST ensure that the creation timestamp is sufficiently close to the current time given expected network delay and clock skew.  The signer SHOULD include the "nonce" parameter with a unique and unguessable value.  When included, the verifier MUST determine that the nonce value is unique within a reasonably short time period such as several minutes. </ins> If the signer's key presented is a JWK, the "keyid" parameter of the signature MUST be set to the "kid" value of the JWK, the signing algorithm used MUST be the JWS algorithm denoted by the key's "alg"


in the IANA Named Information Hash Algorithm Registry [1]. If the "hash_method" value is not present in the client instance's <del> request, the algorithm defaults to "sha3-512". </del>  <del> For example, the "sha3-512" hash method consists of hashing the input string with the 512-bit SHA3 algorithm.  The byte array is then </del>  encoded using URL-Safe Base64 with no padding RFC4648.  The resulting string is the hash value. <del> The "sha2-512" hash method consists of hashing the input string with the 512-bit SHA2 algorithm.  The byte array is then encoded using </del>  URL-Safe Base64 with no padding RFC4648.  The resulting string is the hash value. This is explicitly defined as the signature algorithm specified by the associated key material and the content digest is calculated <del> using sha-512. </del>  All key binding methods used by this specification MUST cover all relevant portions of the request, including anything that would parameters are defined: This example uses the ECDSA signing algorithm over the P384 curve and <del> the SHA-256 hashing algorithm for the content digest. </del>  When the proof method is specified in string form, the signing algorithm MUST be derived from the key material (such as using the JWS algorithm in a JWK formatted key), and the content digest <del> algorithm MUST be "sha-512". </del>  When using this method, the signer creates an HTTP Message Signature as described in I-D.ietf-httpbis-message-signatures.  The covered

To edit notification comments on pull requests, go to your .
Nothing more than yaron's feedback
From IETF115 comments: Change the default hash for interaction_hash to sha256, and change the MTI profile to use the same.
Please search for some remaining occurrences of "sha-512".

in the IANA Named Information Hash Algorithm Registry [1]. If the "hash_method" value is not present in the client instance's  <ins> request, the algorithm defaults to "sha-256". </ins>  <ins> For example, the "sha-256" hash method consists of hashing the input string with the 256-bit SHA2 algorithm.  The byte array is then </ins> encoded using URL-Safe Base64 with no padding RFC4648.  The resulting string is the hash value.  <ins> The "sha3-512" hash method consists of hashing the input string with the 512-bit SHA3 algorithm.  The byte array is then encoded using </ins> URL-Safe Base64 with no padding RFC4648.  The resulting string is the hash value. This is explicitly defined as the signature algorithm specified by the associated key material and the content digest is calculated  <ins> using sha-256. </ins> All key binding methods used by this specification MUST cover all relevant portions of the request, including anything that would parameters are defined: This example uses the ECDSA signing algorithm over the P384 curve and  <ins> the SHA-512 hashing algorithm for the content digest. </ins> When the proof method is specified in string form, the signing algorithm MUST be derived from the key material (such as using the JWS algorithm in a JWK formatted key), and the content digest  <ins> algorithm MUST be "sha-256". </ins> When using this method, the signer creates an HTTP Message Signature as described in I-D.ietf-httpbis-message-signatures.  The covered


header.  The verifier MUST validate the signature against the expected key of the signer.  7.3.1.1. When rotating a key using HTTP Message Signatures, the message, which

Built To edit notification comments on pull requests, go to your .
In 7.3.1 (use of gnap with HTTP message signatures), we do not mention the signature name (the string for which we always use ). This is a real issue because multiple signatures are possible on any message. Some options: Specify an explicit name, e.g. or better yet . Include a signature name in the object (but that would preclude the string version of this parameter).
I'm not seeing why this is an issue. Are there security or interoperability concerns? In the design of HTTP Signatures, the signature's label ( here) is meant to be effectively random and not controlled by the application. The label is not covered by the signature, partially for this reason. We actively don't want people to rely on the value of the signature label at the application level. The reason for this is that the label is only meant as syntax to the carrier and not something that should be relied upon. If any of the attached signatures for a message meet the requirements for the GNAP protocol (it's the right key, it covers the right components, it validates correctly), then it should be fine no matter what the label is. Furthermore, I wouldn't expect all libraries to let you set the label explicitly when you're adding a signature to a message. In other words, you should expect a developer to be able to say "take this message and sign it with this key" and be done with it. The label value would be generated internally, after the value of the body has been created, and that should be fine.
Sorry, this still doesn't make sense to me. As a receiver, if I get multiple signatures on the same message (which granted is weird but allowed, and with proxy chains may even be realistic), am I really expected to analyze each one of them and apply heuristics to decide which one I like? And yes, a confused verifier is obviously a security issue. IMO a library that doesn't let you set the sig name provides an incomplete interface.
Yes, I would expect a receiver to check all signatures and see that: it covers method, target-uri, content-digest, possibly authorization if there's a token it has a created time that's not too far in the past it has a tag parameter with the value "gnap" it has a nonce parameter that we haven't seen before in recent-ish memory (like maybe two or three times the allowable gap from the creation time) If there's one that passes all that, then the message is accepted and the other signatures are ignored. This is one of the things that the parameter helps narrow down, because you can immediately filter on that parameter for each signature when you go to process it, more easily ignoring the others. The others might have been added by any number of other applications or processes that aren't GNAP.
The sole purpose of the signature name is to bind the and header field entries together. They have no semantic value. They could just be randomly generated UUIDs and that would be fine. Support for multiple signatures isn't just an accident of the design; it's a very intentional feature. Verifiers must examine each signature on the message until they are satisfied that their requirements are met, and should generally ignore signatures they cannot verify. (e.g., because they do not understand the key ID, they do not accept the algorithm, the key material is expired, etc.) I expect that usually a verifier will find either zero or one signatures that satisfy all of its requirements. In some cases, a verifier may permit or even require multiple signatures, for example: A service behind a load balancer may expect a signature from the client that covers all of the application-level requirements, and a signature from the load balancer covering the header field. A service that sits behind a gateway that transforms requests might expect a signature from the client, and one from the transforming gateway. A service could vend out signatures as a way to limit a client's authorization to make an API request. For example, a vended signature might cover one request parameter, thereby fixing the value that the client can submit for that parameter while allowing the client to control over parameters. Such a service would expect the vended signature along with a client-issued signature covering the vended signature and the remaining request parameters.
Also, this is addressed in the security considerations for Signatures, and GNAP relying on the label having a specific value would be counter to that advice: URL
That seems pretty clear, maybe it could help if we'd extend that considerations with what NAME explained above ?
Before going into the more complicated use cases, please add some text that addresses basic interoperability. For example:
NAME please let us know if we can merge the PR and close this issue ?
NAME Yes, thank you all.

header.  The verifier MUST validate the signature against the expected key of the signer. <ins> A received message MAY include multiple signatures, each with its own label.  The verifier MUST examine all included signatures until it finds (at least) one that's acceptable according to its policy and meets the requirements in this section. </ins> 7.3.1.1. When rotating a key using HTTP Message Signatures, the message, which


attacks as discussed in security-ssrf. When receiving the request, the client instance MUST parse the JSON <del> object and validate the hash value as described in interaction-hash, or else return an "unknown_interaction" error (response-error).  If the hash validates, the client instance sends a continuation request to the AS as described in continue-after-interaction using the interaction reference value received here. </del>  4.2.3.

The current formulation regarding the client instance's validation of a pushed interaction completion notification can be misunderstood as "client instance must either parse JSON & verify hash or return an error", whereas I think the intended meaning is "client instance must parse JSON and verify hash. If either fails, return an error."
Built To edit notification comments on pull requests, go to your .

attacks as discussed in security-ssrf. When receiving the request, the client instance MUST parse the JSON  <ins> object and validate the hash value as described in interaction-hash. If either fails, the client instance MUST return an "unknown_interaction" error (response-error).  If the hash validates, the client instance sends a continuation request to the AS as described in continue-after-interaction using the interaction reference value received here. </ins> 4.2.3.


2.1.1. To request a single access token, the client instance sends an <del> "acccess_token" object composed of the following fields. </del>  The values of the "flags" field defined by this specification are as follows: 13.22. During the interaction process, the client instance usually hands <del> control of the user experience over to another component, beit the </del>  system browser, another application, or some action the resource owner is instructed to take on another device.  By using an interaction finish method, the client instance can be securely a number of protocol elements that it needs to manage, including nonces, references, keys, access tokens, and other elements.  During the interaction process, the client instance usually hands control of <del> the user experience over to another component, beit the system </del>  browser, another application, or some action the resource owner is instructed to take on another device.  In order for the client instance to make its continuation call, it will need to recall all of

type, - beit -> be it,
To edit notification comments on pull requests, go to your .
"beit" isn't a word, it should be "be it".
As I was reading through the latest version of the draft, I spotted a typo within section 2.1.1. It should says accesstoken object, not acccess_token object.

2.1.1. To request a single access token, the client instance sends an  <ins> "access_token" object composed of the following fields. </ins> The values of the "flags" field defined by this specification are as follows: 13.22. During the interaction process, the client instance usually hands  <ins> control of the user experience over to another component, be it the </ins> system browser, another application, or some action the resource owner is instructed to take on another device.  By using an interaction finish method, the client instance can be securely a number of protocol elements that it needs to manage, including nonces, references, keys, access tokens, and other elements.  During the interaction process, the client instance usually hands control of  <ins> the user experience over to another component, be it the system </ins> browser, another application, or some action the resource owner is instructed to take on another device.  In order for the client instance to make its continuation call, it will need to recall all of


each time a new TLS connection is established, both the client and the server (or the server only when using mtls) have to validate the other party's identity.  Such a verification can be achieved via <del> methods described in I-D.ietf-uta-6125bis), but these are not enough to establish the identity of the client instance in many cases. </del>  To counter this, GNAP defines a set of key binding methods in binding-keys that allow authentication and proof of possession by the

Built To edit notification comments on pull requests, go to your .
[I-D.ietf-uta-6125bis] " BROKEN REFERENCE ".

each time a new TLS connection is established, both the client and the server (or the server only when using mtls) have to validate the other party's identity.  Such a verification can be achieved via  <ins> methods described in I-D.ietf-uta-rfc6125bis, but these are not enough to establish the identity of the client instance in many cases. </ins> To counter this, GNAP defines a set of key binding methods in binding-keys that allow authentication and proof of possession by the


In this example flow, the client instance receives an access token to access a resource server through some valid GNAP process.  The client instance uses that token at the RS for some time, but eventually the <del> access token expires.  The client instance then gets a new access token by rotating the expired access token at the AS using the </del>  token's management URI. The client instance request. section for details. The AS validates the rotation request including the signature and <del> keys presented in (7) and returns a response-token-single.  The response includes a new access token and can also include updated token management information, which the client instance will store in place of the values returned in (2). </del>  1.6.7.

Built To edit notification comments on pull requests, go to your .
In section 6.1. of the document where it discusses Access Token Rotation, I'm slightly surprised by the lack of support for Refresh Tokens? From my interpretation of the specification, the only valid way to rotate an expired Access Token is to pass in this same expired Token (signing the request with the appropriate cryptographic key), and then the AS expected to validate this expired Access Token and conclude that it is valid? I also can't see any provision within the specification for the AS to (optionally) issue a Refresh Token along with the Access Token(s) that it sends to Client? There is something that feels quite wrong about expecting the AS to determine that an expired Access Token has successfully passed validation. On top of this, the lack of Refresh Token support could be confusing for someone who is familiar with using OAuth 2.0 - at the very least, I think Refresh Tokens should be mentioned in the document with a short explanation as to why they aren't supported (if this is indeed the case, and if this is a deliberate decision). I know the aim here is to have a fresh start and to not automatically replicate all of the concepts and details from OAuth, but I wasn't aware that Refresh Tokens was one of those concepts that needed removing. I'd welcome your thoughts on these points.
There are no refresh tokens in GNAP as they are no longer required due to the existence of a comprehensive grant API. The equivalent action to using a refresh token would be to use a continuation call for an existing grant to get a new access token (section 5), specifically something like that what's listed here (section 5.2): URL GNAP also separately allows for the rotation of an existing access token, which is the section you're referring to above. This would change the value and reset the expiration of an access token, not issue a new one from the existing grant.
Thanks for the response Justin. I'm not sure I completely follow your logic here. I'm specifically talking about the scenario described in section 1.6.6. In this section it describes the flow that needs to be followed when the Access Token to call the RS has expired. In the text for step 8 of the flow it says the following: Given that the value and the expiration date of the Access Token are being changed, this is a new Access Token that is being issued, as it says in the text quoted above. This contradicts your response above. So my general point here is that when the Token Management URI is called within the flow described in section 1.6.6, I'd expect to have the option to pass a Refresh Token (that is associated with the expired Access Token) into the Token Management URI (or at least, the option to pass in a different Access Token linked to the other Access Token that is specially used to access the Token Management URI), and use that separate (non-expired) Token as the means of getting my expired Access Token rotated. This would then mean that the Token Management URI wouldn't be required to have to treat an expired Access Token as "valid" - as doing this seems to be slightly clumsy (and bad practice). If an Access Token has expired then it shouldn't used to successfully access anything - even if that thing is a Token Management URI.
The quoted text should not say "a new access token", and that should be fixed, thanks for pointing out that inconsistency. We'd gone through and fixed a lot of that language, but we seem to have missed this one. It might help to think of it in terms of implementation. Let's say I have a grant, G1, that has two access tokens, A1 and A2. These tokens have values and expiration dates associated with them: When the client rotates access token A1, it changes the data structure like so: But if the client instead calls the grant continuation endpoint to create a new access token, the data structure changes like so: We'd briefly talked about having a separate access token to access the token management API, like we do with the continuation URI, but that seemed like it would be a much more significant overhead in terms of complexity and the amount of items the client needs to track to perform basic functions. The AS already needs to associate the presented access token with the token management URI and dereference it to a previously-granted set of access rights, which are represented by that access token. The thought was that we've already got an access token value, let's just re-use that in place. The AS can determine whether or not it wants to rotate an expired access token. This isn't any more complex for the client -- it takes the token value and drops it into the request in the right way. Also note that all calls to token rotation are signed by the client's key, so the AS has a strong association with the caller. The signature acts as the proof of the caller's right to call, the token value merely points at which data record above the action is performed on.
In your example above where you rotate token A1, I view the Access Token that is returned from that call as a "new" token. Access Tokens are immutable - therefore, if you need to change any item within the token data structure (whether that be the expiry date, or the value) then you're generating a new token (even if that new token has the same name or label, it is a new token). I think this is just about differing interpretations of what "new" means. It's not a big deal, but I do have a slight concern that by not referring to the new version of token A1 in your example above as "new" then readers of the specification may get the impression that Access Tokens are mutable, when clearly they aren't mutable. Regarding the discussion about whether the Token Management URI should have a separate Access Token that is used to access it - I completely understand the concern that it would add significant overhead and complexity. I agree that it would add a lot of extra complexity to the protocol to add this in, however, I don't think that argument alone satisfies my original concern here. If the expectation is the token rotation calls to the Token Management URI are being protected only by the client signing the request with their private key, then the expired Access Token shouldn't be being passed into the request within the Authorization header - perhaps it would be more appropriate to instead pass the Access Token within a separate parameter in the body of the POST request in this instance. Putting the Access Token in the Authorization gives the impression that this token is expected to be fully validated by the AS and that it is being used to evidence that the client is authorized to make that particular call.
I accidentally closed the issue - I didn't intend to do that. Can it be re-opened?
I wouldn't say it's necessarily clear or universal that access tokens are not mutable in the wild -- but it depends on what you're talking about when you say "access token". If you're talking about the value that goes over the wire, then yes, that's probably pretty accurate. If you're talking about what that token represents, then that's the kind of thing that can and does change in real systems today. I don't think we see it explicitly out there a lot because you usually see short-lived access tokens in use. Plus the use of self-contained structured tokens like JWTs conflates things a bit, because the value of the token contains everything that the token represents, including its own expiry.
I like this approach - I think a light touch is the right way to go about it.

In this example flow, the client instance receives an access token to access a resource server through some valid GNAP process.  The client instance uses that token at the RS for some time, but eventually the  <ins> access token expires.  The client instance then gets a refreshed access token by rotating the expired access token at the AS using the </ins> token's management URI. The client instance request. section for details. The AS validates the rotation request including the signature and  <ins> keys presented in (7) and refreshes the response-token-single. The response includes a new version of the access token and can also include updated token management information, which the client instance will store in place of the values returned in (2). </ins> 1.6.7.


Grant Negotiation and Authorization Protocol Resource Server Connections <del> draft-ietf-gnap-resource-servers-latest </del>  Abstract BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.  2. When the AS issues an access token for use at an RS, the RS needs to A GNAP AS offering RS-facing services can publish its features on a well-known discovery document using the URL ".well-known/gnap-as-rs". <del> This endpoint contains a JSON document consisting of a single JSON object with any combination of the following optional fields: </del>  The URL of the endpoint offering introspection.

Deploy preview for gnap-resource-servers-editors-draft ready! Built with commit 24fa4dc27f079697512f5eb15ca85b15f1c7ec62 https://deploy-preview-1--gnap-resource-servers-editors-URL

Grant Negotiation and Authorization Protocol Resource Server Connections  <ins> draft-ietf-gnap-resource-servers-00 </ins> Abstract BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here. <ins> This document contains non-normative examples of partial and complete HTTP messages, JSON structures, URLs, query components, keys, and other elements.  Some examples use a single trailing backslash '' to indicate line wrapping for long values, as per RFC8792.  The "" character and leading spaces on wrapped lines are not part of the value. </ins> 2. When the AS issues an access token for use at an RS, the RS needs to A GNAP AS offering RS-facing services can publish its features on a well-known discovery document using the URL ".well-known/gnap-as-rs".  <ins> This endpoint contains a JSON document RFC8259 consisting of a single JSON object with any combination of the following optional fields: </ins> The URL of the endpoint offering introspection.


However, it is often desirable to have the RS and AS communicate at runtime for a variety of purposes, including allowing the RS to validate and understand the rights and privileges associated with a <del> grant of access represented by an access token issued by (AS), or </del>  negotiating the capabilities of either party.  These types of connections are particularly useful for connecting an AS and RS from different vendors, allowing interoperable distributed deployments of the request with its own key (not the client instance's key or the token's key). <del> The AS validates the access token value and the client instance's </del>  request and returns the introspection response for the token. The RS fulfills the request from the client instance. at the secondary RS.  This internal secondary token is issued in the context of the incoming access token. <del> While it is possible to use a [token format]{#structure} that allows for the RS to generate its own secondary token, the AS can allow the RS to request this secondary access token using the same process used by the original client instance to request the primary access token. Since the RS is acting as its own client instance from the perspective of GNAP, this process uses the same grant endpoint, request structure, and response structure as a client instance's request. </del>  The client instance calls RS1 with an access token.

Deploy preview for gnap-resource-servers-editors-draft ready! Built with commit 122ea374f78cfa417b0d1d80101e64990c448665 https://deploy-preview-11--gnap-resource-servers-editors-URL

However, it is often desirable to have the RS and AS communicate at runtime for a variety of purposes, including allowing the RS to validate and understand the rights and privileges associated with a  <ins> grant of access represented by an access token issued by the AS, or </ins> negotiating the capabilities of either party.  These types of connections are particularly useful for connecting an AS and RS from different vendors, allowing interoperable distributed deployments of the request with its own key (not the client instance's key or the token's key).  <ins> The AS validates the access token value and the Resource Server's </ins> request and returns the introspection response for the token. The RS fulfills the request from the client instance. at the secondary RS.  This internal secondary token is issued in the context of the incoming access token.  <ins> While it is possible to use a structure that allows for the RS to generate its own secondary token, the AS can allow the RS to request this secondary access token using the same process used by the original client instance to request the primary access token.  Since the RS is acting as its own client instance from the perspective of GNAP, this process uses the same grant endpoint, request structure, and response structure as a client instance's request. </ins> The client instance calls RS1 with an access token.


communicate these aspects with each other, including structured access tokens and RS-facing APIs.  This specification also discusses methods for an RS to derive a downstream token for calling another <del> chained RS as well as a client-facing discovery mechanism that can be used to bootstrap the GNAP process when the client instance does not know which AS protects a given RS. </del>  The means of the authorization server issuing the access token to the client instance and the means of the client instance presenting the The AS responds with a handle appropriate to represent the resources list that the RS presented. <del> The RS MAY make this handle available as part of a rs-request- without-token or as documentation to developers. </del>  [[ See issue #117 [2] ]] 5. <del> If the client instance calls an RS without an access token, or with an invalid access token, the RS MAY respond to the client instance with an authentication header indicating that GNAP needs to be used to access the resource.  The address of the GNAP endpoint MUST be sent in the "as_uri" parameter.  The RS MAY additionally return a resource reference that the client instance MAY use in its access token request.  This resource reference handle SHOULD be sufficient for at least the action the client instance was attempting to take at the RS.  The RS MAY use the rs-register-resource-handle to register a new resource handle, or use a handle that has been pre-configured to represent what the RS is protecting.  The content of this handle is opaque to the RS and the client instance in both cases. The client instance then makes a call to the "as_uri" as described in I-D.ietf-gnap-core-protocol, with the value of "access" as one of the members of the "access" array in the "access_token" portion of the request.  The client instance MAY request additional resources and other information, and MAY request multiple access tokens. [[ See issue #118 [4] ]] 6. </del> [[ TBD: There are a lot of items in the document that are expandable through the use of value registries. ]] <del> 7. </del>  [[ TBD: There are a lot of security considerations to add. ]] handles act as shared secrets, though they can be combined with a requirement to provide proof of a key as well. <del> 8. </del>  [[ TBD: There are a lot of privacy considerations to add. ]] from an RS, this can be used to derive information about the resources being protected without releasing the resources themselves. <del> 9.  References </del>  <del> 9.1.  URIs </del>  [1] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115 [2] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/117 [3] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/116 <del> [4] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/118 </del>

See also related PR at ietf-wg-gnap/gnap-core-protocol
Deploy preview for gnap-resource-servers-editors-draft ready! Built with commit ec0063ea1a01f824c05137ecaaf8c7760dfee083 https://deploy-preview-26--gnap-resource-servers-editors-URL
Following the review I checked this PR too, seems fine

communicate these aspects with each other, including structured access tokens and RS-facing APIs.  This specification also discusses methods for an RS to derive a downstream token for calling another  <ins> chained RS. </ins> The means of the authorization server issuing the access token to the client instance and the means of the client instance presenting the The AS responds with a handle appropriate to represent the resources list that the RS presented.  <ins> The RS MAY make this handle available as part of a discovery response as described in I-D.ietf-gnap-core-protocol or as documentation to developers. </ins> [[ See issue #117 [2] ]] 5.  [[ TBD: There are a lot of items in the document that are expandable through the use of value registries. ]]  <ins> 6. </ins> [[ TBD: There are a lot of security considerations to add. ]] handles act as shared secrets, though they can be combined with a requirement to provide proof of a key as well.  <ins> 7. </ins> [[ TBD: There are a lot of privacy considerations to add. ]] from an RS, this can be used to derive information about the resources being protected without releasing the resources themselves.  <ins> 8.  References </ins>  <ins> 8.1.  URIs </ins> [1] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115 [2] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/117 [3] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/116


character and leading spaces on wrapped lines are not part of the value.  2. When the AS issues an access token for use at an RS, the RS needs to

closing
:heavycheckmark: Deploy Preview for gnap-resource-servers-editors-draft ready! Built :hammer: Explore the source changes: 35665c3208b87850c24d51a1083919c030a1978d :mag: Inspect the deploy log: :sunglasses: Browse the preview:
Added the list of terms
Include a reference to the Terminology section of the Core doc.
I think we should list out the terminology in question here as well as the general reference.

character and leading spaces on wrapped lines are not part of the value. <ins> Terminology specific to GNAP is defined in the terminology section of the core specification I-D.ietf-gnap-core-protocol, and provides definitions for the protocol roles: Authorization Server (AS), Client, Resource Server (RS), Resource Owner (RO), End-user; as well as the protocol elements: Attribute, Access Token, Grant, Privilege, Protected Resource, Right, Subject, Subject Information.  The same definitions are used in this document. </ins> 2. When the AS issues an access token for use at an RS, the RS needs to


have some means of understanding what the access token is for in order to determine how to respond to the request.  The core GNAP protocol makes no assumptions or demands on the format or contents of <del> the access token, but such token formats can be the topic of agreements between the AS and RS. </del>  Self-contained structured token formats allow for the conveyance of information between the AS and RS without requiring the RS to call <del> the AS at runtime as described in introspection. </del>  Some token formats, such as Macaroons and Biscuits, allow for the RS to derive sub-tokens without having to call the AS as described in token-chaining.  3. To facilitate runtime and dynamic connections, the AS can offer an be https, a host component, and optionally, port, path and query components and no fragment components. <del> A list of token formats supported by this AS. </del>  The URL of the endpoint offering resource registration.  The location MUST be a URL RFC3986 with a scheme component that MUST [[ TBD: There are a lot of items in the document that are expandable through the use of value registries. ]]  6. [[ TBD: There are a lot of security considerations to add. ]]

Adds registry and discussion for access token formats and where they could be used in the protocol, particularly as part of discovery from the AS. Addresses
:heavycheckmark: Deploy Preview for gnap-resource-servers-editors-draft ready! :hammer: Explore the source changes: 99546a7caad92bf2495cb9416f5e4604f9fcc7c0 :mag: Inspect the deploy log: :sunglasses: Browse the preview:
Section 3.1 mentions: A sub-section describing the structure of this list of token formats is currently missing.
In section 2. Access Token Formats, the text states: Token formats can be the topic of agreements between the AS and RS , if the AS has prior relationships with every RS. However, it should be mentioned that the access token format can also be negotiated. Add:
The negotiation is between the AS and RS, not the client. This spec is about negotiation between the AS and RS.

have some means of understanding what the access token is for in order to determine how to respond to the request.  The core GNAP protocol makes no assumptions or demands on the format or contents of  <ins> the access token, and in fact the token format and contents are opaque to the client instance.  However, such token formats can be the topic of agreements between the AS and RS. </ins> Self-contained structured token formats allow for the conveyance of information between the AS and RS without requiring the RS to call  <ins> the AS at runtime as described in introspection.  Structured tokens can also be used in combination with introspection, allowing the token itself to carry one class of information and the introspection response to carry another. </ins> Some token formats, such as Macaroons and Biscuits, allow for the RS to derive sub-tokens without having to call the AS as described in token-chaining. <ins> The supported token formats can be communicated dynamically at runtime between the AS and RS in several places. The AS can declare its supported token formats as part of RS- facing discovery The RS can require a specific token format be used to access a registered resource set The AS can return the token's format in an introspection response In all places where the token format is listed explicitly, it MUST be one of the registered values in the GNAP Token Formats Registry iana- token-format. </ins> 3. To facilitate runtime and dynamic connections, the AS can offer an be https, a host component, and optionally, port, path and query components and no fragment components.  <ins> A list of token formats supported by this AS.  The values in this list MUST be registered in the GNAP Token Format Registry. </ins> The URL of the endpoint offering resource registration.  The location MUST be a URL RFC3986 with a scheme component that MUST [[ TBD: There are a lot of items in the document that are expandable through the use of value registries. ]] <ins> 5.1. This specification establishes the GNAP Token Format Registry to define token formats. 5.1.1. 5.1.2. The table below contains the initial contents of the GNAP Token Format Registry. </ins> 6. [[ TBD: There are a lot of security considerations to add. ]]


3.2. <del> Unless otherwise specified, the RS protects its calls to the AS using any of the signature methods defined by GNAP.  This signing method MUST cover all of the appropriate portions of the HTTP request </del>  message, including any body elements, tokens, or headers required for functionality. <del> The AS MAY require an RS to pre-register its keys or could alternatively allow calls from arbitrary keys, in a trust-on-first- use model.  The RS MAY present its keys by reference or by value in the same fashion as a client instance calling the AS in the core protocol of GNAP I-D.ietf-gnap-core-protocol. </del>  3.3. Since the RS is acting as a client instance, the RS MUST identify itself with its own key in the "client" field and sign the request <del> just as any client instance would. [[ See issue #116 [2] ]] </del>  The AS responds with a token for the downstream RS2 as described in I-D.ietf-gnap-core-protocol.  The downstream RS2 could repeat this 8.1.  URIs [1] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115 <del> [2] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/116 </del>

Expands discussion of RS authentication, with examples. Re-uses structures from client instance auth used in core. Addresses
:heavycheckmark: Deploy Preview for gnap-resource-servers-editors-draft ready! :hammer: Explore the source changes: 71b0e6f2bdaa5a34903865e3130160be29eefc4b :mag: Inspect the deploy log: :sunglasses: Browse the preview:

3.2.  <ins> Unless otherwise specified, the RS MUST protect its calls to the AS using any of the signature methods defined by GNAP.  This signing method MUST cover all of the appropriate portions of the HTTP request </ins> message, including any body elements, tokens, or headers required for functionality.  <ins> The RS MAY present its keys by reference or by value in a similar fashion to a client instance calling the AS in the core protocol of GNAP, described in I-D.ietf-gnap-core-protocol.  In the protocols defined here, this takes the form of the resource server identifying itself using a "key" field or by passing an instance identifier directly. or by reference: The AS MAY require an RS to pre-register its keys or could allow calls from arbitrary keys in a trust-on-first-use model. </ins> 3.3. Since the RS is acting as a client instance, the RS MUST identify itself with its own key in the "client" field and sign the request  <ins> just as any client instance would, as described in authentication. </ins> The AS responds with a token for the downstream RS2 as described in I-D.ietf-gnap-core-protocol.  The downstream RS2 could repeat this 8.1.  URIs [1] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115


different vendors, allowing interoperable distributed deployments of GNAP-protected systems. <del> This specification defines several means for a RS and AS to </del>  communicate these aspects with each other, including structured access tokens and RS-facing APIs.  This specification also discusses methods for an RS to derive a downstream token for calling another When the AS issues an access token for use at an RS, the RS needs to have some means of understanding what the access token is for in order to determine how to respond to the request.  The core GNAP <del> protocol makes no assumptions or demands on the format or contents of the access token, and in fact the token format and contents are opaque to the client instance.  However, such token formats can be the topic of agreements between the AS and RS. </del>  Self-contained structured token formats allow for the conveyance of information between the AS and RS without requiring the RS to call

:heavycheckmark: Deploy Preview for gnap-resource-servers-editors-draft ready! Built :hammer: Explore the source changes: ee6b3fc9832467191449ff86c6651ebf548d33ea :mag: Inspect the deploy log: :sunglasses: Browse the preview:
A couple of other minor things it sounds to me like an optional step for the RS to validate the signature if the key object is presented in the introspection response. That should be MUST, right? The third step in section "Token Introspection" states that I think that the AS should validate the RS's request and only after that the AT's value.
The RS always has to validate the signature, but sometimes it can't fully validate it until after it looks up the token's data using introspection. We should look at what OAuth MTLS and DPoP say in terms of RS validation steps. The intent of the language for the AS validation was not to imply an order in either direction, so we can look to tweak this to make that more clear.

different vendors, allowing interoperable distributed deployments of GNAP-protected systems.  <ins> This specification defines several means for an RS and AS to </ins> communicate these aspects with each other, including structured access tokens and RS-facing APIs.  This specification also discusses methods for an RS to derive a downstream token for calling another When the AS issues an access token for use at an RS, the RS needs to have some means of understanding what the access token is for in order to determine how to respond to the request.  The core GNAP  <ins> protocol makes neither assumptions nor demands on the format or contents of the access token, and in fact, the token format and contents are opaque to the client instance.  However, such token formats can be the topic of agreements between the AS and RS. </ins> Self-contained structured token formats allow for the conveyance of information between the AS and RS without requiring the RS to call


The discovery response is a JSON document RFC8259 consisting of a single JSON object with the following fields: <del> OPTIONAL.  The URL of the endpoint offering introspection.  The location MUST be a URL RFC3986 with a scheme component that MUST be https, a host component, and optionally, port, path and query components and no fragment components. A list of token formats supported by this AS.  The values in this list MUST be registered in the GNAP Token Format Registry. The URL of the endpoint offering resource registration.  The location MUST be a URL RFC3986 with a scheme component that MUST be https, a host component, and optionally, port, path and query components and no fragment components. REQUIRED.  The location of the AS's grant request endpoint, used by the RS to derive downstream access tokens.  The location MUST be a URL RFC3986 with a scheme component that MUST be https, a host component, and optionally, port, path and query components and no fragment components.  This URL MUST be the same URL used by client instances in support of GNAP requests. OPTIONAL.  A list of the AS's supported key proofing mechanisms. The values of this list correspond to possible values of the "proof" field of the key section of the request. </del> 3.2. Unless otherwise specified, the RS MUST protect its calls to the AS The RS signs the request with its own key and sends the access token as the body of the request. <del> REQUIRED.  The access token value presented to the RS by the client instance. RECOMMENDED.  The proofing method used by the client instance to bind the token to the RS request. REQUIRED.  The identification used to authenticate the resource server making this call, either by value or by reference as described in authentication. OPTIONAL.  The minimum access rights required to fulfill the request.  This MUST be in the format described in the Resource Access Rights section of I-D.ietf-gnap-core-protocol. </del> The AS MUST validate the access token value and determine if the token is active.  An active access token is defined as a token that presentation, such as its intended proofing mechanism and key material. <del> REQUIRED.  If "true", the access token presented is active, as defined above.  If any of the criteria for an active token are not true, or if the AS is unable to make a determination (such as the token is not found), the value is set to "false" and other fields are omitted. </del> If the access token is active, additional fields from the single access token response structure defined in I-D.ietf-gnap-core- protocol are included.  In particular, these include the following: <del> REQUIRED.  The access rights associated with this access token. This MUST be in the format described in the Resource Access Rights section of I-D.ietf-gnap-core-protocol.  This array MAY be filtered or otherwise limited for consumption by the identified RS, including being an empty array. REQUIRED if the token is bound.  The key bound to the access token, to allow the RS to validate the signature of the request from the client instance.  If the access token is a bearer token, this MUST NOT be included. OPTIONAL.  The set of flags associated with the access token. </del> The response MAY include any additional fields defined in an access token response and MUST NOT include the access token "value" itself. the AS's resource registration endpoint along with information about what the RS will need to validate the request. <del> REQUIRED.  The list of access rights associated with the request in the format described in the "Resource Access Rights" section of I-D.ietf-gnap-core-protocol. REQUIRED.  The identification used to authenticate the resource server making this call, either by value or by reference as described in authentication. OPTIONAL.  The token format required to access the identified resource.  If the field is omitted, the token format is at the discretion of the AS.  If the AS does not support the requested token format, the AS MUST return an error to the RS. OPTIONAL.  If present and set to "true", the RS expects to make a token introspection request as described in introspection.  If absent or set to "false", the RS does not anticipate needing to make an introspection request for tokens relating to this resource set. </del> The RS MUST identify itself with its own key and sign the request. The AS responds with a reference appropriate to represent the resources list that the RS presented in its request as well as any additional information the RS might need in future requests. <del> REQUIRED.  A single string representing the list of resources registered in the request.  The RS MAY make this handle available to a client instance as part of a discovery response as described in I-D.ietf-gnap-core-protocol or as documentation to client software developers. OPTIONAL.  An instance identifier that the RS can use to refer to itself in future calls to the AS, in lieu of sending its key by value. OPTIONAL.  The introspection endpoint of this AS, used to allow the RS to perform token introspection. </del> 4. Some architectures require an RS to act as a client instance and use 5.  [[ TBD: There are a lot of items in the document that are expandable through the use of value registries. ]] <del> 5.1. </del>  This specification establishes the GNAP Token Format Registry to define token formats. <del> 5.1.1. </del>  <del> 5.1.2. </del>  The table below contains the initial contents of the GNAP Token Format Registry. <del> 6. </del>  [[ TBD: There are a lot of security considerations to add. ]] handles act as shared secrets, though they can be combined with a requirement to provide proof of a key as well. <del> 7. </del>  [[ TBD: There are a lot of privacy considerations to add. ]] from an RS, this can be used to derive information about the resources being protected without releasing the resources themselves. <del> 8.  References </del>  <del> 8.1.  URIs </del>  [1] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115

Deploy Preview for gnap-resource-servers-editors-draft ready! Explore the source changes: 94d11a4362aaea79f357583969d87ec4955655a9 Inspect the deploy log: Browse the preview:

The discovery response is a JSON document RFC8259 consisting of a single JSON object with the following fields:  3.2. Unless otherwise specified, the RS MUST protect its calls to the AS The RS signs the request with its own key and sends the access token as the body of the request.  The AS MUST validate the access token value and determine if the token is active.  An active access token is defined as a token that presentation, such as its intended proofing mechanism and key material.  If the access token is active, additional fields from the single access token response structure defined in I-D.ietf-gnap-core- protocol are included.  In particular, these include the following:  The response MAY include any additional fields defined in an access token response and MUST NOT include the access token "value" itself. the AS's resource registration endpoint along with information about what the RS will need to validate the request.  The RS MUST identify itself with its own key and sign the request. The AS responds with a reference appropriate to represent the resources list that the RS presented in its request as well as any additional information the RS might need in future requests.  4. Some architectures require an RS to act as a client instance and use 5. <ins> (TODO: the ACK section should probably be split between the documents) 6. </ins> [[ TBD: There are a lot of items in the document that are expandable through the use of value registries. ]]  <ins> 6.1. </ins> This specification establishes the GNAP Token Format Registry to define token formats.  <ins> 6.1.1. </ins>  <ins> 6.1.2. </ins> The table below contains the initial contents of the GNAP Token Format Registry.  <ins> 7. </ins> [[ TBD: There are a lot of security considerations to add. ]] handles act as shared secrets, though they can be combined with a requirement to provide proof of a key as well.  <ins> 8. </ins> [[ TBD: There are a lot of privacy considerations to add. ]] from an RS, this can be used to derive information about the resources being protected without releasing the resources themselves.  <ins> 9.  References </ins>  <ins> 9.1.  URIs </ins> [1] https://github.com/ietf-wg-gnap/gnap-core-protocol/issues/115


well as CoAP groups, by using the RD-Groups usage pattern of the CoRE Resource Directory (RD), as defined in Appendix A of I-D.ietf-core- resource-directory.  In particular, an application group can be <del> registered to the RD, specifying the reference IP multicast address, hence its associated CoAP group.  The registration is typically performed by a Commissioning Tool.  Later on, CoAP endpoints can discover the registered application groups and related CoAP group, by using the lookup interface of the RD. CoAP endpoints can also discover application groups by performing a group discovery query using the /.well-known/core resource.  Such a request may be sent to a known CoAP group multicast address associated to application group(s), or to the All CoAP Nodes multicast address. </del>  When secure communication is provided with Group OSCORE (see chap- oscore), the approach described in I-D.tiloca-core-oscore-discovery <del> and also based on the RD can be used, in order to discover the security group to join. </del>  In particular, the responsible OSCORE Group Manager registers its own security groups to the RD, as links to its own corresponding

Pr clarify appl group discovery for
Oops, this PR accidentally contains also the changes of the other PR for . (This should be ignored by readers...)
Current draft says: I don't quite understand how that'd happen; I see two possible interpretations: Use .wk/c to discover content of application groups, eg. by requesting URL, picking really only one response, and hoping that it's just the content of the group resources and not everything on the host (cf. -- URL was requested, but what comes back is coap://[fe80::f00]/.well-known/core actually). Send out a broad multicast and wait for links that describe groups. However, other than the RD Appendix A methods (which aren't really applicable here), I don't know of any description format to be used. Is "The description of the group may be provided in an application specific or a yet to be defined generic format." meant here?
Above PR expands the text with discovery use cases and examples. We may still expand this later on with discovery examples or the link format attribute(s) defined by draft-tiloca-core-oscore-discovery; but that is not done yet. (I would need some more time still to read that draft first)
Reading the paragraph after "An application group can be named in many ways", I was left a bit confused: Why should it be encoded in the Uri-Query? That'd need coordination among all applications running on that host (for it is interfering with the query argument space that's usually left for the application to use). The common partitioning of applications inside a host is left-to-right in the URI, and that puts it in the very last spot. I think I do see what is meant by the discouragement of using the Uri-Host, but doubt that it'd be immediately obvious to general readers. How I understand Uri-Host to be impractical here is that while the request is sent to a well-defined and named URI, the response is a representation of the same URI with the individual server's IP replaced into the authority component, and if two application groups on the same CoAP group use the same path, then there may be clashes, not on the request-response layer (where the responses are bound to request for a particular host name) but in the client's cache of the responses. (And once one is at the point where application groups in the same CoAP group have a disjunct path set, one can do away with identification altogether and just address the unique path). I don't quite follow how this is not "as intended in RFC7252": It is an identifier for who is being addressed, and as such just part of the URI. (For example, if I define my lights group to be named URL and name the resource , then the host name is exactly the group name, and already needs to be put into the request unless there is known URI aliasing). See also URL on "send a Uri-Host" option, with the caveat that I'm a strong proponent of answer A2. Furthermore, the text seems to imply that virtual hosting is something a server would need to go out of its way to implement. It isn't: The Uri-Host option is critical, and a host needs to make the conscious decision to ignore that option; otherwise it's just as much part of finding the addressed resource as all the other Uri-* options are. The best practice is something I can get behind, although I suggest using no identifier on the wire (and just the disjunct set of resources) as a byte saving alternative when the administrative effort of ensuring path uniqueness can be afforded.
Thanks; we do need to improve the current text on these aspects. On Uri-Host and your example "URL" where authority component includes the application group: in this group communication example the sending client would normally DNS-resolve "URL" to a particular multicast IP address, then send the CoAP request to this multicast IP address destination, without including any Uri-Host Option. This works as long as you have a unique 1:1 association between application-group and CoAP-group. In case multiple application-groups map to a single CoAP-group, this doesn't work anymore : a client could be e.g. configured to always include the "Uri-Host" Option to indicate the hostname. Still not the preferred approach I would think. Btw I can't follow answer A2 on the CoAP-Faq, unfortunately: formulation is too complex. In some (common?) constrained use cases, the DNS name would not even be configured in the client and the client would just be configured directly with the IPv6 multicast address of the CoAP group to send it to. Then, the application-group would need to be encoded in some way still, e.g. using the Uri-Path Option. Now what our original text tried to suggest is to "misuse" a Uri-Host Option for that. So instead of using an option like: Uri-Path = group123 You would instead use an option: Uri-Host = group123 So this is not a "real" URI hostname but rather a low-level hack to let the client's CoAP stack insert by force an additional option just before sending out the CoAP request. The receiver's CoAP stack would just parse it as the ID of the application-group and not really as a URI-host. Because this gets confusing and potentially messy (proven by the present discussion !) we don't recommend it. So, trying to reiterate if one has configured Group URIs of the form coap://[mcast-ip-address]/resource on the client then by default the Uri-Host Option would get elided. The above mentioned "hack" is to put it back to encode application-group. This has the issue that the application-group name isn't present in the Group URI. if one has configured Group URIs of the form URL on the client then normally by default the authority gets resolved to some IP multicast address before sending it out, and thus while sending it the Uri-Host Option is NOT included in the CoAP encoding but elided. So the receiving server doesn't see the application-group ID because it's not encoded in the request data. (We assume here that multiple application-groups use the same CoAP-group.) Maybe we should discuss this further; what's the effort here / who ensures it / unique between what and what?
Initial text proposed in above PR! We'll merge it in by tomorrow evening, as an improvement (hopefully). What is not included yet is a statement saying that we don't recommend using the non-Group-URI methods of encoding application group name. To do so we would need to clearly state why that is not recommended; still not clear at this moment what the disadvantages of these are.

well as CoAP groups, by using the RD-Groups usage pattern of the CoRE Resource Directory (RD), as defined in Appendix A of I-D.ietf-core- resource-directory.  In particular, an application group can be  <ins> registered to the RD, specifying the reference IP multicast address of its associated CoAP group.  The registration of groups is typically performed by a Commissioning Tool.  Later on, CoAP endpoints can discover the registered application groups and related CoAP group(s), by using the lookup interface of the RD. CoAP endpoints can also discover application groups and/or CoAP groups using a GET request on the /.well-known/core resource.  Such a request may be sent to a known CoAP group multicast address that is associated to one or more application group(s), or to the All CoAP Nodes multicast address; and the request may be sent with or without a query component.  These particular details of the request are selected depending on the intented discovery action of the client and on the particular encoding of group names in names and/or attributes of resources which is application-specific.  The following types of request may typically be used: Discovery of all application groups that are part of a CoAP group. For example, in case the application group name is encoded in the URI path as "/grp/<groupname>" then the discovery query may use URI "/.well-known/core?href=/grp/*" and it is sent to the IP multicast address of the CoAP group.  The query matches any application group name.  The result of this query is a list of resources at CoAP servers that are a member of at least one application group associated to the CoAP group.  Each resource represents an application group membership at one CoAP server. Discovery of a particular application group with a known name. For example, in case the known application group name is "mygroup1" and is encoded in the URI path as "/grp/<groupname>" then the discovery query may use URI "/.well-known/core?href=/grp/ mygroup1" and it is sent to the IPv6 All CoAP Nodes multicast address of a particular chosen scope (e.g. site-local, or realm- local).  The result of this query is a list of resources at CoAP servers that are a member of "mygroup1".  Each resource represents the membership of the responding server to the application group "mygroup1". Discovery of all application groups of a particular type.  For example, in case the application group type is "mytype1" and is encoded as a resource type (rt) attribute of the application group resource, and the application group resource is "/grp/<groupname>" then the discovery query may use URI "/.well-known/ core?rt=mytype1" and it is sent to the All CoAP Nodes multicast address.  The query result is a list of resources at CoAP servers that have at least one application group of type "mytype1"; each server response identifies the membership to one or more application group(s) of type "mytype1" for that server.  Each resource in the list represents one membership of a server to one application group of type "mytype1". Discovery of all application groups that are configured on the client's 6LoWPAN wireless mesh network.  In the following example a request without query is used.  So, the URI "/.well-known/core" is used and the request is sent to the IPv6 All CoAP Nodes multicast address of realm-local scope.  Each CoAP server (including any application group members) will return a list of its resources, which in this example includes the resources used to encode the application group name.  If each application group resource is known to be "/g/<groupname>" then the client marks each returned resource under the root resource "/g" as a discovered application group.  Not using a query has the disadvantage that potentially a lot of response traffic will be generated on the mesh network, including responses from servers that are not a member of any application group.  But it may be needed in particular use cases, e.g. if some of the CoAP servers do not support the optional link format query functionality (as mentioned in Section 4.1 of RFC6690). Note that all the above examples are application-specific; there is currently no standard way of encoding application group names or CoAP group names in CoAP resources and/or CoRE link attributes at the CoAP server.  (The aforementioned registration and discovery of groups in the RD is only defined for use with an RD, not for discovery on CoAP servers without using an RD.) </ins> When secure communication is provided with Group OSCORE (see chap- oscore), the approach described in I-D.tiloca-core-oscore-discovery  <ins> also based on the RD can be used, in order to discover the security group to join. </ins> In particular, the responsible OSCORE Group Manager registers its own security groups to the RD, as links to its own corresponding


<del> An HTTPS-based Transport for Configured Subscriptions </del>  draft-ietf-netconf-https-notif-latest Abstract

Updates based on reviewing comments from Martin and Jan.
I was expecting more changes. What about the Title?
good enough but, FYI, there's no need to set the "abbrev" attribute if it's the same value as the title...
Looks like the "abbrev" text is too long. How about "HTTPS YANG Notifications"?
Or maybe "HTTPS Notif Transport" ??? Either way is fine by me.

<ins> An HTTPS-based Transport for YANG Notifications </ins> draft-ietf-netconf-https-notif-latest Abstract


<del> An HTTPS-based Transport for Configured Subscriptions </del>  draft-ietf-netconf-https-notif-latest Abstract <del> This document defines both a protocol for sending notifications over HTTPS as well as extensions to the data model for configured subscriptions defined in RFC 8639.  It also presents an example module for configuration without using the data model defined in RFC 8639. </del>  This document requires that the publisher is a "server" (e.g., a NETCONF or RESTCONF server), but does not assume that the receiver is RFC8639, the notification method defined in this document MAY be used outside of RFC8639 by using some of the definitions from this module along with the grouping defined in I-D.ietf-netconf-http-client- <del> server.  For an example on how that can be done, see Section 8.2. </del>  1.2. 2. The protocol consists of two HTTP-based target resources presented by <del> the receiver: A target resource enabling the publisher to discover what optional capabilities a receiver supports.  Publishers SHOULD query this target when before sending any notifications or if ever an error occurs. A target resource enabling to publish to send one or more notification to a receiver.  This document defines support for sending only one notification per message; a future effort MAY extend the protocol to send multiple notifications per message. </del>  The protocol is illustrated in the diagram below: The POST messages MAY be "pipelined" (not illustrated in the diagram above), whereby multiple notifications are sent without waiting for <del> the HTTP response for a previous request. </del>  3. supported encoding is necessary only when the "/subscriptions/subscription/encoding" leaf is not configured, per the "encoding" leaf's description statement in the "ietf-subscribed- <del> notification" module.  FIXME: do they need to discover *any* capabilities? </del>  3.2. To learn the capabilities of a receiver, a publisher can issue an <del> HTTPS GET request to the "capabilities" resource under a known path on the receiver with "Accept" header set using the "application/xml" and/or "application/json" media-types, with latter as the mandatory </del>  to implement, and the default in case the type is not specified. 3.3. Even though a YANG module is not defined for this interaction, the response body MUST conform to the following YANG-modeled format:  3.4. The publisher can send the following request to learn the receiver capabilities.  In this example, the "Accept" states that the receiver <del> wants to receive notifications in XML but, if not supported, to use JSON encoding. </del>  If the receiver is able to reply using "application/xml", and assuming it is able to receive JSON and XML encoded notifications, <del> the response might look like this: </del>  If the receiver is unable to reply using "application/xml", the response might look like this: 4.1. <del> The publisher sends an HTTPS POST request to the "relay- notifications" resource under a known path on the receiver with the "Content-Type" header set to either "application/json" or "application/xml" and a request body containing the notification encoded using the specified format. </del>  XML-encoded notifications are encoded using the format defined by RFC5277 for XML. Instead of saying that, for JSON-encoding purposes, the module name for the "notification" element is "ietf-restconf, the module <del> name will instead by "ietf-https-notif". </del>  4.2. 8.3. <del> Following the guidelines defined in RFC5226, this document defines a </del>  new registry called "Capabilities for HTTPS Notification Receivers". This registry defines capabilities that can be supported by HTTPS- based notification receivers.

Getting the draft ready for publication. Did file a bug with libyang folks and even though it was an operator error on my part, the default in yanglint now is to enable all features when none are mentioned. The examples now validate correctly.

<ins> An HTTPS-based Transport for YANG Notifications </ins> draft-ietf-netconf-https-notif-latest Abstract  <ins> This document defines a protocol for sending notifications over HTTPS.  YANG modules for configuring publishers are also defined. Examples are provided illustrating how to configure various publishers. </ins> This document requires that the publisher is a "server" (e.g., a NETCONF or RESTCONF server), but does not assume that the receiver is RFC8639, the notification method defined in this document MAY be used outside of RFC8639 by using some of the definitions from this module along with the grouping defined in I-D.ietf-netconf-http-client-  <ins> server.  For an example on how that can be done, see Section A.2. </ins> 1.2. 2. The protocol consists of two HTTP-based target resources presented by  <ins> the receiver.  These two resources share a common prefix that the publisher must know.  If the data model in section 6.2 is used, this common prefix is defined by the "path" leaf in the "http-client- parameters" container. "capabilities": A target resource enabling the publisher to discover what optional capabilities a receiver supports. Publishers SHOULD query this target before sending any notifications or if ever an error occurs. "relay-notifications": A target resource enabling the publisher to send one or more notification to a receiver.  This document defines support for sending only one notification per message; a future effort MAY extend the protocol to send multiple notifications per message. </ins> The protocol is illustrated in the diagram below: The POST messages MAY be "pipelined" (not illustrated in the diagram above), whereby multiple notifications are sent without waiting for  <ins> the HTTP response for a previous POST. </ins> 3. supported encoding is necessary only when the "/subscriptions/subscription/encoding" leaf is not configured, per the "encoding" leaf's description statement in the "ietf-subscribed-  <ins> notification" module. </ins> 3.2. To learn the capabilities of a receiver, a publisher can issue an  <ins> HTTPS GET request to the "capabilities" resource (see overview) on the receiver with "Accept" header set using the "application/xml" and/or "application/json" media-types, with the latter as mandatory </ins> to implement, and the default in case the type is not specified. 3.3. Even though a YANG module is not defined for this interaction, the response body MUST conform to the following YANG-modeled format: <ins> As it is possible that the receiver may return custom capability URIs, the publisher MUST ignore any capabilities that it does not recognize. </ins> 3.4. The publisher can send the following request to learn the receiver capabilities.  In this example, the "Accept" states that the receiver  <ins> wants to receive the capabilities response in XML but, if not supported, then in JSON. </ins> If the receiver is able to reply using "application/xml", and assuming it is able to receive JSON and XML encoded notifications,  <ins> and it is able to process the RFC 8639 state machine, the response might look like this: </ins> If the receiver is unable to reply using "application/xml", the response might look like this: 4.1.  <ins> The publisher sends an HTTPS POST request to the "relay-notification" resource (see overview) on the receiver with the "Content-Type" header set to either "application/json" or "application/xml" and a body containing the notification encoded using the specified format. </ins> XML-encoded notifications are encoded using the format defined by RFC5277 for XML. Instead of saying that, for JSON-encoding purposes, the module name for the "notification" element is "ietf-restconf, the module  <ins> name will instead be "ietf-https-notif". </ins> 4.2. 8.3.  <ins> Following the guidelines defined in RFC8126, this document defines a </ins> new registry called "Capabilities for HTTPS Notification Receivers". This registry defines capabilities that can be supported by HTTPS- based notification receivers.


2.1. <del> The "Idempotency-Key" request header field describes </del>  Clients MUST NOT include more than one "Idempotency-Key" header field in the same request.

NAME pls review
While not a mandatory requirement for new fields, using SF has a number of benefits: Well-defined parsing and serialisation algorithms Corresponding reduction of interop and security issues Existing implementation support Possibility of more efficient serialisation support (i.e., binary HTTP headers) URL
Closing this, PR is merged after NAME comment is addressed.

2.1.  <ins> "Idempotency-Key" is an Item Structured Header RFC8941.  Its value MUST be a String.  Refer to Section 3.3.3 of RFC8941 for ABNF of "sf- string": </ins> Clients MUST NOT include more than one "Idempotency-Key" header field in the same request.