document of pki component

The (n)Code PKI Component

Integration Manual

Overview of PKI Component

The (n)Code PKI Component provides line of business application with user authentication, digital signature & verification for data and files and asymmetric encryption/decryption based on PKI technologies & X.509 digital certificates. The document provides procedures and know-how required to PKI enable their application using this component. This procedure is application in scenarios where the PKI component is installed on a separate server of its own.

The document contains software & hardware component requirements for the server, description of various files which needs to be referred by the application, various operations performed by the PKI Component and descriptions of methods and parameters required to perform these operations.

Process description

Typically, PKI component is used for: 1) User Authentication 2) Data Signing & Verification and 3) File Signing & verification.

User Authentication is carried out using Data Signing procedures. It is required that a certificate is mapped to the user id of application beforehand. Processes are described in following sections. Actual integration details will follow these process descriptions.


Integration Manual

Database & Schema requirements

Provisions for storing details generated during the digital signature & verification process should be made before hand. Following three fields need to be defined in the database:

Sr.No. Field Description

1 Serial Number Serial Number is one of the attributes which represents a digital certificate uniquely. Recommended length of the field is 100.

2 Thumb Print Serial Number is one of the attributes which represents a digital certificate uniquely. Recommended length of the field is 100.

3 Signed Data The signature generated as the output of digital signature process. Its length typically is around 8000 characters. Recommended length is 9000 characters.

All of above fields are texts. The lengths of these fields are only indicative, based on outputs from digital certificates

issued by (n)Code Solutions CA. It should be tested with all CA certificates, in case the application wants to utilize certificates form CAs other then (n)Code Solutions as well.

Typically signed data is stored in LOB/CLOB fields. Each of these fields should be mapped against the record that was signed and needs to

be verified later. Each User should also be mapped to these fields. In case of file signing, it’s not required to store original files, as the signatures are

embedded in the file itself.


Integration Manual

User Certificate mapping

A. Typically done at time of registration or first login by the user. B. The user, at the time of registration is presented the certificate selection popup (ActiveX

Control). On selecting the certificate corresponding to the user, the username and corresponding thumbprint and the serial number along with the signed username are stored in the database corresponding to the particular user for verification on all subsequent occasions when the user goes through the above process. The authentication process expects parameters like serial number of certificate & thumb prints etc., which are not available at the time of registration.

C. User is presented with a certificate selection applet, which will list down all certificate passing criteria of allowed certifying authority, validity of dates & presence of complete certificate chain (CCA India CA ((n)Code Solutions CA) User Certificate.

D. User selects the certificate which is to be used with the application. This certificate must contain a private key, which will be used for data signing later & should be of correct class type ( Class II Or III ) as defined by the requirements of application.

E. User ID, passed by the application will be signed using the selected certificate. If the digital signature operation is completed correctly, the serial number of certificate, thumb print, the signed data & other parameters will be returned.

F. The application will store the signature, serial number & thumbprint against the user id, in the database fields, created for this purpose. Required fields are described later in the document.


Integration Manual

User Authentication

A. Every time the user logs in after registration, the aim is to identify the user by matching the signed string, thumbprint and the serial number stored during registration process, with those obtained from the current process, to carry out authentication. The serial number & thumb print should be available to the application as an output of the registration process. The user first enters his username and clicks the login button.

B. The ActiveX PKI Component will display certificate selection to the user. Once the user selects the certificate, its serial number will be verified against the one provided by the application.

C. If the serial numbers match, the user id provided by user for login will be signed using the certificate. It will be matched with the signature provided by the application & the signatures will be verified.

Data & file Signing

A. Whenever the data or a file has to be signed digitally, the application will call the ActiveX Component with required parameters and the data which is to be signed or the physical path of the file to be signed.

B. The ActiveX PKI component will display certificate selection popup to the user. Once the user selects the certificate with which the target file will be signed.

C. In case of file signing, a new file with “.p7sec” extension will be generated at the same path as that of the original file.

D. All specified parameter will be returned to the calling application.

Data & File Verification

A. Original data, the signature for the data generated during the digital signature process &

all other required parameters will be passed to the PKI Component on Server Side. B. In case of file verification, complete physical path of the file which is to be verified is

passed. In this case original file is not required. C. Extension of the file to be verified must be “.p7sec”. D. The data or the file is verified for integrity & authenticity of the data using the public key of

the user who has signed the data/file. E. If the verification is successful, success flag is returned along with other data to the

calling application. F. In case of file, the extension “.p7sec” can be optionally removed and the file is restored

with the original extension.


Integration Manual

Functions exposed by the ActiveX component

Map Certificate

MapCertificate(AKI As String, Class As String, Optional CertNumber As String) As String

Sr.No. Parameter Variable Name Data Type Mandatory?

1 Authority Key Identifier AKI String Yes. Pass (“0”)

2 Certificate class Class String Yes.

3 Certificate Serial Number SerialNumber String No

Note: For the first time when user logs in, use MapCertificate function and pass only AKI parameter inside the function. Function will give pop up to the end user/customer for certificate selection. After the successful login map/store users certificate serial number and thumbprint of particular user in the database.

For consecutive login use MapCertificate function and along with AKI pass the serial number stored in the database and the function will automatically map the certificate at the time of login without any pop-up to the user/customer.

At the time of next login component would check for the certificate in the client’s certificate with its private key exists, chain exists, time validity exists in MapCertificate function.

Note: In MapCertificate function pass “0” for both Class2 & Class 3 certificate.

Pass “1” for Class2 certificate only & pass “2” for Class3 certificate only.

e.g. MapCertificate(“0”,”1”,”999999”) for filtering ‘Class2’ certificate.


Integration Manual

Data signing

SignAnyData (signdata As String, Method As Integer, AKI As String, Optional CertNumber As String, Optional selectBox As Boolean, Optional CreateSignfile As Boolean) As String.


1 Data to be signed SignData String Yes

2 Method of Signing method Integer Yes

3 Authority Key Identifier AKI String Yes ( “” (blank string in case of data signing))

4 Cert Number CertNumber Text No. Defaults to null.

5 SelectionBox SelectBox boolean No. Defaults to True.

6 Create Sign File CreateSignFile boolean No. Defaults to false.

After SignAnyData function certain other customer’s certificate properties will be returned as follows:-

a.) SignMailID – Returns Customer’s mail id. b.) SignIssName – Returns Issuer name of the certificate. c.) SignSubjName – Returns Subject name of the certificate. d.) SignValidFrom – Returns ValidFrom date of the certificate. e.) SignVaidTo – Returns ValidTo date of the certificate. f.) SignThumbPrn – Returns Thumbprint of the certificate. g.) SignOwnerNm – Returns Owner name of the certificate. h.) SignSrNo – Returns the Serial number of the certificate. i.) pkey – Returns the Public key of the Customer’s certificate.


