Draft: draft-ietf-gnap-core-protocol

Commentary: Refactors the key , token , and proofing sections into a new presentation section . Cleans up language around key presentation and binding . Also cleans up a few items missed by the merge of 
 Netlify deployed gnap - core - protocol - editors - draft as draft https://--gnap - core - protocol - editors- 
 Netlify deployed gnap - core - protocol - editors - draft as draft https://--gnap - core - protocol - editors- 
 Netlify deployed gnap - core - protocol - editors - draft as draft https://--gnap - core - protocol - editors- 
 Netlify deployed gnap - core - protocol - editors - draft as draft https://--gnap - core - protocol - editors- 
 Originally posted by in 
 In general I would tend to think this does n't need to be specified by us , supporting the current text " The means of dereferencing this value are out of scope for this specification . " But before we can conclude , I 'd like to ask a few questions : related the lifecycle of the referenced key ( cf ) : is it something ephemeral ( linked to a specific request ) or not ? ( but knowing that continuation could last for some time , what do we do then ? ) could it have an impact on error management ? ( for instance collision of references ? ) 
 In draft 7 , says that dereferencing key references are out of scope . Add to 7.1.1 to clarify : The common case is such that key references are created by the AS and are not necessarily deferenceable by the client , they are just an internal AS reference If an implementation ( or ecosystem of implementations ) wants to use references that are resolvable by both clients and ASs ( i.e. the client publishes its key at a URL ) , that could be described as an extension 
 regrouping and to provide guidance 
 I would appreciate more detail here : A finite list of specific extension points that we want to enable ( additional claims in the request ? in the response ? ) . IMO supporting too many extension points leads to code complexity , hence security issues . It also makes it harder to formally verify the protocol . Features that we trimmed and that we 'd like to enable to reinstate if someone cares about them ( maybe signature methods ? ) . Additional requirements ( having named extensions ? allowing a protocol party to declare that one or more extensions are critical ? ) . We should aim for a strict protocol definition ( e.g. messages can be validated using   ) where implementations refuse to accept unexpected " stuff " , and only allow very specific places where additional " stuff " is acceptable . This may not be best practice for JSON - using protocols , but it is for security protocols . 
 I would be in favor of further reducing some of the options in the core spec , and putting them in extensions ( + that provides concrete examples of what we mean by extensions ) This may concern :  assertions ( + makes sense to isolate due to distinct security issues with XML ) detached / attached JWS : because there 's an adherence on JOSE , that we do n't find anywhere else 
 I agree with in principle , but let 's not go too far . I think that  is functionality that 'll be widely used from day one ( correct me if I am wrong ) . If so , it needs to stay in the core spec . 
 After discussion between editors , that 's currently what will be proposed ( draft8 includes the related security considerations ) , and I agree with that  the question of JOSE , which will be discussed at IETF112 . Personally I believe a separate draft would make sense ( detached and attached JWS could be used by the oauth community as well ) and it would also be easier to rally people that dislike  to the GNAP WG . In short we 'd be agnostic to those subjective assessments . Additional comment after IETF112 : note that security is already baked into the protocol via HTTP message signatures or mTLS . We now need to decide if  methods are also needed in the core protocol , which of course could be useful to people already relying a lot on  ( as an alternative to HTTP message signatures ) . However , this does n't go into the direction of option minimization ( for the same features ) . 
 Editors will list all intended extension points within Core , probably pulling together all the existing stubs for extensions in different sections into a larger discussion . This would require at least a shell of the IANA section for creating necessary registries . In cases where it 's not clear how an extension would happen , the extension point should be removed explicitly . The goal being to have only clearly defined extension points in Core . 
 Currently , the field is defined in the client 's initial request but its format is referenced in a number of other places throughout the spec . It 's awkward calling back to this request field , so we should factor the key definition and its semantics to its own separate section . I think it would fit well under the " binding keys " section of the document since that also defines the presentation mechanisms . 
 +1 for that
