Signature protocols
The RP API’s main use case is to provide digital signatures which is enabled by use of signature protocols.
The signature protocol ACSP_V1 is used for authentication requests and RAW_DIGEST_SIGNATURE signature protocol for signing.
ACSP_V1 signature protocol
Authentication Context Signature Protocol version 1 makes the signature non-replayable by adding a server-side component to the signed object.
The RP must provide the digest algorithm to use as well a challenge it needs signed. The challenge must be generated anew for every single authentication request.
It must be remembered by the RP for the duration of the authentication session, and later it is used to reconstruct and validate the signed authentication data structure.
The recommended way of generating the challenge this is to use the Java SecureRandom class[1] or equivalent method in other programming languages, to generate a random value for each new authentication request.
The value of the randomChallenge must be kept in the current user’s session on the backend for later use in response validation.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
|
string |
+ |
A random value which is calculated by generating random bits with size in the range of 32 bytes … 64 bytes and applying Base64 encoding (according to rfc4648). It is generated per each |
|
string |
+ |
Digital signature algorithm name. See here for supported signature algorithms. |
The following table describes the signature body for ACSP_V1 protocol that the RP will receive in the session response.
Notice that the actual object that was signed is not present — it needs to be compiled by the RP using the previously sent randomChallenge and the serverRandom returned in this response. This re-constructed object is then used to validate the signature.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
|
string |
+ |
Signature value, base64 encoded. |
|
string |
+ |
A random value of 24 or more characters from Base64 alphabet, which is generated at RP API service side. RP must validate that the value contains only valid Base64 characters, and that the length is not less than 24 characters. This value will be returned from RP API and RelyingParties must use it exactly as it was returned during the validation of signature. There are not any guarantees that the returned value length is the same in each call of the RP API. |
|
string |
+ |
Digital signature algorithm name. This is a reference name to algorithm defined in some Public-Key cryptography standards. See here for supported signature algorithms. |
{
"signatureProtocol": "ACSP_V1",
"signature": {
"value": "B+A9CfjIBZnDHHav3B4F...",
"serverRandom": "B+C9XVjIAZnCHH9vfBSv...",
"signatureAlgorithm": "sha512WithRSAEncryption"
}
}To verify the signature.value the RP client must reconstruct its input digest (hash) and calculate it themselves. The digest is calculated over the concatenation of the signatureProtocol, the Base64 encoded serverRandom and the Base64 encoded randomChallenge separated by semicolons:
digest(signatureProtocol + ";" + serverRandom + ";" + randomChallenge)
Note that signature.serverRandom in the response and the randomChallenge in the initial request are already Base64 encoded.
The signature algorithm that was used to generate the signature based on the digest is specified in signature.signatureAlgorithm.
Full verification of the signature and response is described in Response verification.
RAW_DIGEST_SIGNATURE signature protocol
The RAW_DIGEST_SIGNATURE signature protocol allows direct signing of the digest that is requested by the RP.
The RP must provide the digest algorithm to use as well the digest hash that is being signed. In case an electronic signature is being created this is calculated from the electronic signature container.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
|
string |
+ |
Base64 encoded digest to be signed (RFC 4648). |
|
string |
+ |
Digital signature algorithm name. This is a reference name to algorithm defined in some Public-Key cryptography standards. See here for supported signature algorithms. |
The following table describes the signature body for the RAW_DIGEST_SIGNATURE protocol that the RP will receive in the session response.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
|
string |
+ |
Signature value, base64 encoded. |
|
string |
+ |
Digital signature algorithm name. This is a reference name to algorithm defined in some Public-Key cryptography standards. See here for supported signature algorithms. |
{
"signatureProtocol": "RAW_DIGEST_SIGNATURE",
"signature": {
"value": "B+A9CfjIBZnDHHav3B4F...",
"signatureAlgorithm": "sha512WithRSAEncryption"
}
}Supported signature algorithms
| Algorithm | Description |
|---|---|
|
Secure Hash Algorithm 256 (SHA-256) with Rivest, Shamir and Adleman (RSA) encryption RFC8017, Appendix A.2.4, OID 1.2.840.113549.1.1.11. |
|
Secure Hash Algorithm 384 (SHA-384) with Rivest, Shamir and Adleman (RSA) Encryption RFC8017, Appendix A.2.4, OID 1.2.840.113549.1.1.12. |
|
Secure Hash Algorithm 512 (SHA-512) with Rivest, Shamir and Adleman (RSA) encryption RFC8017, Appendix A.2.4, OID 1.2.840.113549.1.1.13. |