BCSS - person signing: Role of Signature Creation Application Service Provider (SCASP)

Abstract

Buypass Remote eSignature Service implements parts of the REST API defined by the Cloud Signature Consortium (CSC) Protocol version 2.0 and supports the creation of advanced and qualified signatures using short-lived keys and certificates.

The intended audience for this document is service providers assuming the role of “Signature Application Provider” as defined in the CSC specification. This document should, together with the CSC specification, contain all the details needed to create a functioning client consuming the Buypass Remote eSignature Service API.

The API defined by the CSC specification contains a number of endpoints, few of which are mandatory. Buypass Remote eSignature Service only implements two of the optional endpoints.

The specification also allows for a number of different authorization mechanisms; Buypass Remote eSignature Service mandates the use of Oauth 2.0 through a dedicated Oauth2 provider. End-user authentication is delegated to an external Identity Provider.

Table of Contents

1 Abstract
2 Overview
3 Authentication/Authorization
- 3.1 Authentication
  - 3.1.1 Example request
  - 3.1.2 Example response
- 3.2 Code To Token
  - 3.2.1 Example request
  - 3.2.2 Example response
- 3.3 Creating the client assertion
  - 3.3.1 Assertion header
  - 3.3.2 Assertion payload
  - 3.3.3 Java example
- 3.4 Servers
4 CSC API
- 4.1 /info
  - 4.1.1 Servers
  - 4.1.2 Authorization
  - 4.1.3 Request details
  - 4.1.4 Response details
  - 4.1.5 Example Request
  - 4.1.6 Example Response
- 4.2 /credentials/list
- 4.3 Servers
  - 4.3.1 Authorization
  - 4.3.2 Request details
  - 4.3.3 Response details
  - 4.3.4 Example Request
  - 4.3.5 Example Response
- 4.4 /signatures/signHash
- 4.5 Servers
  - 4.5.1 Authorization
  - 4.5.2 Request details
  - 4.5.3 Response details
  - 4.5.4 Example Request
  - 4.5.5 Example Response
5 Certificate Revocation Information
- 5.1 Servers

Overview

For reference in the following text, the figure below shows

The services involved in the creation of a signature
The overall control flow and data exchange in the solution

User requests to sign a document
SCA sends an authentication request to the eSignature OIDC server
The eSignature OIDC server translates the (possibly IDP-specific) ID claims to a standard set of claims to be included in the signing certificate.
The End-User accepts the creation of short-lived certificate and user agreement.
An access token authorizing certificate issuance and signing is then returned to the SCA.
The ID claims are retained in the OIDC server.
The SCA sends a request to issue the signing certificate to the SSA.
The request uses the /credentials/list endpoint according to the CSC specification, and is authorized by the access token received by the SCA in the previous step.
SSA returns the certificate to the SCA.
The SCA then prepares a set of attributes to be signed, including the document hash, certificate reference, signing time and possibly others.
The set of attributes is then hashed, and the resulting hash is submitted to SSA for signing through the CSC-specified /signature/signHash endpoint.
The signing operation is authorized with
- the access token previously issued, which must then have both the service and credential scopes, or
- a new access token having the credential scope
SSA returns the signature to SCA according to the CSC API specification.
The SCA then
- collects the necessary elements for LTV (Long Term Validation), typically revocation information and a certified time stamp,
- assembles the complete signature according to the format required by the document type,
- returns the signed document to the user.

Authentication/Authorization

The end-user requesting a document to be signed must be authenticated, and the necessary access token authorizing use of the CSC API must be obtained by the SCA.

The SCA starts by sending an Oauth2 authentication request to the Buypass Oauth2 server. This should be done using the authorization code flow.

Authentication

The request must include:

the scopes requested; these are
- service for access to the CSC API
- credential for access to the /signHash CSC API endpoint
- openid for gathering the identity attributes
client_id; provided by Buypass
response_type; determines what flow will be used in order to authenticate the end-user
- code
redirect_uri; where to redirect the user after successful authentication, url encoded value

The request may include:

state; value used to maintain state between redirect/callback and authentication request from the SCA
bp_signature_qualifier; the requested signature qualification level where possible values are
- aes for advanced electronic signature. This is the default if signature qualification level is not specified
- qes for qualified electronic signature. Note that fulfillment of the request is conditional and depends on the quality of the end-user’s ID instrument.
login_hint; value used to indicate information about the end-user/customer
- Value is passed on to the IPSP without any processing

