A JavaScript variable XORKEESIGN will be available to the website which is accesses the G2C JavaScript API. If this is not available it indicates that the G2C extension is not installed or access has not been obtained for the website’s domain from Odyssey. All the required interfaces should be referred using this XORKEESIGN name space.

The G2C extension validates all the inputs from the caller which when not provided in the expected format will return an error to the caller. The extension also records custom messages detailing the error along with the name of the function called in the web browser's console to aid troubleshooting during the development.

The interfaces to sign or decrypt (the ones that access the user’s private key) need user’s consent in their xorkee app. The xorkee notification will carry the domain name of the host website and some additional information to clarify the context in which the API was invoked. The information presented in the xorkee app cannot be customized.

To identify the user, the API takes either the digital certificate or the xorkee handle of the user. The host site should obtain the user’s xorkee handle by framing an appropriate interface. The host site can then obtain the digital certificate of a user through the “XORKEESIGN.p7SignData” interface by providing the user’s handle. It is advised to capture and save the digital certificate of the user and then provide the digital certificate in later calls that need user’s consent.

If the interfaces to sign or decrypt are invoked with neither the digital certificate nor the xorkee handle, the API will display its own prompt to capture the xorkee handle from the user. This prompt will also have pointers to Odyssey website to download the xorkee app and obtain a handle.

1. Get Signer

This function is used to identify the signer through the xorkee handle or digital certificate and hence should be called before using any other function pertaining to PDF signing. As the signer should carry a qualified digital certificate to sign PDF documents, the extension also takes care of validating that before returning to the caller.

Function name

XORKEESIGN.getSigner

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const signer = await XORKEESIGN.getSigner();
														//'signer' contains information about the signer
														//should be preserved for use in subsequent calls
												}catch( [ errorCode , errorString , handle ] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.getSigner()
											.then( ( signer ) => {
														//'signer' contains information about the signer
														//should be preserved for use in subsequent calls
											})
											.catch( [ errorCode , errorString , handle ] ) => {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
											});
										
									

2. Initialize PDF signing

This function prepares the PDF for signing by adding signature related objects to the PDF and calculate and return the digest to be signed. If the host site permits more than one PDF document to be signed in a single call to the user, this function should be called once for each document.

The extension signs PDF with the signature status indicator (tick mark) in the bottom-left position of the signature by default.

Function name

XORKEESIGN.init

3. Sign PDF digest

This function gets the signature from the user (identified by the xorkee handle) through xorkee. It would suffice to call this function once even to get multiple signatures. To sign multiple documents in one go the signer should have a dual subscription (2 units/month) to xorkeesign. Other signers need to have only a standard subscription (1 unit/month).

Function name

XORKEESIGN.sign

4. Finalize PDF signing

The function packs the signature into the intermediate PDF (returned in XORKEESIGN.init) and make it final. As this function takes only one PDF and signature as input, it should be called multiple times when more than one document are signed in one go.

Function name

XORKEESIGN.finalize

Documents other than PDF can be signed in a standard compliant PKCS#7 signed data format (RFC 5652). The call includes an option to include the data in the signature (attached signature). Another option can be specified to include the signer’s certificate in the signature. The API verifies the signatures before returning them to the caller.

It is recommended to provide the certificate while calling the function, as the signature can be later verified against that certificate. When not provided the signature verification will be performed with the certificate that is available within the signature received from the user. When the certificate is not passed as input and also not available within the signature the host site should verify the signature before acting on the same. PKCS#7 signature verification is available in many programming languages and tools like OpenSSL for the site to independently validate if desired.

The signature can be computed over the document/data or just using a digest. Whenever the data is provided, the API computes the digest locally in the browser and sends only the digest to xorkeesign for signature. Currently only SHA2 digest algorithm is supported. The maximum size of the document/data that can be provided is 8 MB.

Apart from signing documents, consumers can build various useful solutions using PKCS#7 signatures. It can be used for authentication, HTML form signing, workflow management, user consent, etc. Depending upon the use case the data to be signed should be framed in a manner that suits the need.

Consumers planning to use digital signatures for authentication can extract the digital certificate and save them against a user identifier. Later at the time of login the user identifier can be used as the data to be signed and the user can be allowed to login only if the resulting signature verifies fine.

1. Sign data as PKCS#7

This function is used to sign the data in PKCS#7 signed data format whenever the signer has a qualified digital certificate. If the signer certificate is not available, the host site can prompt for the xorkee handle of the signer to pass as input to this function. The caller is provided with options to pack the data and the certificate (along with the complete certificate chain if necessary).

