Signature Web Services API

This section describes how to configure the Signature Web Service (SWS) with the SafeNet IDPrime Virtual (IDPV) Server.

Overview

SWS allows the user to sign documents with a private key without the middleware/minidriver. This feature does not require the middleware or minidriver to be installed, user can configure the SWS APIs with any 3rd party application or service.

SWS APIs are based on Cloud Signature Consortium (CSC) standard.

CSC is a nonprofit association founded by industry and academic organizations to provide Cloud-based Digital Signatures, also defined as remote Electronic Signatures. Private keys are stored remotely in a secure environment, protected with hardware devices like Luna HSM, DPoD or KeySecure. For more information, refer to https://cloudsignatureconsortium.org/wp-content/uploads/2020/01/CSC_API_V1_1.0.4.0.pdf.

For detailed information about the SWS APIs, refer to Signature Web Service APIs Guide.

Setting up Signature Web Service

Perform the following steps to set the Signature Web Service:

1. Install IDPV server, refer to Installing SafeNet IDPrime Virtual Server section.

2. Create a tenant with parameter -c sws, refer to Creating a tenant section.

   For example:

   
       setuptenant/Thales.IDPrimeVirtual.SetupTenant create -i Config/idpconfiguration.json -p Config/policyconfiguration.json -k true (or false) –a "bd99baf5-0fd6-4ea2-87be-dfee484eb29a" -n sws -s Config/sws.json
     

Admin can access the provisioning API with the API key generated above.

By default, multiple tenant is disabled. To enable the multiple tenant support, set EnableSWSMultiTenant to true in the appsettings.yml file.

SWS is successfully set to perform API functions.

Prerequisites of Signature Web Service

The following prerequisites are required:

1. Login with provisioning admin.

2. Create a token for the user.

   Only one token per user is allowed.

3. Import PFX certificate in a token.

4. Mark provisioning complete for the token.

For detailed information, refer to Provisioning API Guide provided with the IDPV package.

Signature Web Service APIs

This section lists the SWS APIs methods. APIs methods return the values in json format.

Below figure shows the APIs methods and its layout with the IDPV server.

info

Returns information about the remote service and list of implemented API methods.

Input Parameter

This method allows the following parameter:

Parameter	Value	Description
X-IDPrimeVirtual-TenantId	String	The tenantId is provided in the X-IDPrimeVirtual-TenantId header if the multi-tenant flag is enabled. Type: Required Conditional

Output Parameter

This method returns the following parameters:

Output parameters are configured from CSCInfo.json file inside the docker container.

Parameter	Value	Description
specs	String	This provides the current IDPV release version.
name	String	* The commercial name of the remote service. * The maximum size of the string is 255 characters.
logo	String	* The URI of the image file containing the logo of the remote service, which is published online. * The image file is in JPEG or PNG format and not larger than 256x256 pixels.
lang	String	This supports en-US language only.
region	String	The code of the country where the remote service provider is established. For example, US for United States.
description	String	A free form description of the remote service in the lang language. The maximum size of the string is 255 characters.
multisign	Number ≥ 1 Number ≤ 25	* The multisign value is configured from appsettings.yml. The default value is 5 and can be configured up to maximum 25. * This feature allows end user to sign multiple documents in single login.
authType	Array of String	This supports the oauth2code authorization only.
oauth2	String	Add the Identity Provider Issuer URL in CSCInfo.json.
methods	Array of String	The following API methods are supported: > credentials/list > credentials/info > signatures/signHash

For example, https://idp.eu-staging.safenetid.com/auth/realms/47R8IUXGHT-STA

Sample Request

Sample Response

Credentials/list

Returns the list of credentialIDs (X509 certificates) associated to a user.

A user may have one or multiple credentials hosted by a single remote signing service provider.

Input Parameters

This method allows the following parameters:

Parameter	Value	Description
X-IDPrimeVirtual-TenantId	String	The tenantId is provided in the X-IDPrimeVirtual-TenantId header if the multi-tenant flag is enabled. Type: Required Conditional

Output Parameters

This method returns the following parameters:

Parameter	Value	Description
credentialIDs	Array of String	One or more credentialIDs associated with the JWT (JWT used for the authorization).