Example request

https://auth.esign.qa-04.buypass.no/auth/realms/esignature/protocol/openid-connect/auth?
response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A4567%2F
&state=OWhHgUpEsgOPWKElcRMNMvtJ8fCwSbL7Z_wYHlOszdU
&client_id=remote-esignature-demo
&scope=openid+service+credential
&bp_signature_qualifier=aes
&login_hint=12345678910

Example response

HTTP/1.1 302 Found
Location: http://localhost/4567?
    code=xxxxx
    &state=OWhHgUpEsgOPWKElcRMNMvtJ8fCwSbL7Z_wYHlOszdU

Code To Token

When the authentication is successful and the user is redirected back to the redirect_uri provided in the initial authentication request, the SCA needs to use the code returned in order to retrieve the access_token.

This will be done at the token endpoint. To do the exchange credentials are needed, and this is in the form of a client_assertion.

The token request must include:

a client_assertion in the form of a signed, Base64-URL-encoded JWT.
This authenticates the SCA to the Buypass Oauth2 server.
The JWT must be signed with the private key linked to a merchant certificate issued by Buypass.
Construction of the client_assertion is detailed in the section titled: Creating the client assertion
code; retrieved from the authentication response
client_assertion_type; the type of assertion provided
- urn:ietf:params:oauth:client-assertion-type:jwt-bearer
grant_type;
- authorization_code
redirect_uri; same value as when doing authentication request

Example request

POST https://auth.esign.qa-04.buypass.no/auth/realms/esignature/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
   code=xxxxx&
   redirect_uri=http%3A%2F%2Flocalhost%3A4567%2F&
   client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
   client_assertion=< jwt >

Example response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIxNFVL...",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyOWM1...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "8e55274c-0d41-4006-a5a1-b62acc60ef4a",
    "scope": "openid service credential"
}

The response will be a JSON structure containing an access_token claim, the value of which is the access token to be submitted as Bearer token in the Authorization header in subsequent requests to the CSC API.

Creating the client assertion

The client needs to construct a valid client_assertion, which is a base 64 encoded signed jwt. There are numerous libraries that are capable to do this. Here are some details regarding the assertion:

Assertion header

{
  "typ": "JWT",
  "alg": "RS256"
}

These values are currently fixed. NOTE: Do not include a “kid” claim in the header.

Assertion payload

{
  "jti": "d90854d1-7df9-4541-b0df-bdca97209065",    // A unique requestid
  "iat": 1574940763,                                // Issued at 'seconds since epoch'. The client should provide 'now'
  "sub": "remote-esignature-client-778899",          // The client ID (specific to each client)
  "iss": "remote-esignature-client-778899",          // The client ID (specific to each client)
  "nbf": 1574940763,                                // Not valid before 'seconds since epoch'. The client should provide 'now'
  "exp": 1574944363,                                // Expiry date of the token. Can be set til 'now' + 1 hour
  "aud": "https://auth.esign.qa-04.buypass.no/auth/realms/esignature"   // URL of the OIDC server
}

Java example

In java the client assertion can be created with the following code:

private String createSignedJWT()
    KeyStore keystore = ...
    keystore.load(...);
    PrivateKey key = (PrivateKey)keystore.getKey(...);
 
    PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(key.getEncoded());
    KeyFactory kf = KeyFactory.getInstance("RSA");
    PrivateKey privKey = kf.generatePrivate(keySpec);
 
    JwtBuilder builder = Jwts.builder()
        .setHeaderParam("typ", "JWT")
        .setId(createUniqueId())
        .setIssuedAt(now())
        .setSubject("remote-esignature-client-778899")
        .setIssuer("remote-esignature-client-778899")
        .setNotBefore(now())
        .setExpiration(nowPlusOneHour())
        .setAudience("https://auth.esign.qa-04.buypass.no/auth/realms/esignature")
        .signWith(RS256, privKey);
 
    return builder.compact();
}

Servers

Environment	Issuer	Discovery Endpoint

Environment	Issuer	Discovery Endpoint
QA	https://auth.esign.qa-04.buypass.no/auth/realms/esignature/	https://auth.esign.qa-04.buypass.no/auth/realms/esignature/.well-known/openid-configuration
Production	https://auth.esign.buypass.no/auth/realms/esignature/	https://auth.esign.buypass.no/auth/realms/esignature/.well-known/openid-configuration

