Description

Alison-Server is a Remote Signing Service Provider. It is a service that manages credentials on behalf of multiple users and allowing them to create a remote signature with a stored credential. A credential is the combination of a public/private key pair and a public x.509 certificate.

Alison-Server allows:

• The generation of credentials, protecting them with second-factor authentication (such as PIN and OTP).

• Use the credentials to create remote signatures in different formats.

Its REST interface allows managing the complete life cycle of a credential, and it may require the participation of the holder for some tasks, such as the renewal or re-issue of it.

Alison-Server has a modular

architecture, which allows defining several redundant modules to operate in high availability mode, with clusters replicated by means of a shared database.

Alison-Server is designed so the same instance can be shared between different

organisations. It is also possible to separate different users of the same

organisation into isolated groups.

Below are some fundamental terms that are useful to understand the configuration and architecture:

Alison-Server

It refers to the installation of a component (distributed in .WAR format) that must be installed on an Application Server, such as Wildfly or IBM WebSphere.It is also distributed as a docker image and is the recommended way to install itdistributed as a Docker component. Each component can manage several tenants.

Tenant

A Tenant defines the minimum control unit of Alison-Server, and it store certificates and credentials from related  end users.

Each credential is created within a Tenant, which usually represents a complete organizationorganisation.

A Tenant can contain credentials with certificates that were issued by different issuers (ACs) within the PKI of an organizationorganisation.

Alison-Server can manage several Tenants within its configuration and each of them managed with its own security policy.

Seat

A Seat represents an individual, holder of a credential. Each Seat belongs to a particular Tenant.

A Seat can contain several credentials.

Credential

A credential is the combination of a public/private key pair and an x.509 public certificate.

It is protected with second-factor authentication (OTP and PIN) to improve security.

Second Factor Authentication

An authentication factor is a piece of information used to verify the identity of an entity.

A second-factor authentication means that in order to access the protected resource (the credential) the user must have something to prove his identity. Alison-Server supports the use of PINs, OTPs or both.

OAuthClient

An OAuthClient is an application that can make use of Alison-Server services.

It must have a key (API-Key) that allows access to all Alison-Server resources.

Each OAuthClient has the following attributes: 

ClientId

An identifier of the client.

ClientSecret

A secret that is used to authenticate to the authorization server

Authorized Grant Types

The OAuth2 grant type that the client can use. Currently, only "client_credentials" is supported.

Access Token Validity

Defines the validity time (in seconds) of the generated token. Only values greater than 0 are accepted.

An example of this definition is below:

{ 
	"clientId": "acme",
	"clientSecret": "acme_password",
	"authorizedGrantTypes": "client_credentials",
	"accessTokenValidity": 3600 
}

Alison-Server protects its resources with OAuth2 mechanisms. In order to access any resource, it is necessary to send an authorization token, which is provided by an authorization server.

In order to get a token the following information must be sent:

ClientId

The ClientId that was used when creating the OAuthClient.

ClientSecret

The secret that was sent when creating the OAuthClient.

Grant Type

The OAuth2 grant type that will be used for authorization. Currently, only "client_credentials" is supported.

Scope

A string containing information of the seat and tenant that will be used in the following requests. Both seat and tenant are required.

The scope's format is:

seat:$value tenant:$value

All the information must be sent as form-data.

Example:

client_id		acme
client_secret	acme_password
grant_type		client_credentials
scope			seat:jdoe@acme

Tokens can be checked through the "check_token" service. This is useful to check if the token has expired before making a request to a service.

Tokens also can be revoked through the "revoke" service. When a token is revoked, it cannot be used again.

Any client application can create a credential following these steps:

1. Obtain an OAuth2 Token.

Client must obtain an OAuth2 token from Alison-Server to access any service. In this case a scope is not required.

2. Create a Credential.

When creating a credential it is mandatory to indicate an Authorization Configuration. A parameter indicating the number of Multi Signatures can be sent too.

Authorization Configuration

This configuration specifies the type of authorization (explicit, implicit and oauth2) and any extra configuration associated with the chosen type. For example, in explicit authorization you have to configure either OTP or PIN or both are required. The configuration is indicated passing the ID of the configuration.

Multi Signature

This value specifies the maximum number of signatures that can be created in one request. Default is 1.

3. Add Second Factors.

Once the credential is created, it is neccesary to add the required second factors according to the chosen configuration.