Integration Manual

File signing

SignAnyFile (filepath As String, Method As Integer, AKI As String, Optional CertNumber As String, Optional selectBox As Boolean, Optional CreateSignfile As Boolean) As String


1 File Path FilePath String Yes

2 Method of Signing method Int Yes. (0 for Attached Signing, 1 for Detached Signing)

3 Authority Key Identifier AKI String Yes ( “” (blank string in case of data signing))

4 Cert Number CertNumber Text No. Defaults to null.

5 SelectionBox SelectBox boolean No. Defaults to True.

6 Create Sign File CreateSignFile boolean Yes.


Integration Manual

Data verification

VerifyAnyData (strHash As String, Optional strContent As String, Optional Method As Integer, Optional CertValid As Boolean, Optional Certdisp As Boolean) As Boolean


1 Data to be Verified StrHash String Yes

2 Original Content StrContent String Mandatory for detached signing. Non-mandatory for attached signing.

3 Method of Verification method Int No

4 Cert Validity CertValid boolean Yes for signature and certificate, No for only signature.

5 Cert Display CertDisp boolean Defaults to No. (Yes for display Signing Certificate.)


Integration Manual

File verification

VerifyAnyFile (strHash As String, Optional filepath As String, Optional Method As Integer, Optional CertValid As Boolean, Optional Certdisp As Boolean, Optional killfile As Boolean) As Boolean


1 Signed File to be Verified (Path)

StrHash String Yes

2 Original Content filepath String Mandatory for detached signing. Non-mandatory for attached signing.

3 Method of Verification Method int 0 for Attached, 1 for Detached signing.

4 Cert Validity CertValid boolean Yes for signature and certificate, No for only signature.

5 Cert Display CertDisp boolean Defaults to No. (Yes for display Signing Certificate.)

6 Delete the Signed File. killfile boolean No. Defaults to false.


Integration Manual

Data Encryption

EncryptAnyData(strData As String, Optional CustSerialNumber As String, Optional selectBox As Boolean) As String


1 Data To Be Encrypted strData String Yes

2 Certificate Serial Number CustSerialNumber String No.

3 SelectionBox selectBox Boolean No. (Defaults to False.)

Note: EncryptAnyData function will return the encrypted data.

Also, after encryption certain other certificate properties will be returned as follows:-