Sample Request

Sample Response

Credentials/Info

Retrieves the credential info and returns the main identity information and the public key certificate or the certificate chain associated to it.

Input Parameters

This method allows the following parameters:

Parameter	Value	Description
X-IDPrimeVirtual-TenantId	String	The tenantId is provided in the X-IDPrimeVirtual-TenantId header if the multi-tenant flag is enabled. Type: Required Conditional
credentialID	String	The unique credential identifier. Type: Mandatory
certificates	String none, single, chain	Specifies which certificates from the certificate chain is returned in certs/certificates. • none: No certificate is returned. • single: Only the bad entity certificate is returned. • chain: The full certificate chain is returned. Type: Optional
certInfo	Boolean	* Request to return various parameters containing information from the end entity certificate. * This is useful in case the signature application wants to retrieve some details of the certificate without decoding it first. * The default value is “false”, so if the parameter is omitted then the information is not returned. Type: Optional

Output Parameters

This method returns the following parameters:

Parameter	Value	Description
key/status	String, enabled, disabled	This is not supported.
key/algo	Array of String	The list of OIDs of the supported key algorithms. For example: 1.2.840.113549.1.1.1 = RSA encryption, 1.2.840.10045.4.3.2 = ECDSA with SHA256.
key/len	Number	The length of the cryptographic key in bits.
cert/certificates	Array of String	* If the certificates parameter is chain, the entire certificate chain is returned with the end entity certificate at the beginning of the array. * If the certificates parameter is single, only the end entity certificate is returned. * If the certificates parameter is none, this value is not returned.
cert/issuerDN	String	This value is returned when certInfo is true.
cert/serialNumber	String	This value is returned when certInfo is true.
cert/subjectDN	String	This value is returned when certInfo is true.
cert/validFrom	String	This value is returned when certInfo is true.
cert/validTo	String	This value is returned when certInfo is true.
authMode	String	This returns oauth2code authorization only.
multisign	Number ≥ 1 Number ≤ 25	* A number equal or higher to 1 representing the maximum number of signatures that can be created with this credential with a single authorization request. (For example, by calling credentials/signHash method or calling it multiple times.) * The value of numSignatures specified in the authorization request must not exceed the this value. * The multisign value is configured from appsettings.yml. The default value is 5 and can be configured up to maximum 25.

Sample Request

Sample Response

Signatures/signHash

This API calculates the remote digital signature of one or multiple hash values provided in input.

Input Parameters

This method allows the following parameters:

Parameter	Value	Description
X-IDPrimeVirtual-TenantId	String	The tenantId is provided in the X-IDPrimeVirtual-TenantId header if the multi-tenant flag is enabled. Type: Required Conditional
credentialID	String	The unique credential identifier. Type: Mandatory
SAD	String	* By Default, SAD validation is disabled. * Enable EnableSADValidation from appsettings.yml. If you enable EnableSADValidation then it is mandatory to provide a claim signing_hashes with a JWT access token. The value of this claim must be the list of hash array separated with a comma, which need to be signed. For example: signing_hashes: 6ROPONl5yBylKKmnPL2QiS90E0lrB2vGVezJNzJTaaQ=, 5Nz6fB9cO1q13sHLOAltdlVQ4KK9oSRbY+0evuIhOd4= Type: Required Conditional
hash	Array of String	One or more hash values is signed. This parameter contain the Base64-encoded raw message digest(s). For example: 6ROPONl5yBylKKmnPL2QiS90E0lrB2vGVezJNzJTaaQ=, 5Nz6fB9cO1q13sHLOAltdlVQ4KK9oSRbY+0evuIhOd4= Type: Mandatory
hashAlgo	String	This is not supported.
signAlgo	String	The following algorithm is only supported: 1.2.840.113549.1.1.11 Type: Mandatory
signAlgoParams	String	This is not supported.

Output Parameters

This method returns the following parameters:

Parameter	Value	Description
signatures	Array of String	One or more Base64-encoded signed hash(s). In case of multiple signatures, the signed hashes are returned in the same order as the corresponding hashes provided as an input parameter.

Sample Request

Sample Response