Skip to content

Latest commit

 

History

History
1315 lines (1219 loc) · 38.7 KB

rqes-walledriven.md

File metadata and controls

1315 lines (1219 loc) · 38.7 KB
Raw

Wallet Centric rQES Specification

This document focuses mainly on the interaction between the EUDIW (and its external component, Signature Creation Application) and the QTSP that manages the Server Signing Application.

Table of contents

1. Wallet Centric rQES Architecture

The following figure presents the current conceptual architecture and the components that interact in this environment.

Figure 1 - Wallet centric rQES conceptual architecture

2. Wallet Components and Corresponding Functionality

  • Signature Activation Component (SAC)

    The Signature Activation Component (SAC) receives and responds to (extended[1]) “OID4VP” protocol requests from the Signature Activation Module (SAM). The SAC will prompt the user to share their PID data (enabling the SAM to authenticate the user) and will also request the user’s consent for the SAM to access their private key to sign a hash. The (extended) “OID4VP” request will include details about what the SAM is requesting to sign, and this information will be displayed to the user before they consent to allow the SAM to access their private key for signing.

  • Signature Creation Component (SCC)

    The Signature Creation Component (SCC) acts as the ‘controller’ for the entire process. It receives the request to sign a document, along with the document itself, from the Relying Party (RP) Application, calls the Presentation component to display the document to the user, and allows the user to decide whether to sign the document and select the appropriate certificate. The SCC also interacts with the external Signature Creation Application (SCA) and the QTSP (SSA), listing the available QTSPs for the user to choose from.

  • Presentation Component (PC)

    The Presentation Component (PC) displays the document and associated information received from the RP Application. After showing the document, the wallet allows the user to decide whether to sign it or not.”

3. Wallet centric Signature flow

The following wallet centric signature flow is analyzed in this document:

  1. Service (QTSP) Authentication

  2. Credential Listing

  3. Document Signing

3.1 Service (QTSP) Authentication

Before initiating the credential listing or signing operation, the Wallet must authenticate itself to the QTSP. In this signature flow, it is assumed that the wallet has been previously registered with the QTSP.

To initiate user authentication with the QTSP (Service Authentication process), the SIC (Signature Activation Component) will send a request to the QTSP Authorization Server. The authentication is carried out using the OAuth2 protocol, complemented by the OpenId4VP protocol:

  1. The user selects the QTSP they want to use to sign the document. We assume that at least one QTSP (the one offering free signatures) will be configured in the Wallet.

  2. The EUDIW sends an HTTP request to the /oauth2/authorize endpoint of the Authorization Server (QTSP) to initiate the user authentication process.

  3. The QTSP makes a request to the OpenId4VP Verifier to start the Authorization Request.

  4. The QTSP generates a deep link to the Wallet .

  5. The EUDIW requests the user to share the necessary PID information.

  6. After sharing, the wallet will be redirected to the redirect_url (provided in step 4) in the QTSP.

  7. The QTSP interacts with the Verifier to obtain the VP Token.

  8. After validating the VP Token, the QTSP marks the current Session ID Cookie as authenticated, and redirects the client back to the /oauth2/authorize endpoint. If all parameters are valid, a code is generated, and the client app is redirected to the "redirect_url" specified in the request.

  9. With that code value, an access token can be requested at the /oauth2/token endpoint. This access token will grant access to the QTSP Resource Server.

3.1.1 OpenId4VP Interactions

3.1.1. Example of the Authorization Request (Authorization Server to OID4VP Verifier)

3.1.1. Authorization Request returns:

3.1.1. Additional Interactions

With the values from the request and from the response, we will generate two links:

1. eudi-openid4vp://dev.verifier-backend.eudiw.dev?client_id={client_id}&request_uri={request_uri}

This deep link is generated using the client_id and the request_uri from the Authorization Request’s returned value. It should then be sent to the Wallet to redirect the user to a page where they can select which data to share.

2. https://dev.verifier-backend.eudiw.dev/ui/presentations/{presentation\_id}?nonce={nonce}

Using this link, the QTSP can obtain the VP Token from the Verifier once the user has authorized the sharing of the requested data.

