Document Version 6.6.0 - Ascertia · Service. The document assumes a reasonable knowledge of web application development, specifically RESTful Web services and ADSS Server. 1.3 Conventions

© 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



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

mailto:[email protected]

mailto:[email protected]



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.



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



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.



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

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx#pageid=creating_a_new_hardware_crypto_profile

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx#pageid=creating_a_new_hardware_crypto_profile

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx#pageid=alert_settings

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx#pageid=alert_settings

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=ars_service_configuration



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


• 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


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


• 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



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

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=creating_an_identity_profile

http://manuals.ascertia.com/ADSS-Admin-Guide/default.aspx?pageid=ra_profiles



Signing Profile


• 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



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





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.



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" }



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



Request Body {




"key_alias": "sample_cert_alias",

"key_length": "2048",

"key_algorithm": "RSA"

}


201 Created

200 Ok {

"error": "12345",

"error_description": "Detailed error message"

}

400 Bad Request {

"error": "12345",




}

403 Forbidden {

"error": "12345",


}

500 Internal Server

Error

{

"error": "12345",


}

Item Details

Name Description

Request Parameters


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



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



Request

Body

{




"subject_dn": "CN=Sample User"

}


200 Ok {

"csr": " MIICUzCCATsCAQAwDjEMMAoGA1……KJh"

}

400 Bad Request {

"error": "12345",


}

403 Forbidden {



"error": "12345",


}

500 Internal Server

Error

{

"error": "12345",


}

Item Details

Name Description

Request Parameters


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



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



Request Body {





"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"

}


200 Ok {




"transaction_id": "3213123213213213213"

}

400 Bad Request {

"error": "12345",


}

403 Forbidden {

"error": "12345",


}

500 Internal Server

Error

{

"error": "12345",


}

Item Details

Name Description

Request Parameters


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


transaction_id An identifier to be used later in the status request



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



Request Body {


"transaction_id": "3213123213213213213"

}


200 Ok {




"transaction_id": "3213123213213213213",

"status": "SIGNED",

"pkcs1_signature": "h5+Qp9fHwXwD…/kcefaz3caxJ",

"authorised_acf": "PEF1dGhv…xPcmlnaW5hdG9ySUQ+c"

}

400 Bad Request {

"error": "12345",


}

403 Forbidden {

"error": "12345",


}

500 Internal Server

Error

{

"error": "12345",


}

Item Details

Name Description

Request Parameters


transaction_id Transaction ID against which the status needs to be checked.

Response Parameters


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



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



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 ***

Documents

Document Version 6.6.0 - Ascertia · Service. The document assumes a reasonable knowledge of web application development, specifically RESTful Web services and ADSS Server. 1.3 Conventions