Draft: draft-ietf-gnap-core-protocol

Commentary: Adds IANA registries for extensible parts of the protocol and centralizes discussion of extension practices into an appendix . 
 To edit notification comments on pull requests , go to your . 
 Seems fairly complete
Paragraph (version A):
Additional members of this request object can be defined by
extensions to this protocol as described in request-extending.
Paragraph (version B):
Additional members of this request object can be defined by
extensions using the IANA-grant-request.
Paragraph (version B):
If the client instance is requesting information about the RO from
the AS, it sends a "subject" field as a JSON object.  This object MAY
contain the following fields.
Paragraph (version B):
Additional fields are defined in the IANA-subject-request.
Paragraph (version A):
Additional fields are defined in IANA.
Paragraph (version B):
Additional fields are defined in the IANA-client-instance.
Paragraph (version B):
The client instance MUST prove possession of any presented key by the
"proof" mechanism associated with the key in the request.  Key
proofing methods are defined in the IANA-key-proof-methods and an
initial set of methods is described in binding-keys.
Paragraph (version A):
Additional display fields are defined by IANA.
Paragraph (version B):
Additional display fields are defined by the IANA-client-instance-
display.
Paragraph (version B):
Individual modes MAY define additional parameters to be required in
the object.
Paragraph (version B):
Additional start modes are defined in the IANA-interaction-start-
modes.
Paragraph (version A):
The following sections detail requests for interaction hints.
Additional interaction hints are defined in IANA.
Paragraph (version B):
The following sections detail requests for interaction hints.
Additional interaction hints are defined in the IANA-interaction-
hints.
Paragraph (version A):
Additional interaction start modes, finish modes, and hints are
defined in IANA.
Paragraph (version A):
The request object MAY be extended by registering new items in IANA.
Extensions SHOULD be orthogonal to other parameters.  Extensions MUST
document any aspects where the extension item affects or influences
the values or behavior of other request and response objects.
Paragraph (version B):
Additional fields can be defined by extensions to GNAP in the IANA-
grant-response.
Paragraph (version A):
Additional interaction mode responses can be defined in IANA.
Paragraph (version B):
Additional interaction mode responses can be defined in the IANA-
interaction-response.
Paragraph (version A):
Extensions to this specification can define new interaction mode
responses in IANA.  Extensions MUST document the corresponding
interaction request.
Paragraph (version A):
Extensions to this specification MAY define additional response
properties in IANA.
Paragraph (version B):
Extensions to this specification MAY define additional response
properties in the IANA-subject-response.
Paragraph (version A):
Extensions to this specification MAY define additional fields for the
grant response in IANA.
Paragraph (version A):
Additional key formats are defined in IANA.
Paragraph (version B):
Additional key formats are defined in the IANA-key-formats.
Paragraph (version A):
Additional proofing methods are defined by IANA.
Paragraph (version B):
Additional proofing methods are defined by the IANA-key-proof-
methods.
Paragraph (version B):
Additional fields can be defined the IANA-as-discovery.
Paragraph (version B):
IANA is requested to create XX registries for the Grant Negotiation
and Authorization Protocol and to populate those registries with
initial values as described in this section.
Paragraph (version B):
All use of value typing is based on RFC8259 data types and MUST be
one of the following: number, object, string, boolean, or array.
When the type is array, the contents of the array MUST be specified,
as in "array of objects".  If a parameter is available in different
types, each type SHOULD be registered separately.
Paragraph (version B):
General guidance for extension parameters is found in extensions.
Paragraph (version B):
This document defines a GNAP grant request, for which IANA is asked
to create and maintain a new registry titled "Grant Request
Parameters".  Initial values for this registry are given in IANA-
grant-request-contents.  Future assignments and modifications to
existing assignment are to be made through the Expert Review
registration policy RFC8126 and shall follow the template presented
in IANA-grant-request-template.
Paragraph (version B):
Each grant request parameter's definition MUST specify the expected
behavior of the AS for each potential state of the grant request.
Paragraph (version B):
This document defines a GNAP access token flags, for which IANA is
asked to create and maintain a new registry titled "Access Token
Flags".  Initial values for this registry are given in IANA-token-
flags-contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126 and shall follow the template presented in IANA-token-
flags-template.
Paragraph (version B):
Each flag MUST specify whether it can be requested by clients
instances or is only allowed in responses from the AS.
Paragraph (version B):
This document defines a means to request subject information from the
AS to the client instance, for which IANA is asked to create and
maintain a new registry titled "Subject Information Request Fields".
Initial values for this registry are given in IANA-subject-request-
contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126 and shall follow the template presented in IANA-
subject-request-template.
Paragraph (version B):
This document defines a means to pass identity assertions between the
AS and client instance, for which IANA is asked to create and
maintain a new registry titled "Assertion Formats".  Initial values
for this registry are given in IANA-assertion-formats-contents.
Future assignments and modifications to existing assignment are to be
made through the Expert Review registration policy RFC8126 and shall
follow the template presented in IANA-assertion-formats-template.
Paragraph (version B):
Each assertion format definition MUST specify the serialization
format of the assertion value as used within GNAP.
Paragraph (version B):
This document defines a means to send information about the client
instance, for which IANA is asked to create and maintain a new
registry titled "Client Instance Fields".  Initial values for this
registry are given in IANA-client-instance-contents.  Future
assignments and modifications to existing assignment are to be made
through the Expert Review registration policy RFC8126 and shall
follow the template presented in IANA-client-instance-template.
Paragraph (version B):
This document defines a means to send end-user facing displayable
information about the client instance, for which IANA is asked to
create and maintain a new registry titled "Client Instance Display
Fields".  Initial values for this registry are given in IANA-client-
instance-display-contents.  Future assignments and modifications to
existing assignment are to be made through the Expert Review
registration policy RFC8126 and shall follow the template presented
in IANA-client-instance-display-template.
Paragraph (version B):
This document defines a means for the client instance to begin
interaction between the end-user and the AS, for which IANA is asked
to create and maintain a new registry titled "Interaction Start
Modes".  Initial values for this registry are given in IANA-
interaction-start-modes-contents.  Future assignments and
modifications to existing assignment are to be made through the
Expert Review registration policy RFC8126 and shall follow the
template presented in IANA-interaction-start-modes-template.
Paragraph (version B):
Each interaction start mode that uses an "object" type MUST declare
all additional parameters.
Paragraph (version B):
This document defines a means for the client instance to be notified
of the end of interaction between the end-user and the AS, for which
IANA is asked to create and maintain a new registry titled
"Interaction Finish Methods".  Initial values for this registry are
given in IANA-interaction-finish-methods-contents.  Future
assignments and modifications to existing assignment are to be made
through the Expert Review registration policy RFC8126 and shall
follow the template presented in IANA-interaction-finish-methods-
template.
Paragraph (version B):
This document defines a set of hints that a client instance can
provide to the AS to facilitate interaction with the end user, for
which IANA is asked to create and maintain a new registry titled
"Interaction Hints".  Initial values for this registry are given in
IANA-interaction-hints-contents.  Future assignments and
modifications to existing assignment are to be made through the
Expert Review registration policy RFC8126 and shall follow the
template presented in IANA-interaction-hints-template.
Paragraph (version B):
This document defines a GNAP grant response, for which IANA is asked
to create and maintain a new registry titled "Grant Response
Parameters".  Initial values for this registry are given in IANA-
grant-response-contents.  Future assignments and modifications to
existing assignment are to be made through the Expert Review
registration policy RFC8126 and shall follow the template presented
in IANA-grant-response-template.
Paragraph (version B):
Each grant response parameter's definition MUST specify the states
for which the client instance can expect this parameter.
Paragraph (version B):
This document defines a means for the AS to provide to the client
instance information that is required to complete a particular
interaction mode, for which IANA is asked to create and maintain a
new registry titled "Interaction Mode Responses".  Initial values for
this registry are given in IANA-interaction-response-contents.
Future assignments and modifications to existing assignment are to be
made through the Expert Review registration policy RFC8126 and shall
follow the template presented in IANA-interaction-response-template.
Paragraph (version B):
Interaction mode responses MUST document the corresponding
interaction start mode that triggers the response's inclusion.
Paragraph (version B):
This document defines a means to return subject information from the
AS to the client instance, for which IANA is asked to create and
maintain a new registry titled "Subject Information Response Fields".
Initial values for this registry are given in IANA-subject-response-
contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126 and shall follow the template presented in IANA-
subject-response-template.
Paragraph (version B):
This document defines a set of errors that the AS can return to the
client instance, for which IANA is asked to create and maintain a new
registry titled "Error Responses".  Initial values for this registry
are given in IANA-error-response-contents.  Future assignments and
modifications to existing assignment are to be made through the
Expert Review registration policy RFC8126 and shall follow the
template presented in IANA-error-response-template.
Paragraph (version B):
This document defines methods that the client instance can use to
prove possession of a key, for which IANA is asked to create and
maintain a new registry titled "Key Proofing Methods".  Initial
values for this registry are given in IANA-key-proof-methods-
contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126 and shall follow the template presented in IANA-key-
proof-methods-template.
Paragraph (version B):
This document defines formats for a public key value, for which IANA
is asked to create and maintain a new registry titled "Key Formats".
Initial values for this registry are given in IANA-key-formats-
contents.  Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy RFC8126 and shall follow the template presented in IANA-key-
formats-template.
Paragraph (version B):
This document defines a discovery document for an AS, for which IANA
is asked to create and maintain a new registry titled "Authorization
Server Discovery Fields".  Initial values for this registry are given
in IANA-as-discovery-contents.  Future assignments and modifications
to existing assignment are to be made through the Expert Review
registration policy RFC8126 and shall follow the template presented
in IANA-as-discovery-template.
Paragraph (version B):
In addition to the normative requirements in this document,
implementors are strongly encouraged to consider these additional
security considerations in implementations and deployments of GNAP.