# BankID CSC Signing API The BankID CSC Signing API is used to create qualified electronic signatures. This API is based on version 2.0.0.2 of the [Cloud Signature Consortium API](https://cloudsignatureconsortium.org/resources/). ## Pre-requisites ### Access to the BankID CSC Signing API To access the BankID CSC Signing API the merchant must have a BankID OIDC client with the scope `esign/csc`. This access token is only used for CSC `oauth2/token` (subsequent calls are authorized with the CSC access token). ```bash curl --request POST \ --url https://auth.{{env}}.bankid.no/auth/realms/{env}/protocol/openid-connect/token \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data scope=esign/csc \ --data 'client_id={{client_id}}' \ --data 'client_secret={{client_secret}}' ``` ### BankID Test users Create BankID test users in [BankIDs preprod environment](https://ra-preprod.bankidnorge.no/#/generate). Instructions on how to create test users can be found [here](https://bidbax.atlassian.net/wiki/spaces/DEVPUB/pages/29232606/RA+Light+User+Guide). ## BankID CSC Signing API The following methods are used in the BankID CSC Signing API: | CSC Call | Description | Authorization | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | `POST /info` | (Optional) Get information about the CSC service such as supported methods. | None | | `GET /oauth2/authorize` | Initiate OAuth 2.0 authorization flow | None, but clientID and redirectUri are validated | | `POST /oauth2/token` | Exchange the authorization code for an access token | Client credential access token from BankID OIDC | | `POST /credentials/list` | Start the key and certificate generation. Returns a list of available credentials and certificates | CSC service token from `/oauth2/token` | | `POST /credentials/info` | Retrieve the credential and return the main identity information and the public key certificate or the certificate chain associated to it. | CSC service token from `/oauth2/token` | | `POST /credentials/authorize` | Authorize the access to the credential for remote signing, according to the authorization mechanisms associated to it. This method returns the Signature Activation Data (SAD) required to authorize the signatures/signHash method. | CSC service token from `/oauth2/token` | | `POST /signatures/signHash` | Sign the data-to-be-signed hash | CSC service token from `/oauth2/token` | ### Hash algorithm and signature algorithm restrictions The service only supports the following algorithms: - Hash algorithm OID: `2.16.840.1.101.3.4.2.1` - Signature algorithm OID: `1.2.840.10045.4.3.2` ### Acquiring Norwegian National Identity Number (NNIN) / Fødselsnummer To include the Norwegian National Identity Number (NNIN) / fødselsnummer in the certificate, the scope `esign/nnin` must be used when acquiring the access token from BankID OIDC _and_ during the user authorization request to `/oauth2/authorize`. The user will be given the option to approve to including the NNIN in the certificate during the authentication. Be aware that the user may decline this, in which case the process will be aborted with an `access_denied` error. The NNIN will be included in the public certificate as a custom extension with the OID `2.16.578.1.61.2.4`. The merchant must ensure that they handle this information in accordance with applicable data protection regulations. ### Signature response The response from the `POST /signatures/signHash` method contains the raw base64 encoded signature value (`r || s`).\ For use in CMS and other formats it usually needs to be transformed to ASN.1 DER format, like: ``` Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER } ``` For example [`com.nimbusds.jose.crypto.impl.ECDSA.transcodeSignatureToDER`](https://javadoc.io/doc/com.nimbusds/nimbus-jose-jwt/latest/com/nimbusds/jose/crypto/impl/ECDSA.html#transcodeSignatureToDER\(byte%5B%5D\)) ## Not Yet Implemented ### Login_hint Login_hint is not yet supported. ## OpenAPI Specification Please refer to the [BankID CSC OpenAPI spec](https://docs.stoe.no/bankid-esign-provider/apis/csc/csc-v2.0.external.json) for more details and examples. ## Sequence diagram ```mermaid sequenceDiagram autonumber title: BankID CSC Signing API %%{ init: { 'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#7C0000', 'fontFamily': 'Arial', 'fontSize': '24px' } } }%% participant Merchant as Merchant participant BIDOIDC as BankID OIDC actor User box rgb(255,204,203) BankID eSign Infrastructure participant BIDCSC as BankID CSC participant OIDC as eID Integration Hub end Note over Merchant, BIDOIDC: Merchant request API access Merchant-->>+BIDOIDC: Request access (scope esign/csc) BIDOIDC-->>-Merchant: Return access token Note over Merchant, BIDCSC: CSC: Authentication Merchant->>User: Redirect for CSC authentication User->>BIDCSC: Initiate CSC authentication BIDCSC -->>+User: Redirect to eID Hub User->>OIDC: Initiate OIDC authorization OIDC -->>User: Present IDPs User->>-OIDC: Authorize Note over User, OIDC: T&C and Certificate acceptance OIDC ->>+User: Present certificate-to-be and T&C User -->>-OIDC: User accepts OIDC-->>User: Redirect Authorize response (auth code ) User-->>BIDCSC: Redirect Authorize response (auth code ) Note over Merchant, BIDCSC: CSC: User onboarding BIDCSC-->>Merchant: Redirect with auth code Merchant->>+BIDCSC: Get Token (POST oauth2/token) BIDCSC-->>-Merchant: Return Access Token (scope service) Merchant->>+BIDCSC: Post CSC credentials/list BIDCSC-->>-Merchant: Return certificates Merchant->>Merchant: Create *AdES structure and final data-to-be-signed hash Note over Merchant, BIDCSC: CSC: Signature Authorization Merchant->>+BIDCSC: CSC POST credentials/authorize BIDCSC-->>-Merchant: Return SAD Note over Merchant, BIDCSC: CSC Signature Creation Merchant->>+BIDCSC: CSC POST signatures/signHash BIDCSC-->>-Merchant: Return signature ``` ## Signature Visual Appearance You may use the following image as template for the visual appearance of the signature. ![BankID Signature Appearance](https://docs.stoe.no/bankid-esign-provider/apis/csc/bidseal.png) ## Restrictions and limitations ### Token single-use Each access token obtained from `/oauth2/token` must be used in the following endpoint order, exactly once per endpoint: 1. `POST /credentials/list` 2. `POST /credentials/authorize` 3. `POST /signatures/signHash` If a token is reused at an endpoint it has already been used at, or if endpoints are called out of order, the service will respond with error code `token_already_used` (HTTP 400). To sign again, obtain a new access token by starting a new authorization flow. `POST /credentials/info` can be called at any point and does not affect the token lifecycle. `POST /credentials/list` will return the same list of credentials and certificates for the same token, but the token must still be used in the correct order at the other endpoints. ## Ensuring signer access to signed Documents When using this service, you _must_ ensure that the end user who signs receives a copy of the signed document. If multiple signers are involved, you may wait to share the document until all participants have completed their signing. ### iframe The CSC service does not support iframe embedding. ### Supported IDPs The service supports the following IDPs: - BankID Norway (High) ### Max amount of hashes to be signed The service supports signing of multiple hashes in one call. The maximum number of hashes that can be signed in one call is 50.