CSC API

Buypass Remote eSignature Service implements the following endpoints in the CSC specification:

info
credentials/list
signatures/signHash

NOTE : The CSC specification should be used as the primary source of information about the endpoints; this document provides only additional details particular to the Buypass implementation.

/info

This is the only mandatory endpoint in the CSC specification. Its most relevant use is to obtain the URL of the OAuth2 endpoint instead of configuring it.

Servers

Test environment
POST https://api.esign.qa-04.buypass.no/csc/v2/info
Production
POST https://api.esign.buypass.no/csc/v2/info

Authorization

None

Request details

The optional lang parameter in the request body is not interpreted and has no effect. The language used is en-US.

Response details

None

Example Request

$ curl -X POST https://api.esign.qa-04.buypass.no/csc/v2/info
-H "Content-Type: application/json"
-d '{}'

Example Response

{
    "specs": "2.0.0.2",
    "name": "Buypass Remote eSignature SSA",
    "logo": "https://www.buypass.no/ressurser/foto-logo/_/image/4f880aa1-ad83-4609-b690-e51ea9f22acd:33039d053f7aea8c873dfdf8dcd75b34a4d4298c/block-393-393/card-Buypass-logo-farge.svg",
    "region": "NO",
    "lang": "en-US",
    "description": "Buypass remote signing services",
    "authType": [
        "oauth2code"
    ],
    "oauth2": "https://auth.esign.qa-04.buypass.no/auth/realms/esignature",
    "methods": [
        "info",
        "signatures/signHash",
        "credentials/list"
    ],
    "signAlgorithms": {
        "algos": ["1.2.840.10045.4.3.2"]
    }
}

/credentials/list

The semantics of this endpoint differ somewhat from the CSC specification due to the use of short-lived keys and certificates. As specified by the CSC, the endpoint is supposed to return a list of the user’s existing (and presumably long-lived) credentials. In the Buypass implementation, calling this endpoint will trigger the following server-side actions:

The QSCD generates a signing key pair on behalf of the user
The CA issues a short-lived signing certificate containing
- the public signing key
- the user’s ID attributes resulting from the user authentication
The signing certificate is returned as part of the response

The response will therefore always contain one and only one credential which is valid for a short period of time.

Servers

Test environment
POST https://api.esign.qa-04.buypass.no/csc/v2/credentials/list
Production
POST https://api.esign.buypass.no/csc/v2/credentials/list

Authorization

The access token with the “service” scope, received from the previously described Oauth2 endpoint, must be submitted as Bearer token in the Authorization header.

Request details

Parameter	Comment

Parameter	Comment
userID	Ignored if present
credentialInfo	MUST be set to “true”, otherwise the response will omit information necessary for the subsequent signHash request.
certificates	“chain”or “single”
certInfo	“true” if attributes extracted from the certificate should be returned.
authInfo	“true” if information about available authentication methods should be returned.
onlyValid	Ignored if present. Exactly one valid credential is always returned.
lang	Ignored if present. The language is always as specified in the response from the /info endpoint.
clientData	REQUIRED. This must be a UUID which will be used as log correlation ID throughout.

Response details

Attribute	Comment

Attribute	Comment
credentialIDs	The array always contains exactly one element.
onlyValid	Always “true”
credentialInfo/signatureQualifier	“eu_eidas_aes” or “eu_eidas_qes”, depending on the signature qualification level requested from the Oauth2 endpoint described above.
credentialInfo/key/status	Always “enabled”
credentialInfo/key/algo	“1.2.840.10045.4.3” (ecdsa-with-sha2)
credentialInfo/cert/status	Always “valid”
credentialinfo/cert/certificates	single certificate or complete chain, depending on the value of the “certificates” attribute in the request.
credentialInfo/SCAL	“Sole Control Assurance Level”. Always 2.
credentialInfo/auth/mode	Always “oauth2code”
credentialInfo/multisign	Maximum number of hashes in a single signature request.

Example Request

$ curl -X POST https://api.esign.qa-04.buypass.no/csc/v2/credentials/list
-H 'Content-Type application/json'
-H 'Authorization: Bearer eyJhbGciOi....<Base64 URL-encoded access token>'
-d '{"credentialInfo": true,\
  "certificates": "chain",\
  "certInfo": true,\
  "authInfo": true,\
  "clientData": "415a1588-c11d-4cf7-a1f1-c679e48f5489"\
}'