Function name

XORKEESIGN.p7SignData

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const [ signature , certificate , signerInfo ] = await XORKEESIGN.p7SignData( certificate , tbs , true , true , false );
														/*
															* 'signature' contains the PKCS#7 signature from the signer
															* 'certificate' is the digital certificate of the signer
															* this will be 'null' when the certificate is provided as input
															* 'signerInfo' contains information extracted from the signer's certificate
															*/
														
												} catch( [ errorCode , errorString , handle , subscriptionUrl ] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.p7SignData(certificate , tbs , true , true , false)
											.then( ( [ signature , certificate , signerInfo ] ) => {
												/*
												* 'signature' contains the PKCS#7 signature from the signer
												* 'certificate' is the digital certificate of the signer
												* this will be 'null' when the certificate is provided as input
												* 'signerInfo' contains information extracted from the signer's certificate
												*/
												//should be preserved for use in subsequent calls
											})
											.catch( [errorCode , errorString , handle , subscriptionUrl] ) => {
												//host site should take appropriate action based on the error code
												//error message can be displayed by the host site
											});
										
									

2. Sign digest as PKCS#7

This function is similar to the XORKEESIGN.p7SignDigest function where instead of the data we take the digest of the data as input. This would be useful in scenarios where the size of the data to be signed is greater than 8 MB. The host site can compute the digest at its server and send it to the web page to get the user’s signature.

If the host server can create the digest of a PDF document as per the PDF signature specifications, the signature from this function can be embedded into the document to form a signed PDF. To sign PDF documents the function should be invoked to include the digital certificate of the signer ie. the ‘includeCert’ argument should be true.

Function name

XORKEESIGN.p7SignDigest

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const [ signature , certificate , signerInfo ] = await XORKEESIGN.p7SignDigest( certificate , digest , true , false );
														/*
														* 'signature' contains the PKCS#7 signature from the signer
														* 'certificate' is the digital certificate of the signer
														* this will be 'null' when the certificate is provided as input
														* 'signerInfo' contains information extracted from the signer's certificate
														*/
												} catch( [ errorCode , errorString , handle , subscriptionUrl ] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.p7SignDigest(certificate , digest , true , false)
											.then( ( [ signature , certificate , signerInfo ] ) => {
												/*
												* 'signature' contains the PKCS#7 signature from the signer
												* 'certificate' is the digital certificate of the signer
												* this will be 'null' when the certificate is provided as input
												* 'signerInfo' contains information extracted from the signer's certificate
												*/
												//should be preserved for use in subsequent calls
											})
											.catch( [errorCode , errorString , handle , subscriptionUrl] ) => {
												//host site should take appropriate action based on the error code
												//error message can be displayed by the host site
											});
										
									

3. Sign multiple digests as PKCS#7

This function is similar to the XORKEESIGN.p7SignDigest function where multiple digests can be provided at the same time to get the signatures. The maximum number of digests that can be provided is 100. All the digests will be signed through a single notification to the user’s xorkee app. Apart from the regular subscription, one unit will be additionally charged for a user-signer to avail this facility.

Function name

XORKEESIGN.p7SignMultipleDigest

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const [ signatures , certificate , signerInfo ] = await XORKEESIGN.p7SignMultipleDigest( certificate , digest , true , false );
														/*
														* 'signatures' contains the PKCS#7 signatures from the signer
														* 'certificate' is the digital certificate of the signer
														* this will be 'null' when the certificate is provided as input
														* 'signerInfo' contains information extracted from the signer's certificate
														*/
												} catch( [ errorCode , errorString , handle , subscriptionUrl ] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.p7SignMultipleDigest(certificate , digest , true , false)
											.then( ( [ signatures , certificate , signerInfo ] ) => {
												/*
												* 'signatures' contains the PKCS#7 signature from the signer
												* 'certificate' is the digital certificate of the signer
												* this will be 'null' when the certificate is provided as input
												* 'signerInfo' contains information extracted from the signer's certificate
												*/
												//should be preserved for use in subsequent calls
											})
											.catch( [errorCode , errorString , handle , subscriptionUrl] ) => {
												//host site should take appropriate action based on the error code
												//error message can be displayed by the host site
											});
										
									

xorkeesign supports hybrid encryption following the PKCS#7 Enveloped Data Format (RFC 5652). Here the data is encrypted using AES-256 algorithm in GCM mode and the data encryption key is protected using RSA public keys (ie. the encryption certificate) of the intended recipients.