3.1.2 oauth2/authorize

Name Presence Type Description
response_type REQUIRED String The value SHALL be “code”.
client_id REQUIRED String The client identifier as defined in oauth2 [RFC 6749].
redirect_uri

REQUIRED

Conditional

 String

The URL where the user will be redirected after the authorization process has completed.

If omitted, the remote service will use the default redirect URI pre-registered by the signature application.
scope OPTIONAL String For Service Authentication flow SHALL be “service”: it SHALL be used to obtain an authorization code suitable for service authorization.
code_challenge REQUIRED String Cryptographic nonce binding the transaction to a certain user agent, used to detect code replay and CSRF attacks.
code_challenge_method OPTIONAL String Code verifier transformation method. Used to obtain the “code_challenge” from the “code_verifier”. Defaults to “plain”, but the recommended value is “S256”.
state OPTIONAL String A value used by the client to maintain state between the request and callback, as defined in oauth2 [RFC 6749].
request_uri

REQUIRED

Conditional

 String URI pointing to a pushed authorization request previously uploaded by the client. (Note: this mechanism is not currently supported)
lang OPTIONAL String Request a preferred language according to RFC 5646. If specified, the authorization server SHOULD render the authorization web page in this language, if supported.
description OPTIONAL String A free form description of the authorization transaction in the lang language.
account_token OPTIONAL String An account_token as defined in [CSC-API] section 8.4.1. (Note: this parameter is not currently supported)
clientData OPTIONAL String Arbitrary data from the signature application.

3.1.2.Response (output of the /oauth2/authorize)

Name Presence Type Description
code REQUIRED String The authorization code generated by the authorization server. It SHALL be bound to the client identifier and the redirection URI.
state

REQUIRED

Conditional

 String Contains the arbitrary data from the signature application that was specified in the state attribute of the input request.
error

REQUIRED

Conditional

 String See [CSC-API] section 8.4.2.
error_description OPTIONAL String See [CSC-API] section 8.4.2.
error_uri OPTIONAL String See [CSC-API] section 8.4.2.

3.1.3 oauth2/token

Requirement: In the Authentication header, there should be the value of the Basic Auth obtained from the oauth2’s client_id and client_secret

Name Presence Type Description
grant_type REQUIRED String

The grant type, which depends on the type of OAuth 2.0 flow:

  • “authorization_code” SHALL be used in case of Authorization Code Grant
code REQUIRED String The authorization code returned by the authorization server. It SHALL be bound to the client identifier and the redirection URI.
client_id REQUIRED String A client_id that was send before by Signature Interaction Component (SIC) during request (see Section 3.4.3.3 of CSC).
code_verifier REQUIRED String The String value (nonce) that was used to generate the code_challenge from the /oauth2/authorize. See PKCE resources.
redirect_uri REQUIRED String An URL that was send before by Signature Interaction Component (SIC) and where the user was redirected after the authorization process completed. It is used to validate that it matches the original value previously passed to the authorization server.

3.2 Credential Listing

For this flow, it is assumed that the Wallet has already executed the service authentication (see section 3.1) on the QTSP that will be used.

After the user has agreed to sign the document and selected which QTSP will be used, the Wallet shall display the available credentials from the chosen QTSP. To achieve this, the Wallet shall request the list of credentials (including certificates and additional information) from the QTSP via the /credentials/list endpoint.

Additionally, the EUDI Wallet can show detailed information about each credential by setting credentialInfo to true in the /credentials/list request, or by making a request to the /credentials/info endpoint if available.

[Note: The HTTP request has the authentication token in the header]

3.2.1 /credentials/list

Parameter Presence Value Description
userID REQUIRED Conditional String

This parameter SHALL NOT be present as the service authorization will be user-specific. The userID is already implicit in the service access token passed in the Authorization header.

It SHALL NOT be allowed to use this parameter to obtain the list of credentials associated to a different user. The remote service SHALL return an error in such case.
credentialInfo OPTIONAL Boolean Request to return the main information included in the public key certificate and the public key certificate itself or the certificate chain associated to the credentials. The default value is “false”.
certificates OPTIONAL Conditional String | none | single | chain