Example Response

{
    "credentialIDs": ["d6ZvqJiVD1u4rmijjYaOnvZWXKg"],
    "credentialInfos": [{
            "credentialID": "d6ZvqJiVD1u4rmijjYaOnvZWXKg",
            "description": "Signing certificate and chain",
            "signatureQualifier": "eu_eidas_qes",
            "key": {
                "status": "enabled",
                "algo": ["1.2.840.10045.2.1"],
                "len": 2048,
                "curve": "secp256r1"
            },
            "cert": {
                "status": "valid",
                "certificates": [
                    "<Base64-encoded_X.509_end_entity_certificate>",
                    "<Base64-encoded_X.509_intermediate_CA_certificate>",
                    "<Base64-encoded_X.509_root_CA_certificate>"
                ]
            },
            "SCAL": "2",
            "auth": {
                "mode": "oauth2code"
            },
            "multisign": 10,
            "lang": "en-US"
        }
    ],
    "onlyValid": true
}

/signatures/signHash

This endpoint has the same semantics as in the CSC specification, but must be invoked with a request referring to a credential created with an immediately preceding invocation of the credentials/list endpoint.

After performing the signing operation, the server will destroy the credential’s signing key. In other words, a credential may be used in only one call to signHash; however, in accordance with the CSC specification it is permitted to submit multiple hashes to be signed in the same request.

Servers

Test environment
POST https://api.esign.qa-04.buypass.no/csc/v2/signatures/signHash
Production
POST https://api.esign.buypass.no/csc/v2/signatures/signHash

Authorization

The access token with the “credential” scope, received from the previously described Oauth2 endpoint, must be submitted as Bearer token in the Authorization header.

Request details

Parameter	Comment

Parameter	Comment
credentialID	The credentialID returned by /credentials/list
SAD	Ignored if present. The SAD is generated by the SSA.
hashes	Array of Base64-encoded hash values to be signed.
hashAlgorithmOID	May be specified, but will be ignored for ECDSA.
signAlgo	The following will be accepted: 1.2.840.10045.4.3 “ecdsa-with-sha2” 1.2.840.10045.4.3.2 “ecdsa-with-sha256” 1.2.840.10045.4.3.3 “ecdsa-with-sha384” 1.2.840.10045.4.3.4 “ecdsa-with-sha512”
operationMode	Must have the value “S” or be omitted. Asynchronous operation is not supported.
clientData	REQUIRED. This must be the same UUID as was submitted in the preceding request to /credentials/list.

Response details

Parameter	Comment

Parameter	Comment
signatures	Array of Base64-encoded signatures.

Example Request

$ curl -X POST https://api.esign.qa-04.buypass.no/csc/v2/signatures/signHash
-H 'Content-Type application/json'
-H 'Authorization: Bearer eyJhbGciOi....<Base64 URL-encoded access token>'
-d '{
    "credentialID": "d6ZvqJiVD1u4rmijjYaOnvZWXKg",\
    "hashes": ["IjNEVWZ3iJmqu...", "IjNEVWZ3iJmqu8zd..."],\
    "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1",\
    "signAlgo": "1.2.840.10045.4.3.2",\
    "signAlgoParams": null,\
    "operationMode": "S",\
    "clientData": "415a1588-c11d-4cf7-a1f1-c679e48f5489"\
}'

Example Response

{
    "signatures": ["MEUCIQDngDwYxYgj4ooWM...", "MEQCICi6oFkd3GhAaTo+msYN..."],
    "responseID": "3bfb085e-23cc-4400-9e63-1d107fecb75d"
}

Certificate Revocation Information

The signing certificates issued are short-lived, hence revocation services are not implemented and revocation checks are not needed when validating signatures. Consequently, the certificates

do not include the CRL Distribution Points extension
do not include OCSP URL in the Authority Information Access extension

However, since signature validators may not support verification of short-lived certificates based only on these certificate attributes, Buypass provides a CRL service that enables the SCA to fetch a (presumably empty) CRL immediately after invoking the /signHash endpoint. The CRL may then be included in an LTV-enabled signature.

Servers

Test environment
GET http://crl.qa-04.buypassca.com/BPCl3CaG2HTPSBCSS.crl
Production
http://crl.buypassca.com/BPCl3CaG2HTPSBCSS.crl