eSign API Specifications

Version 2.1
Feb 2023

Controller of Certifying Authorities

Ministry of Electronics and Information Technology
Document Control

Document Name eSign API Specifications

Status Release
Version 2.1
Release date 04.05.2018
Last update 07.02.2023
Document Owner Controller of Certifying Authorities, India

ii
Table of Contents
1. Introduction .............................................................................................................................. 1
1.1. Target Audience ......................................................................................................................... 2
1.2. Objective of the document ......................................................................................................... 2
1.3. Terminology ............................................................................................................................... 2
1.4. Legal Framework ........................................................................................................................ 3
2. Understanding eSign Service ..................................................................................................... 3
2.1. eSign Service at a glance ............................................................................................................. 3
3. eSign Service API ....................................................................................................................... 4
3.1. eSign - Usage scenarios ............................................................................................................... 4
3.1.1. eSign using e-KYC made by ESP ........................................................................................ 4
3.2. API Protocol - eSign Service......................................................................................................... 5
3.3. eSign API: Input Data Format - eSign Service ............................................................................... 6
3.3.1. eSign XML structure ......................................................................................................... 6
3.3.1.1. Element Details ......................................................................................................... 6
3.4. eSign API: Response Data Format - eSign Service ........................................................................ 9
3.4.1. Element Details ................................................................................................................ 9
3.4.2. Error Codes .................................................................................................................... 10
Change History................................................................................................................................ 12

iii
1. Introduction

Information Technology Act, 2000 grants legal recognition to electronic records and electronic
signatures. IT Act,2000 provides that where any law requires that information or any other matter
shall be authenticated by affixing signature then notwithstanding anything contained in the law,
such requirement shall be deemed to be fulfilled if such information is authenticated by means of
electronic signatures affixed in a manner prescribed by the Central Government. Under the IT Act,
2000, ’Electronic signatures’ means authentication of an electronic record by a subscriber by means
of electronic technique specified in second schedule and includes Digital signatures. Digital Signature
means authentication of any electronic record by a subscriber by means of procedure specified in
Section 3 of the IT Act, 2000.

The Controller exercises supervision over activities of Certifying Authorities and certifies public keys
of certifying authorities. The Certifying Authorities are granted licence under the IT Act, 2000 by the
Controller to issue Digital Signature Certificates. Any person can make an application to Certifying
Authority for issue of an Electronic signature Certificate in such form as may be prescribed by the
Central Government. For issuance of Digital Signature Certificates, the applicant’s Personal identity,
address and other details to be included in the DSC need to be verified by CAs against an identity
document. For class III, physical presence of the individual is also required. Digital Signatures are
widely used for authentication in the electronic environment. The cost of verification individual’s
identity and address and also the secure storage of private keys are the stumbling block in the
widespread usage of Digital Signature in the electronic environment.

X.509 Certificate Policy for India PKI states that the certificates will confirm that the information in
the application provided by the subscriber does not conflict with the information in well-recognized
consumer databases. The database of individual’s information maintained by e-KYC providers will be
used for eSign . The accepted e-KYC providers are listed in the e-authentication guidelines.

Verification of the Proof of Identity (PoI) and Proof of Address (PoA) is a pre-requisite for issuance of
Digital Signature Certificates by Certifying Authorities.

e-KYC Service providers can provide a paperless KYC experience by using e-KYC and avoid the cost of
repeated KYC, the cost of paper handling and storage, and the risk of forged documents. The real-
time e-KYC service makes it possible for service providers to provide instant service delivery to eSign
Users which otherwise would have taken a few days for activation based on the verification of KYC
documents, digitization, etc.
ESP and ASP have to make sure that mechanisms implemented for authentication of individuals
adhere to the guidelines of e-KYC provider

The Government has introduced Electronic Signature or Electronic Authentication Technique and
Procedure Rules, 2015 in which the technique known as “e-authentication technique using e-KYC
services” has been introduced to eliminate stumbling block in the widespread usage of Digital
Signature.