By principle and by design xorkeesign supports encryption only when the keys are certified by a public CA under the Indian CCA hierarchy. Moreover the encryption certificate holder should have a qualified signing certificate and a xorkee handle corresponding to the signing certificate. Both the signing and encryption certificates should be available in a cryptographic token (either same or different tokens).

The host site can query the encryption certificates that are under the possession of the user by providing the user's signing certificate to the API. On user's consent through xorkee, the API will return all the encryption certificates from the token carrying the signing certificate and any certificates found in any other USB tokens connected to the same system and the user will be allowed to choose one of the certificates. The encryption certificate that is chosen by the user can then be stored against the user identifier.

While mapping the encryption certificate against a user, it is advised to get the user's consent by means of a PKCS#7 signature using the XORKEESIGN.p7SignData or XORKEESIGN.p7SignDigest interfaces with the encryption certificate as the data to be signed. The host site should save the user consent against the user.

To encrypt the data, the encryption certificates of all the recipients (or the person whom the data is intended for) should be provided and the API will return a single PKCS#7 enveloped data encompassing all the information required to decrypt the same. Even here the encryption happens locally in the browser but the user's consent is not required as it involves only the public keys.

To decrypt the data, both the signing and encryption certificate of the recipient should be provided. The token carrying the decryption key and the signing key should be plugged into the same machine with the xorkee app and the data-encryption key will be decrypted once the user enters the token password. The actual data decryption will happen locally in the browser.

1. Get encryption certificates

To encrypt the data in hybrid format, the host site should have the encryption certificate of the recipient/user for whom the data is to be encrypted. This function gets all the encryption certificates available with the intended recipient. The recipient will be identified through the signing certificate.

The host site can list all the certificates to the user allowing her to choose the one that will be used for encryption. This function also returns a few information extracted from the certificate that can be presented to the user to aid her select a certificate.

Function name

XORKEESIGN.getEncryptionCerts

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const encCerts = await XORKEESIGN.getEncryptionCerts(signerCert);
														//'encCerts' is an array of objects
														//each object contains an encryption certificate
														//and a few other information extracted from the certificate
												}catch( [ errorCode , errorString , handle , subscriptionUrl] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.getEncryptionCerts(signerCert)
											.then( ( signerCert ) => {
												//'encCerts' is an array of objects
													//each object contains an encryption certificate
													//and a few other information extracted from the certificate
											})
											.catch( [ errorCode , errorString , handle , subscriptionUrl] ) => {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
											});
										
									

2. Encryption

The data will be encrypted using a AES-256 symmetric key and this data encryption key will be encrypted using the certificates of one or more recipients. The data encryption key will be generated internally in the function and will not be available to the caller. The encryption certificates fetched from the recipients using the XORKEESIGN.getEncryptionCerts interface should be saved by the host site and provided here as input.

User consent is not required for encryption as only the public keys are involved. It is up to the caller to carefully preserve the list of recipients and input the corresponding encryption certificate at the time of decryption.

Function name

XORKEESIGN.encrypt

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const encData = await XORKEESIGN.encrypt( data , encCerts );
														//'encData' contains the encrypted data in PKCS#7 enveloped data format
												}catch( [ errorCode , errorString , handle ] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.encrypt(data, encCerts)
											.then( ( encData ) => {
												//'encData' contains the encrypted data in PKCS#7 enveloped data format
											})
											.catch( [ errorCode , errorString , handle ] ) => {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
											});
										
									

3. Decryption

The PKCS#7 enveloped data can be decrypted using this function. The signing certificate will be used to identify the user/recipient and the encryption certificate will be used to identify the decryption key. Once the key is decrypted, the data decryption will happen locally in the browser. Even if there are multiple recipients, the presence of at least one recipient will be sufficient to decrypt the data.

Function name

XORKEESIGN.decrypt

Usage

										

											Copy to clipboard
										
										
											Method 1 (synchronous)
											try {
													const encData = await XORKEESIGN.decrypt( signerCert , encCert , encData );
														//'decData' contains the decrypted data in base 64 encoded format
												}catch( [ errorCode , errorString , handle ] ) {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
												}
											

											Method 2 (asynchronous)
											XORKEESIGN.decrpt( signerCert , encCert , encData )
											.then( ( decData ) => {
												//'decData' contains the decrypted data in base 64 encoded format
											})
											.catch( [ errorCode , errorString , handle , subscriptionUrl ] ) => {
														//host site should take appropriate action based on the error code
														//error message can be displayed by the host site
											});