Alison Server - Credential Usage
- Armando Carratala
Create a Signature
Any client application can create a signature follow these steps:
1. Obtain an OAuth2 Token.
The client must obtain an OAuth2 Token from Alison-Server to access any service. When requesting this token a scope must be specified. This scope indicates the Seat that must be used in the following requests. The scope has the following format:
seat:jdoe@acme
2. List Credentials and Credential Info.
List
All stored credentials can be listed. The result of the listing service is a list of IDs. Only the credentials of the Seat that appears in the scope of the OAuth2 Token are listed.
CredentialInfo
In order to retrieve the information of a credential, the Credential Info service must be used, passing the Credential ID. Other parameters can be specified too, such as:
Certificates
Indicates if the certificate in Base64 must be returned. Values are:
"none" (no certificate is returned),
"single" (only end entity certificate is returned),
"chain" (the whole certificate chain is returned).
The default value is "single".
CertInfo
Requests to retrieve the information of the certificate in different attributes. If set to true, the Certificate will be parsed and all the information will be retrieved in different attributes.
The default value is "false".
AuthInfo
Request to return various parameters containing information on the authorization mechanisms supported by this credential (PIN and OTP groups).
The default value is “false”.
3. Authorize Credential
When signing a hash, a SAD is required. A SAD is a token that allows access to the signature service. The token is attached to the information to be signed to increase security. To obtain a SAD the Authorize Credential service must be used. This service requires, besides the Credential ID:
numSignature | The number of signatures that will be done with the SAD. This value must be less or equal to the number of multi-signatures that the credential allows. |
hash | An array containing all the hashes to be signed. The number of hashes must be equal to numSignature. |
PIN | If the credential is protected with a PIN, the PIN Value must be sent. |
OTP | If the credential is protected with OTP, the OTP Value must be sent. |
If the PIN and OTP values are correct, a SAD is generated and returned.
This SAD is associated with the hashes sent in the request, so trying to sign a different hash with this SAD will throw an error.
4. Create Signature
When creating a signature the following parameters are required:
credentialId | The ID of the credential that will sign the hashes. |
SAD | The Signature Activation Data is generated with the service Authorize Credential. |
hash | An array with all the hashes to be signed. All the hashes must be associated with the given SAD. |
hashAlgo | The algorithm is used to hash the sent data. If not specified then the signAlgo must have the name of the hash algorithm. |
signAlgo | The algorithm will be used to sign the data. It can have the name of the hash algorithm, for example, SHA256WITHRSA. In this case, the hashAlgo must NOT be specified. If only the signature algorithm is specified in this parameter, for example, RSA, then the hashAlgo must be specified. |
If the sign process is successful, an array with all the signatures will be returned. The signatures will be returned in the same order as the hashes were sent.
Errors
When an error occurs a specific response is sent to the client that made the request. The structure of all error responses is the following:
{
"error": <error>,
"error_description": "<error_description>"
}General errors
error | error_description | cause |
|---|---|---|
invalid_request | Payload is required | The service expects a payload in the request but none was sent |
OAuth2Client errors
error | error_description | cause |
|---|---|---|
invalid_request | ClientId is null or empty | The clientId was not sent or is an empty string |
invalid_request | ClientSecret is null or empty | The clientSecret was not sent or is an empty string |
invalid_request | AuthorizedGrantTypes is null or empty | The authorizedGrantTypes was not sent or is an empty string |
invalid_request | Unsupported grant type | The specified grant type is not currently supported by the server |
invalid_request | AccessTokenValidity is null | The access token validity was not sent |
invalid_request | The Access Token Validity must be greater than 0 | The access token validity is less or equals 0 |
invalid_request | The client already exists | The value specified in clientId is already taken by another client |
not_found | The client was not found | There was no client that matches the specified clientId |
Authorization errors
error | error_description | cause |
|---|---|---|
invalid_client | Bad client credentials | Either client_id or client_secret or both are invalid |
unsupported_grant_type | Unsupported grant type: $grant_type_value | The sent grant type ($grant_type_value) is not supported |
invalid_token | Token was not recognized | When calling check_token with a token that does not exist |
invalid_token | Token has expired | The access token validity time has elapsed |