1
e-Sign facilitates digitally signing a document by an eSign user using an Online Service. While
authentication of the signer is carried out using e-KYC , the signature on the document is carried out
on a backend server, which is the e-Sign provider. The service shall be offered only by Certifying
Authorities. The eSign is an integrated service that facilitates issuing a Signature Certificate and
performing Signing of requested data on basis of authenticated e-KYC response. The eSign Service
shall be implemented in line with e-authentication guidelines issued by Controller. The certificate
issued through eSign service will have a limited validity period and is only for one-time signing of
requested data.

1.1. Target Audience

This is a technical document and is targeted at Application Service Providers who require signing of
digital document(s) in their application.

1.2. Objective of the document

This document provides eSign Service API specification. This includes API Data format, protocol and
other related specifications. eSign is designed for applying Digital Signature based on the response
received from e-KYC service.

1.3. Terminology
"eSign" or “eSign Service” is an online Electronic Signature Service in which the key pair generation,
certification of the public key by the CA and digital signature creation for electronic document are
facilitated by the eSign online Electronic Signature Service provider instantaneously within a single
online service based on successful authentication of individual using e-KYC services

"eSign User" is an individual requesting for eSign online Electronic Signature Service of eSign Service
provider. This individual shall be using the application of ASP and represents himself/herself for
signing the document under the legal framework. For the purposes of DSC by the CA, the eSign user
shall also be the ‘applicant/subscriber for digital certificate’, under the scope of IT Act.

"e-KYC" means the transfer of digitally signed demographic data such as Name, Address,
photograph etc of an individual. collected and verified by e-KYC provider on successful
authentication of same individual

"response code" is the identification number maintained by e-KYC provider to identify the
authentication

Application Service Provider (ASP): An organization or an entity using eSign service as part of their
application to digitally sign the content. Examples include Government Departments, Banks and
other public or private organizations. Currently there is no process of registration of ASP. ASP may
contact the ESP (eSign Service Provider) directly to avail the service within its framework.

eSign Service Provider (ESP): An organization or an entity providing eSign service. ESP is a “Trusted
Third Party”, as per the definitions of Second Schedule of Information Technology Act. ESP will
facilitate subscriber’s key pair-generation, storing of key pairs on hardware security module and
creation of digital signature. ESP must be/ integration with a CA for the purpose of obtaining
Signature Certificate for the generated Key-pair.

2
Certifying Authority (CA): An organization or an entity licensed under CCA for issuance of Digital
Certificate and carrying out allied CA operations.

e-KYC Number’ shall mean the unique identification number maintained by e-KYC
provider;

e-KYC provider shall mean any e-KYC provider listed in e-Authentication Guidelines

‘OTP’ shall mean one time password sent to the eSign User’s cell phone for the purpose of
authentication;

UIDAI: An authority established by Government of India to provide unique identity to all Indian
residents. It also runs the e-KYC authentication service for the registered KYC User Agency (KUA).

1.4. Legal Framework

eSign service will operate under the provisions of the Second Schedule of Information
Technology Act, 2000 ( e-authentication technique using Aadhaar e-KYC services) as notified
vide (notification details)

2. Understanding eSign Service

This chapter describes eSign Service, some of the envisioned usage scenarios, and working details.
Technical details follow in subsequent chapters.

2.1. eSign Service at a glance

3
3. eSign Service API
This chapter describes the API in detail including the service flow, communication protocol, and data
formats.

This API expects that authentication of the individual will be carried out by ESP and the digitally
signed e-KYC data is made available to ESP. The authentication needs to be carried out independent
of this API

The suggested method for obtaining authenticated e-KYC response is

ESP facilitates authentication of eSign user by calling authentication URL or ESP's SDK. The e-
KYC response will be received by ESP and performs eSign on the eSign request received from
ASP within permissible time limit.

3.1. eSign - Usage scenarios

The API specifications remain common for all eSign Service provider. However, the parameters
which will vary for each ESP are eSign Service URL and ASP ID (Unique User ID provided by the ESP).

