The (n)Code PKI Component

Integration Manual
OverviewofPKIComponent
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.

Processdescription
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.

The (n)Code PKI Component

Integration Manual

Database&Schemarequirements

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

Serial Number

Serial Number is one of the attributes which

represents
a
digital
certificate
uniquely.
Recommended length of the field is 100.

Thumb Print

Serial Number is one of the attributes which

represents
a
digital
certificate
uniquely.
Recommended length of the field is 100.

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, its not required to store original files, as the signatures are
embedded in the file itself.

The (n)Code PKI Component

Integration Manual

UserCertificatemapping
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.

The (n)Code PKI Component

Integration Manual

UserAuthentication
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&fileSigning
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&FileVerification
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.

The (n)Code PKI Component

Integration Manual
FunctionsexposedbytheActiveXcomponent
MapCertificate

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

Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Authority Key Identifier

AKI

String

Yes. Pass (0)

Certificate class

Class

String

Yes.

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 clients 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.

The (n)Code PKI Component

Integration Manual
Datasigning

SignAnyData (signdata As String, Method As Integer, AKI As String, Optional CertNumber

As String, Optional selectBox As Boolean, Optional CreateSignfile As Boolean) As String.

Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Data to be signed

SignData

String

Yes

Method of Signing

method

Integer

Yes

Authority Key Identifier

AKI

String

Yes ( (blank
string in case of
data signing))

Cert Number

CertNumber

Text

No. Defaults to
null.

SelectionBox

SelectBox

boolean

No. Defaults to
True.

Create Sign File

CreateSignFile

boolean

No. Defaults to
false.

After SignAnyData function certain other customers certificate properties will be returned
as follows:a.)
b.)
c.)
d.)
e.)
f.)
g.)
h.)
i.)

SignMailID Returns Customers mail id.

SignIssName Returns Issuer name of the certificate.
SignSubjName Returns Subject name of the certificate.
SignValidFrom Returns ValidFrom date of the certificate.
SignVaidTo Returns ValidTo date of the certificate.
SignThumbPrn Returns Thumbprint of the certificate.
SignOwnerNm Returns Owner name of the certificate.
SignSrNo Returns the Serial number of the certificate.
pkey Returns the Public key of the Customers certificate.

The (n)Code PKI Component

Integration Manual

Filesigning

SignAnyFile (filepath As String, Method As Integer, AKI As String, Optional CertNumber As

String, Optional selectBox As Boolean, Optional CreateSignfile As Boolean) As String

Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

File Path

FilePath

String

Yes

Method of Signing

method

Int

Yes.
(0
for
Attached Signing,
1 for Detached
Signing)

Authority Key Identifier

AKI

String

Yes ( (blank
string in case of
data signing))

Cert Number

CertNumber

Text

No. Defaults to
null.

SelectionBox

SelectBox

boolean

No. Defaults to
True.

Create Sign File

CreateSignFile

boolean

Yes.

The (n)Code PKI Component

Integration Manual

Dataverification

VerifyAnyData (strHash As String, Optional strContent As String, Optional Method As

Integer, Optional CertValid As Boolean, Optional Certdisp As Boolean) As Boolean

Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Data to be Verified

StrHash

String

Yes

Original Content

StrContent

String

Mandatory
for
detached signing.
Non-mandatory
for
attached
signing.

Method of Verification

method

Int

No

Cert Validity

CertValid

boolean

Yes for signature

and
certificate,
No
for
only
signature.

Cert Display

CertDisp

boolean

Defaults to No.
(Yes for display
Signing
Certificate.)

The (n)Code PKI Component

Integration Manual

Fileverification

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
Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Signed File to be Verified

(Path)

StrHash

String

Yes

Original Content

filepath

String

Mandatory
for
detached signing.
Non-mandatory
for
attached
signing.

Method of Verification

Method

int

0 for Attached, 1
for
Detached
signing.

Cert Validity

CertValid

boolean

Yes for signature

and
certificate,
No
for
only
signature.

Cert Display

CertDisp

boolean

Defaults to No.
(Yes for display
Signing
Certificate.)

Delete the Signed File.

killfile

boolean

No. Defaults to
false.

The (n)Code PKI Component

Integration Manual
DataEncryption
EncryptAnyData(strData As String, Optional CustSerialNumber As String, Optional
selectBox As Boolean) As String
Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Data To Be Encrypted

strData

String

Yes

Certificate Serial Number

CustSerialNumber

String

No.

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.)
2.)
3.)
4.)
5.)
6.)
7.)
8.)

EncryptMailID Returns Customers mail id.

EncryptIssName Returns Issuer name of the certificate.
EncryptSubjName Returns Subject name of the certificate.
EncryptValidFrom Returns ValidFrom date of the certificate.
EncryptVaidTo Returns ValidTo date of the certificate.
EncryptThumbPrn Returns Thumbprint of the certificate.
EncryptOwnerNm Returns Owner name of the certificate.
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.

The (n)Code PKI Component

Integration Manual

DataDecryption
DecryptAnyData(strEnc As String, Serial As String) As String
Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Encrypted Data

strEnc

String

Yes

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.)
2.)
3.)
4.)
5.)
6.)
7.)
8.)

DecryptMailID Returns Customers mail id.

DecryptIssName Returns Issuer name of the certificate.
DecryptSubjName Returns Subject name of the certificate.
DecryptValidFrom Returns ValidFrom date of the certificate.
DecryptVaidTo Returns ValidTo date of the certificate.
DecryptThumbPrn Returns Thumbprint of the certificate.
DecryptOwnerNm Returns Owner name of the certificate.
DecryptSrNo Returns the Serial number of the certificate.

The (n)Code PKI Component

Integration Manual
FileEncryption
EncryptAnyFile(filepath As String, CertNumber As String, Optional selectBox As Boolean)
As String
Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Path of file

filepath

String

Yes

Certificate Serial Number

CertNumber

String

Yes

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.)
2.)
3.)
4.)
5.)
6.)
7.)
8.)

EncryptMailID Returns Customers mail id.

EncryptIssName Returns Issuer name of the certificate.
EncryptSubjName Returns Subject name of the certificate.
EncryptValidFrom Returns ValidFrom date of the certificate.
EncryptVaidTo Returns ValidTo date of the certificate.
EncryptThumbPrn Returns Thumbprint of the certificate.
EncryptOwnerNm Returns Owner name of the certificate.
EncryptSrNo Returns the Serial number of the certificate.

The (n)Code PKI Component

Integration Manual
FileDecryption
DecryptAnyFile(strEnc As String, Optional filepath As String) As String
Sr.No.

Parameter

Variable Name

Data Type

Mandatory?

Encrypted File to be
Decrypted (Full Path)

strEnc

String

Yes

Path of File

filepath

String

No

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

The (n)Code PKI Component

Integration Manual

Technicalrequirements

ServerRequirements
Sr.No.

Component

Supported Platforms

Operating System

Windows
Server/Windows
Server

Web/Application Server

IIS 5.5 & Above

2000
2003

ClientRequirements
Sr.No.

Component

Supported Platforms

Operating System

Windows 2000/2003/XP/VISTA

Browser

IE 6.0/7.0

The (n)Code PKI Component

Integration Manual

ProcessofusingPKISigningComponentwithApplication

(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.

The (n)Code PKI Component

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.

The (n)Code PKI Component

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: - rrkaranjgaokar@gnvfc.net
URL :- https://www.ncodesolutions.com