Draft: draft-ietf-gnap-core-protocol

Commentary: Adds an initial set of security considerations to the GNAP core draft . Additional considerations to be in future edits as discussion evolves . 
 Deploy Preview for gnap - core - protocol - editors - draft ready ! Explore the source changes : Inspect the deploy log : Browse the preview : 
 About Section 12 . Security Considerations ( page 109 ) Section 12.1 states : This has nothing to do with the title of this section which is " TLS Protection in Transit " . There is no justification of the reason(s ) why the requests from the client instance to the AS should or shall be signed . Section 12.1 also states : This has nothing to do with the title of this section which is " TLS Protection in Transit " . There is no justification of the reason(s ) why key - bound access tokens should or shall be used . The next sentence states : It should be observed that those keys and signatures associated to a bound access token do not prevent an attacker from using a stolen token , if a legitimate client collaborates with another client . Section 12.2 ( Protection of Client Instance Key Material ) states : The rational for authentication client instances using a unique key is not explained . The access tokens contain the rights or privileges of a human user and not those for a client instance . The relationship between client instances and end - users is not explained . Section 12.3 states : While the text explicitly states that the AS authenticates the client software , the text is mute about the authentication of the end - user by the AS . Section 12.6 is about Bearer Access Tokens states : In the context of GNAP , bearer tokens are not defined . However , there exists a definition of the bearer flag which is the following : However , it is possible to obtain a protection against the use of an access token by another client by using bearers tokens , if they include a specific field that does not exist in draft -07 . Such a protection is explained in details in draft - pinkas - gnap - core - protocol-00 . See the text on page 9 about the " buid " field which is a " binding user identifier " that allows a RS to verify that the access token is associated with the right ( short - term or long - term ) user account . This field allows to detect the inappropriate use of an access token by a malicious user . Section 12.6 states : and also : Both sentences are incorrect , as soon as a " binding user identifier " field is used in the access token . Section 12.8 ( Exposure of End - user Credentials to Client Instance ) states : Such an incorrect conclusion is the consequence of a missing trust relationship . A key point is whether the end - user is trusting or not his client instance for not stealing his credentials and for displaying the correct information . The end - user authentication towards the AS is even considered as " dangerous " ! Furthermore , " end - user authentication " is implicitly interpreted as being the use of a password . GNAP should be targeted to be world - wide usable , including within Europe and the EU . As of December 31 st , 2020 , the European Union ( EU ) is requiring that consumer electronic payments over € 50 ( $ 60 ) require MFA ( Multi - factor authentication ) . This requirement is defined as part of the Payments Services Directive ( PSD2 ) that took effect in January 2018 . In 2016 , for example , the Dutch Data Protection Authority ( Dutch DPA ) specifically indicated that hospitals need to use 2FA in patient portals . It can be concluded that the Dutch DPA believes that medical data , which is sensitive personal data according to the GDPR , needs to be secured with 2FA ( Two factors authentication ) . It is thus fundamental for GNAP to be able to support both 2FA ( Two factors authentication ) and MFA ( Multi - factor authentication ) . draft - pinkas - gnap - core - protocol-00 supports the end - user authentication as a mandatory feature of the core protocol . It is able to support any kind of end - user multi - factor authentication protocol . Section 12.9 ( Mixing Up Authorization Servers ) states : 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 . This threat does not exist as soon as TLS is supported and the end - user verifies that it is connected to the appropriate AS . Section 12.10 ( Processing of Client - Presented User Information ) states : This highlights the fact that the information presented by the client about the end - user is only identifying the claimed end - user and by no way authenticating it . This is insecure . Later on the text continues with : Such a condition would not comply with the EU Payments Services Directive ( PSD2 ) that took effect in January 2018 . In addition , the core protocol does not support any feature able to make the difference between a trusted client instance and an untrusted client instance . Section 12.11 ( Client Instance Pre - registration ) states : Such a statement would change the model , since access tokens only contain information about end - users and not about client instances . Section 12.12 ( Client Instance Impersonation ) states : Since the end - user needs to trust his client , such a threat does not exist . In summary , this Security Considerations section exhibits major security weaknesses present in draft -07 . A redesign of the protocol would be necessary , but such a redesign will only be possible once the trust relationships will be reconsidered and rewritten . 
 since you relate the core of your criticisms to the trust relationships , I guess we should resolve this first . But I suspect we just have different world views and objectives , which makes you present GNAP as " insecure " or " not private by design " , while those choices are very conscious design decisions ( just not yours ) . And quite importantly , we demonstrated over and over again why your criticisms do n't hold true . 
 I do n't see any reason to support symmetric keys for Client identification etc . Removing them will remove a ( small ) point of complexity , at zero cost . Moreover , whenever people use " shared keys " nowadays these are usually passwords ( even if we say explicitly not to use passwords as keys ) and those come with a bunch of security issues . In other words , is anybody still using shared symmetric keys in a justified and secure way ? 
 I take the opposite view about their inclusion -- it does n't make sense to disallow them because there 's no complexity . Symmetric keys can be referenced just like public keys / keypairs , and if we are referring to keys by reference rather than value , then the security is comparable in many ways . The security problems with symmetric crypto tends not to be in the actual crypto but in the key management and distribution . GNAP firmly says that it does n't have any part in symmetric key management : any key you present by value has to be a public key . You can also do secure key derivation that ends up with a symmetric algorithm in the end , so you take the registered key and some other part of the request to create the derived key to be used with the actual request , and we should n't disallow those schemes . Right now we do n't even mention those , but that 's more for the security considerations as it does n't have a direct effect on the protocol itself . Another argument for allowing symmetric cryptography is to look toward post - quantum signatures . I 'm not an expert here but it 's my understanding that many symmetric algorithms are more robust against quantum attacks . I 'd like to see this raised as part of a larger security review . Maybe this is an issue to bring to CRFG or a similar crowd ? 
 I tend to worry about implementation barriers for novices like me . Unless there are major security benefits , I hope we consider if symmetric keys could be an easier way for developers to transition from OAuth or other authorization schemes into GNAP . This is the kind of stuff that I 'm having trouble understanding as we move our project from UMA 2 and OIDC to GNAP , RAR , DIDs , and VCs . 
 I 'll try to say it without sounding obnoxius ... This is exactly what I 'm worried about . Developers who have a hard time using public / private key pairs ( and I understand why it is difficult and totally agree we should document specific implementations and how these keys can be et up ) are the same developers who 'd easily end up using passwords instead of symmetric keys and NOT using sophisticated key management . I understand Justin 's position but given that he 's talking about sophisticated large scale systems , it still makes sense to leave it for a future extension . BTW , symmetric keys have been the root cause of as well , which further proves my point that they are a footgun . 
 Symmetric keys are only supported by reference , so I think it 's quite explicit their management needs to be external to gnap . And anyways , as soon as you authorize the management of keys by reference ( meaning : that does n't necessarily have to be managed within GNAP itself ) , the case will happen . Having some wording calling for caution , as is done currently in the text , seems the best we can do . 
 answered by 
 The more I 'm reading the new Security Considerations , the more I am convinced that we need to get rid of symmetric keys . They add complexity , and they basically prevent any meaningful security proofs ( because any system role can pretend to be any other role ) . Again , this is best left to an extension . BTW , even if we authorize management of keys by reference , we can still restrict the type of keys allowed by the protocol . 
 I do n't think that changes anything to security proofs of the GNAP protocol itself . Of course the assumption is that keys are well managed and that each party maintains the identity of its counterparts . So there 's always the need to make the correspondance between the keys and the roles . Or am I missing something ? 
 As far as security proofs are concerned , if you have access to a secret key you might as well be the key 's owner . So , the AS can impersonate the Client etc . Security proofs ( usually ) do not assume that people are playing by the rules . 
 Well , sharing a secret between the client and the AS seems far stretched ( but ok , if you read the spec very literally without refering to security considerations , maybe someone could come up with the idea ) . I was more thinking of a scenarii like a joint RS - AS service backed by some cloud KMS ( usually they do n't support asymmetric keys ) . But I get your point . 
 Summarizing some offline discussion , we might relax the sentence related to PQ threats and symmetric keys , and enhance the security considerations ( symmetric keys are n't intended as human memorable password or a value derived from one ) . 
 Continuing a Grant Request :  's note : What 's a reasonable amount of time to wait by default so as not to DOS the server if the field is missing ? 
 Might have to broaden the perspective and provide more general guidance on how to avoid / limit DDoS 
 I think we need general considerations as well , but this is a specific case where a naive implementation could accidentally DoS the system by polling too quickly . 
 yes . Then it 's simple , anything around the minute should work . 
 Discussed in security considerations However , still no normative requirement in the polling section so this issue is staying open until that 's in . 
 Need to add this to the interaction response section . I suggest " SHOULD NOT be less than five seconds " and " omission MUST NOT be treated as zero " . 
 I agree with the suggested changes , as discussed during the editor 's meeting . Maybe we 'll find additional topics to cover later on , but that 's a very good starting point . Also includes answers to many open issues , which we 'll be able to close
Paragraph (version A):
All requests have to be over TLS or equivalent as per BCP195.  Many
handles act as shared secrets, though they can be combined with a
requirement to provide proof of a key as well.
Paragraph (version B):
All requests in GNAP have to be made over TLS or equivalent as
outlined in BCP195 to protect the contents of the request and
response from manipulation and interception by an attacker.  This
includes all requests from a client instance to the AS, all requests
from the client instance to an RS, any requests back to a client
instance such as the push-based interaction finish method, and any
back-end communications such as from an RS to an AS as described in
I-D.draft-ietf-gnap-resource-servers.  Additionally, all requests
between a browser and other components, such as during redirect-based
interaction, need to be made over TLS or use equivalent protection.
Paragraph (version B):
Even though requests from the client instance to the AS are signed,
the signature method alone does not protect the request from
interception by an attacker.  TLS protects the response as well as
the request, preventing an attacker from intercepting requested
information as it is returned.  This is particularly important in the
core protocol for security artifacts such as nonces and for personal
information such as subject information.
Paragraph (version B):
The use of key-bound access tokens does not negate the requirement
for protecting calls to the RS with TLS.  While the keys and
signatures associated a bound access token will prevent an attacker
from using a stolen token, without TLS an attacker would be able to
watch the data being sent to the RS and returned from the RS during
legitimate use of the client instance under attack.  Additionally,
without TLS an attacker would be able to profile the calls made
between the client instance and RS, possibly gaining information
about the functioning of the API between the client software and RS
software that would be otherwise unknown to the attacker.
Paragraph (version B):
TLS or equivalent protection also needs to be used between the
browser and any other components.  This applies during initial
redirects to an AS's components during interaction, during any
interaction with the resource owner, and during any redirect back to
the client instance.  Without TLS protection on these portions of the
process, an attacker could wait for a valid request to start and then
take over the resource owner's interaction session.
Paragraph (version B):
Client instances are identified by their unique keys, and anyone with
access to a client instance's key material will be able to
impersonate that client instance to all parties.  This is true for
both calls to the AS as well as calls to an RS using a key-bound
access token.
Paragraph (version B):
Different types of client software have different methods available
for creating, managing, and registering keys.  GNAP explicitly allows
for ephemeral clients, such as SPAs, and single-user clients, such as
mobile applications, to create and present their own keys during the
initial grant request.  The client software can securely generate a
keypair on-device and present the public key, along with proof of
holding that public key, to the AS as part of the initial request.
To facilitate trust in these ephemeral keys, GNAP further allows for
an extensible set of client information to be passed with the
request.  This information can include device posture and third-party
attestations of the client software's provenance and authenticity,
depending on the needs and capabilities of the client software and
its deployment.
Paragraph (version B):
From GNAP's perspective, each distinct key is a different client
instance.  However, multiple client instances can be grouped together
by an AS policy and treated similarly to each other.  For instance,
if an AS knows of several different keys for different servers within
a cluster, the AS can decide that authorization of one of these
servers applies to all other servers within the cluster.  An AS that
chooses to do this needs to be careful with how it groups different
client keys together in its policy, since the breach of one instance
would have direct effects on the others in the cluster.
Paragraph (version B):
Additionally, if an end user controls multiple instances of a single
type of client software, such as having an application installed on
multiple devices, each of these instances is expected to have a
separate key and be issued separate access tokens.  However, if the
AS is able to group these separate instances together as described
above, it can streamline the authorization process for new instances
of the same client software.  For example, if two client instances
can present proof of a valid installation of a piece of client
software, the AS would be able to associate the approval of the first
instance of this software to all related instances.  The AS could
then choose to bypass an explicit prompt of the resource owner for
approval during authorization, since such approval has already been
given.  An AS doing such a process would need to take assurance
measures that the different instances are in fact correlated and
authentic, as well as ensuring the expected resource owner is in
control of the client instance.
Paragraph (version B):
Finally, if multiple instances of client software each have the same
key, then from GNAP's perspective, these are functionally the same
client instance as GNAP has no reasonable way to differentiate
between them.  This situation could happen if multiple instances
within a cluster can securely share secret information among
themselves.  Even though there are multiple copies of the software,
the shared key makes these copies all present as a single instance.
It is considered bad practice to share keys between copies of
software unless they are very tightly integrated with each other and
can be closely managed.  It is particularly bad practice to allow an
end-user to copy keys between client instances and to willingly use
the same key in multiple instances.
Paragraph (version B):
The AS performs critical functions in GNAP, including authenticating
client software, managing interactions with end-users to gather
consent and provide notice, and issuing access tokens for client
instances to present to resource servers.  As such, protecting the AS
is central to any GNAP deployment.
Paragraph (version B):
If an attacker is able to gain control over an AS, they would be able
to create fraudulent tokens and manipulate registration information
to allow for malicious clients.  These tokens and clients would be
trusted by other components in the ecosystem under the protection of
the AS.
Paragraph (version B):
If the AS is using signed access tokens, an attacker in control of
the AS's signing keys would be able to manufacture fraudulent tokens
for use at RS's under the protection of the AS.
Paragraph (version B):
If an attacker is able to impersonate an AS, they would be able to
trick legitimate client instances into making signed requests for
information which could potentially be proxied to a real AS.  To
combat this, all communications to the AS need to be made over TLS or
its equivalent, and the software making the connection has to
validate the certificate chain of the host it is connecting to.
Paragraph (version B):
Consequently, protecting, monitoring, and auditing the AS is
paramount to preserving the security of a GNAP-protected ecosystem.
Paragraph (version B):
The cryptographic methods used by GNAP for key-proofing can support
both asymmetric and symmetric cryptography, and can be extended to
use a wide variety of mechanisms.  While symmetric cryptographic
systems have some benefits in speed and simplicity, they have a
distinct drawback that both parties need access to the same key in
order to do both signing and verification of the message.  This means
that when the client instance calls the AS to request a token, the AS
needs to know the exact value of the client instance's key (or be
able to derive it) in order to validate the key proof signature.
With asymmetric keys, the client needs only to send its public key to
the AS to allow for verification that the client holds the associated
private key, regardless of whether that key was pre-registered or not
with the AS.
Paragraph (version B):
When used to bind to an access token, a key value must be known by
the RS in order to validate the proof signature on the request.
Common methods for communicating these proofing keys include putting
information in a structured access token and allowing the RS to look
up the associated key material against the value of the access token.
With symmetric cryptography, both of these methods would expose the
signing key to the RS, and in the case of an structured access token,
potentially to any party that can see the access token itself unless
the token's payload has been encrypted.  Any of these parties would
then be able to make calls using the access token by creating a valid
signature.  With asymmetric cryptography, the RS only needs to know
the public key associated with the token in order to validate, and
therefore cannot create any new calls.
Paragraph (version B):
Symmetric keys also have the expected advantage of providing better
protection against quantum threats in the future.  Also, these types
of keys (and their secure derivations) are widely supported among
many cloud-based key management systems.
Paragraph (version B):
While both signing approaches are allowed, GNAP treats these two
classes of keys somewhat differently.  Only the public portion of
asymmetric keys are allowed to be sent by value in requests to the AS
when establishing a connection.  Since sending a symmetric key (or
the private portion of an asymmetric key) would expose the signing
material to any parties on the request path, including any attackers,
sending these kinds of keys is prohibited.  Symmetric keys can still
be used by client instances, but only a reference to the key and not
its value can be sent.  This allows the AS to use pre-registered
symmetric keys as well as key derivation schemes to take advantage of
symmetric cryptography but without requiring key distribution at
runtime, which would expose the keys in transit.
Paragraph (version B):
Both the AS and client software can use systems such as hardware
security modules to strengthen their key security storage and
generation for both asymmetric and symmetric keys.
Paragraph (version B):
The content of access tokens need to be such that only the generating
AS would be able to create them, and the contents cannot be
manipulated by an attacker to gain different or additional access
rights.
Paragraph (version B):
One method for accomplishing this is to use a cryptographically
random value for the access token, generated by the AS using a secure
randomization function with sufficiently high entropy.  The odds of
an attacker guessing the output of the randomization function to
collide with a valid access token are exceedingly small, and even
then the attacker would not have any control over what the access
token would represent since that information would be held close by
the AS.
Paragraph (version B):
Another method for accomplishing this is to use a structured token
that is cryptographically signed.  In this case, the payload of the
access token declares to the RS what the token is good for, but the
signature applied by the AS during token generation covers this
payload.  Only the AS can create such a signature and therefore only
the AS can create such a signed token.  The odds of an attacker being
able to guess a signature value with a useful payload are exceedingly
small.  This technique only works if all targeted RS's check the
signature of the access token.  Any RS that does not validate the
signature of all presented tokens would be susceptible to injection
of a modified or falsified token.  Furthermore, an AS has to
carefully protect the keys used to sign access tokens, since anyone
with access to these signing keys would be able to create seemingly-
valid access tokens using them.
Paragraph (version B):
Bearer access tokens can be used by any party that has access to the
token itself, without any additional information.  As a natural
consequence, any RS that a bearer token is presented to has the
technical capability of presenting that bearer token to another RS,
as long as the token is valid.  It also means that any party that is
able capture of the token value in storage or in transit is able to
use the access token.  While bearer tokens are inherently simpler,
this simplicity has been misapplied and abused in making needlessly
insecure systems.
Paragraph (version B):
In GNAP, key-bound access tokens are the default due to their higher
security properties.  While bearer tokens can be used in GNAP, their
use should be limited onto to cases where the simplicity benefits
outweigh the significant security downsides.
Paragraph (version B):
Key-bound access tokens, as the name suggests, are bound to a
specific key and must be presented along with proof of that key
during use.  The key itself is not presented at the same time as the
token, so even if a token value is captured, it cannot be used to
make a new request.  This is particularly true for an RS, which will
see the token value but will not see the keys used to make the
request.
Paragraph (version B):
Key-bound access tokens provide this additional layer of protection
only when the RS checks the signature of the message presented with
the token.  Acceptance of an invalid presentation signature, or
failure to check the signature entirely, would allow an attacker to
make calls with a captured access token without having access to the
related signing key material.
Paragraph (version B):
In addition to validating the signature of the presentation message
itself, the RS also needs to ensure that the signing key used is
appropriate for the presented token.  If an RS does not ensure that
the right keys were used to sign a message with a specific token, an
attacker would be able to capture an access token and sign the
request with their own keys, thereby negating the benefits of using
key-bound access tokens.
Paragraph (version B):
The RS also needs to ensure that a sufficient portions of the message
are covered by the signature.  Any items outside the signature could
still affect the API's processing decisions, but these items would
not be strongly bound to the token presentation.  As such, an
attacker could capture a valid request, then manipulate portions of
the request outside of the signature envelope in order to cause
unwanted actions at the protected API.
Paragraph (version B):
Some key-bound tokens are susceptible to replay attacks, depending on
the details of the signing method used.  If a signature method covers
only portions of a given request, that same signature proof can be
used by an attacker to make a similar call, potentially even varying
elements that are outside of the protection of the signature.  Key
proofing mechanisms used with access tokens therefore need to use
replay protection mechanisms covered under the signature such as a
per-message nonce, a reasonably short time validity window, or other
uniqueness constraints.  The details of using these will vary
depending on the key proofing mechanism in use, but for example, HTTP
Message Signatures has both a "created" and "nonce" signature
parameter as well as the ability to cover significant portions of the
HTTP message.
Paragraph (version B):
As a delegation protocol, one of the main goals of GNAP is to prevent
the client software from being exposed to any credentials or
information about the end-user or resource owner as a requirement of
the delegation process.  By using the variety of interaction
mechanisms, the resource owner can interact with the AS without ever
authenticating to the client software, and without the client
software having to impersonate the resource owner through replay of
their credentials.
Paragraph (version B):
Consequently, no interaction methods defined in the GNAP core require
the end-user to enter their credentials, but it is technologically
possible for an extension to be defined to carry such values.  Such
an extension would be dangerous as it would allow rogue client
software to directly collect, store, and replay the end-user's
credentials outside of any legitimate use within a GNAP request.
Paragraph (version B):
The concerns of such an extension could be mitigated through use of a
challenge and response unlocked by the end user's credentials.  For
example, the AS presents a challenge as part of an interaction start
method, and the client instance signs that challenge using a key
derived from a password presented by the end user.  It would be
possible for the client software to collect this password in a secure
software enclave without exposing the password to the rest of the
client software or putting it across the wire to the AS.  The AS can
validate this challenge response against a known password for the
identified end user.  While an approach such as this does not remove
all of the concerns surrounding such a password-based scheme, it is
at least possible to implement in a more secure fashion than simply
collecting and replaying the password.  Even so, such schemes should
only ever be used by trusted clients due to the ease of abusing them.
Paragraph (version B):
If a client instance is able to work with multiple AS's
simultaneously, it is more possible for an attacker to add a
compromised AS to the client instance's configuration and cause the
client software to start a request at the compromised AS.  This AS
could then proxy the client's request to a valid AS in order to
attempt to get the resource owner to approve access for the
legitimate client instance.
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 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):
GNAP allows the client instance to present assertions and identifiers
of the current user to the AS as part of the initial request.  This
information should only ever be taken by the AS as a hint, since the
AS has no way to tell if the represented person is present at the
client software, without using an interaction mechanism.  This
information does not guarantee the given user is there, but it does
constitute a statement by the client software that the AS can take
into account.
Paragraph (version B):
For example, if a specific user is claimed to be present prior to
interaction, but a different user is shown to be present during
interaction, the AS can either determine this to be an error or
signal to the client instance through returned subject information
that the current user has changed from what the client instance
thought.  This user information can also be used by the AS to
streamline the interaction process when the user is present.  For
example, instead of having the user type in their account identifier
during interaction at a redirected URL, the AS can immediately
challenge the user for their account credentials.  Alternatively, if
an existing session is detected, the AS can determine that it matches
the identifier provided by the client and subsequently skip an
explicit authentication event by the resource owner.
Paragraph (version B):
In cases where the AS trusts the client software more completely, due
to policy or by previous approval of a given client instance, the AS
can take this user information as a statement that the user is
present and could issue access tokens and release subject information
without interaction.  The AS should only take such action in very
limited circumstances, as a client instance could assert whatever it
likes for the user's identifiers in its request.
Paragraph (version B):
When a client instance presents an assertion to the AS, the AS needs
to evaluate that assertion.  Since the AS is unlikely to be the
intended audience of an assertion held by the client software, the AS
will need to evaluate the assertion in a different context.  Even in
this case, the AS can still evaluate that the assertion was generated
by a trusted party, was appropriately signed, and is within any time
validity windows stated by the assertion.  If the client instance's
audience identifier is known to the AS and can be associated with the
client instance's presented key, the AS can also evaluate that the
appropriate client instance is presenting the claimed assertion.  All
of this will prevent an attacker from presenting a manufactured
assertion, or one captured from an untrusted system.  However,
without validating the audience of the assertion, a captured
assertion could be presented by the client instance to impersonate a
given end user.  In such cases, the assertion offers little more
protection than a simple identifier would.
Paragraph (version B):
A special case exists where the AS is the generator of the assertion
being presented by the client instance.  In these cases, the AS can
validate that it did issue the assertion and it is associated with
the client instance presenting the assertion.
Paragraph (version B):
Each client instance is identified by its own unique key, and for
some kinds of client software such as a web server or backend system,
this identification can be facilitated by registering a single key
for a piece of client software ahead of time.  This registration can
be associated with a set of display attributes to be used during the
authorization process, identifying the client software to the user.
In these cases, it can be assumed that only one instance of client
software will exist, likely to serve many different users.
Paragraph (version B):
A client's registration record needs to include its identifying key.
Furthermore, it is the case that any clients using symmetric
cryptography for key proofing mechanisms need to have their keys pre-
registered.  The registration should also include any information
that would aid in the authorization process, such as a display name
and logo.  The registration record can also limit a given client to
ask for certain kinds of information and access, or be limited to
specific interaction mechanisms at runtime.
Paragraph (version B):
It also is sensible to pre-register client instances when the
software is acting on its own behalf, without the need for a runtime
approval by a resource owner or any interaction with an end-user.  In
these cases, an AS needs to rest on the trust decisions that have
been determined prior to runtime in determining what rights and
tokens to grant to a given client instance.
Paragraph (version B):
However, it does not make sense to pre-register many types of
clients.  Single-page applications (SPAs) and mobile/desktop
applications in particular present problems with pre-registration.
For SPAs, the instances are ephemeral in nature and long-term
registration of a single instance leads to significant storage and
management overhead at the AS.  For mobile applications, each
installation of the client software is a separate instance, and
sharing a key among all instances would be detrimental to security as
the compromise of any single installation would compromise all copies
for all users.
Paragraph (version B):
An AS can treat these classes of client software differently from
each other, perhaps by allowing access to certain high-value APIs
only to pre-registered known clients, or by requiring an active end-
user delegation of authority to any client software not pre-
registered.
Paragraph (version B):
An AS can also provide warnings and caveats to resource owners during
the authorization process, allowing the user to make an informed
decision regarding the software they are authorizing.  For example,
if the AS has done vetting of the client software and this specific
instance, it can present a different authorization screen compared to
a client instance that is presenting all of its information at
runtime.
Paragraph (version B):
If client instances are allowed to set their own user-facing display
information, such as a display name and website URL, a malicious
client instance could impersonate legitimate client software for the
purposes of tricking users into authorizing the malicious client.
Paragraph (version B):
Requiring clients to pre-register does not fully mitigate this
problem since many pre-registration systems have self-service portals
for management of client registration, allowing authenticated
developers to enter self-asserted information into the management
portal.
Paragraph (version B):
An AS can mitigate this by actively filtering all self-asserted
values presented by client software, both dynamically as part of GNAP
and through a registration portal, to limit the kinds of
impersonation that would be done.
Paragraph (version B):
An AS can also warn the resource owner about the provenance of the
information it is displaying, allowing the resource owner to make a
more informed delegation decision.  For example, an AS can visually
differentiate between a client instance that can be traced back to a
specific developer's registration and an instance that has self-
asserted its own key and display information.
Paragraph (version B):
Most information passed through the web-browser is susceptible to
interception and possible manipulation by elements within the browser
such as scripts loaded within pages.  Information in the URL is
exposed through browser and server logs, and can also leak to other
parties through HTTP "Referrer" headers.
Paragraph (version B):
GNAP's design limits the information passed directly through the
browser, allowing for opaque URLs in most circumstances.  For the
redirect-based interaction finish mechanism, named query parameters
are used to carry unguessable opaque values.  For these, GNAP
requires creation and validation of a cryptographic hash to protect
the query parameters added to the URL and associate them with an
ongoing grant process.  The client instance has to properly validate
this hash to prevent an attacker from injecting an interaction
reference intended for a different AS or client instance.
Paragraph (version B):
Several interaction start mechanisms use URLs created by the AS and
passed to the client instance.  While these URLs are opaque to the
client instance, it's possible for the AS to include parameters,
paths, and other pieces of information that could leak security data
or be manipulated by a party in the middle of the transaction.
Paragraph (version B):
The callback URL used in interaction finish mechanisms is defined by
the client instance.  This URL is opaque to the AS, but can contain
information relevant to the client instance's operations.  In
particular, the client instance can include state information to
allow the callback request to be associated with an ongoing grant
request.
Paragraph (version B):
Since this URL is exposed to the end-user's browser, it is
susceptible to both logging and manipulation in transit before the
request is made to the client software.  As such, a client instance
should never put security-critical or private information into the
callback URL in a cleartext form.  For example, if the client
software includes a post-redirect target URL in its callback URL to
the AS, this target URL could be manipulated by an attacker, creating
an open redirector at the client.  Instead, a client instance can use
an unguessable identifier into the URL that can then be used by the
client software to look up the details of the pending request.  Since
this approach requires some form of statefulness by the client
software during the redirection process, clients that are not capable
of holding state through a redirect should not use redirect-based
interaction mechanisms.
Paragraph (version B):
GNAP does not specify how a client instance's keys could be made
known to the AS ahead of time.  Public Key Infrastructure (PKI) can
be used to manage the keys used by client instances when calling the
AS, allowing the AS to trust a root key from a trusted authority.
This method is particularly relevant to the MTLS signature method,
where the client instance presents its certificate to the AS as part
of the TLS connection.  An AS using PKI to validate the MTLS
connection would need to ensure that the presented certificate was
issued by a trusted certificate authority before allowing the
connection to continue.  PKI-based certificates would allow a key to
be revoked and rotated through management at the certificate
authority without requiring additional registration or management at
the AS.  PKI has historically been difficult to deploy, especially at
scale, but it remains an appropriate solution for systems where the
required overhead is not an impediment.
Paragraph (version B):
MTLS need not use a PKI backing, as self-signed certificates and
certificates from untrusted authorities can still be presented as
part of a TLS connection.  In this case, the AS or RS would validate
the connection but accept whatever certificate was presented by the
client software.  This specific certificate would then be bound to
all future connections from that client software by being bound to
the resulting access tokens.
Paragraph (version B):
Responses from the AS contain information vital to both the security
and privacy operations of GNAP.  This information includes nonces
used in cryptographic calculations, subject identifiers, assertions,
public keys, and information about what client software is requesting
and was granted.
Paragraph (version B):
In addition, if bearer tokens are used or keys are issued alongside a
bound access token, the response from the AS contains all information
necessary for use of the contained access token.  Any party that is
capable of viewing such a response, such as an intermediary proxy,
would be able to exfiltrate and use this token.  If the access token
is instead bound to the client instance's presented key,
intermediaries no longer have sufficient information to use the
token.  They can still, however, gain information about the end user
as well as the actions of the client software.
Paragraph (version B):
The keys for client instances could be distributed as part of the
deployment process of instances of the client software.  For example,
an application installation framework could generate a keypair for
each copy of client software, then both install it into the client
software upon installation and registering that instance with the AS.
Paragraph (version B):
Additionally, it's possible for the AS to generate keys to be used
with access tokens that are separate from the keys used by the client
instance to request tokens.  In this method, the AS would generate
the asymmetric keypair or symmetric key and return the entire key,
including all private signing information, to the client instance
alongside the access token itself.  This approach would make
interception of the return from the token endpoint equivalent to that
of a bearer token, since all information required to use the access
token would be present in the request.
Paragraph (version B):
During the interaction process, the client instance usually hands
control of the user experience over to another component, beit the
system browser, another application, or some action the resource
owner is instructed to take on another device.  By using an
interaction finish method, the client instance can be securely
notified by the AS when the interaction is completed and the next
phase of the protocol should occur.  This process includes
information that the client instance can use to validate the finish
call from the AS and prevent some injection, session hijacking, and
phishing attacks.
Paragraph (version B):
Some types of client deployment are unable to receive an interaction
finish message.  Without an interaction finish method to notify it,
the client instance will need to poll the grant continuation API
while waiting for the resource owner to approve or deny the request.
An attacker could take advantage of this situation by capturing the
interaction start parameters and phishing a legitimate user into
authorizing the attacker's waiting client instance, which would in
turn have no way of associating the completed interaction with the
start of the request.
Paragraph (version B):
However, it is important to note that this pattern is practically
indistinguishable from some legitimate use cases.  For example, a
smart device emits a code for the resource owner to enter on a
separate device.  The smart device has to poll because the expected
behavior is that the interaction will take place on the separate
device, without a way to return information to the original device's
context.
Paragraph (version B):
As such, developers need to weigh the risks of forgoing an
interaction finish method against the deployment capabilities of the
client software and its environment.  Due to the increased security,
an interaction finish method should be employed whenever possible.
Paragraph (version B):
When starting an interactive grant request, a client application has
a number of protocol elements that it needs to manage, including
nonces, references, keys, access tokens, and other elements.  During
the interaction process, the client instance usually hands control of
the user experience over to another component, beit the system
browser, another application, or some action the resource owner is
instructed to take on another device.  In order for the client
instance to make its continuation call, it will need to recall all of
these protocol elements.  Usually this means the client instance will
need to store these protocol elements in some retrievable fashion.
Paragraph (version B):
If the security protocol elements are stored on the end-user's
device, such as in browser storage or in local application data
stores, capture and exfiltration of this information could allow an
attacker to continue a pending transaction instead of the client
instance.  Client software can make use of secure storage mechanisms,
including hardware-based key and data storage, to prevent such
exfiltration.
Paragraph (version B):
Note that in GNAP, the client instance has to choose its interaction
finish URL prior to making the first call to the AS.  As such, the
interaction finish URL will often have a unique identifier for the
ongoing request, allowing the client instance to access the correct
portion of its storage.  Since this URL is passed to other parties
and often used through a browser, this URL should not contain any
security-sensitive information that would be valuable to an attacker,
such as any token identifier, nonce, or user information.  Instead, a
cryptographically random value is suggested.
Paragraph (version B):
When a client instance starts off an interactive process, it will
eventually need to continue the grant request in a subsequent message
to the AS.  It's possible for a naive client implementation to
continuously send continuation requests to the AS while waiting for
approval, especially if no interaction finish method is used.  Such
constant requests could overwhelm the AS's ability to respond to both
these and other requests.
Paragraph (version B):
To mitigate this for well-behaved client software, the continuation
response contains a "wait" parameter that is intended to tell the
client instance how long it should wait until making its next
request.  This value can be used to back off client software that is
checking too quickly by returning increasing wait times for a single
client instance.
Paragraph (version B):
If client software ignores the "wait" value and makes its
continuation calls too quickly, or if the client software assumes the
absence of the "wait" values means it should poll immediately, the AS
can choose to return errors to the offending client instance,
including possibly canceling the ongoing grant request.  With well-
meaning client software these errors can indicate a need to change
the client software's programmed behavior.
Paragraph (version B):
Several parts of the GNAP process make use of unguessable randomized
values, such as nonces, tokens, and randomized URLs.  Since these
values are intended to be unique, a sufficiently powerful attacker
could make a large number of requests to trigger generation of
randomized values in an attempt to exhaust the random number
generation space.  While this attack is particularly applicable to
the AS, client software could likewise be targeted by an attacker
triggering new grant requests against an AS.
Paragraph (version B):
To mitigate this, software can ensure that its random values are
chosen from a significantly large pool that exhaustion of that pool
is prohibitive for an attacker.  Additionally, the random values can
be time-boxed in such a way as their validity windows are reasonably
short.  Since many of the random values used within GNAP are used
within limited portions of the protocol, it is reasonable for a
particular random value to be valid for only a small amount of time.
For example, the nonces used for interaction finish hash calculation
need only to be valid while the client instance is waiting for the
finish callback and can be functionally expired when the interaction
has completed.  Similarly, artifacts like access tokens and the
interaction reference can be limited to have lifetimes tied to their
functional utility.  Finally, each different category of artifact
(nonce, token, reference, identifier, etc.) can be generated from a
separate random pool of values instead of a single global value
space.