In case of multiple eSign provider, ASP shall have the parameters configurable for each request. The
routing of requests to each APIs of ESP can be a round-robin, or a failure switchover, or an eSign user
selection basis, or any other manner implemented by ASP.

The eSign service API can be used in the scenario where

ASP initiates eSign request and ESP authenticates user for eKYC before eSign

3.1.1. eSign using e-KYC made by ESP

Flow of eSign process using this option:

In this scenario:
1. ASP client application asks eSign user to sign the document
2. ASP client application creates the document hash (to be signed) on the client side
3. ASP client application asks the eSign user to provide consent for certificate generation and
signature
4. ASP forms the input data for eSign API
5. ASP redirect to ESP's URL or uses ESP's SDK application and submit request XML
a. ESP validates the calling application and the input.
b. ESP verifies the Digital signature of ASP for eSign XML received
c. ESP logs the transaction

4
 d. ESP redirects eSign user to e- authentication page
e. ESP performs authentication and get e-KYC information from e-KYC provider
f. ESP show the document hash along with document information to eSign user.
g. ESP creates a new key pair and CSR for eSign user.
h. ESP calls the CA service and gets a Digital Signature Certificate for eSign user. The
certificate will be a e-KYC class Digital Signature Certificate, which has e-KYC
number, Name of the eSign user, e-KYC response code, Authentication Type, and
Time Stamp embedded.
i. ESP signs the ‘document hash’ and provides response XML to the ASP by redirecting
to ASP’s response URL.
6. ASP receives the document signature and the eSign user’s Digital Signature Certificate.
7. ASP client application attaches the signature to the document.
8. eSign user can accept or reject the signature and DSC

The web page flow for eSign using e-KYC made by ESP is as given below

3.2. API Protocol - eSign Service

eSign service is exposed as stateless service over HTTPS. Usage of open data format in XML and
widely used protocol such as HTTPS allows easy adoption and deployment of this service. To support
strong end to end security and avoid request tampering and man-in-the-middle attacks, it is
essential that the requests and responses are digitally signed.

The usage of HTTPS shall ensure transport layer encryption, while digital signing of XML shall ensure
integrity & authenticity of data.

5
Following is the URL format and the parameters for eSign service:
API URL ESP shall expose URL as under:
1. URL2: HTTPS redirect URL for requests where ESP has to perform
electronic KYC of eSign user.
Protocol HTTPS
Method POST
Content-Type “application/xml”
Post data A well-formed XML, as per the specifications provided in this
document.

ASP is required to collect the necessary API URL from the respective ESP.

3.3. eSign API: Input Data Format - eSign Service

eSign Service uses XML as the data format for input and output.

3.3.1. eSign XML structure

Following is the XML data format for eSign XML.

<Esign ver="" sc="" ts="" txn="" ekycId="" ekycIdType="" aspId=""

AuthMode="" responseSigType="" responseUrl="">
<Docs>
<InputHash id="" hashAlgorithm="" docInfo="">Document
Hash in Hex</InputHash>
</Docs>
<Signature>Digital signature of ASP</Signature>
</Esign>

3.3.1.1. Element Details

Element Name: Esign

• Description: Root element of the eSign xml
• Requirement of tag: Mandatory
• Value: Sub-elements
• Attributes: Table below

Sl No Attribute Required? Value

1. ver Mandatory eSign version (mandatory). ESP may host multiple
versions for supporting gradual migration. As of this
specification, API Version is “2.1”.
2. sc mandatory sc – (mandatory) ASP should have taken a clear
consent from ‘eSign user’ to carry on eSign from
their front ending application. This attribute
represents signatory’s explicit consent is obtained by
ASP for using the signatory’s identity and address
data received from e-KYC provider to, generate and
submit the electronic DSC application form to CA,
creation of key pairs by ESP for signatory, submission
of certificate to CA for certification, one time
creation of signature on the hash along with this
request, deletion of key pairs from the after applying

6
 signature. Only valid value is “Y”.

Check box[Y/N*] *No by default

3. ts Mandatory Request timestamp in ISO format.

The value should be in Indian Standard Time (IST),