1.) EncryptMailID – Returns Customer’s mail id. 2.) EncryptIssName – Returns Issuer name of the certificate. 3.) EncryptSubjName – Returns Subject name of the certificate. 4.) EncryptValidFrom – Returns ValidFrom date of the certificate. 5.) EncryptVaidTo – Returns ValidTo date of the certificate. 6.) EncryptThumbPrn – Returns Thumbprint of the certificate. 7.) EncryptOwnerNm – Returns Owner name of the certificate. 8.) EncryptSrNo – Returns the Serial number of the certificate.

Note: User can store all the properties returned into its database as per requirement for future use.


Integration Manual

Data Decryption

DecryptAnyData(strEnc As String, Serial As String) As String


1 Encrypted Data strEnc String Yes

2 Serial Number Serial String Yes

Note: DecrypAnytData function will return the decrypted data.

Also, after decryption certain other certificate properties will be returned as follows:-

1.) DecryptMailID – Returns Customer’s mail id. 2.) DecryptIssName – Returns Issuer name of the certificate. 3.) DecryptSubjName – Returns Subject name of the certificate. 4.) DecryptValidFrom – Returns ValidFrom date of the certificate. 5.) DecryptVaidTo – Returns ValidTo date of the certificate. 6.) DecryptThumbPrn – Returns Thumbprint of the certificate. 7.) DecryptOwnerNm – Returns Owner name of the certificate. 8.) DecryptSrNo – Returns the Serial number of the certificate.


Integration Manual

File Encryption

EncryptAnyFile(filepath As String, CertNumber As String, Optional selectBox As Boolean) As String


1 Path of file filepath String Yes

2 Certificate Serial Number CertNumber String Yes

3 Select Box selectBox Boolean No.

Note: EncryptAnyFile function will create an encrypted file with “.enc” extension.

Also, after file encryption certain other certificate properties will be returned as follows:-

1.) EncryptMailID – Returns Customer’s mail id. 2.) EncryptIssName – Returns Issuer name of the certificate. 3.) EncryptSubjName – Returns Subject name of the certificate. 4.) EncryptValidFrom – Returns ValidFrom date of the certificate. 5.) EncryptVaidTo – Returns ValidTo date of the certificate. 6.) EncryptThumbPrn – Returns Thumbprint of the certificate. 7.) EncryptOwnerNm – Returns Owner name of the certificate. 8.) EncryptSrNo – Returns the Serial number of the certificate.


Integration Manual

File Decryption

DecryptAnyFile(strEnc As String, Optional filepath As String) As String


1 Encrypted File to be Decrypted (Full Path)

strEnc String Yes

2 Path of File filepath String No

Note: DecryptAnyFile function will decrypt file and create the original file.


Integration Manual

Technical requirements

Server Requirements

Sr.No. Component Supported Platforms

1 Operating System Windows 2000 Server/Windows 2003 Server

2 Web/Application Server IIS 5.5 & Above

Client Requirements

Sr.No. Component Supported Platforms

1 Operating System Windows 2000/2003/XP/VISTA

2 Browser IE 6.0/7.0


Integration Manual

Process of using PKI Signing Component with Application

(n)Code Solutions’ PKI Signing Component is an ActiveX Control that has to be integrated with any web application .The component can be used for Data/Form signing and verification and File singing and verification purpose.

In order to provide better control over the process it is desirable that every user of the application is mapped to a unique certificate and the use of certificate is restricted by checking the serial number and thumbprint stored in the database with the one used for singing or verification operations.


Integration Manual

Integration Process

1. Copy nCode.CAB and nCode.html in the same folder where the pages which are going to use digital signatures reside.

2. Add a reference to nCode.Ocx file in the ASP.Net Web Application project.

3. Include nCode.cab into the web application project.

4. Open the nCode.html file in notepad, copy the object tag

Eg: <OBJECT ID="LRADemo"

CLASSID="CLSID:CF05C12C-9B97-4A86-A6D1-B82371D07C3C"

CODEBASE="nCode.CAB#version=1,0,0,0">

</OBJECT>

and paste it under the head tag of the .ASPX page which is using PKI Component as shown in the demo application.

5. Component can be invoked using Javascript in your application.

For e.g.: var obj = new ActiveXObject("nCode.LRADemo");

After invoking the ActiveX control, all the methods of the component can be accessed. For e.g.: var s1 = obj.SignAnyData(arg1,arg2,arg3);

6. PKI Component is ready to be used by invoking appropriate methods and accessing required properties.

7. Please refer the demo application for further clarification.


Integration Manual

For further information, please contact:

(n)Code Solutions - A division of GNFC Limited-IT Division

301, GNFC Info Tower, S.G.Road, Bodakdev, Ahmedabad :-380 054 Phone: - 91-79-26857311/12/13 Email: - [email protected]

URL :- https://www.ncodesolutions.com

document of pki component

Documents