jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Sec . 1.5 ( Sequences ) would be clearer if we named the top sequence - all other sequences have been named . Maybe " main authorization flow " ? 
 The sequences have not been names per say , they just happen to be related to a subtitle . We could of course create a new subsection , but the idea was to place this sequence above the others . 
 This is purely editorial . Naming it would make it easier to refer to this sequence .
Paragraph (version B):
The following diagram provides a general overview of GNAP, including
many different optional phases and connections.  The diagrams in the
following sections provide views of GNAP under more specific
circumstances.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 The text says : protected by the client instance as secrets . Instance identifier values MUST be unguessable and MUST NOT contain any sensitive information . This is weird , because we 're saying both that they should be treated as secrets and that they are not sensitive . I would suggest instead : protected by the client instance as secrets . Instance identifier values MUST be unguessable and MUST NOT contain any information that would compromise the AS if revealed . 
 We 're not saying that they 're not sensitive , we 're saying that they ca n't contain sensitive information . This is like saying your password is sensitive and it also should n't contain your medical record number at your hospital , because that 's also a sensitive piece of information . Still I think the wording is an improvement , thanks ! 
 I agree the proposed wording is better , thanks !
Paragraph (version A):
Dynamically generated client instance identifiers are string values
that MUST be protected by the client instance as secrets.  Instance
identifier values MUST be unguessable and MUST NOT contain any
sensitive information.  Instance identifier values are opaque to the
client instance.
Paragraph (version B):
Dynamically generated client instance identifiers are string values
that MUST be protected by the client instance as secrets.  Instance
identifier values MUST be unguessable and MUST NOT contain any
information that would compromise any party if revealed.  Instance
identifier values are opaque to the client instance.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Requesting User Information :  's note : We 're potentially conflating these two types in the same structure ( and are both in ) , so perhaps these should be split . There 's also a difference between user information and authentication event information . 
 Question : do we need to manage assertions about someone else ( like : I 'm the doctor for this patient ) ? or limited to same user ? Should the label be " sub_assertions " then ( to further convey that the assertion is related to the same subject ) ? 
 Suggest closing for same reason as 
 This issue is tagged next to the following cryptic sentence : What do we mean by " a different subject identifier " ? 
 You could get back something like this as a subject identifier : But the assertion could be an ID Token with : Basically the assertions and identifiers are all talking about the same PERSON but they do n't have to all do so in the same WAY . 
 So please reword the sentence to clarify . E.g. : Note : the " formats " and " assertions " request fields are independent of each other , and a returned assertion MAY use a different subject identifier than specified in the request , as long as it refers to the same person . 
 yes , that 's clearer . I 'll make a PR
Paragraph (version A):
Note: the "sub_id_formats" and "assertion_formats" request fields are
independent of each other, and a returned assertion MAY use a
different subject identifier.
Paragraph (version B):
The "formats" and "assertions" request fields are independent of each
other, and a returned assertion MAY use a different subject
identifier than other assertions and subject identifiers in the
response.  All subject identifiers and assertions returned MUST refer
to the same person.
Draft: draft-ietf-gnap-core-protocol

Commentary: Actually a very minor editorial change to specify the actions . 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 So I was starting to have a look at rotation / revocation issues ( keys or tokens ) , as we have many open issues that relate to that Interesting insight from DIF KERI ( Universal Identifier Theory paper ) " The term revocation has two completely different meanings in the identity space . In key management one may speak of revoking keys . With statement issuance , authorization issuance , or credential issuance , one may speak of revoking an authorization statement , a token , or a credential . This becomes confusing when the act of revoking keys also implicitly revokes the authorization of statements signed with those keys . " and "  terminology usually avoids that confusion between rotation and revocation because a key rotation operation is the equivalent of a key revocation operation followed by a key replacement operation . So one operation , rotate , is implemented instead of two operations ( revoke and replace ) . " 
 Related question : what is persistent ( drawback , need to store that info somewhere , safely ) ? what is ephemeral ? what 's the lifecycle of related objects ? And more specifically : every new request needs to provide a key -don't need long term persistance for that , we simply need to handle key rotations during a single request ( as described in issue ) objets derived from some underlying key however ( including bound tokens ) might be more tricky ( ex ) . Do we need some kind of registry to keep track of the changes over time , to keep them alive even if the key changes ? Or do we just consider that they get revoked ? ( and what happens if you fall into that case at some point , what 's your next action ? ) 
 This is already managed by section 7.2 " If the flags field does not contain the bearer flag and the key is absent , 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):
If an access token response includes the "manage" parameter as
described in response-token-single, the client instance MAY call this
URL to manage the access token with any of the actions defined in the
following sections.  Other actions are undefined by this
specification.
Paragraph (version B):
If an access token response includes the "manage" parameter as
described in response-token-single, the client instance MAY call this
URL to manage the access token with any of the actions defined in the
following sections: rotate and revoke.  Other actions are undefined
by this specification.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview : 
 in 4.2.3.1 and 4.2.3.2 , for  encoded URLs with no padding ( + by the way , we should explain what we mean by no padding and URL safe ) 
 Base64 URL - safe encoding , with and without padding , is defined in RFC4648 . URLsafe : Optional padding : 
 thanks exactly the links i needed
Paragraph (version A):
The "sha3" hash method consists of hashing the input string with the
512-bit SHA3 algorithm.  The byte array is then encoded using URL
Safe Base64 with no padding.  The resulting string is the hash value.
Paragraph (version A):
The "sha2" hash method consists of hashing the input string with the
512-bit SHA2 algorithm.  The byte array is then encoded using URL
Safe Base64 with no padding.  The resulting string is the hash value.
Paragraph (version B):
The "sha3" hash method consists of hashing the input string with the
512-bit SHA3 algorithm.  The byte array is then encoded using URL
Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Paragraph (version B):
The "sha2" hash method consists of hashing the input string with the
512-bit SHA2 algorithm.  The byte array is then encoded using URL
Safe Base64 with no padding RFC4648.  The resulting string is the
hash value.
Draft: draft-ietf-gnap-core-protocol

Commentary: with array of objects to account for the possibility of several assertions 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 As a completely random comment , I find it interesting that computer science commonly refers to an array as a collection of elements with the same data type . It 's also a fixed - size collection of elements . clearly defines and uses an array . Moreover , it says that what 's a bit more important is that this specification should probably use " array of ... " everywhere as this is n't true right now . I see the use of both " list of ... " and " array of ... " at the same time . 
 Since  is based around JSON for its data model , we use JSON - native data types and their names . The name for an unlabeled , ordered collection is a " JSON array " , as you pointed out . If there are places in GNAP where we 're using " list " where we should be saying " array " , we should fix that . 
 Todo : inner description to change ( key ) assertions -format subid_formats or something like that 
 Requesting User Information :  's note : The values are lifted from ] 's " token type identifiers " list , but is there a better source ? : Identifying the User : Editor 's note : The keys are lifted from [ RFC8693 ] 's " token type identifiers " list , but is there a better source ? Additionally : should this be an array of objects with internal typing like the subids ? Do we expect more than one assertion per user anyway ? Returning User Information :  's note : Should be an array of objects with internal typing like the subids ? Do we expect more than one assertion per user anyway ? 
 A related topic is , ZKP , etc . A specific type of assertion is used in to prove ownership of a sub ( through JWT ) . 
 I think that should be an in " Returning User Information " . If not , at least , it could be renamed to " assertion " because the current draft uses " assertions " and defines it as . This is a minor editorial thing though . The more major thing is that what are the strong reasons even to mention SAML assertions in the spec ? In recent times , XML is often referred to as a potentially insecure format which is n't great due to a long list of vulnerabilities in XML libraries . 
 We 'll discuss that and more at IETF110 . I agree that assertions are probably an array ( it 's not just editorial , and there 's another issue open on that ) + for the very same reasons you mention I would suggest we remove  assertions from the core ( but still we can plan an extension in the registry , already mentioned as a possibility ) . 
 There 's now a security consideration related to XML .
Paragraph (version A):
Note: the "formats" and "assertions" request fields are independent
of each other, and a returned assertion MAY use a different subject
identifier.
Paragraph (version B):
Note: the "sub_id_formats" and "assertion_formats" request fields are
independent of each other, and a returned assertion MAY use a
different subject identifier.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview : 
 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 
 I think the text looks good , left one note on formatting / structure but it 's not a showstopper .
Paragraph (version A):
The means of dereferencing this value are out of scope for this
specification.
Paragraph (version B):
The means of dereferencing this value are out of scope for this
specification.  Commonly, key references are created by the AS and
are not necessarily needed to be dereferencable by the client.  These
types of key references are an internal reference to the AS, such as
an identifier of a record in a database.  In other applications, it
can be useful to use key references that are resolvable by both
clients and ASs, which could be accomplished by e.g. a client
publishing a public key at a URL.  For interoperability, this method
could later be described as an extension.
Draft: draft-ietf-gnap-core-protocol

Commentary: Added security considerations for cuckoo token , 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Client instance uses different keys with each AS Stolen token bound to different keys , RS will reject Client has strong binding between RS and AS used Attacker ca n’t convince client to use “ wrong ” AS
Paragraph (version B):
A client instance that is capable of talking to multiple AS's SHOULD
use a different key for each AS to prevent a class of mix-up attacks
as described in security-cuckoo.
Paragraph (version B):
If a client instance can request tokens at multiple AS's, and the
client instance uses the same keys to make its requests across those
different AS's, then it is possible for an attacker to replay a
stolen token issued by an honest AS from a compromised AS, thereby
binding the stolen token to the client instance's key in a different
context.  The attacker can manipulate the client instance into using
the stolen token at an RS, particularly at an RS that is expecting a
token from the honest AS.  Since the honest AS issued the token and
the client instance presents the token with its expected bound key,
the attack succeeds.
Paragraph (version B):
This attack has several preconditions.  In this attack, the attacker
does not need access to the client instance's key and cannot use the
stolen token directly at the RS, but the attacker is able to get the
access token value in some fashion.  The client instance also needs
to be configured to talk to multiple AS's, including the attacker's
controlled AS.  Finally, the client instance needs to be able to be
manipulated by the attacker to call the RS while using a token issued
from the stolen AS.  The RS does not need to be compromised or made
to trust the attacker's AS.
Paragraph (version B):
To protect against this attack, the client instance can use a
different key for each AS that it talks to.  Since the replayed token
will be bound to the key used at the honest AS, the uncompromised RS
will reject the call since the client instance will be using the key
used at the attacker's AS instead with the same token.  When the MTLS
key proofing method is used, a client instance can use self-signed
certificates to use a different key for each AS that it talks to, as
discussed in security-mtls-patterns.
Paragraph (version B):
Additionally, the client instance can keep a strong association
between the RS and a specific AS that it trusts to issue tokens for
that RS.  This strong binding also helps against some forms of
security-mixup.  Managing this binding is outside the scope of GNAP
core, but it can be managed either as a configuration element for the
client instance or dynamically through rs-request-without-token.
Paragraph (version B):
The details of this attack are available in HELMSCHMIDT2022 with
additional discussion and considerations.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 Some unicode characters within the document break the build tools , specifically we see being changed to in the rendered document .
Paragraph (version A):
A client instance needs to always be aware of which AS it is talking
to throughout a grant process, and ensure that any callback for one
AS does not get conflated with the callback to different AS.  The
interaction finish hash calculate allows a client instance to protect
against this kind of substitution, but only if the client instance
validates the hash.  If the client instance does not use an
interaction finish method or does not check the interaction finish
hash value, the compromised AS can be granted a valid access token on
behalf of the resource owner.  See attack-surfaces for details of one
such attack, which has been since addressed in this document by
including the grant endpoint in the interaction hash calculation.
The client instance still needs to validate the hash for the attack
to be prevented.
Paragraph (version B):
A client instance needs to always be aware of which AS it is talking
to throughout a grant process, and ensure that any callback for one
AS does not get conflated with the callback to different AS.  The
interaction finish hash calculate allows a client instance to protect
against this kind of substitution, but only if the client instance
validates the hash.  If the client instance does not use an
interaction finish method or does not check the interaction finish
hash value, the compromised AS can be granted a valid access token on
behalf of the resource owner.  See AXELAND2021 for details of one
such attack, which has been since addressed in this document by
including the grant endpoint in the interaction hash calculation.
The client instance still needs to validate the hash for the attack
to be prevented.
Draft: draft-ietf-gnap-core-protocol

Commentary: May later make a link to security considerations related to phishing attacks but currently the section has not been merged in trunk , so it would create an error 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview : 
 To be described ( interactions )
Paragraph (version B):
end-user / AS: when the client supports it (see response-
interact), the end-user gets to interact with front-channel URLs
provided by the AS.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview :
Paragraph (version A):
If desired, the AS MAY also generate and return some of these
references dynamically to the client instance in its response to
facilitate multiple interactions with the same software.  The client
instance SHOULD use these references in future requests in lieu of
sending the associated data value.  These handles are intended to be
used on future requests.
Paragraph (version A):
Dynamically generated handles are string values that MUST be
protected by the client instance as secrets.  Handle values MUST be
unguessable and MUST NOT contain any sensitive information.  Handle
values are opaque to the client instance.
Paragraph (version A):
All dynamically generated handles are returned as fields in the root
JSON object of the response.  This specification defines the
following dynamic handle return, additional handles can be defined in
IANA.
Paragraph (version A):
This non-normative example shows one handle along side an issued
access token.
Paragraph (version B):
If desired, the AS MAY also generate and return an instance
identifier dynamically to the client instance in the response to
facilitate multiple interactions with the same client instance over
time.  The client instance SHOULD use this instance identifier in
future requests in lieu of sending the associated data values in the
"client" field.
Paragraph (version B):
Dynamically generated client instance identifiers are string values
that MUST be protected by the client instance as secrets.  Instance
identifier values MUST be unguessable and MUST NOT contain any
sensitive information.  Instance identifier values are opaque to the
client instance.
Paragraph (version B):
This non-normative example shows an instance identifier along side an
issued access token.
Draft: draft-ietf-gnap-core-protocol

Commentary: In the current version , the AS must include an access token . " if the AS includes an access token " sounds like the inclusion of an access token is optional . 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview :
Paragraph (version A):
REQUIRED.  The URI at which the client instance can make
continuation requests.  This URI MAY vary per request, or MAY be
stable at the AS if the AS includes an access token.  The client
instance MUST use this value exactly as given when making a
continue-request.
Paragraph (version B):
REQUIRED.  The URI at which the client instance can make
continuation requests.  This URI MAY vary per request, or MAY be
stable at the AS.  The client instance MUST use this value exactly
as given when making a continue-request.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview :
Paragraph (version A):
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 "bound" and "key" parameters in response-token-single and
response-token-multiple responses.
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 by
the "key" parameter and the "bearer" flag in response-token-single
and response-token-multiple responses.
Draft: draft-ietf-gnap-core-protocol

Commentary: Deploy Preview for gnap - core - protocol - editors - draft ready ! Built Explore the source changes : Inspect the deploy log : Browse the preview :
Paragraph (version A):
When using the response-interact-finish with the "push" method, the
AS signals to the client instance that interaction is complete and
the request can be continued by sending an HTTP POST request to the
client instance's callback URL sent in request-interact-callback-
push.
Paragraph (version B):
When using the response-interact-finish, the AS signals to the client
instance that interaction is complete and the request can be
continued by sending an HTTP POST request to the client instance's
callback URL sent in request-interact-callback-push.
Paragraph (version A):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter of the "callback".  If the
"hash_method" value is not present in the client instance's request,
the algorithm defaults to "sha3".
Paragraph (version B):
The party then hashes this string with the appropriate algorithm
based on the "hash_method" parameter under the "finish" key.  If the
"hash_method" value is not present in the client instance's request,
the algorithm defaults to "sha3".