and should be within the range of maximum 30
minutes deviation to support out of sync server
clocks.
4. txn Mandatory Transaction ID of the ASP calling the API, this is
logged and returned in the output for correlation
5. e-KYCIdType Mandatory This represents the type of e-KYC ID being used. The
value can be any one out of below:
1. Aadhaar = A
6. ekycId Optional If present, the value must be UID TOKEN.
ESP should process the request only if ekycId of
input XML and e-KYC authentication response are
same.
7. aspId Mandatory Organization ID issued by ESP to the ASP
8. AuthMode Mandatory Authentication Mode being used for e-KYC
Authentication, either to be performed by ESP, or as
already made by the ASP.

Allowed values are:

• OTP or TOTP = 1
• Fingerprint = 2
• IRIS = 3
• Face=4

Class of eSign Certificate will be “Single Factor” for

OTP based authentication. For Fingerprint and IRIS,
the class will be “Multi Factor”. These will be as per
definitions of “Class of Certificate” in India PKI-CP.
9. responseSigType Mandatory This value represents the response signature type,
where ASP can request for a specific type of
signature from one of the following

1. rawrsa
2. PKCS7(with only the signer certificate in the
certificate section and no revocation
information)
3. PKCS7pdf(all issuer certificates up to and
including root CA certificate and CRLs/OCSP
responses of each issuer certificates should be
included in the response. In case, the number
CRL entries are more than 5, only OCSP
responses are allowed. The signature should also
be time stamped using the time stamping
services of CA. The revocation information
should be included as a signed attribute under
pdfRevocationInfoArchival(1.2.840.113583.1.1.8)
4. PKCS7complete(All issuer certificates & its
revocation information in unsigned info)

7
 5. Rawecdsa
10. responseUrl Mandatory This is mandatory.
This should contain a valid HTTPS URL of the ASP, to
which ESP has to redirect back to ASP with response
XML.

Element Name: Docs

• Description: Contains one sub-element with Document Hash
• Requirement of tag: Mandatory
• Value: Sub-elements
• Attributes: Not applicable

Element Name: InputHash

• Description: Contains the value of Document Hash, which has to be signed.
• Requirement of tag: Mandatory
• Value: SHA256 hash value of the document in Hex format
• Attributes: Table below

Sl No Attribute Required? Value

1. id Mandatory This should be 1. Only single document hash is
allowed
2. hashAlgorithm Mandatory Should be fixed to “SHA256”
3. docInfo Mandatory Description for the respective document being
signed, not more than 50 characters.

docInfo should be strictly adhere to the content of

document. Multiple documents of same type or
different types should not be included in a single file.

Element Name: Signature

• Description: Contains the signature of ASP.
• Requirement of tag: Mandatory
• Value:
o Signed value of Input XML, as per the W3C recommendation on XML Signature
Syntax and Processing (Second Edition)
o Refer http://www.w3.org/TR/xmldsig-core/ for more information
• Attributes: Not applicable

If eSign user does not provide this explicit consent, application SHOULD NOT process data using
this API. ASP front-end application must ensure it takes an “explicit informed signatory’s consent”
authorizing the ESP to retrieve the resident data, DSC application form generation and submission,
key-pair generation, CSR request to CA, Digital Signature on the hash submitted and key pair
deletion after Digital Signature creation.

IMPORTANT NOTE: Digital Signature at e-KYC XML level is mandatory .The eSign request XML
should be digitally signed by ASP for authentication purposes.

8
3.4. eSign API: Response Data Format - eSign Service

Below is the response format of eSign Service API. Note that, the API does not give any identity
related data of the eSign user.

<EsignResp status="" ts="" txn="" resCode="" errCode="" errMsg="">

<UserX509Certificate>base64 value of eSign user certificate
(.cer)</UserX509Certificate>
<Signatures>
<DocSignature id="" sigHashAlgorithm="SHA256" error="">
Signature data in raw (PKCS#1) or raw( ECDSA ) or
PKCS7 (CMS) signature as requested
</DocSignature>
</DocSignature>
</Signatures>
<Signature>Signature of ESP</Signature>
</EsignResp>

ASP should provide mechanism to verify and accept the contents of DSC.

3.4.1. Element Details

Element Name: EsignResp

• Description: This element is the root element of the response and contains the meta values.
• Value: Sub-elements
• Attributes: Table below

Sl No Attribute Value
1. status In case of success, it will be “1”
In case of failure, it will be “0”
2. ts Will contain the response timestamp in ISO format.
3. txn The Transaction ID provided by ASP in the request.
4. resCode A unique response code provided by ESP. This is a unique id for
the transaction provided by ESP. It shall make the transaction
traceable, and ASP is expected to store this code in their audit log.
5. errCode In case of failure, this will contain the failure error code.
In case of success, it will be “NA”
6. errMsg In case of failure, this will contain a descriptive message against
the error code.
In case of success, it will be “NA”

Element Name: UserX509Certificate

• Description: This element will contain the Base 64 value of the Certificate. No private key
information is shared. For manual verification, this value can be copied and saved as .cer file
(With begin and end statements - PEM Format).
• Presence: Mandatory, if success.
• Value: Base 64 value of eSign user certificate (public).
• Attributes: Not Applicable

Element Name: Signatures

• Description: This element contains the sub-elements of signatures corresponding to
InputHash.

9
 • Presence: Mandatory, if success.
• Value: Sub-elements.
• Attributes: Not Applicable

Element Name: DocSignature

• Description: This element will contain the signed value which will be verifiable against
original document.
• Presence: Mandatory
• Value: Signed value in raw (PKCS#1) or raw( ECDSA ) or PKCS7 (CMS) signature format
as per the request XML.
• Attributes: Table Below

Sl No Attribute Value
1. Id Contains the corresponding ID to the Input Hash received
2. sigHashAlgorithm Should be fixed to “SHA256”
3. error In case of failure, this will contain the corresponding error

Element Name: Signature

• Description: This element will contain the signature of ESP, which can be used for
verification by ASP and protect the response from any kind of tamper.
• Value:
o Signed value of response XML, as per the W3C recommendation on XML Signature
Syntax and Processing (Second Edition)
o Refer http://www.w3.org/TR/xmldsig-core/ for more information
• Attributes: Not Applicable

3.4.2. Error Codes

The List of error codes are available at annexure 1. ASP can automate their application based on
prominent errors, in order to ease the flow for eSign user.

10
 Annexure 1
eSign Service -error codes
AADHAAR authentication errors relevant to ASP may be forwarded to ASP with respective error
codes. Please refer the latest error codes of UIDAI in Authentication API document

Sl Error Error message Originator

No Code
1. ESP-901 Invalid Authentication Mode ESP
2. ESP-902 Invalid ASP ID. It cannot be Empty ESP
3. ESP-903 Invalid ASP ID. It may not exist or may be inactive. ESP
4. ESP-905 Document Hash not received ESP
5. ESP-906 UID Token does not match ESP
6. ESP-907 Request Time Stamp cannot be Empty ESP
7. ESP-908 Request Time Stamp is not valid. Please check the server time. ESP
8. ESP-909 Transaction ID cannot be Empty ESP
9. ESP-910 Duplicate Transaction ID for the given ASP. ESP
10. ESP-911 Input XML Signature verification failed. ESP
11. ESP-922 Invalid Signature on Input XML. Please use the corresponding ESP
certificate mapped with ESP.
12. ESP-944 User terminated eKYC process ESP
13. ESP-945 User terminated eKYC process after OTP Generation ESP
14. ESP-946 User interface page expired ESP
15. ESP-991 ESP Database Connectivity Error ESP
16. ESP-992 Input XML Parsing Error. ESP
17. ESP-993 Error Parsing CA Response XML ESP
18. ESP-999 Unknown Error ESP

11
 Change History
Change History
Section Ver Date Modification
3.3.1.1. 2.1 10.08.2020 In the value field of "responseSigType", added PKCS7pdf &
PKCS7complete
3.3.1.1. 2.1 07.02.2023 Element Details (8) - Added Face authentication

12