Credentials can be protected with PIN, OTP or both, but al least one of the second factors is required, otherwise the credential would be left unprotected. If more than one second factor is required, two calls to the service must be done indicating in each case the type of second factor that is being added.

PIN

When adding a PIN, a secret value must be specified. This value is the raw password that will be required when trying to access the credential.

OTP

When adding an OTP, no secret value must be specified because it is generated by the service. In the response the generated secret will be returned as well as any other information associated with the generated OTP, such as the issuer and the user.

After generating the secret it is neccesary to confirm that the OTP has successfully been retrieved. When confirming the OTP an OTP Value must be sent.

4. Generate Key Pair.

After all required Second Factors has been added a Key Pair can be generated. In this case the key algorithm and length must be sent, as well as the CSR signature algorithm. When generating the Key Pair, a CSR is returned. This CSR must be signed by a CA, in order to get a Certificate.

5. Add a Certificate.

Once the CSR has been signed by a CA and a Certificate is obtained, it must be asociated with the credential. The Certificate must be sent with the complete Certificate Chain (root, intermediate and end certificates). It has to be sent in PKCS7 format. If the end Certificate Public Key does not match the stored public key an error will be returned.

Any client application can create a signature follow these steps:

1. Obtain an OAuth2 Token.

Client must obtain an OAuth2 Token from Alison-Server to access any service. When requesting this token a scope must be specified. This scopes 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 list 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 differente attributes. Default 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 the 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 done with the SAD. This value must be less or equals to the number of multi signatures that the credential allows.
• hash: An array containg all the hashes to be signed. The number of hashes must be equals to numSignature.
• PIN: If the credential is protected with 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 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 used to hash the sent data. If not specified then the signAlgo must have the name of the hash algorithm.
• signAlgo: The algorithm that 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.

Alison Server requires several configurations. This configurations must be done in different places.

Environment Variables

Key that will be used when encrypting and decrypting a SAD.

Invent your own key and replace it.

Volumes

The following volumes must be mounted on the Docker image to overwrite the variables of each defined tenant.

Configuration File

This file contains properties that are used by Alison Server.

# DB
spring.datasource.url=jdbc:postgresql:your_url
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.datasource.driver-class-name=org.postgresql.Driver
spring.jpa.hibernate.ddl-auto=none
spring.jpa.properties.hibernate.dialect=com.certisur.alison.server.config.db.PostgreSQLDialectCustom

# HSM
alison.server.hsm.type=homo
alison.server.hsm.folder=/alison-server/hsm

# NTP
alison.server.ntp.url=time.google.com
alison.server.ntp.timeout_in_seconds=2
alison.server.ntp.sync_time_in_min=1

# AWS
alison.server.aws.enabled=false

DB: All the following values are used for database connection.

spring.datasource.url: The connection url of the database.

spring.datasource.username: User name to connect to the database.

spring.datasource.password: Password to connect to the database.

spring.datasource.driver-class-name: The full class name of the  database engine's driver.

spring.jpa.hibernate.ddl-auto: Should always be NONE.

spring.jpa.properties.hibernate.dialect= Should always be com.certisur.alison.server.config.db.PostgreSQLDialectCustom.

HSM: The place where private keys, public keys and certificates are stored.

alison.server.hsm.type: The type of HSM that server will create. Possible values are: homo, test, kms. In production kms should be configured.

alison.server.hsm.folder: Depending on the value of alison.server.hsm.type, this value must be completed. For values homo and kms, this value is required. It indicates where the hsm objects (public key, encrypted private key and certificate) will be stored.

NTP: All the following values are used for NTP server communication. When calculating a TOTP it is necessary to have a good synchronization of the time. To grant this synchronization a NTP server is used as reference for the current time.

alison.server.ntp.url: The url of the NTP server used to synchronize the time.

alison.server.ntp.timeout_in_seconds: Timeout of the connection with the NTP server. When a synchronization is being done, this is the maximum time to wait for the NTP server to respond.

alison.server.ntp.sync_time_in_min: Time to wait before a new synchronization with the NTP server is done.

AWS: Some features rely on the use of amazon services.

alison.server.aws.enabled: Turn to true if any amazon service is going to be used, for example, when alison.server.hsm.type=kms.

Follow this /wiki/spaces/ASP/pages/503414829.

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

OAuth2Client errors

Authorization errors