Specifies which certificates from the certificate chain SHALL be returned in certs/certificates:

  • “none”: No certificate SHALL be returned.

  • “single”: Only the end entity certificate SHALL be returned.

  • “chain”: The full certificate chain SHALL be returned.

The default value is “single”.

This parameter MAY be specified only if the parameter credentialInfo is “true”.
certInfo OPTIONAL Conditional Boolean

Request to return various parameters containing information from the end entity certificate(s). This is useful in case the signature application wants to retrieve some details of the certificate(s) without having to decode it first. The default value is“false”.

This parameter MAY be specified only if the parameter credentialInfo is “true”.
authInfo OPTIONAL Conditional Boolean Request to return various parameters containing information on the authorization mechanisms supported by the corresponding credential (auth group). The default value is “false”. This parameter MAY be specified only if the parameter credentialInfo is “true”.
onlyValid OPTIONAL Conditional Boolean

Request to return only credentials usable to create a valid signature. The default value is “false”, so if the parameter is omitted then the method will return all credentials available to the owner.

The remote server may not support this parameter.
lang OPTIONAL String Request a preferred language of the response to the remote service.
clientData OPTIONAL String Arbitrary data from the signature application.

3.2.2 /credentials/info

Parameter Presence Value Description
credentialID REQUIRED String The unique identifier associated to the credential.
certificates OPTIONAL String | none | single | chain The certificates as defined in the previous table.
certInfo OPTIONAL Boolean The certInfo as defined in the previous table.
authInfo OPTIONAL Boolean The authInfo as defined in the previous table
lang OPTIONAL String Request a preferred language of the response to the remote service.
clientData OPTIONAL String Arbitrary data from the signature application.

3.3 Document Signing

For this flow, it is assumed that the Wallet has already completed the credential listing (see section 3.2).

The flow described in this section begins after the document to be signed has been displayed to the user, the user has approved the signing of the document, and if the user has selected an existing certificate for the signature.

The signature process is divided into two main operations: credential authorization and document signing.

In the credential authorization flow, the Wallet sends the document to be signed, along with the certificate and the certificate chain of the credential chosen, and other relevant information required by the /signatures/calculate_hash endpoint in the SCA. The SCA then computes the hash of the document to be signed. Following this, the Wallet requests authorization from the QTSP to use the private signing key, initiating an OAuth2 flow with OpenID for Verifiable Presentations.

Once the Wallet receives the token granting access to the chosen credential, the document signing process can proceed. The Wallet should then use the QTSP API to obtain the signature for the hash value. Finally, a request should be sent to the SCA with the signature value, the document to be signed, the certificate, and any other required data.

In the future, the extended “OID4VP” request will include details about what the SAM is requesting to sign and which credential will be used, with this information displayed to the user before they consent to allowing the SAM to access their private key for signing.

[Note: All requests include the received token in the HTTP header]

3.3.1 /oauth2/authorize

Name Presence Type Description
response_type REQUIRED String The value SHALL be “code”.
client_id REQUIRED String The client identifier as defined in oauth2 [RFC 6749].
redirect_uri

REQUIRED

Conditional

 String

The URL where the user will be redirected after the authorization process has completed.

If omitted, the remote service will use the default redirect URI pre-registered by the signature application.
scope OPTIONAL String For Document Signing flow SHALL be “credential”: it SHALL be used to obtain an authorization code suitable for credentials authorization.
authorization_details OPTIONAL JSON object as String

The details on the access request for credentials. Details presented on the CSC v2.0.0.2.

If this parameter is used, all values relevant for credential authorization SHALL be passed in this object. The scope “credential” as well as any request parameter relevant for credential authorization SHALL NOT be used in this case.
code_challenge REQUIRED String Cryptographic nonce binding the transaction to a certain user agent, used to detect code replay and CSRF attacks.
code_challenge_method OPTIONAL String Code verifier transformation method. Used to obtain the “code_challenge” from the “code_verifier”. Defaults to “plain”, but the recommended value is “S256”.
state OPTIONAL String A value used by the client to maintain state between the request and callback, as defined in oauth2 [RFC 6749].
request_uri

