]> Fynbos

omer@fynbos.dev

Fynbos

adrian@fynbos.dev

Security Grant Negotiation and Authorization Protocol gnap secure payment confirmation extension GNAP Secure Payment Confirmation (SPC) Extension is a Grant Negotiation and Authorization Protocol () extension that defines a method for authentication of the end user during a payment transaction. This extension helps leverage hardware and software authenticators such as biometric scanners while authenticating the end user. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction GNAP Secure Payment Confirmation Extension is an extension developed on top of the Grant Negotiation and Agreement Protocol . It defines a method for authentication of the end user during a payment transaction using Secure Payment Confirmation (). This extension helps leverage authenticators such as fingerprint scanners, facial recognition systems, etc. while authenticating during a GNAP interaction. Secure Payment Confirmation () is a Web Platform API implemented in Web browsers which allows a website to invoke to both authenticate the end user and confirm the details of the payment during a payment transaction. A method for detecting this capability in the client software is provided in .

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Secure Payment Confirmation Interaction When using SPC in , the end user is prompted to authenticate during the interaction phase of the protocol, when the grant is in the pending state. The overall flow of the protocol is shown here: | | | | | | | |<-(2)-- Interaction Needed -------+ | | | | | | | .----. | | | | | End | | | | | | User | | | | |<==(3)===>|------+ | | | | SPC | RO | | | | | | | | | | | `----` | | | | | | | +--(4)--- Continue Request ------->| | | | | | | | ,---+ | | | (5) | | | | | SPC `-->| | | | | | | |<-(6)----- Grant Access ----------+ | | | | | +--------+ +--------+ ]]>

1. The client instance makes a grant request to the AS, indicating that it can support SPC as an interaction start method. The client instance includes an identifier for the intended end user in the request. The client instance does not include an interaction finish method, since the interaction will happen outside of the AS and the client software will not need to be signaled by the AS to continue the grant request. ()
2. The AS creates a new grant request in the pending state and responds to the grant request with a challenge to be signed by a set of candidate credentials that are known to have been provisioned for the end user identified by the client. ()
3. The client instance engages the SPC protocol to sign the challenge. ()
4. The client instance continues the grant request, including the results of the SPC challenge response from (3) in the grant continuation request. ()
5. The AS validates the signature, completing the SPC process and placing the grant in the approved state. ()
6. The AS returns an access token in a standard GNAP grant response.

The end user provides confirmation using their credential, which the client instance presents back to the AS in a continuation response. The AS then verifies this confirmation in order to process the grant request and grant access to the client instance.

Requesting Credentials A client instance that is able to use SPC for user interaction can request a grant from an authorization server with SPC as an interaction start method. The SPC interaction start method is defined as a string type with value spc. If the spc interaction start method is accepted, the corresponding response is returned as discussed in . When requesting the SPC interaction method the client MUST identify the end user using the user property in the grant request object to allow the AS to find the registered credentials for the user. If the user property is not included in the request, the AS MUST NOT enable this interaction mode for this request. A non-normative example of a grant request that uses SPC as its interaction start method is below.

Providing a Credential Challenge In response to a client instance's grant request, if the AS determines that it has one or more registered SPC credentials of the end user, the AS responds with an spc field in the interact object. The AS determines the end user using the user property from the grant request. The user property should have the required information such as email addresses, usernames, etc. for determining the end user, see . If the user property is not included in the request, it is not possible for the AS to determine the credentials for the end user.

spc (object):

An object containing parameters required for performing secure payment confirmation on the end user's device. REQUIRED if the AS is allowing SPC interaction for this request.

This object contains the following properties:

credential_ids (array of strings):

A list of identifiers of credentials that could potentially be used to respond to this interaction mode. Each credential identifier MUST be base64url encoded with no padding. REQUIRED.

challenge (string):

A random challenge that the relying party (the AS) generates on the server side to prevent replay attacks. The challenge MUST be base64url encoded with no padding. REQUIRED.

payment_instrument (object):

An object describing the payment instrument which will be used to execute the payment. REQUIRED.

The payment instrument object has the following properties:

display_name (string):

A display name to use in the SPC user interface. REQUIRED.

icon (string):

The URL of an icon to display in the SCP user interface. The URL may either identify an image on an internet-accessible server (e.g., https://bank.com/card.png), or directly encode the icon data via a Data URL . Between the two types of URLs, Data URLs offer several benefits to the Relying Party. They can improve reliability (e.g., in the case that the icon hosting server may be unavailable). They can also enhance validation because the Relying Party has cryptographic evidence of what the browser displayed to the user: the icon URL is signed as part of the authentication ceremony.REQUIRED.

icon_must_be_shown (boolean):

Indicates whether the specified icon must be successfully fetched and shown for the request to succeed. Defaults to TRUE if not provided. OPTIONAL.

A non-normative example of a grant request continue response that uses SPC as its interaction method is below.

Authenticating User When the client instance receives an spc interaction response from the AS, the client instance SHOULD initiate the authentication ceremony following Section 4 of . When performing this ceremony, the client instance decodes the challenge and each credential from credential_ids using base64url and converts them to a buffer for input into the browser API. The challenge value is used as the challenge input parameter and the credential_ids value is used as the credentialIds input parameter in the SecurePaymentConfirmationRequest dictionary passed to the browser API. The instrument input parameter is constructed by copying the display_name, icon, and icon_must_be_shown properties from the payment_instrument object into a new PaymentCredentialInstrument. When the client initates the authentication ceremony, the browser API checks if the device has at least one of the credential ids and continues to the authentication ceremony only if the device has one of the credentials. In this phase, the credential that the end user chooses as the authentication method is going to be used for signing the cryptogram. When the authentication ceremony is complete, the client instance will have access to the response data from the ceremony to be returned to the AS.

Completing Interaction Once the authentication ceremony is complete, the client instance continues the grant request by calling the grant continuation URI. The client instance includes a body in the grant continuation request including a field named public_key_cred:

public_key_cred (object):

The results of the SPC authentication ceremony in response to the AS, to be used by the AS to authorize the request.

The public_key_cred object contains the following fields as defined by the Web Authentication Assertion object :

client_data_json (string):

clientDataJSON property from Web Authentication Assertion object. This MUST be encoded using base64url. REQUIRED.

authenticator_data (string):

authenticatorData property from Web Authentication Assertion object. This MUST be encoded using base64url. REQUIRED.

signature (string):

signature property from Web Authentication Assertion object. This MUST be encoded using base64url. REQUIRED.

user_handle (string):

userHandle property from Web Authentication Assertion object. This MUST be encoded using base64url. REQUIRED.

A non-normative example of an interaction completion response body is below. Since the signature is in response to a challenge provided by the AS, the client instance MUST NOT send this parameter to a new grant request. The grant request MUST be in the pending state when this parameter is sent to the AS.

Verifying Authentication Assertion When the AS receives the public_key_cred value in a grant continuation request, the AS MUST perform the steps specified in Section 8.1 of . Each property of a public key credential returned following successful invocation of the SPC handler client_data_json, authenticator_data, signature and user_handle MUST be present as expected for starting verification. The AS MUST decode each property of the public key credential in the response using base64url before performing the verification. The grant request MUST be in the pending state when this parameter is received in order for it to be processed. If the grant request is in any other state, the AS MUST return an error. The AS MUST ensure that the transaction details encoded in the public key credential match the details of the transaction that the client instance is requesting a grant to perform. If the AS determines that the authorization is sufficient, the AS grants access tokens and releases subject information to the client instance.

Security Considerations TODO Security

IANA Considerations IANA is requested to register the following values into the named registries.

Interaction Start Modes IANA is requested to register the following modes into the Interaction Start Modes registry defined by .

Mode	Type	Specification document(s)
spc	string	of RFC nnnn

Interaction Mode Responses IANA is requested to register the following methods into the Interaction Mode Responses registry defined by .

Name	Specification document(s)
spc	of RFC nnnn

Grant Request Parameters IANA is requested to register the following parameters into the Grant Request Parameters registry defined by .

Name	Type	Specification document(s)
public_key_cred	object	of RFC nnnn

Acknowledgments TODO acknowledge.

References Normative References Bespoke Engineering acert.io GNAP defines a mechanism for delegating authorization to a piece of software, and conveying the results and artifacts of that delegation to the software. This delegation can include access to a set of APIs as well as subject information passed directly to the software. A new URL scheme, "data", is defined. It allows inclusion of small data items as "immediate" data, as if it had been included externally. [STANDARDS-TRACK] In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References

Checking Feature Support This extension only works if the end user's user agent supports the Payment Request API and SPC. To detect whether SPC is supported on the browser, the client instance can send a fake call to canMakePayment(). The following code provides a feature detect function for the Payment Request API and SPC that could be executed on a merchant's website. { if (!'PaymentRequest' in window) { return [false, 'Payment Request API is not supported']; } try { // The data below is the minimum required to create the request and // check if a payment can be made. const supportedInstruments = [ { supportedMethods: "secure-payment-confirmation", data: { // RP's hostname as its ID rpId: 'rp.example', // A dummy credential ID credentialIds: [new Uint8Array(1)], // A dummy challenge challenge: new Uint8Array(1), instrument: { // Non-empty display name string displayName: ' ', // Transparent-black pixel. icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==', }, // A dummy merchant origin payeeOrigin: 'https://non-existent.example', } } ]; const details = { // Dummy shopping details total: {label: 'Total', amount: {currency: 'USD', value: '0'}}, }; const request = new PaymentRequest(supportedInstruments, details); const canMakePayment = await request.canMakePayment(); return [canMakePayment, canMakePayment ? '' : 'SPC is not available']; } catch (error) { console.error(error); return [false, error.message]; } }; ]]>