Electronic Signature Provider API
The Electronic signature API generates digital signatures (PKCS #1) with the signing identities managed by the platform.
Obtain Signing Identity Information
There is two types of signing identity, one for electronic signing and one for authentication
Request
GET /trustedx-resources/esigp/v1/sign_identities/{sign_identity_id}
Authorization
The request must contain a bearer access token generated by a trusted authorization server of the service from which the information on the signing identity is requested and that is associated to the domain to which the identity belongs. This token must be used as explained in RFC 6750. It must have the urn:safelayer:eidas:sign:identity:profile scope.
Basically, the token must be included in an HTTP Authorization header as follows:
Authorization: Bearer <token>
The access token can be obtained via an authorization code grant or Service provider's credentials grant OAuth 2.0 flow.
Example
GET /trustedx-resources/esigp/v1/sign_identities/12345678 HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM
Response
Response body representation in JSON as follows
{
"id" : {string},
"self" : {string},
"description" : {string},
"labels" : [ {string} ],
"type" : {string},
"device_id" : {string},
"domain" : {string},
"access" : [ {
"user_id" : {string}
} ]
"details" : {
"certificate" : {string},
"activation_mode": {string},
"public_key" : {string}
},
"links" : {
<operation_alias> : {
"auth" : {
"oauth2": {
"scopes": [ {string} ]
}
}
}
},
"status" : {
"value" : {string},
"reason" : {string}
}
}
Property | Description |
---|---|
id | Identifier of the signing identity. |
self | Access URL for the signing identity. |
description | Description of the signing identity. |
labels[ ] | List of tags associated to the signing identity. |
type | Type of signing identity. This property currently always takes the pki:x509 value. |
device_id | Device where the private part of the keys associated to the signing identity is located. Only the signing identities on mobile devices have this property. |
domain | Domain the signing identity belongs to. |
access[ ] | Information on access control to the signing identity. |
access[ ].user_id | Identifier of a end-user with access to the signing identity. |
details | Details for implementing the signing identity. |
details.certificate | X.509 certificate encoded in DER and base64. Only pki:x509 signing identities have this property. |
details.activation_mode | Activation mode of the signing identity. Only server signing identities have this property and it can take the following values: "hsm-pwd": the signature identity is activated by a password entered by the owner and validated by the HSM. |
details.public_key | Public part of the keys associated to the signing identity. PublicKeyInfo ASN.1 structure encoded in DER and base64. Only pki:x509 signing identities have this property. |
links | Information on operations that use the signing identity. |
links.<operation_alias> | Information on the <operation_alias> operation regarding the use of the signing identity. Currently the only value possible for <operation_alias> is Signatures.create.server.raw |
links.<operation_alias>.auth | Authorization information on the <operation_alias> operation regarding the use of the signing identity. |
links.<operation_alias>.auth.oauth2 | OAuth 2.0 authorization information on the <operation_alias> operation regarding the use of the signing identity. |
links.<operation_alias>.auth.oauth2.scopes[ ] | Set of OAuth 2.0 scopes required for accessing the <operation_alias> operation so that this operation can use the signing identity. |
status | Information on the status of the signing identity. |
status.value | Status of the signing identity. "enabled": The signing identity is enabled. "disabled": The signing identity is disabled. "locked": The signing identity is locked. |
status.reason | Reason why the signing identity is in its current state. This property is optional and is normally used to indicate why a signing identity has been locked or disabled. |
For receiving signing certificate, labels array shall contain serverid tag.
For receiving authentication certificate, labels array shall contain mobileid tag.
Create a Digital Signature on the Server
Description
Creates a digital signature (PKCS #1) of data using a signing identity on server. As input, the hash of the data or a byte string to be signed raw can be received.
The signature is created with the signing identity on server specified in the request. This identity must belong to the end-user on behalf of whom the operation is performed.
Request
POST /trustedx-resources/esigp/v1/signatures/server/raw
Content-Type Header
Content-Type: application/json
Body
{
"digest_value" : {string},
"signature_algorithm" : {string},
"sign_identity_id" : {string}
}
Property | Description |
---|---|
digest_value | Hash of the data to be signed encoded in base64. |
signature_algorithm | Algorithm that must be used to generate the digital signature (rsa-sha1, rsa-sha256, rsa-sha384, rsa-sha512 and ecdsa). Signature algorithm choice must be based on key algorithm found in clients certificate. |
sign_identity_id | Identifier of the signing identity that must be used for generating the signature (it must be a server signing identity that belongs to the end-user on behalf of whom the signature is performed). |
Example
POST /trustedx-resources/esigp/v1/signatures/server/raw
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
"digest_value" : "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg",
"signature_algorithm" : "rsa-sha256",
"sign_identity_id" : "nio...omq"
}
Response
Response contains the binary value of the PKCS #1 signature.
If you are using Sign API service, PKCS#1 shall be base64 encoded (hexToBase64)
Create a Digital Signature Batch on the Server
Description
Creates a batch of digital signatures from the hashes of the data to be signed using a server signing identity.
The signature is created with the signing identity on server specified in the request. This identity must belong to the end-user on behalf of whom the operation is performed.
This method can be used for single signing as well. Main differences: Batch method response with base64 encoded Signed data, but single signing method response with PKCS#1 raw signature.
Request
POST /trustedx-resources/esigp/v1/signatures/server/raw/batch
Content-Type Header
Content-Type: application/json
Body
{
"sign_identity_id" : {string},
"signature_algorithm" : {string},
"requests" : [
{
"digest_value" : {string},
"signature_algorithm" : {string}
}
]
}
Property | Description |
---|---|
sign_identity_id | Identifier of the signing identity that must be used for generating the signature (it must be a server signing identity that belongs to the end-user on behalf of whom the signature is performed). |
signature_algorithm | Algorithm for obtaining the cryptographic hashes to be used for generating the signatures (rsa-sha1, rsa-sha256, rsa-sha384 and rsa-sha512) if no other algorithm is specified for each of them. |
requests[ ] | Information on the cryptographic hashes to be used for generating the signatures. |
requests[ ].digest_value | Base64 encoding of the cryptographic hash used to generate the signatures. |
requests[ ].signature_algorithm | Algorithm that must be used to generate the digital signature (rsa-sha1, rsa-sha256, rsa-sha384, rsa-sha512 and ecdsa). Signature algorithm choice must be based on key algorithm found in clients certificate. |
Access Control
The request must contain a bearer access token generated by a trusted authorization server associated to the domain of the signing identity to be used for generating the signature. This token must have a scope that includes the value configured for the signing identity (by default, urn:safelayer:eidas:sign:identity:use:server) and must be used as explained in RFC 6750. Basically, the token must be included in an Authorization header as follows:
Authorization: Bearer <token>
The access token must be obtained via an authorization code grant OAuth 2.0 flow.
Example
POST /trustedx-resources/esigp/v1/signatures/server/raw/batch
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
"sign_identity_id": "12345678",
"signature_algorithm": "rsa-sha1",
"requests": [
{
"digest_value": "RXN0byBlcyB1biBoYXNoIFNoYTE=",
"signature_algorithm": "rsa-sha1"
},
{
"digest_value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k",
"signature_algorithm": "rsa-sha256"
}
]
}
Response
Body
{
"signatures" : [ {string} ]
}
Property | Description |
---|---|
signatures[] | Digital signatures encoded in base64. The signatures follow the same order as the cryptographic hashes from which they were created appear in the request. |
Updated about 1 year ago