REQUIRED

Conditional

 String URI pointing to a pushed authorization request previously uploaded by the client. (Note: this mechanism is not currently supported)
lang OPTIONAL String Request a preferred language according to RFC 5646. If specified, the authorization server SHOULD render the authorization web page in this language, if supported.
credentialID

REQUIRED

Conditional

 String The identifier associated to the credential to authorize. It SHALL be used only if the scope of the OAuth 2.0 authorization request is “credential”.
signatureQualifier REQUIRED Conditional String This parameter contains the symbolic identifier determining the kind of signature to be created. It SHALL be used only if the scope is “credential” and if there is no parameter “credentialID” present. (Note: this mechanism is not currently supported)
numSignatures REQUIRED Conditional Number The number of signatures to authorize.
hashes REQUIRED Conditional String One or more base64url-encoded hash values to be signed. It SHALL be used if the scope is “credential” and if the SCAL parameter returned by credentials/info method for the chosen credential is “2”.
hashAlgorithmOID REQUIRED Conditional String String containing the OID of the hash algorithm used to generate the hashes.
description OPTIONAL String A free form description of the authorization transaction in the lang language.
account_token OPTIONAL String An account_token as defined in [CSC-API] section 8.4.1. (Note: this parameter is not currently supported)
clientData OPTIONAL String Arbitrary data from the signature application.


  • Authorization details (authorization_details) type “credential” as defined in the CSC API v2.0.0.2:
Name Presence Type Description
type REQUIRED String Authorization details type identifier. It SHALL be set to “credential”.
credentialID REQUIRED String The identifier associated to the credential to authorize.
signatureQualifier REQUIRED String This parameter contains the symbolic identifier determining the kind of signature to be created. (Note: this mechanism is not currently supported)
documentDigests REQUIRED JSON Array

An array composed of entries for every document to be signed. Every entry is composed of the following elements:

  • “hash”: Base64-encoded octet-representation of the hash of the document

  • “label”: A human-readable description of the respective document
hashAlgorithmOID REQUIRED String String containing the OID of the hash algorithm used to generate the hashes listed in documentDigests.

3.3.2 /signatures/calculate_hash

3.3.2.1 Request:

Parameter Presence Value Description
documents REQUIRED JSON Array An array containing JSON objects, each of them containing a base64-encoded document content to be signed and further request parameter.
endEntityCertificate REQUIRED String
certificateChain Optional List of String The certificate chain to be used when calculating the hash, excluding the end-entity certificate. If the list of certificates is not provided, it will be considered empty.
hashAlgorithmOID REQUIRED String String containing the OID of the hash algorithm used to generate the hashes.

3.3.2.2 Response:

Parameter Presence Value Description
hashes REQUIRED List of String One or more Base64 URL-encoded hash values to be signed.
signature_date REQUIRED long The date of the signature request, as a long, which should be used when obtaining a signed document.

3.3.2.3 Documents JSON Array:

Parameter Presence Value Description
document REQUIRED String Base64-encoded document content to be signed.
signature_format REQUIRED String

The required signature format:

  • “C” SHALL be used to request the creation of a CAdES signature;

  • “X” SHALL be used to request the creation of a XAdES signature.

  • “P” SHALL be used to request the creation of a PAdES signature.

  • “J” SHALL be used to request the creation of a JAdES signature.
conformance_level REQUIRED String The required signature conformance level.
signed_props OPTIONAL Array of attribute List of signed attributes. The attributes that may be included depend on the signature format and the signature creation policy.
signed_envelope_property REQUIRED String The required property concerning the signed envelope.
container REQUIRED String

3.3.3 /oauth2/token

Name Presence Type Description
grant_type REQUIRED String

The grant type, which depends on the type of OAuth 2.0 flow:

  • “authorization_code”: SHALL be used in case of Authorization Code Grant
