© Ascertia Limited. All rights reserved. This document contains commercial-in-confidence material. It must not be disclosed to any third party without the written authority of Ascertia Limited.
Commercial-in-Confidence
A D S S A u t h o r i s e d R e m o t e S i g n i n g ( A R S )
D e v e l o p e r s G u i d e
AS C E RTI A LT D
F E B R U A R Y 2 0 2 0
D o c u m e n t V e r s i o n - 6 . 6 . 0 . 1
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 2 of 18
CONTENTS
1 INTRODUCTION ................................................................................................................................... 3
1.1 SCOPE ............................................................................................................................................ 3
1.2 INTENDED READERSHIP ................................................................................................................... 3
1.3 CONVENTIONS ................................................................................................................................. 3
1.4 TECHNICAL SUPPORT ....................................................................................................................... 3
2 ADSS ARS SERVICE OVERVIEW ...................................................................................................... 4
2.1 GO>SIGN MOBILE APP .................................................................................................................... 4
3 ARS SERVICE INTEGRATION ............................................................................................................ 6
4 CONFIGURING ADSS SERVER FOR AUTHORISED REMOTE SIGNING ....................................... 7
4.1 CONFIGURE HARDWARE CRYPTO SOURCE ....................................................................................... 7
4.2 CONFIGURE SMS SETTINGS ............................................................................................................ 7
4.3 ENABLE ARS FEATURE .................................................................................................................... 7
5 INTEGRATION USING ADSS RA AND ADSS SIGNING SERVICES ................................................ 8
6 SAMPLE PROGRAMS ....................................................................................................................... 10
7 INTEGRATION USING RESTFUL API .............................................................................................. 11
7.1 USER SERVICES ............................................................................................................................ 11
7.2 CERTIFICATE SERVICES ................................................................................................................. 12
7.3 SIGNING SERVICES ........................................................................................................................ 14
8 ERROR CODES.................................................................................................................................. 17
FIGURES
FIGURE 1 - ARS SERVICE & BUSINESS APPLICATION INTERACTION ....................................................................4
TABLES
TABLE 1 - REGISTER USER ........................................................................................................................... 12
TABLE 2 - GENERATE KEY PAIR..................................................................................................................... 13
TABLE 3 - GET CSR ..................................................................................................................................... 14
TABLE 4 - SIGNING REQUEST ........................................................................................................................ 15
TABLE 5 - STATUS REQUEST ......................................................................................................................... 16
TABLE 6 - ERROR CODES .............................................................................................................................. 18
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 3 of 18
1 Introduction
1.1 Scope This document provides information on how to integrate ADSS ARS Service in to your business application.
1.2 Intended Readership This guide is intended for developers who are integrating business applications with ADSS ARS Service. The document assumes a reasonable knowledge of web application development, specifically RESTful Web services and ADSS Server.
1.3 Conventions The following typographical conventions are used in this guide to help locate and identify information:
• Bold text identifies menu names, menu options, items you can click on the screen, file names, folder names, and keyboard keys.
• Courier New font identifies code and text that appears on the command line.
• Bold Courier New identifies commands that you are required to type in.
• Courier New font identifies Ajax request/response in HTTP message body.
1.4 Technical support If Technical Support is required, Ascertia has a dedicated support team providing debugging assistance, integration assistance and general customer support. Ascertia Support can be accessed in the following ways:
Website https://www.ascertia.com
Email [email protected]
Knowledge Base https://www.ascertia.com/products/knowledge-base/adss-server/
FAQs http://faqs.ascertia.com/display/ADSS/ADSS+Server+FAQs
In addition to the free support service describe above, Ascertia provides formal support agreements with all product sales. Please contact [email protected] for more details.
A Product Support Questionnaire should be completed to provide Ascertia Support with further information about your system environment. When requesting help, it is always important to confirm:
• System Platform details.
• ADSS Server version number and build date.
• Details of specific issue and the relevant steps taken to reproduce it.
• Database version and patch level.
• Product log files
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 4 of 18
2 ADSS ARS Service Overview ADSS Authorised Remote Signing (ARS) Service provides the capability to manage users and their signing keys. It provides the required API interface for business applications to register users, send hash signing requests, checking the status of pending signing requests and getting the signed hash (i.e. PKCS#1 signature).
ARS Service also provides a Signature Activation Module (SAM) which is the most important component of the ARS solution. This component is responsible for maintaining the details of registered users, authorised mobile devices, authorisation requests and their current statuses
Figure 1 - ARS Service & Business Application Interaction
Authorised Remote Signing (ARS) Service provides the required API interface for business applications to register the users, send hash signing requests, check the status of pending signing requests and get the signed hash (i.e. PKCS#1 signature).
ARS Service is basically a new service module which is deployed on the Ascertia's ADSS Server product. In ARS Service, the private keys of the users are held at server side in an HSM. To access these keys, the user must authorise the signing request on his/her mobile device. The user must sign an Authorisation Control File (ACF) on his/her mobile device with an authorisation key generated during the device registration process in the Go>Sign Mobile App. The ARS Service validates this signed ACF and other user credentials to access the document signing key and proceeds with signing the document/transaction.
2.1 Go>Sign Mobile App Go>Sign Mobile App gives users the ability to securely authorise and approve the signing of documents or transactions. Business applications can trigger the signing process and users can authorise this remotely from their mobile device using two-factor authentication.
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 5 of 18
2.1.1 Supported Devices
• Android version 6.0 and above.
• iOS version 9.0 and above.
Mobile device must have built-in finger print scanning feature.
Before accessing the Go>Sign Mobile App, the following tasks must be done:
• User must be registered in the ARS Service
• User’s device must be registered in the ARS Service
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 6 of 18
3 ARS Service Integration Business applications can integrate with ADSS ARS Service in the following ways:
• Using ADSS RA and Signing Services
• Using RESTful APIs
ADSS configurations are required for ARS service integration in above methods.
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 7 of 18
4 Configuring ADSS Server for Authorised Remote Signing
4.1 Configure Hardware Crypto Source In Authorised Remote Signing, all the keys for users will be held in an HSM so that’s why it is mandatory to have a hardware crypto source configured for the ARS Service. Follow ADSS Server Admin Guide to configure hardware crypto source.
4.2 Configure SMS Settings SMS settings must be enabled in ADSS Server because during the mobile device registration ADSS ARS service sends an OTP to the user’s registered mobile number for authentication. Follow ADSS Server Admin Guide to enable the SMS settings.
4.3 Enable ARS feature It is required to enable the ARS settings for the client who wants to use ARS Service.
Client Manager
• Launch the ADSS Server Console
• Navigate to Client Manager
• Select the client samples_test_client and click on Edit button.
• Click on the ARS Service tab
• Enable the check box Allow this client to access the ADSS ARS Service
• Select the Hardware Crypto profile
• Click on the Save button to have the changes take into effect
For more information about Client Manager, see the link:
http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=ars_service_configuration
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 8 of 18
5 Integration using ADSS RA and ADSS Signing Services In this integration mode, business application utilizes ADSS RA Service and Signing Service to register user, user’s qualified keys/certificate generation and document/transaction signing. Following configurations are required:
Certification Profile
• Launch the ADSS Server Console
• Navigate to Certification Service > Certification Profiles
• Create a new certification profile adss:certification:profile:002
o Under Request Details section enable the check box Allow authorise remote signing and configure the ARS Service address e.g. http://localhost:8777/adss/ars
o Under the Certificate Details section, select the hardware crypto profile (created for ARS in Key Manager earlier).
o Clicking on the Save button
• Navigate to Client Manager
o Select the client samples_test_client and click on Edit button.
o Go to Certification Service tab to assign the above created profile to the client
• Navigate to Certification Service > Service Manager to restart the Certification Service and have the changes take into effect
For more information about Certification Profile, see the link:
http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=creating_an_identity_profile
RA Profile
• Launch the ADSS Server Console
• Navigate to RA Service > RA Profiles
• Create/edit the RA profile adss:ra:profile:001
o Under the CA Details section change the Certification profile to e.g. adss:certification:profile:002 as created above
o Under the Certificate Details section enable the check box Allow auto-approval for web based requests (no manual approval required)
o Under the ARS Service Settings enable the check box Allow user registration through ARS Service and configure the ARS Service address accordingly e.g. http://localhost:8777/adss/ars
o Click on the Save button
• Navigate to Client Manager
o Select the client samples_test_client and click on Edit button.
o Go to RA Service tab to assign the above created/edited profile to the client
• Use the Service Manager to restart the RA Service and have the changes take into effect
For more information about RA profile, see the link:
http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=ra_profiles
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 9 of 18
Signing Profile
• Launch the ADSS Server Console
• Navigate to Signing Service > Signing Profiles
• Create/edit the signing profile adss:signing:profile:001
o Navigate to Advanced Settings tab
o Under Authorise Remote Signing section enable the check box Allow authorise remote signing and configure the ARS Service address e.g. http://localhost:8777/adss/ars
o Click on the Save button
• Navigate to Client Manager
o Select the client samples_test_client and click on Edit button.
o Go to Signing Service tab to assign the above created/edited profile to the client
• Use the Service Manager to restart the Signing Service and have the changes take effect
For more information about signing profile, see the link:
http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=step_3_-_configuring_a_signing_profile
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 10 of 18
6 Sample Programs After successfully configuring the ADSS Server, business application needs to perform the following operations:
• Register a user using RA Service
• Enroll User Signing Certificate using RA Service
• Perform the signing using Signing Service
• Check the status of the transaction
Two sample programs ARSRegisterUser.bat/sh and ARSSignPDF.bat/sh are added inside ADSS Client SDK package to simulate above operations.
• ARSRegisterUser.bat/sh registers users and generates qualified keys/certificate for the user.
• ARSSignPDF.bat/sh sends a signing request and then subsequent status calls.
The status of the transaction will be polled automatically by the sample program; it will remain shown PENDING unless it is AUTHORISED/DECLINED by the registered user from Go>Sign Mobile App or is EXPIRED. Once the signing transaction is authorized from the Go>Sign Mobile app, the status will be changed to approved and signed document is downloaded at location: [ADSS Client SDK Home]/API/samples/data/signing/test_input_signed.pdf
See ADSS-Developers-Guide for further explanation of the API used in samples.
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 11 of 18
7 Integration using RESTful API Business applications can integrate with ADSS ARS RESTful Services using standard HTTP messages.
7.1 User Services User services includes the following web service:
• Register User
7.1.1 Register User
Create a user in ARS Service. When a new user is created then response status ‘201’ is returned.
http://server:8777/adss/ars/v1/users/register
HTTP Verb PUT
Content-Type application/json
Accept application/json
Request Body {
"client_id": "samples_test_client",
"user_name": "John Doe",
"user_id": "johnDoe12",
"user_password": "password",
"user_email": "[email protected]",
"user_mobile": "00448007720442"
}
Status Code Message Response Body
201 Created
200 Ok { "error": "12345",
"error_description": "Detailed error message" }
400 Bad Request { "error": "12345", "error_description": "Detailed error message" }
403 Forbidden { "error": "12345", "error_description": "Detailed error message" }
500 Internal Server
Error
{ "error": "12345", "error_description": "Detailed error message" }
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 12 of 18
Item Details
Name Description
Request Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
user_name (Optional) User name an optional attribute used as friendly name for the registered
user in ARS service (max. 50 characters)
user_id User ID identifying the registered user in ARS service (max. 50 characters)
user_password Password for the registered user in ARS service (max. 50 characters)
user_email (Optional) Email for the registered user in ARS service (max. 100 characters)
user_mobile Mobile number for the registered user in ARS service. It will be used to send OTP for
device registration etc. (max. 100 characters)
Response Parameters
error The error code.
error_description Error description message
Table 1 - Register User
7.2 Certificate Services Certificate services includes the following web services:
• Generate Key Pair
• Get CSR
7.2.1 Generate Key Pair
Creates a key pair for the provided user in ARS Service. When a new key pair is created the response status ‘201’ is returned.
http://server:8777/adss/ars/v1/certification/keygen
HTTP Verb PUT
Content-Type application/json
Accept application/json
Request Body {
"client_id": "samples_test_client",
"user_id": "johnDoe12",
"user_password": "password",
"key_alias": "sample_cert_alias",
"key_length": "2048",
"key_algorithm": "RSA"
}
Status Code Message Response Body
201 Created
200 Ok {
"error": "12345",
"error_description": "Detailed error message"
}
400 Bad Request {
"error": "12345",
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 13 of 18
"error_description": "Detailed error message"
}
403 Forbidden {
"error": "12345",
"error_description": "Detailed error message"
}
500 Internal Server
Error
{
"error": "12345",
"error_description": "Detailed error message"
}
Item Details
Name Description
Request Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
user_id User ID identifying the registered user in ARS service.
user_password Password for the registered user in ARS service
key_alias Key Alias of key pair for which CSR to be generated
key_algorithm Supported values are “RSA” and “ECDSA”
key_length For “RSA” 1024, 2048, 3072, 4096, 8192 For “ECDSA” 192, 224, 256, 384, 521
Response Parameters
error The error code.
error_description Error description message
Table 2 - Generate Key Pair
7.2.2 Get CSR
Returns the base64 encoded CSR (Certificate Signing Request i.e. PKCS#10) of the key pair generated for the provided user.
http://server:8777/adss/ars/v1/certification/csr
HTTP Verb POST
Content-Type application/json
Accept application/json
Request
Body
{
"client_id": "samples_test_client",
"user_id": "johnDoe12",
"key_alias": "sample_cert_alias",
"subject_dn": "CN=Sample User"
}
Status Code Message Response Body
200 Ok {
"csr": " MIICUzCCATsCAQAwDjEMMAoGA1……KJh"
}
400 Bad Request {
"error": "12345",
"error_description": "Detailed error message"
}
403 Forbidden {
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 14 of 18
"error": "12345",
"error_description": "Detailed error message"
}
500 Internal Server
Error
{
"error": "12345",
"error_description": "Detailed error message"
}
Item Details
Name Description
Request Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
user_id User ID identifying the registered user in ARS service.
key_alias Key Alias of key pair for which CSR to be generated.
subject_dn Subject DN to be used in CSR
Response Parameters
csr Base 64 encoded CSR
error The error code.
error_description Error description message
Table 3 - Get CSR
7.3 Signing Services Signing services includes the following web services:
• Signing Request
• Status Request
7.3.1 Signing Request
Add a signing request to pending authorised requests queue.
http://server:8777/adss/ars/v1/signing/sign
HTTP Verb POST
Content-Type application/json
Accept application/json
Request Body {
"client_id": "samples_test_client",
"user_id": "johnDoe12",
"user_password": "password",
"key_alias": "sample_cert_alias",
"data_to_be_signed": "ATsCAQAwDjE=",
"data_to_be_displayed": "A pending signing request",
"document_id": "document_id_01",
"document_name": "This is a sample document"
}
Status Code Message Response Body
200 Ok {
"client_id": "samples_test_client",
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 15 of 18
"transaction_id": "3213123213213213213"
}
400 Bad Request {
"error": "12345",
"error_description": "Detailed error message"
}
403 Forbidden {
"error": "12345",
"error_description": "Detailed error message"
}
500 Internal Server
Error
{
"error": "12345",
"error_description": "Detailed error message"
}
Item Details
Name Description
Request Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
user_id User ID identifying the registered user in ARS service
user_password Password for the registered user in ARS service
key_alias Qualified signing key alias
data_to_be_signed Base 64 encoded data to be signed
data_to_be_displayed Message to be shown on the mobile device
document_id ID of the document to be signed
document_name Name of the document to be signed
Response Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
transaction_id An identifier to be used later in the status request
error The error code.
error_description Error description message
Table 4 - Signing Request
7.3.2 Status Request
Check the status of signing request and return a signature if computed by the service on behalf of the user.
http://server:8777/adss/ars/v1/signing/status
HTTP Verb POST
Content-Type application/json
Accept application/json
Request Body {
"client_id": "samples_test_client",
"transaction_id": "3213123213213213213"
}
Status Code Message Response Body
200 Ok {
"client_id": "samples_test_client",
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 16 of 18
"transaction_id": "3213123213213213213",
"status": "SIGNED",
"pkcs1_signature": "h5+Qp9fHwXwD…/kcefaz3caxJ",
"authorised_acf": "PEF1dGhv…xPcmlnaW5hdG9ySUQ+c"
}
400 Bad Request {
"error": "12345",
"error_description": "Detailed error message"
}
403 Forbidden {
"error": "12345",
"error_description": "Detailed error message"
}
500 Internal Server
Error
{
"error": "12345",
"error_description": "Detailed error message"
}
Item Details
Name Description
Request Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
transaction_id Transaction ID against which the status needs to be checked.
Response Parameters
client_id Client's Originator ID which is configured in ADSS Console > Client Manager
transaction_id Transaction ID against which the status is checked by the service.
status PENDING, SIGNED, EXPIRED, DECLINED
pkcs1_signature Base64 encoded PKCS#1 signature
authorised_acf Base64 encoded signed ACF
Table 5 - Status Request
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 17 of 18
8 Error Codes Errors
error error_description
58001 An internal error occurred while processing the request - see the ARS service debug logs for
details
58002 Failed to process request - ARS service is stopped
58003 Failed to process request - ARS service is not enabled in license
58004 Failed to process request - ARS service license has expired
58005 Failed to process request - ARS service is not enabled in system
58006 Failed to process request - ARS service is not allowed
58007 Failed to process request - Invalid
58008 Failed to process request - client does not exist
58009 Failed to process request - user does not exist
58010 Failed to process request - invalid password
58011 Failed to process request - user already exists
58012 Failed to process request - $param_name is missing
58013 Failed to process request - key alias does not exist
58014 Failed to process request - transaction ID does not exist
58015 Failed to validate authorisation control file - originator ID is missing
58016 Failed to validate authorisation control file - originator ID does not match with the originator ID
in request
58017 Failed to validate authorisation control file - user ID is missing
58018 Failed to validate authorisation control file - user ID does not match with the user ID in
request
58019 Failed to validate authorisation control file - valid from date is missing
58020 Failed to validate authorisation control file - valid from date has invalid format
58021 Failed to validate authorisation control file - validity period is not yet valid
58022 Failed to validate authorisation control file - valid to date is missing
58023 Failed to validate authorisation control file - valid to date has invalid format
58024 Failed to validate authorisation control file - validity period has expired
58025 Failed to validate authorisation control file - no signature found
58026 Failed to validate authorisation control file - digest algorithm or signature value is missing
58027 Failed to validate authorisation control file - signature is invalid
58028 Failed to validate authorisation control file - certificate ID is missing
58029 Failed to validate authorisation control file - certificate ID does not match with the certificate
ID in request
58030 Failed to validate authorisation control file - document hash is missing
58031 Failed to validate authorisation control file - document hash does not match with the
document hash in request
58032 A key pair with same alias already exists
58033 Failed to process request - user ID is invalid
58034 Failed to process request - user ID or password is invalid
58035 Failed to process request - certificate alias does not exist
58036 Failed to process request - client is inactive
58037 Failed to process request - user is inactive
58038 Failed to process request - signing key is inactive
58039 Failed to process request - $param_name exceeds the allowed limit
ADSS Authorised Remote Signing (ARS) - Developers Guide
© Ascertia Limited Commercial-in-Confidence Page 18 of 18
58040 Failed to process request - the license limit for user registration has reached
58041 ARS service user registration is not allowed
58042 Failed to process request - client_id is missing
58043 Failed to process request - user_id is missing
58044 Failed to process request - key_alias is missing
58045 Failed to process request - subject_dn is missing
58046 Failed to process request - user_password is missing
58047 Failed to process request - key_length is missing
58048 Failed to process request - key_algorithm is missing
58049 Failed to process request - request_data is missing
58050 Failed to process request - user_name is missing
58051 Failed to process request - data_to_be_signed is missing
58052 Failed to process request - password is missing
58053 Failed to process request - user_mobile is missing
58054 Failed to process request - key_alias exceeds the allowed limit
58055 Failed to process request - user_id exceeds the allowed limit
58056 Failed to process request - user_name exceeds the allowed limit
58057 Failed to process request - user_password exceeds the allowed limit
58058 Failed to process request - user_mobile exceeds the allowed limit
58059 Failed to process request - user_email exceeds the allowed limit
58060 Failed to process request - transaction_id is missing
Table 6 - Error Codes
*** End of document ***