Paragraph (version A):
This document defines a mechanism for delegating authorization to a
piece of software, and conveying that delegation to the software.
This delegation can include access to a set of APIs as well as
information passed directly to the software.
Paragraph (version A):
This document has been prepared by the GNAP working group design team
of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones, and
Justin Richer.  This document is intended as a starting point for the
working group and includes decision points for discussion and
agreement.  Many of the features in this proposed protocol can be
accomplished in a number of ways.  Where possible, the editor has
included notes and discussion from the design team regarding the
options as understood.
Paragraph (version B):
GNAP defines a mechanism for delegating authorization to a piece of
software, and conveying that delegation to the software.  This
delegation can include access to a set of APIs as well as information
passed directly to the software.
Paragraph (version A):
also needs to be prepared for the RQ never being returned to the
client instance and handle time outs appropriately.
Paragraph (version B):
also needs to be prepared for the end-user never being returned to
the client instance and handle time outs appropriately.
Paragraph (version A):
The RQ authenticates at the AS, taking on the role of the RO.
Paragraph (version A):
Identifies the RQ to the AS in a manner that the AS can verify,
either directly or by interacting with the RQ to determine their
status as the RO.
Paragraph (version A):
The access requested for a given object when using these fields is
the cross-product of all fields of the object.  That is to say, the
object represents a request for all "action" values listed within the
object to be used at all "locations" values listed within the object
for all "datatype" values listed within the object.  Assuming the
request above was granted, the RC could assume that it would be able
to do a "read" action against the "images" on the first server as
well as a "delete" action on the "metadata" of the second server, or
any other combination of these fields, using the same access token.
Paragraph (version A):
To request a different combination of access, such as requesting one
"action" against one "location" and a different "action" against a
different "location", the RC can include multiple separate objects in
the "resources" array.  The following non-normative example uses the
same fictitious "photo-api" type definition to request a single
access token with more specifically targeted access rights by using
two discrete objects within the request.
Paragraph (version B):
To request a different combination of access, such as requesting one
"action" against one "location" and a different "action" against a
different "location", the client instance can include multiple
separate objects in the "resources" array.  The following non-
normative example uses the same fictitious "photo-api" type
definition to request a single access token with more specifically
targeted access rights by using two discrete objects within the
request.
Paragraph (version A):
A single "resources" array MAY include both object-type and string-
type resource items.  In this non-normative example, the RC is
requesting access to a "photo-api" and "financial-transaction" API
type as well as the reference values of "read", "dolphin-metadata",
and "some other thing".
Paragraph (version B):
The public key of the client instance to be used in this request
as described in key-format or a reference to a key as described in
key-reference.  This field is REQUIRED.
Paragraph (version A):
Value of the public key as a JSON Web Key. MUST contain an "alg"
field which is used to validate the signature.  MUST contain the
"kid" field to identify the key in the signed object.
Paragraph (version A):
PEM serialized value of the certificate used to sign the request,
with optional internal whitespace.
Paragraph (version A):
The certificate thumbprint calculated as per RFC8705 in base64 URL
encoding.
Paragraph (version A):
Additional key types are defined in IANA.
Paragraph (version A):
This non-normative example shows a single key presented in multiple
formats using a single proofing mechanism.
Paragraph (version A):
continue-request MUST use the same key (or its most recent rotation)
and proof method as the initial request.
Paragraph (version A):
An array of subject identifiers for the RQ, as defined by I-
D.ietf-secevent-subject-identifiers.
Paragraph (version A):
If the identified RQ does not match the RO present at the AS during
an interaction step, the AS SHOULD reject the request with an error.
Paragraph (version B):
Many times, the AS will require interaction with the RO in order to
approve a requested delegation to the client instance for both
resources and direct claim information.  Many times the end-user
using the client instance is the same person as the RO, and the
client instance can directly drive interaction with the AS by
redirecting the end-user on the same device, or by launching an
application.  Other times, the client instance can provide
information to start the RO's interaction on a secondary device, or
the client instance will wait for the RO to approve the request
asynchronously.  The client instance could also be signaled that
interaction has completed by the AS making callbacks.  To facilitate
all of these modes, the client instance declares the means that it
can interact using the "interact" field.
Paragraph (version A):
Indicates the RQ's preferred locales that the AS can use during
interaction, particularly before the RO has authenticated.
Paragraph (version A):
The AS MUST return the "subject" field only in cases where the AS is
sure that the RO and the RQ are the same party.  This can be
accomplished through some forms of user-interaction.
Paragraph (version B):
The access token is initially 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 URL, the
client instance MUST present the 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 B):
If the token is a bearer token, the client instance MUST present
proof of the same request-client as described in binding-keys.
Paragraph (version A):
If the key value is the boolean "false", the access token is a bearer
token sent using the HTTP Header method defined in RFC6750.
Paragraph (version B):
In GNAP, the client instance secures its requests to the AS and RS by
presenting an access token, presenting proof of a key that it
possesses, or both an access token and key proof together.
Paragraph (version B):
When an access token is used with a key proof, this is a bound
token request.  This type of request is used for calls to the RS
as well as the AS during negotiation.
Paragraph (version B):
When a key proof is used with no access token, this is a non-
authorized signed request.  This type of request is used for calls
to the AS to initiate a negotiation.
Paragraph (version B):
When an access token is used with no key proof, this is a bearer
token request.  This type of request is used only for calls to the
RS, and only with access tokens that are not bound to any key as
described in response-token-single.
Paragraph (version B):
Several different places in GNAP require the presentation of key
material by value.  Proof of this key material MUST be bound to a
request, the nature of which varies with the location in the protocol
the key is used.  For a key used as part of a client instance's
initial request in request-client, the key value is the client
instance's public key, and proof of that key MUST be presented in
that request.  For a key used as part of an access token response in
response-token-single, the proof of that key MUST be used when
presenting the access token.
Paragraph (version B):
The form of proof that the client instance will use when
presenting the key.  The valid values of this field and the
processing requirements for each are detailed in binding-keys.
The "proof" field is REQUIRED.
Paragraph (version B):
PEM serialized value of the certificate used to sign the request,
with optional internal whitespace per RFC7468.  The PEM header and
footer are optionally removed.
Paragraph (version B):
The certificate thumbprint calculated as per RFC8705 in base64 URL
encoding.  Note that this format does not include the full public
key.
Paragraph (version B):
Additional key formats are defined in IANA.
Paragraph (version B):
This non-normative example shows a single key presented in multiple
formats.  This key is intended to be used with the detached-jws
proofing mechanism, as indicated by the "proof" field.
Paragraph (version B):
Keys in GNAP can also be passed by reference such that the party
receiving the reference will be able to determine the appropriate
keying material for use in that part of the protocol.
Paragraph (version B):
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 MUST be bound to a single proofing
mechanism.
Paragraph (version B):
The means of dereferencing this value are out of scope for this
specification.
Paragraph (version B):
The method the client instance uses to send an access token depends
on whether the token is bound to a key, and if so which proofing
method is associated with the key.  This information is conveyed in
the "key" and "proof" parameters in response-token-single.
Paragraph (version B):
If the "key" value is the boolean "false", the access token is a
bearer token sent using the HTTP Header method defined in RFC6750.
Paragraph (version B):
If the "key" value is the boolean "true", the access token MUST be
sent using the same key and proofing mechanism that the client
instance used in its initial request (or its most recent rotation).
Paragraph (version A):
When used to bind to an access token, the access token MUST be
covered by the signature method.
Paragraph (version B):
When a key proofing mechanism is bound to an access token, the access
token MUST be covered by the signature method of the proofing
mechanism.
Paragraph (version B):
When used for delegation in GNAP, these key binding mechanisms allow
the AS to ensure that the keys presented by the client instance in
the initial request are in control of the party calling any follow-up
or continuation requests.  To facilitate this requirement, the
response-continue includes an access token bound to the request-
client, and that key (or its most recent rotation) MUST be proved in
all continuation requests continue-request.  Token management
requests token-management are similarly bound to either the access
token's own key or, in the case of bearer tokens, the client
instance's key.
Paragraph (version A):
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 request-key of the request.
Paragraph (version B):
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-format of the request.