code REQUIRED String The authorization code returned by the authorization server. It SHALL be bound to the client identifier and the redirection URI.
client_id REQUIRED String A client_id that was send before by Signature Interaction Component (SIC) during request (see Section 3.4.3.3 of CSC).
code_verifier REQUIRED String The String value (nonce) that was used to generate the code_challenge from the /oauth2/authorize. See PKCE resources.
redirect_uri REQUIRED String An URL that was send before by Signature Interaction Component (SIC) and where the user was redirected after the authorization process completed. It is used to validate that it matches the original value previously passed to the authorization server.
authorization_details

REQUIRED

Conditional

 JSON object as String An authorization detail that was send before by Signature Interaction Component (SIC) during the /oauth2/authorize. It contains the authorization details as approved during the authorization process.

3.3.4 /signatures/obtain_signed_doc

3.3.4.1 Request:

Parameter Presence Value Description
documents REQUIRED JSON Array An array containing JSON objects, each of them containing a base64-encoded document content to be signed and further request parameter.
returnValidationInfo OPTIONAL Boolean This parameter SHALL be set to “true” to request the service to return the “validationInfo” as defined below. The default value is “false”, i.e. no“validationInfo” info is provided. (Note: this mechanism is not currently supported)
hashAlgorithmOID REQUIRED String The OID of the algorithm used to calculate the hash value(s).
endEntityCertificate REQUIRED String The certificate to be used. It SHALL match the endEntityCertificate from the calculate_hash request.
certificateChain REQUIRED List of String The certificate chain to be used when calculating the hash, excluding the end-entity certificate. If the list of certificates is not provided, it will be considered empty.
date REQUIRED long The value of signature_date received in the response to the calculate_hash request.
signatures REQUIRED List of String The signature value of the hash received from the calculate_hash request.

3.3.4.2 Response:

Parameter Presence Value Description
documentWithSignature

REQUIRED

Conditional

 Array of String “One or more Base64-encoded signatures enveloped within thedocuments.” (CSC)
signatureObject

REQUIRED

Conditional

 Array of String “One or more Base64-encoded signatures detached from the documents.” (CSC)
validationInfo REQUIRED Conditional JSON Object “The validationInfo is a JSON Object containing validation data that SHALL be included in the signing response if requested using the input parameter “returnValidationInfo”.” (CSC)

3.3.5 /signatures/signHash

Parameter Presence Type Description
credentialID REQUIRED String The unique identifier associated to the credential. It should match the credentialID defined in the /oauth2/authorize request with scope “credential”
SAD REQUIRED Conditional String The Signature Activation Data returned by the Credential Authorization methods. Not needed if the signing application has passed an access token in the “Authorization” HTTP header with scope “credential”, which is also good for the credential identified by credentialID. (Note: this mechanism is not currently supported)
hashes REQUIRED Array One or more hash values to be signed. This parameter SHALL contain the Base64-encoded raw message digest(s).
hashAlgorithmOID REQUIRED Conditional String The OID of the algorithm used to calculate the hash value(s). This parameter SHALL be omitted or ignored if the hash algorithm is implicitly specified by the signAlgo algorithm. Only hashing algorithms as strong or stronger than SHA256 SHALL be used.
signAlgo REQUIRED String The OID of the algorithm to use for signing. It SHALL be one of the values allowed by the credential as returned in keyAlgo by the credentials/info method.
signAlgoParams REQUIRED String The Base64-encoded DER-encoded ASN.1 signature parameters, if required by the signature algorithm. (Note: this mechanism is not currently supported)
operationMode OPTIONAL String The synchronous operation mode SHALL be supported. (Note: this mechanism is not currently supported)
validity_period OPTIONAL Conditional Integer Maximum period of time, expressed in milliseconds, until which the server SHALL keep the request outcome(s) available for the client application retrieval. If the parameter operationMode is not “A” this parameter SHOULD not be specified. (Note: this mechanism is not currently supported)
response_uri OPTIONAL Conditional String Value of one location where the server will notify the signature creation operation completion, as an URI value. If the parameter operationMode is not “A” this parameter SHOULD not be specified. (Note: this mechanism is not currently supported)
clientData OPTIONAL String Arbitrary data from the signature application.

Annex 1

The following image illustrates an architecture defined by the CSC for a similar implementation:

[1] The extended “OID4VP” request/messages will only be implemented after the extension is added to the OID4VP draft.