BCSS - person signing (eSigning)

Owned by Stine Granviken
Last updated: Apr 18, 2024 by Terje Megård
10 min read

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

Overview

For reference in the following text, the figure below shows

  • The services involved in the creation of a signature, as well as the subsystems comprising Buypass Remote eSignature Service

  • The overall control flow and data exchange in the solution

 

 

 

Step description

  1. User requests to sign a document

  2. SCA sends an authentication request to the eSignature OIDC server

  3. eSignature OIDC server delegates user authentication to an external IDP

  4. The user presents an ID instrument and is authenticated

  5. The external IDP returns tokens containing proof of authentication and ID claims to eSignature OIDC server

  6. The eSignature OIDC server translates the (possibly IDP-specific) ID claims to a standard set of claims to be included in the signing certificate.
    An access token authorizing certificate issuance and signing is then returned to the SCA.
    The ID claims are retained in the OIDC server.

  7. 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.

  8. SSA requests claims about the authenticated user

  9. SSA receives claims about the authenticated user

  10. SSA requests the SAM to generate the user’s signing key pair.

  11. SSA receives a blob with the key pair (public key and encrypted private key).

  12. SSA constructs a CSR (Certificate Signing Request) containing

    • The ID attributes received from the OIDC server

    • The public key received from SAM
      The CSR is then signed with the user’s private signing key by the SAM (not explicitly shown in the drawing), and the CSR is submitted to the CA.

  13. SSA receives the user’s short-lived, qualified signing certificate from the CA.
    The certificate and the (encrypted) signing key blob are then stored in a memory-based cache in the SSA.

  14. SSA returns the certificate to the SCA.

  15. 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

  16. SSA sends a signing request to SAM. The request contains the hash value(s) to be signed as well as the signing algorithm to be used.
    Use of the SAM’s signing endpoint is authorized by the SAD.

  17. The SAM verifies the SAD and creates the digital signature with the user’s private signing key in the HSM.
    The signature is then returned to SSA.

  18. SSA returns the signature to SCA according to the CSC API specification.

  19. 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.

Authorization Code Flow

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

  • 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 should include:

  • 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.

 

The request may include:

  • state; value used to maintain state between redirect/callback and authentication request from the SCA

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

Example response

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

 

Token exchange

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

 

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& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=< jwt >

 

Example response

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

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

Assertion payload

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

QA
https://auth.esign.qa-04.buypass.no/auth/realms/esignature/

Production
https://auth.esign.buypass.no/auth/realms/esignature/

well-known discovery path:

/.well-known/openid-configuration

 

For testing with client_credentials grant

(not available for all clients)

Example request

Example response

 

 

 

 

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

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

Example Response

/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 singing 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

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

 

Example Response

 

 

/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

 

 

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

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

Example Response

 

 

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

  • include the ocspNoCheck extension, indicating that the certificate is short-lived and revocation check is not needed

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