Draft: draft-ietf-gnap-core-protocol

Commentary: Addresses 
 To edit notification comments on pull requests , go to your .
Paragraph (version A):
While it is possible to deploy an AS in a stateless environment, such
deployments will need a way to manage the current state of the grant
request in a secure and deterministic fashion.
Paragraph (version B):
While it is possible to deploy an AS in a stateless environment, GNAP
is a stateful protocol and such deployments will need a way to manage
the current state of the grant request in a secure and deterministic
fashion without relying on other components, such as the client
software, to keep track of the current state.
Paragraph (version A):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the client instance to response-continue
at a future time through additional polling.  This response can
include refreshed credentials as well as information regarding how
long the client instance should wait before calling again.  The
client instance replaces its stored continuation information from
the previous response (2).  Note that the AS may need to determine
that the RO has not approved the request in a sufficient amount of
time and return an appropriate error to the client instance.
Paragraph (version B):
If the access request has not yet been authorized by the RO in
(6), the AS responds to the client instance to response-continue
at a future time through additional polling.  Note that this
response is not an error message, since no error has yet occurred.
This response can include refreshed credentials as well as
information regarding how long the client instance should wait
before calling again.  The client instance replaces its stored
continuation information from the previous response (2).  Note
that the AS may need to determine that the RO has not approved the
request in a sufficient amount of time and return an appropriate
error to the client instance.
Paragraph (version A):
If access is approved, the resulting access token is valid for the
described resource and, since no flag is provided in this example, is
bound to the client instance's key (or its most recent rotation).
The token is labeled "token1-23".  The token response structure is
described in response-token-single.
Paragraph (version B):
If access is approved, the resulting access token is valid for the
described resource.  Since the "bearer" flag is not provided in this
example, the token is bound to the client instance's key (or its most
recent rotation).  The token is labeled "token1-23".  The token
response structure is described in response-token-single.
Paragraph (version A):
Subject identifiers are hints to the AS in determining the RO and
MUST NOT be taken as authoritative statements that a particular RO is
present at the client instance and acting as the end user.
Assertions SHOULD be validated by the AS.
Paragraph (version B):
Subject identifiers are hints to the AS in determining the RO and
MUST NOT be taken as authoritative statements that a particular RO is
present at the client instance and acting as the end user.
Paragraph (version B):
Assertions presented by the client instance SHOULD be validated by
the AS.  While the details of such validation are outside the scope
of this specification, common validation steps include verifying the
signature of the assertion against a trusted signing key, verifying
the audience and issuer of the assertion map to expected values, and
verifying the time window for the assertion itself.  However, note
that in many use cases, some of these common steps are relaxed.  For
example, an AS acting as an IdP could expect that assertions being
presented using this mechanism were issued by the AS to the client
software.  The AS would verify that the AS is the issuer of the
assertion, not the audience, and that the client instance is instead
the audience of the assertion.  Similarly, an AS might accept a
recently-expired assertion in order to help bootstrap a new session
with a specific end user.
Paragraph (version A):
One means of dynamically obtaining such a user reference is from the
AS returning an "opaque" subject identifier as described in response-
subject.  Other means of configuring a client instance with a user
identifier are out of scope of this specification.
Paragraph (version A):
User reference identifiers are not intended to be human-readable user
identifiers or structured assertions.  For the client instance to
send either of these, use the full request-user instead.
Paragraph (version B):
One means of dynamically obtaining such a user reference is from the
AS returning an "opaque" subject identifier as described in response-
subject.  Other means of configuring a client instance with a user
identifier are out of scope of this specification.  The lifetime and
validity of these user references is determined by the AS and this
lifetime is not exposed to the client instance in GNAP.  As such, a
client instance using such a user reference is likely to keep using
that reference until such a time as it stops working.
Paragraph (version B):
User reference identifiers are not intended to be human-readable user
identifiers or structured assertions.  For the client instance to
send either of these, the client can use the full request-user
instead.
Paragraph (version A):
Interaction start modes are specified by a string, which consists of
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.
Paragraph (version A):
Individual modes defined as objects MAY define additional parameters
to be required in the object.
Paragraph (version B):
Interaction start modes defined as objects MAY define additional
parameters to be required in the object.
Paragraph (version B):
The "start" array can contain both string-type and object-type modes.
Paragraph (version A):
The AS MAY refuse to issue one or more of the requested access
tokens, for any reason.  In such cases the refused token is omitted
from the response and all of the other issued access tokens are
included in the response the requested names appropriate names.  If
the client instance request-token-multiple, the AS MUST NOT respond
with a single access token structure, even if only a single access
token is granted.  In such cases, the AS MUST respond with a multiple
access token structure containing one access token.
Paragraph (version B):
The AS MAY refuse to issue one or more of the requested access
tokens, for any reason.  In such cases the refused token is omitted
from the response and all of the other issued access tokens are
included in the response under their respective requested labels.  If
the client instance request-token-multiple, the AS MUST NOT respond
with a single access token structure, even if only a single access
token is granted.  In such cases, the AS MUST respond with a multiple
access token structure containing one access token.
Paragraph (version A):
After starting interaction, the client instance can then make a
continue-request either in response to a signal indicating the
interaction-finish, through polling, or through some other method
defined by an extension of this specification.
Paragraph (version B):
After starting interaction, the client instance can then make a
continue-request either in response to a signal indicating the
interaction-finish, after a time-based polling, or through some other
method defined by an extension of this specification through the
IANA-interaction-response.
Paragraph (version A):
This mode is designed to be used when the client instance is not able
to communicate or facilitate launching an arbitrary URI.  The
associated URI could be statically configured with the client
instance or in the client software's documentation.  As a
consequence, these URIs SHOULD be short.  The user code URI MUST be
reachable from the end user's browser, though the URI is usually be
opened on a separate device from the client instance itself.  The URI
MUST be accessible from an HTTP GET request and MUST be protected by
HTTPS or equivalent means.
Paragraph (version B):
This mode is designed to be used when the client instance is not able
to communicate or facilitate launching an arbitrary URI.  The
associated URI could be statically configured with the client
instance or in the client software's documentation.  As a
consequence, these URIs SHOULD be short.  The user code URI MUST be
reachable from the end user's browser, though the URI is usually
opened on a separate device from the client instance itself.  The URI
MUST be accessible from an HTTP GET request and MUST be protected by
HTTPS or equivalent means.
Paragraph (version A):
When processing such a call, the AS MUST protect itself against SSRF
attacks as discussed in security-ssrf.
Paragraph (version B):
Since the AS is making an outbound connection to a URI supplied by an
outside party (the client instance), the AS MUST protect itself
against SSRF attacks when making this call as discussed in security-
ssrf.
Paragraph (version A):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter under the "finish" key of the
request-interact-finish.  The resulting byte array from the hash
function is then encoded using URL-Safe Base64 with no padding
RFC4648.  The resulting string is the hash value.
Paragraph (version B):
The party then hashes the bytes of the ASCII encoding of this string
with the appropriate algorithm based on the "hash_method" parameter
under the "finish" key of the request-interact-finish.  The resulting
byte array from the hash function is then encoded using URL-Safe
Base64 with no padding RFC4648.  The resulting string is the hash
value.
Paragraph (version A):
The continuation access token is bound to the same key and method the
client instance used to make the initial request.  As a consequence,
when the client instance makes any calls to the continuation URI, the
client instance MUST present the continuation access token as
described in use-access-token and present proof of the client
instance's key (or its most recent rotation) by signing the request
as described in binding-keys.  The AS MUST validate all keys
presented by the client instance or referenced in an ongoing request
for each call within that request.
Paragraph (version A):
Access tokens other than the continuation access tokens MUST NOT be
usable for continuation requests.
Paragraph (version A):
The AS MUST be able to tell from the client instance's request which
specific ongoing request is being accessed, using a combination of
the continuation URI, the provided continuation access token, and the
client instance identified by the key signature.  If the AS cannot
determine a single active grant request to map the continuation
request to, the AS MUST return an "invalid_continuation" error
(response-error).
Paragraph (version B):
All requests to the continuation API are protected by a bound
continuation access token.  The continuation access token is bound to
the same key and method the client instance used to make the initial
request (or its most recent rotation).  As a consequence, when the
client instance makes any calls to the continuation URI, the client
instance MUST present the continuation access token as described in
use-access-token and present proof of the client instance's key (or
its most recent rotation) by signing the request as described in
binding-keys.  The AS MUST validate the signature and ensure that it
is bound to the appropriate key for the contination access token.
Paragraph (version B):
Access tokens other than the continuation access tokens MUST NOT be
usable for continuation requests.  Conversely, continuation access
tokens MUST NOT be usable to make authorized requests to RS's, even
if co-located within the AS.
Paragraph (version B):
The AS MUST be able to tell from the client instance's request which
specific ongoing request is being accessed, using a combination of
the continuation URI and the continuation access token.  If the AS
cannot determine a single active grant request to map the
continuation request to, the AS MUST return an "invalid_continuation"
error (response-error).
Paragraph (version B):
In both cases, the AS determines which grant is being asked for based
on the URI and continuation access token provided.
Paragraph (version A):
state, the AS could decide to remember the larger scale of access
rights associated with the grant request, allowing the client
instance to make subsequent requests of different subsets of granted
access.  The details of this are out of scope for this specification.
Paragraph (version B):
A client instance requests access to "Foo", and is granted by the
RO.  This results in an access token, "AT1".
Paragraph (version B):
The client instance later modifies the grant request to include
"Foo" and "Bar" together.  Since the client instance was
previously granted "Foo" under this grant request, the RO is
prompted to allow the client instance access to "Foo" and "Bar"
together.  This results in a new access token, "AT2" This access
token has access to both "Foo" and "Bar".  The rights of the
original access token "AT1" are not modified.
Paragraph (version B):
The client instance makes another grant modification to ask only
for "Bar".  Since the client instance was previously granted "Foo"
and "Bar" together under this grant request, the RO is not
prompted and the access to "Bar" is granted in a new access token,
"AT3".  This new access token does not allow access to "Foo".
Paragraph (version B):
The original access token "AT1" expires and the client seeks a new
access token to replace it.  The client instance makes another
grant modification to ask only for "Foo".  Since the client
instance was previously granted "Foo" and "Bar" together under
this grant request, the RO is not prompted and the access to "Foo"
is granted in a new access token, "AT4".  This new access token
does not allow access to "Bar".
Paragraph (version B):
All four access tokens are independent of each other and associated
with the same underlying grant request.  Each of these access tokens
could possibly also be rotated using token management, if available.
For example, instead of asking for a new token to replace "AT1", the
client instance could ask for a refresh of "AT1" using the rotation
method of token management.  This would result in a refreshed "AT1",
potentially with a different token value and expiration from the
original "AT1" but with the same access rights of allowing only
access to "Foo".
Paragraph (version A):
This "continue" field allows the client instance to make an eventual
continuation call.  In the future, the client instance realizes that
it no longer needs "write" access and therefore modifies its ongoing
request, here asking for just "read" access instead of both "read"
and "write" as before.
Paragraph (version B):
This "continue" field allows the client instance to make an eventual
continuation call.  Some time later, the client instance realizes
that it no longer needs "write" access and therefore modifies its
ongoing request, here asking for just "read" access instead of both
"read" and "write" as before.
Paragraph (version A):
Keys referenced in this manner MAY be shared symmetric keys.  The key
reference MUST NOT contain any unencrypted private or shared
symmetric key information.
Paragraph (version B):
Keys referenced in this manner MAY be shared symmetric keys.  See the
additional considerations for symmetric keys in security-symmetric.
The key reference MUST NOT contain any unencrypted private or shared
symmetric key information.
Paragraph (version A):
Finally, an AS can use platform attestations and other signals from
the client instance at runtime to determine whether the software
making the request is legitimate or not.  The details of such
attestations are outside the scope of the core protocol, but the
"client" portion of a grant request provides a natural extension
point to such information.
Paragraph (version B):
Finally, an AS can use platform attestations and other signals from
the client instance at runtime to determine whether the software
making the request is legitimate or not.  The details of such
attestations are outside the scope of the core protocol, but the
"client" portion of a grant request provides a natural extension
point to such information through the IANA-client-instance.