Draft: draft-ietf-gnap-core-protocol

Commentary: To edit notification comments on pull requests , go to your . _ 
 All IANA registry definitions that require a DE need to have explicit instructions for the DE to follow .
Paragraph (version A):
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".  When the type is object, the structure of
the object MUST be specified in the definition.  If a parameter is
available in different types, each type SHOULD be registered
separately.
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" when one subtype is allowed or "array of
strings/objects" when multiple simultaneous subtypes are allowed.
When the type is object, the structure of the object MUST be
specified in the definition.  If a parameter is available in
different types, each type SHOULD be registered separately.
Paragraph (version A):
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 A):
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 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.
Paragraph (version B):
The Designated Expert (DE) is expected to ensure that all
registrations follow the template presented in IANA-grant-request-
template.  The DE is expected to ensure that the request parameter's
definition is sufficiently orthogonal to existing functionality
provided by existing parameters.  The DE is expected to ensure that
registrations for the same name with different types are sufficiently
close in functionality so as not to cause confusion for developers.
The DE is expected to ensure that the request parameter's definition
specifies the expected behavior of the AS in response to the request
parameter for each potential state of the grant request.
Paragraph (version A):
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 A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-token-flags-template.  The DE is expected
to ensure that the flag specifies whether it applies to requests for
tokens to the AS, responses with tokens from the AS, or both.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-subject-request-template.  The DE is
expected to ensure that registrations for the same name with
different types are sufficiently close in functionality so as not to
cause confusion for developers.
Paragraph (version A):
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 A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-assertion-formats-template.  The DE is
expected to ensure that the definition specifies the serialization
format of the assertion value as used within GNAP.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-client-instance-template.  The DE is
expected to ensure that registrations for the same name with
different types are sufficiently close in functionality so as not to
cause confusion for developers.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-client-instance-display-template.  The DE
is expected to ensure that registrations for the same name with
different types are sufficiently close in functionality so as not to
cause confusion for developers.
Paragraph (version A):
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 A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-interaction-start-modes-template.  The DE
is expected to ensure that registrations for the same name with
different types are sufficiently close in functionality so as not to
cause confusion for developers.  The DE is expected to ensure that
any registration using an "object" type declares all additional
parameters, their optionality, and purpose.  The DE is expected to
ensure that all start modes clearly define what actions the client is
expected to take to begin interaction, what the expected user
experience is, and any security considerations for this communication
from either party.  The DE is expected to ensure that all start modes
document incompatibilities with other start modes or finish methods,
if applicable.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-interaction-finish-methods-template.  The
DE is expected to ensure that all finish methods clearly define what
actions the AS is expected to take, what listening methods the client
instance needs to enable, and any security considerations for this
communication from either party.  The DE is expected to ensure that
all finish methods document incompatibilities with any start modes,
if applicable.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-interaction-hints-template.  The DE is
expected to ensure that all interaction hints clearly document the
expected behaviors of the AS in response to the hint, and that an AS
not processing the hint does not impede the operation of the AS or
client instance.
Paragraph (version A):
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 A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-grant-response-template.  The DE is
expected to ensure that the response parameter's definition is
sufficiently orthogonal to existing functionality provided by
existing parameters.  The DE is expected to ensure that registrations
for the same name with different types are sufficiently close in
functionality so as not to cause confusion for developers.  The DE is
expected to ensure that the response parameter's definition specifies
grant states for which the client instance can expect this parameter
to appear in a response message.
Paragraph (version A):
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 A):
Interaction mode responses MUST document the corresponding
interaction start mode that triggers the response's inclusion.
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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-interaction-response-template.  If the
name of the registration matches the name of an interaction start
mode, the DE is expected to ensure that the response parameter is
unambiguously associated with the interaction start mode of the same
name.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-subject-response-template.  The DE is
expected to ensure that registrations for the same name with
different types are sufficiently close in functionality so as not to
cause confusion for developers.
Paragraph (version A):
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 Codes".  Initial values for this registry are
given in IANA-error-code-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-code-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 Codes".  Initial values for this registry are
given in IANA-error-code-contents.  Future assignments and
modifications to existing assignment are to be made through the
Expert Review registration policy RFC8126.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-error-code-template.  The DE is expected
to ensure that the error response is sufficiently unique from other
errors to provide actionable information to the client instance.  The
DE is expected to ensure that the definition of the error response
specifies all conditions in which the error response is returned, and
what the client instance's expected action is.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-key-proof-methods-template.  The DE is
expected to ensure that registrations for the same name with
different types are sufficiently close in functionality so as not to
cause confusion for developers.  The DE is expected to ensure that
the proofing method provides sufficient coverage of and binding to
the protocol messages to which it is applied.
Paragraph (version A):
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 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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-key-formats-template.  The DE is expected
to ensure the key format specifies the structure and serialization of
the key material.
Paragraph (version A):
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):
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.
Paragraph (version B):
The DE is expected to ensure that all registrations follow the
template presented in IANA-as-discovery-template.  The DE is expected
to ensure that registrations for the same name with different types
are sufficiently close in functionality so as not to cause confusion
for developers.  The DE is expected to ensure that the values in the
discovery document are sufficient to provide optimization and hints
to the client instance, but that knowledge of the discovered value is
not required for starting a transaction with the AS.