Zanjia Electronic Science and Technology HSM-ZJ2014 Hardware Security Module User Manual HSM ZJ2014 x

Zanjia Electronic Science & Technology (Beijing) Co., Ltd. Hardware Security Module HSM ZJ2014 x

2ADTB-HSM-ZJ2014 user manual



Zanjia Electronic Science & Technology (Beijing) Co., LTD

HSM-ZJ2014

Guidance Documentation

Level 3 Validation

November 2013

reserved.This is a private document and cannot be distributed.]



Table of Contents

1.Document Overview..........................................................................................................1

2.Product Introduction..........................................................................................................2

2.1.Major Function.......................................................................................................2

2.2.Packing List............................................................................................................2

2.3.Parameter Information............................................................................................3

2.4.Approved Mode of Operation................................................................................4

2.5.Service Delivery Channel.......................................................................................5

2.6.Compatible Standard..............................................................................................5

2.7.Installation Condition.............................................................................................5

2.8.Schematic Diagram................................................................................................6

2.9.Installation Instructions..........................................................................................7

3.HSM Operation Guide.......................................................................................................8

3.1.Create Crypto Officer.............................................................................................8

3.2.Initialize................................................................................................................14

3.2.1.Master Key is Not Generated...........................................................................14

3.2.2.Master Key is generated...................................................................................21

3.3.Modify Smart Card PIN.......................................................................................26

3.4.Shut Down the HSM............................................................................................30

3.5.Error Message.......................................................................................................31

4.Remote Management Application...................................................................................34

4.1.Crypto Officer Logon User Interface...................................................................34

4.2.Device Manager User Interface............................................................................36

4.2.1.User Account and Key Management................................................................37

4.2.2.IP Address Action Table Configuration...........................................................59

4.2.3.Network Configuration.....................................................................................64

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD4

4.3.Auditor User Interface..........................................................................................65

4.3.1.View Audit Log................................................................................................66

4.3.2.Export Audit Log..............................................................................................67

5.Client Guide....................................................................................................................68

5.1.Supported Operating Systems..............................................................................69

5.2.Supported PKCS#11 Function.............................................................................69

5.2.1Library Initialization.........................................................................................69

5.2.2Library Finalization..........................................................................................69

5.2.3Get Library Information...................................................................................69

5.2.4Get Function List..............................................................................................70

5.2.5Get Slot List......................................................................................................71

5.2.6Get Slot Information.........................................................................................72

5.2.7Get Mechanism List..........................................................................................73

5.2.8Get Mechanism Information.............................................................................74

5.2.9Open Session....................................................................................................75

5.2.10Close Session....................................................................................................75

5.2.11Close All Sessions............................................................................................75

5.2.12Login.................................................................................................................76

5.2.13Logout...............................................................................................................77

5.2.14Create Object....................................................................................................77

5.2.15Destroy Object..................................................................................................79

5.2.16Get Attribute Value..........................................................................................79

5.2.17Set Attribute Value...........................................................................................80

5.2.18Find Objects Initialization................................................................................81

5.2.19Find Objects......................................................................................................82

5.2.20Find Objects Finalization..................................................................................82

5.2.21Encryption Initialization...................................................................................83

5.2.22Encrypt.............................................................................................................83

5.2.23Encrypt Update.................................................................................................84

5.2.24Encryption Finalization....................................................................................84

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD5

5.2.25Decryption Initialization...................................................................................86

5.2.26Decrypt.............................................................................................................87

5.2.27Decrypt Update.................................................................................................87

5.2.28Decrypt Finalization.........................................................................................88

5.2.29Hash Initialization.............................................................................................90

5.2.30Hash..................................................................................................................90

5.2.31Hash Update.....................................................................................................90

5.2.32Hash Finalization..............................................................................................91

5.2.33Signing Initialization........................................................................................92

5.2.34Signing..............................................................................................................93

5.2.35Signing Update.................................................................................................93

5.2.36Signing Finalization..........................................................................................94

5.2.37Verification Initialization.................................................................................95

5.2.38Verification.......................................................................................................95

5.2.39Verification Update..........................................................................................96

5.2.40Verification Finalization...................................................................................96

5.2.41Take Random number as Seed.........................................................................97

5.2.42Generate Random Number...............................................................................98



1. Document Overview

This is a guidance document developed for HSM-ZJ2014 from Zanjia

Electronic Science & Technology (Beijing) Co., LTD. It describes the

detailed information of HSM-ZJ2014 and demonstrates how to install and

use it after leaving factory. In this document, the HSM-ZJ2014 is also

referred to as “the HSM”.

Note:

This equipment has been tested and found to comply with the limits for a

Class B digital device, pursuant to part 15 of the FCC Rules. These limits

are designed to provide reasonable protection against harmful

interference in a residential installation. This equipment generates, uses

and can radiate radio frequency energy and, if not installed and used in

accordance with the instructions, may cause harmful interference to radio

communications. However, there is no guarantee that interference will not

occur in a particular installation. If this equipment does cause harmful

interference to radio or television reception, which can be determined by

turning the equipment off and on, the user is encouraged to try to correct

the interference by one or more of the following measures:

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD2

—Reorient or relocate the receiving antenna.

—Increase the separation between the equipment and receiver.

—Connect the equipment into an outlet on a circuit different from that to

which the receiver is connected.

—Consult the dealer or an experienced radio/TV technician for help.

2. Product Introduction

2.1. Major Function

HSM-ZJ2014 provides cryptographic services, including encryption,

decryption, signature generation and verification, and key management

service with various hardware protection mechanisms for its security. The

HSM also provides standard interfaces of cryptographic services

including PKCS #11. In addition, a modular design makes it convenient

to integrate HSM-ZJ2014 with existing information systems.

2.2. Packing List

Table 1 Packing List of HSM-ZJ2014

Component Quantity

HSM-ZJ2014 1

Directly Connected Ethernet Cable(Grey) 1

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD3

Crossover Ethernet Cable(Blue) 1

Fiber Optic Cable 1

Manufacturer's Certificate 1

Packing List 1

Power Line 2

User Guide 1

Crypto Officer Smart Card 8

Product CD 1

Note: this list is only for reference, the packing list in the packing box shall

prevail.

2.3. Parameter Information

Table 2 Parameter Information of HSM-ZJ2014

Parameter Value

1. Physical

Specification 4U

Dimensions(Width× Height× Length) 400mm×177mm×490mm

2. Electrical

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD4

Power Supply 220V, 50Hz

Power Dissipation 620W

Network Interface RJ-45 10/100/1000Mb ×2

Fiber Optic×2

Network Protocol TCP/IP

MTBF >50000 hours

3. Environment

Working Temperature 0℃-40℃

Working Humidity 25%-80%

Storage Temperature -10℃-55℃

2.4. Approved Mode of Operation

The HSM-ZJ2014provides the following approved mode algorithms:

 AES (ECB and CBC mode, 128/192/256-bit, encryption and

decryption)

 ECDSA (NIST p256, signature generation/verification)

 RSA (2048-bit, signature generation/verification)

 SHA-256

 HMAC (HMAC-SHA-256)

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD5

 CTR-DRBG based on 256-bit AES

2.5. Service DeliveryChannel

 Ethernet：10M/100M/1000M Self-Adapt, 10000M Fiber Optic

 Based on TCP/IP

2.6. Compatible Standard

 AES (ECB and CBC mode; 256 bit keys):NIST 197, SP 800-38A;

 RSA(2048bit): FIPS 186-4, PKCS#1 v2.1;

 ECDSA(NIST P-256): FIPS 186-4;

 SHA-256: FIPS 180-4, SP-800-107 Rev.1;

 HMAC(SHA-256):FIPS 198-1, SP-800-107 Rev.1;

 DRBG(CTR_DRBGAES256): SP 800-90A;

 Key Generation: SP 800-133.

2.7. Installation Condition

Before Installation，please make sure：

1. The equipment you receive are intact and correspond with Detailed

List;

2. Power Switch is OFF;

3. Input voltage keeps within 220V10%.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD6

2.8. Schematic Diagram

Front Panel:



Figure 1 Front View of HSM-ZJ2014

Rear Panel:

Figure 2 Rear View of HSM-ZJ2014

A: Touch Screen

B: Smart Card Reader (ID)

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD7

C: Power Switch

D: Smart Card Reader (Key)

E: Reset Switch

N, O: Power Connectors

P: Service Ethernet Port (RJ45)

Q: Management Ethernet Port

R：Service Ethernet Port (Fiber Optic)

2.9. InstallationInstructions

1. Connect the power supply to the HSM.

Note:Before connectingthe power line to the HSM, please make sure power is off

first.

2. Connectcable to the HSM. According to your requirement and

application scenarios, connect your equipment to the HSM’s RJ45 or

Fiber Optic Service Ethernet Port with corresponding cable.

3. Turn on Power Switch, wait until Touch Screen turns to UI below.

Note: If any exception occurs, please contact manufacturer.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD8

Figure 3 Touch Screen UI of HSM-ZJ2014

3. HSM Operation Guide

Crypto Officer Creation, HSM Initialization, Smart Card PIN

Modification and HSM Power Off can be executed using Touch Screen.

When firstly used after leaving factory, the HSM must create Crypto

Officer and be initialized before using.

Note: the default 8-digit PINs of all smart cards are “12345678”.

3.1. Create Crypto Officer

HSM-ZJ2014 supports 4 types of Crypto Officer, which is shown in the

following table.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD9

Table 3 Role Description

Roles Description

Crypto Officer Device Manager:

Executes module initialization, device management and key

management functions. Functions are available via the Touch

Screen or Remote Management Application. The functions related

to accessing key can only executed after Authorizer’s

authorization.

Auditor:

Executes log audit functions. Functions are available via Remote

Management Application. Auditor can view or export the log.

Authorizer:

Executes key authorization functions. Functions are available via

Remote Management Application. Authorizer can authorize Device

Manager’s key management operation.

Key Manager:

Executes master key export and import functions. Functions are

available via Touch Screen and Smart Card Reader.

Before coming into use after leaving factory, the HSM needs to generate

all Crypto Officers and the corresponding smart cards.

Device Manager, Auditor, Authorizer will be generated at first. 5 Key

Managers will not be generated until Master Key is generated, whichis

shown in Section 4.2.1.

After Poweringon, HSM-ZJ2014’sTouch Screen will show as below.Press

“Create CO” button to create Device Manager, Auditor, and Authorizer.

ording t

nager sm

, then pr

re 4 Cr

the mes

art card i

ss “ENT

HSM‐ZJ201

pto Offi

sage dem

to Smar

R” butt

4GuidanceDo

ZanjiaElectr

er Creat

nstrated

Car

umentation

nicScience

on UI of

on Touc

ade

(ID)

Technology

SM-ZJ

Screen,

and inpu

(Beijing)Co.,

014

nsert De

smart c

LTD10

ice

rd’s

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD11

Figure 5 Device Manager Creation UI of HSM-ZJ2014

Then insert Auditor smart card into Smart Card Reader (ID) and input the

smart card PIN, then press “ENTER” button.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD12

Figure 6 Auditor Creation UI of HSM-ZJ2014

Finally, insert Authorizer smart card into Smart Card Reader (ID) and

input the smart card PIN, then press “ENTER” button.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD13

Figure 7 Authorizer Creation UI of HSM-ZJ2014

After Crypto Officers and the corresponding smart cards are generated,

Touch Screen will show message “Crypto Officer Smart Card

Generated!”

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD14

Figure 8 Crypto Officer Generated UI of HSM-ZJ2014

3.2. Initialize

The HSM needs to be initialized in 2 conditions:

 First used after leaving factory(or restoring factory setting)

 Reboot after Master Key is generated

The two kinds of initialization have a little difference, which will

expressin Section 4.2.1 and Section 4.2.2.

3.2.1. Master Key is NotGenerated

When first coming into use after leaving factory, the HSM’s master key is

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD15

not generated yet. Therefore, Master Key shouldbe generated using the

internal RNG and split into 5 shares, andthese 5 shares will be stored into

5 Key Manager smart cards.

Press “INITIALIZE”button, according to the message (Figure 9), firstly

insert the Device Manager smart card into Smart Card Reader(ID) and

input the corresponding PIN to authenticate Device Manager.

Figure 9Device Manager Authentication in Initialization

After authenticating Device Manager successfully, insert 5 Key Manager

smart cards into Smart Card Reader(Key) in order, and input the smart

card PIN, then Press “ENTER” button (Figure 10 -Figure 14).

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD16

Figure 10Key Manager Authentication in Initialization-1

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD17

Figure 11Key Manager Authentication in Initialization-2

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD18

Figure 12Key Manager Authentication in Initialization-3

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD19



Figure 13Key Manager Authentication in Initialization-4

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD20



Figure 14Key Manager Authentication in Initialization-5

After 5 shares are stored into 5 Key Manager smart cards, Touch

Screen will show message “Master Key Generated! Pressbutton to

choose operation. ”

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD21

Figure 15Initialization Finished

3.2.2. Master Key is generated

If Master Key has already been stored into 5 Key Manager smart cards,

when power on, the HSM needs to combine Master Key using 3 Key

Manager smart cards.

Press “INITIALIZE” button, according to the message(Figure 16), first

insert the Device Manager smart card into Smart Card Reader (ID) and

input the corresponding PIN to authenticate Device Manager.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD22

Figure 16 Device Manager Authentication in Initialization

After authenticating Device Manager, insert 3 Key Manager smart cards

into Smart Card Reader(Key) in order, and input the smart card

PIN(Figure 17 - Figure 19).

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD23

Figure 17 Key Manager Authentication in Initialization-1

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD24

Figure 18 Key Manager Authentication in Initialization-2

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD25

Figure 19 Key Manager Authentication in Initialization-3

After 3 shares are imported into HSM, Master Key will be recovered and

Touch Screen will show message“Master Key Imported! Pressbutton to

Choose Operation.” (Figure 20)

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD26

Figure 20 Initialization Finished

3.3. Modify Smart Card PIN

It is highly recommended that you modify Smart Card PIN immediately

Smart Card is created.

If you want to change smart card PIN, please press “CHANGE PIN”

button. According to the message (Figure 21), insert the smart card that

needs PIN modification into Smart Card Reader(ID) and input the old

PIN to authenticate smart card.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD27

Figure 21 PIN Modification - Input Old PIN

After inputting the old PIN, according to the message, input and confirm

the new PIN (Figure 22&Figure 23).

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD28

Figure 22 PIN Modification - Input New PIN

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD29

Figure 23 PIN Modification - Confirm New PIN

After the PIN is modified successfully, Touch Screen will show

message“PIN Modification Succeeds!”(Figure 24)

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD30

Figure 24 PIN Modification Succeeds

3.4. Shut Down the HSM

Press “SHUT DOWN” button. According to the message (Figure 25),

press“ENTER”button to shut down the HSM. If you need not to shut

down the HSM right now, press “CANCEL” button to cancel “SHUT

DOWN” operation.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD31

Figure 25 Shut Down the HSM

3.5. Error Message

The following table describes the error message shown on the Touch

Screen, gives the probable reason and the solution.

Table 4 Error Message Description

Error Message Reason Solution

Fail to Create

Device Manager! 1. There is no card in

Smart Card Reader(ID);

2. The PIN which you

input is not correct.

Make sure you insert card in

Smart Card Reader(ID), and

input correct PIN.

Fail to Create

Auditor!

Fail to Create

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD32

Authorizer!

Authentication

Failed, please Insert

Device Manager

Key Card, and

Input PIN again (8):

1. There is no card in

Smart Card Reader(ID);

2. The card in Smart Card

Reader(ID) is not

Device Manager Smart

card;

3. The PIN which you

input is not correct.

Make sure you insert Device

Manager Smart card in Smart

Card Reader(ID), and input

correct PIN.

Cannot Get Smart

Card UID 1. There is no card in

Smart Card

Reader(Key);

2. The card inserted is

invalid.

Make sure you insert

HSM-matched card in Smart

Card Reader(ID).

The Smart Card has

been inserted

before!

The Smart Card has been

inserted before.

Insert other card that has not

been inserted before.

Master Key

Recovery Failed!

Master Key combined with 3

Master Key Smart Card does

not match with its hash.

1. Make sure Smart Card

that you insert is Master

Key Smart Card. Carry

out INITIALIZE again.

2. Contact manufacturer.

Two PINs is

Inconsistent, Please

input new PIN again

(8):

The two new PINs which

you input are inconsistent

You should retype in new PIN

twice and make sure the two

PINs are consistent.

PIN modification

failed! 1. There is no card in

Smart Card Reader(ID);

2. The old PIN which you

input is not correct.

3. The card inserted is

invalid.

Press “CHANGE PIN” button

again to carry on PIN

modification and make sure

you insert card into the Smart

Card Reader(ID) and input

correct PIN.

Sensor Triggered,

Key Service Stops!

Sensor is triggered. 1. Restore to Factory

Setting and reboot.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD33

2. Contact manufacturer.

Device Key Broken,

Key Service Stops!

Device Key is broken. 1. Restore to Factory

Setting, and reboot.

2. Contact manufacturer.

Factory Setting

Over, Please

Reboot!

HSM is in Factory Setting

state.

Reboot.

Known Answer Test

for Cryptographic

Algorithm fails.

The results of Known

Answer Test for

Cryptographic Algorithm is

inconsistent with known

results.

1. Reboot.

2. Contact manufacturer.

Known Answer Test

for Keyed Hashing

Algorithm fails.

The results of Known

Answer Test for Keyed

Hashing Algorithm is

inconsistent with known

results.

1. Reboot.

2. Contact manufacturer.

Known Answer Test

for Embedded

Cryptographic

Algorithm is fails.

The results of Known

Answer Test for Embedded

Cryptographic Algorithm is

inconsistent with known

results.

1. Reboot.

2. Contact manufacturer.

Protection Card

Test fails.

The protection card state is

inconsistent with the

expected state.

1. Reboot.

2. Contact manufacturer.

RNG Test fails. The random number bits

generated by DRBG of HSM

do not pass the random

number test.

1. Reboot.

2. Contact manufacturer.

Operating System

Test fails.

The operating system state is

inconsistent with the

expected state

1. Reboot.

2. Contact manufacturer.

Hardware Test fails. The hardware state is

inconsistent with the

expected stat.

1. Reboot.

2. Contact manufacturer.

Network The network configuration is 1. Reboot.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD34

Configuration Test

fails.

inconsistent with the

expected configuration. 2. Contact manufacturer.

Application

Integrity Test fails.

If the hash value of

application is inconsistent

with the known hash value.

1. Reboot.

2. Contact manufacturer.

4. Remote Management Application

Remote Management Application is an application developed for

HSM-ZJ2014 and used for managing the HSM. It needs to run on an

individual computer. Before running Remote Management Application,

please make sure your PC or laptop meets requirements below:

 OS: Windows Vista/7/8,32/64 bit

 Dynamic link libraries (*.dll) in product CD has been copied to the

file folder where Remote Management Application installs.

4.1. Crypto Officer Logon User Interface

Before using Remote Management Application, please connect your

computer where runs Remote Management Application to the HSM’s

Management Port and configure your network adaptor as following:

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD35



Figure 26 Network Configuration

Launch Remote Management Application, then Crypto Officer Logon

User Interface (Figure 27) will show up.

Figure 27 Crypto Officer Logon User Interface

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD36

In this UI, you should firstly choose Crypto Officer Type, then insert the

corresponding smart card, input its PIN and Management Port IP address,

then press “Logon”. After authenticating Crypto Officer’s identity, UI

will turn to the corresponding Crypto Officer UI.

4.2. Device Manager User Interface

In Crypto Officer Logon User Interface (Figure 28), choose “Device

Manager” as Crypto Officer Type, then insert Device Manager smart card,

input its PIN and Management Port IP address (Default is172.20.0.1,

generally it needs not to modify), then press “Logon”.

Figure 28 Device Manager Logon Interface

After authenticating Device Manager’s identity, UI will turn to Device

Manager UI.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD37

Figure 29 Device Manager UI

4.2.1. User Account and Key Management

4.2.1.1. Create User Account

In Device Manager UI, press “CreateUser” button, the following UI will

show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD38

Figure 30 User Account Creation

Insert Authorizer smart card into Smart Card Reader (ID) and input the

corresponding PIN, then input and confirm the user password, then press

“CreateUser”. If the user is created successfully, the following UI will

show up. The default key algorithm of the user key is RSA (2048-bit),

ECDSA (NIST p256) can be also chosen as the user key algorithm.

Figure 31 User Account Creation Succeeds

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD39

User ID is assigned by the HSM. Each user has 2 default RSA/ECDSA

keys, which cannot be deleted.

4.2.1.2. Delete User Account

Figure 32 User Account Deletion

In Device Manager UI, pick the target user which needs to be deleted and

press “DeleteUser” button, the following dialog will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD40

Figure 33 User Account Deletion Confirm

According to the dialog (Figure 33), insert Authorizer smart card into

Smart Card Reader (ID) and input the corresponding PIN, then press

“ENTER” to confirm user deletion, otherwise press “CANCEL” to cancel.

If the user is deleted successfully, the following dialog will show up.

Figure 34 User Deletion Succeeds

4.2.1.3. Create Key

In Device Manager UI, press “CreateUser” button, the following UI will

show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD41

Figure 35 User Key Creation

When creating key, the key value can be generated by internal RNG or

imported by 2 shares that Device Manager inputs.

4.2.1.3.1. Generate from Internal RNG

Create Key UI’s default page is “Internal RNG”, which is shown as

below.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD42

Figure 36 Key Creation via Internal RNG

In this page (Figure 36), insert Authorizer smart card into Smart Card

Reader (ID) and input the corresponding PIN, type in User ID which the

key belongs to, choose Key Algorithm, Key Usage and Key Memo

(optional), then Press “CreateKey” button. If the key is created

successfully, the following dialog will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD43

Figure 37 Key Creation Succeeds

Note that Key ID is assigned by HSM.

4.2.1.3.2. Import from Key Shares

In Create Key UI, choose page “Import via Slices”. UI below will

show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD44

Figure 38Key Creation from Shares

In this pageFigure 38, insert Authorizer smart card into Smart Card

Reader (ID) and input the corresponding PIN, type in User ID which the

key belongs to, choose Key Algorithm and Key Memo (optional), then

Press “CreateKey” button.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD45

Figure 39 Key Creation from Shares

If the key is created successfully, the following dialog will show up.

Figure 40 Key Creation Succeeds

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD46

Key ID is assigned by HSM.

4.2.1.4. View Key

Click key in the left tree view, the corresponding key information will

show as below.

Figure 41View Key Information

4.2.1.5. Update Key

In Device Manager UI (Figure 29),pick the target key and press

“UpdateKey” button, below UI will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD47

Figure 42 Key Update

Insert Authorizer smart card into Smart Card Reader (ID) and input the

corresponding PIN first.

The key information which can be updated is Key Usage and Memo.

You can input new information inthe correspondingedit box or tick the

corresponding checkbox. Moreover, if you want to update Key Value,

you can tick the “Update Key Value” checkbox.

Then press “UpdateKey” button. If the key or key information is updated

successfully, the following UI will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD48

Figure 43 Key Update Succeeds

4.2.1.6. Delete Key

In Device Manager UI, pick the target key which needs to be deleted and

press “DeleteKey” button, the following dialog will show up.

Figure 44 Key Deletion

According to the dialog, insert Authorizer smart card into Smart Card

Reader (ID) and input the corresponding PIN, then press “Enter” to

confirm user deletion, otherwise press “Cancel” to cancel. If the key is

deleted successfully, the following dialog will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD49

Figure 45 Key Deletion Succeeds

4.2.1.7. Key Backup and Restore Management

Press “BackupKey” button, the following Backup Management UI will

show up.

Figure 46 Key Backup and Recovery UI

4.2.1.7.1. Backup Key File

In Backup Management UI (Figure 46), insert Authorizer smart card into

Smart Card Reader (ID) and input the corresponding PIN, then press

“Backup” button. The following UI (Figure 47) will show up, which

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD50

allows to select the file path to store the Key Backup file.



Figure 47 Select File Path to Store Key Backup File

After selecting the file path,the RMA will try to backup Key File. If

succeeds, the following dialog will show up, which indicates the Key file

has been backed up successfully and showsthe location of the key backup

file.

Figure 48 Key FileBackup Succeeds

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD51

4.2.1.7.2. Restore Key File

In Backup Management UI (Figure 46), insert Authorizer smart card into

Smart Card Reader (ID) and input the corresponding PIN, then press

“Restore” button. If authenticating Authorizer successfully, the following

dialog (Figure 49) will show up, where you can choose the Key-backup

file location.

Figure 49 Key File Restoration

After choosing Key-backup file, press “Open”. If restoring Key File

successfully, the following dialog will show up and indicate Key File

is restored successfully.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD52

Figure 50 Key Restoration Succeeds

4.2.1.7.3 Export and Import Key File

Key Export and Import function allow backing up Key File from one

HSM to the others.

For convenience，we take the source HSM as A, the destination HSM as

1. Connect HSM A using Remote Management Application. In Backup

Management UI shown in Figure 46, insert Authorizer smart card into

Smart Card Reader (ID) and input the corresponding PIN, then press

“Export” button.

If authenticating Authorizer successfully, Key Export Guide UI will

show up (Figure 51).Before exporting key, 3 Key Managers of HSM

A should be authenticated first. According to the message, insert 3 A’s

Key Manager smart cards into Smart Card Reader(Key)in order, and

input the smart card PIN (Figure 51 - Figure 53).

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD53

Figure 51 Key Export Guide – 1-1

Figure 52 Key Export Guide – 1-2

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD54

Figure 53 Key Export Guide – 1-3

After authenticating HSM A’s 3 Key Manager, you need to import B’s

Master Key to trans-encrypt A’s Key File. According to the message,

insert 3 B’s Key Manager smart cards into Smart Card Reader (Key)

in order and input the smart card PIN (Figure 54 - Figure 56).

Figure 54 Key Export Guide – 2-1

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD55

Figure 55 Key Export Guide – 2-2

Figure 56 Key Export Guide – 2-3

Then the following UI (Figure 57) will show up, which allows to select

the file path to store the Key Backup file.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD56

Figure 57 Select File Path to Store Key Backup File

If exporting Key File successfully, the following dialog will show up,

which indicates the Key file has been backed up successfully and shows

the location of the key backup file.

Figure 58 Key File Export Succeeds

2. Launch HSM B, connect it with Remote Management Application and

enter Backup Management UI shown in Figure 46.Then insert

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD57

Authorizer smart card into Smart Card Reader (ID) and input the

corresponding PIN, then press “Import” button. If authenticating

Authorizer successfully, the following dialog will show up, where you

can choose the location of the Key-backup File.

Figure 59 Location of Key Backup File

Choose Key-backup File, then press “Open”, if importing key file

successfully, the dialog below will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD58

Figure 60 Key File Import Succeeds

In this way, the Key file has been successfully imported from HSM A to

4.2.1.8. Zeroize All Users and Keys

In Device Manager UI (Figure 29), press “Delete All” button, and the

following dialog will show up.

Figure 61 User and Key Zeroization

According to the dialog (Figure 61), insert Authorizer smart card into

Smart Card Reader (ID) and input the corresponding PIN, then press

“ENTER” to confirm user deletion, otherwise press “CANCEL”. If all

keys are deleted successfully, the following dialog will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD59

Figure 62 User and Key Zeroization

4.2.2. IP Address Action Table Configuration

IP Address Action Table is used for allowing HSM to provide

cryptographic service only for the specific IP address range. Any

host whose IP address is not in IP Address Action Table is unable to

access HSM for cryptographic service.

In Device Manager UI(Figure 29), press “SystemConfig” button, System

Configuration UI will show up.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD60

Figure 63 System Configuration

Press “IPAccessCtrl” button, the following UI will show up. You can

determine the range of IP address that can access the HSM for

cryptographic service.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD61

Figure 64 IP Access Control UI

4.2.2.1. Append IP Address Action Table Entry

In IP Access Control UI (Figure 64), Input the start IP and end IP of IP

Address Action Table entry.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD62

Figure 65Add IP Access Control

Then press “Append”. If appending IP Access Action Table entry

successfully, the following dialog will show up, which showsIP

Access Action Table Entry is appended successfully.

Figure 66Add IP Address Action Table Entry Succeeds

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD63

4.2.2.2. Delete IP Address Action Table Entry

Pick the target IP Address Action Table Entry, then press “Delete” button.

Figure 67 IP Address Deletion

If deleting IP Access Action Table entry successfully, the following dialog

will show up, which indicates IP Access Action Table entry is deleted

successfully.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD64

Figure 68 IP Address Deletion Succeeds

4.2.3. Network Configuration

In Device Manager UI(Figure 69), press “SystemConfig” button, System

Configuration UI will show up.

Figure 69 System Configuration UI

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD65

Pick the target Network Interface, then press “Configuration” button. The

following UI will show up.



Figure 70 Network Configuration

Input IP address, net mask and default gateway then press “Enter”.

4.3. Auditor User Interface

In Crypto Officer Logon User Interface, choose “Auditor” as Crypto

Officer Type, then insert Auditor smart card, input its PIN and the

Management Port IP address, press “Logon”.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD66

Figure 71 Crypto Officer Logon User Interface

After authenticating Auditor’s identity, UI will turn to Auditor UI.

Figure 72 Auditor UI

4.3.1. View Audit Log

Choose start date and end date of the Audit Log that Auditor want to view,

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD67

then press “View Log”.

If viewing Audit Log successfully, the Audit Log records will show as

below.

Figure 73 Audit Log

4.3.2. Export Audit Log

Choose start date and end date of the Audit Log that Auditor want to

export, then press “Export Log”.

If exporting Audit Log successfully, the following dialog will show up,

which indicates that Audit Log is exported successfully.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD68

Figure 74 Export Audit Log

The format of Audit Log exported shows as below.

Figure 75 Audit Log

5. Client Guide

When the user account and key are created in HSM-ZJ2014, users can

access cryptographic service through software librarywhich is developed

for the HSM and compiled according to PKCS#11 standard.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD69

5.1. Supported Operating Systems

We provide 2 versions of the library, which can run respectively on Linux

2.6.0 or later and Windows Vista/7/8.

5.2. Supported PKCS#11 Function

5.2.1 Library Initialization

Function

Prototype

CK_RVC_Initialize(CK_VOID_PTR pInitArgs);

Description Initial PKCS#11library

Parameter pInitArgs Can only be NULL

Return Value CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.2 Library Finalization

Function

Prototype

CK_RVC_Finalize(CK_VOID_PTR pReserved);

Description Clean up application space

Parameter pReserved Reserved, Can only be NULL

Return Value CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.3 Get Library Information

Function

Prototype

CK_RVC_GetInfo(CK_INFO_PTR pInfo);

Description Get Library Information

Parameter pInfo Point to Library Information

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD70

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_INFO info;

CK_RV rv;

rv = C_Initialize((CK_VOID_PTR) NULL);

assert(rv == CKR_OK);

rv = C_GetInfo(&info);

assert(rv == CKR_OK);

if (info.version.major == 2) {

/* Do lots of interesting cryptographic things with the token */

}

rv = C_Finalize(NULL_PTR);

assert(rv == CKR_OK);

5.2.4 Get Function List

Function

Prototype

CK_RVC_GetFunctionList(CK_FUNCTION_LIST_PTR_PTR ppFunctionList);

Description Get Library Information

Parameter ppFunctionList Pointer to Pointer to Library List

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_FUNCTION_LIST_PTR pFunctionList;

CK_C_Initialize pC_Initialize;

CK_RV rv;

/* It's OK to call C_GetFunctionList before calling C_Initialize */

rv = C_GetFunctionList(&pFunctionList);

assert(rv == CKR_OK);

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD71

pC_Initialize = pFunctionList->C_Initialize;

/* Call the C_Initialize function in the library */

rv = (*pC_Initialize) (NULL_PTR);

5.2.5 Get Slot List

Function

Prototype

CK_RVC_GetSlotList(CK_BBOOL tokenPresent, CK_SLOT_ID_PTR pSlotList,

CK_ULONG_PTR pulCount);

Description Get slot. If pSlotList is NULL, pulCount returns space size that slot list consumes.

Parameter

tokenPresent Boolean value, return TRUE, If slot List only

contains present token, otherwise, return FALSE.

pSlotList Pointer to Slot List

pulCount Pointer to Number of Slots

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_ULONG ulSlotCount, ulSlotWithTokenCount;

CK_SLOT_ID_PTR pSlotList, pSlotWithTokenList;

CK_RV rv;

/* Get list of all slots */

rv = C_GetSlotList(CK_FALSE, NULL_PTR, &ulSlotCount);

if (rv == CKR_OK) {

pSlotList = (CK_SLOT_ID_PTR) malloc(ulSlotCount *

sizeof(CK_SLOT_ID));

rv = C_GetSlotList(CK_FALSE, pSlotList, &ulSlotCount);

if (rv == CKR_OK) {

/* Now use that list of all slots */

..}

free(pSlotList);

}

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD72

/* Get list of all slots with a token present */

pSlotWithTokenList = (CK_SLOT_ID_PTR) malloc(0);

ulSlotWithTokenCount = 0;

while (1) {

rv = C_GetSlotList(CK_TRUE, pSlotWithTokenList,

ulSlotWithTokenCount);

if (rv != CKR_BUFFER_TOO_SMALL)

break;

pSlotWithTokenList = realloc(pSlotWithTokenList,

ulSlotWithTokenList *

sizeof(CK_SLOT_ID));

}

if (rv == CKR_OK) {

/* Now use that list of all slots with a token present */

}

free(pSlotWithTokenList);

5.2.6 Get Slot Information

Function

Prototype

CK_RVC_GetSlotInfo(CK_SLOT_ID slotID, CK_SLOT_INFO_PTR pInfo);

Description Get Slot Information

Parameter slotID Slot ID

pInfo Pointer to Slot Information

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example CK_ULONG ulCount;

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD73

CK_SLOT_ID_PTR pSlotList;

CK_SLOT_INFO slotInfo;

CK_TOKEN_INFO tokenInfo;

CK_RV rv;

rv = C_GetSlotList(CK_FALSE, NULL_PTR, &ulCount);

if ((rv == CKR_OK) && (ulCount > 0)) {

pSlotList = (CK_SLOT_ID_PTR) malloc(ulCount * sizeof(CK_SLOT_ID));

rv = C_GetSlotList(CK_FALSE, pSlotList, &ulCount);

assert(rv == CKR_OK);

/* Get slot information for first slot */

rv = C_GetSlotInfo(pSlotList[0], &slotInfo);

assert(rv == CKR_OK);

..free(pSlotList);

}

5.2.7 Get Mechanism List

Function

Prototype

CK_RVC_GetMechanismList(CK_SLOT_ID slotID,

CK_MECHANISM_TYPE_PTR pMechanismList,

CK_ULONG_PTR pulCount);

Description Get Mechanism List

Parameter

slotID Slot ID

pMechanismList Pointer to Mechanism List

pulCount Pointer to Number of the Mechanisms in the List

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SLOT_ID slotID;

CK_ULONG ulCount;

CK_MECHANISM_TYPE_PTR pMechanismList;

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD74

CK_RV rv;

rv = C_GetMechanismList(slotID, NULL_PTR, &ulCount);

if ((rv == CKR_OK) && (ulCount > 0)) {

pMechanismList = (CK_MECHANISM_TYPE_PTR)

malloc(ulCount * sizeof(CK_MECHANISM_TYPE));

rv = C_GetMechanismList(slotID, pMechanismList, &ulCount);

if (rv == CKR_OK) {

..}

free(pMechanismList);

}

5.2.8 Get Mechanism Information

Function

Prototype

CK_RVC_GetMechanismInfo(CK_SLOT_ID slotID, CK_MECHANISM_TYPE

type, CK_MECHANISM_INFO_PTR pInfo);

Description Get Mechanism Information

Parameter

slotID Slot ID

type Mechanism Type

pInfo Pointer toMechanism Information

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SLOT_ID slotID;

CK_MECHANISM_INFO info;

CK_RV rv;

/* Get information about the CKM_RSA mechanism for this token */

rv = C_GetMechanismInfo(slotID, CKM_RSA, &info);

if (rv == CKR_OK) {

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD75

if (info.flags&CKF_DIGEST) {

..}

}

5.2.9 Open Session

Function

Prototype

CK_RVC_OpenSession(CK_SLOT_ID slotID, CK_FLAGS flags,

CK_VOID_PTR pApplication, CK_NOTIFY Notify,

CK_SESSION_HANDLE_PTR phSession);

Description Open Session

Parameter

slotID Slot ID

type Session Type

pApplication Pointer to Parameters of Callback Function

Notify Callback Function

phSession Pointer to Session Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.10 Close Session

Function

Prototype

CK_RVC_CloseSession(CK_SESSION_HANDLE hSession);

Description Close Session

Parameter hSession Session Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.11 Close All Sessions

Function

Prototype

CK_RVC_CloseAllSessions(CK_SLOT_ID slotID);

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD76

Description Close All Sessions

Parameter slotID slotID

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SLOT_ID slotID;

CK_BYTE application;

CK_NOTIFY MyNotify;

CK_SESSION_HANDLE hSession;

CK_RV rv;

application = 17;

MyNotify = &EncryptionSessionCallback;

rv = C_OpenSession(slotID, CKF_SERIAL_SESSION | CKF_RW_SESSION,

(CK_VOID_PTR) & application, MyNotify, &hSession);

if (rv == CKR_OK) {

..C_CloseSession(hSession);

}

rv = C_CloseAllSessions(slotID);

5.2.12 Login

Function

Prototype

CK_RVC_Login(CK_SESSION_HANDLE hSession, CK_USER_TYPE

userType,

CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen);

Description Login

Parameter

hSession Session Handle

userType User Type, supports only Type USER.

pPin Pointer to address that stores PIN, PIN is make up of

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD77

8 or less digits.

ulPinLen Length of PIN

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.13 Logout

Function

Prototype

CK_RVC_Logout(CK_SESSION_HANDLEhSession);

Description Close Session

Parameter hSession Session Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_UTF8CHAR userPIN[] = { "MyPIN" };

CK_RV rv;

rv = C_Login(hSession, CKU_USER, userPIN, sizeof(userPIN) - 1);

if (rv == CKR_OK) {

..rv == C_Logout(hSession);

if (rv == CKR_OK) {

..}

}

5.2.14 Create Object

Function

Prototype

CK_RVC_CreateObject(CK_SESSION_HANDLE hSession,

CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount,

CK_OBJECT_HANDLE_PTRphObject);

Description Create Object

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD78

Parameter

hSession Session Handle

pTemplate Pointer to Template

ulCount The number of templates

phObject Pointer to Object Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hKey;

CK_OBJECT_CLASS

keyClass = CKO_PUBLIC_KEY;

CK_KEY_TYPE keyType = CKK_RSA;

CK_BBOOLtrue = CK_TRUE;

CK_ATTRIBUTE keyTemplate[] = {

{CKA_CLASS, &keyClass, sizeof(keyClass)}

{CKA_KEY_TYPE, &keyType, sizeof(keyType)}

{CKA_POINT, point, sizeof(point)}

};

CK_RV rv;

/* Create an RSA public key object */

rv = C_CreateObject(hSession, &keyTemplate, 3, &hKey);

if (rv == CKR_OK) {

}

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD79

5.2.15 Destroy Object

Function

Prototype

CK_RVC_DestroyObject(CK_SESSION_HANDLE hSession,

CK_OBJECT_HANDLE hObject);

Description Destroy Object

Parameter hSession Session Handle

hObject Object Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.16 Get Attribute Value

Function

Prototype

CK_RVC_GetAttributeValue(CK_SESSION_HANDLE hSession,

CK_OBJECT_HANDLE hObject,

CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount);

Description Get Attribute Value

Parameter

hSession Session Handle

hObject Object Handle

pTemplate Pointer to Template List

ulCount Number of Templates

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hObject;

CK_BYTE point;

CK_ATTRIBUTEtemplate[] = {

{CKA_POINT, NULL_PTR, 0}

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD80

};

CK_RV rv;

rv = C_GetAttributeValue(hSession, hObject, &template, 1);

if (rv == CKR_OK) {

point = (CK_BYTE_PTR) malloc(template[0].ulValueLen);

template[0].pValue = point;

/* template[0].ulValueLen was set by C_GetAttributeValue */

rv = C_GetAttributeValue(hSession, hObject, &template, 1);

if (rv == CKR_OK) {

..}

free(point);

}

5.2.17 Set Attribute Value

Function

Prototype

CK_RVC_SetAttributeValue(CK_SESSION_HANDLE hSession,

CK_OBJECT_HANDLE hObject,

CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount);

Description Set

Parameter

hSession Session Handle

hObject Object Handle

pTemplate Pointer to Template List

ulCount Number of Templates

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD81

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hObject;

CK_UTF8CHAR label[] = { "New label" };

CK_ATTRIBUTEtemplate[] = {

CKA_LABEL, label, sizeof(label) - 1

};

CK_RV rv;

rv = C_SetAttributeValue(hSession, hObject, &template, 1);

if (rv == CKR_OK) {

}

5.2.18 Find Objects Initialization

Function

Prototype

CK_RVC_FindObjectsInit(CK_SESSION_HANDLE hSession,

CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount);

Description Find Objects Initialization

Parameter

hSession Session Handle

pTemplate Pointer to Template List

ulCount Number of Templates

Return CKR_OK Success

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD82

Val ue Non-CKR_OK Fail, return error code.

5.2.19 Find Objects

Function

Prototype

CK_RVC_FindObjects(CK_SESSION_HANDLE hSession,

CK_OBJECT_HANDLE_PTR phObject,

CK_ULONG ulMaxObjectCount,

CK_ULONG_PTR pulObjectCount);

Description Find Object

Parameter

hSession Session Handle

phObject Pointer to Object Handle

ulMaxObjectCount Max number of Objects returned

pulObjectCount Pointer to Actual number of Objects returned

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.20 Find Objects Finalization

Function

Prototype

CK_RVC_FindObjectsFinal(CK_SESSION_HANDLE hSession);

Description Finalize Find Object operation

Parameter hSession Session Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_ATTRIBUTE priKeysTemplate[] = {

{CKA_CLASS, &priKeys, sizeof(priKeys)},

};

rc =FunctionPtr->C_FindObjectsInit(hSession, priKeysTemplate, 1);

if (rc != CKR_OK) {

printf("error FindObjectsInit\n");

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD83

}

rc = FunctionPtr->C_FindObjects(hSession, &priKeys_h, 1, &ulObjectCount);

rc = FunctionPtr->C_FindObjectsFinal(hSession);

5.2.21 Encryption Initialization

Function

Prototype

CK_RVC_EncryptInit(CK_SESSION_HANDLE hSession,

CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey);

Description Initialize Encryption

Parameter

hSession Session Handle

pMechanism Pointer to Mechanism

hKey Key Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.22 Encrypt

Function

Prototype

CK_RVC_Encrypt(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,

CK_ULONG ulDataLen, CK_BYTE_PTR pEncryptedData,

CK_ULONG_PTR pulEncryptedDataLen);

Description Encrypt

Parameter

hSession Session Handle

pData Pointer to Plain Data

ulDataLen Length of Plain Data

pEncryptedData Pointer to Cipher Data Buffer

pulEncryptedDataLen Pointer to Length of Cipher Data Buffer

Return CKR_OK Success

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD84

Val ue Non-CKR_OK Fail, return error code.

5.2.23 Encrypt Update

Function

Prototype

CK_RVC_EncryptUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pPart,

CK_ULONG ulPartLen, CK_BYTE_PTR pEncryptedPart,

CK_ULONG_PTR pulEncryptedPartLen);

Description Encrypt Update

Parameter

hSession Session Handle

pPart Pointer to AdditionalPlain Data

ulPartLen Length of AdditionalPlain Data

pEncryptedPart Pointer to Cipher Data Buffer

pulEncryptedPartLen Pointer to Length of Cipher Data Buffer

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.24 Encryption Finalization

Function

Prototype

CK_RVC_EncryptFinal(CK_SESSION_HANDLE hSession,

CK_BYTE_PTR pLastEncryptedPart,

CK_ULONG_PTR pulLastEncryptedPartLen);

Description Finalize Encryption

Parameter

hSession Session Handle

pLastEncryptedPart Pointer to Last Cipher Data

pulLastEncryptedPartLen Pointer to Length of Last Cipher Data

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD85

Example

#define PLAINTEXT_BUF_SZ 200

#define CIPHERTEXT_BUF_SZ 256

CK_ULONG firstPieceLen, secondPieceLen;

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hKey;

CK_BYTE iv[8];

CK_MECHANISM mechanism = {

CKM_AES_ECB, iv, sizeof(iv)

};

CK_BYTE data[PLAINTEXT_BUF_SZ];

CK_BYTE encryptedData[CIPHERTEXT_BUF_SZ];

CK_ULONG ulEncryptedData1Len;

CK_ULONG ulEncryptedData2Len;

CK_ULONG ulEncryptedData3Len;

CK_RV rv;

firstPieceLen = 90;

secondPieceLen = PLAINTEXT_BUF_SZ - firstPieceLen;

rv = C_EncryptInit(hSession, &mechanism, hKey);

if (rv == CKR_OK) {

/* Encrypt first piece */

ulEncryptedData1Len = sizeof(encryptedData);

rv = C_EncryptUpdate(hSession,

&data[0], firstPieceLen,

&encryptedData[0], &ulEncryptedData1Len);

if (rv != CKR_OK) {

..}

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD86

/* Encrypt second piece */

ulEncryptedData2Len = sizeof(encryptedData) - ulEncryptedData1Len;

rv = C_EncryptUpdate(hSession,

&data[firstPieceLen], secondPieceLen,

&encryptedData[ulEncryptedData1Len],

&ulEncryptedData2Len);

if (rv != CKR_OK) {

..}

/* Get last little encrypted bit */

ulEncryptedData3Len =

sizeof(encryptedData) - ulEncryptedData1Len - ulEncryptedData2Len;

rv = C_EncryptFinal(hSession,

&encryptedData[ulEncryptedData1Len +

ulEncryptedData2Len],

&ulEncryptedData3Len);

if (rv != CKR_OK) {

..}

}

5.2.25 Decryption Initialization

Function

Prototype

CK_RVC_DecryptInit(CK_SESSION_HANDLE hSession,

CK_MECHANISM_PTR pMechanism, CK_OBJECT_HANDLE hKey);

Description Decryption Initialization

Parameter

hSession Session Handle

pMechanism Pointer to Mechanism

hKey Key Handle

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD87

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.26 Decrypt

Function

Prototype

CK_RVC_Decrypt(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pEncryptedData,

CK_ULONG ulEncryptedDataLen, CK_BYTE_PTR pData,

CK_ULONG_PTR pulDataLen);

Description Decrypt

Parameter

hSession Session Handle

pEncryptedData Pointer to Cipher Data

ulEncryptedDataLen Length of Cipher Data

pData Pointer to Plain Data Buffer

pulDataLen Pointer to Length of Plain Data Buffer

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.27 Decrypt Update

Function

Prototype

CK_RVC_DecryptUpdate(CK_SESSION_HANDLE hSession,

CK_BYTE_PTR pEncryptedPart,

CK_ULONG ulEncryptedPartLen, CK_BYTE_PTR pPart,

CK_ULONG_PTR pulPartLen);

Description Decrypt Update

Parameter

hSession Session Handle

pEncryptedPart Pointer to CipherData

ulEncryptedPartLen Length of Cipher Data

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD88

pPart Pointer to AdditionalPlain Data Buffer

pulPartLen Pointer to Length of AdditionalPlain Data Buffer

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.28 Decrypt Finalization

Function

Prototype

CK_RVC_DecryptFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pLastPart,

CK_ULONG_PTR pulLastPartLen);

Description Decrypt Finalization

Parameter

hSession Session Handle

pLastPart Pointer to Last Plain Data

pulLastPartLen Pointer to Length of Last Plain Data

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

#define CIPHERTEXT_BUF_SZ 256

#define PLAINTEXT_BUF_SZ 256

CK_ULONG firstEncryptedPieceLen, secondEncryptedPieceLen;

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hKey;

CK_BYTE iv[8];

CK_MECHANISM mechanism = {

CKM_AES_ECB, iv, sizeof(iv)

};

CK_BYTE data[PLAINTEXT_BUF_SZ];

CK_BYTE encryptedData[CIPHERTEXT_BUF_SZ];

CK_ULONG ulData1Len, ulData2Len, ulData3Len;

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD89

CK_RV rv;

firstEncryptedPieceLen = 90;

secondEncryptedPieceLen = CIPHERTEXT_BUF_SZ - firstEncryptedPieceLen;

rv = C_DecryptInit(hSession, &mechanism, hKey);

if (rv == CKR_OK) {

/* Decrypt first piece */

ulData1Len = sizeof(data);

rv = C_DecryptUpdate(hSession,

&encryptedData[0], firstEncryptedPieceLen,

&data[0], &ulData1Len);

if (rv != CKR_OK) {

..}

/* Decrypt second piece */

ulData2Len = sizeof(data) - ulData1Len;

rv = C_DecryptUpdate(hSession,

&encryptedData[firstEncryptedPieceLen],

secondEncryptedPieceLen,

&data[ulData1Len], &ulData2Len);

if (rv != CKR_OK) {

..}

/* Get last little decrypted bit */

ulData3Len = sizeof(data) - ulData1Len - ulData2Len;

rv = C_DecryptFinal(hSession,

&data[ulData1Len + ulData2Len], &ulData3Len);

if (rv != CKR_OK) {

..}

}

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD90

5.2.29 Hash Initialization

Function

Prototype

CK_RVC_DigestInit(CK_SESSION_HANDLE hSession,

CK_MECHANISM_PTR pMechanism);

Description Hash Initialization

Parameter hSession Session Handle

pMechanism Pointer to Mechanism

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.30 Hash

Function

Prototype

CK_RVC_Digest(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,

CK_ULONG ulDataLen, CK_BYTE_PTR pDigest,

CK_ULONG_PTR pulDigestLen);

Description Hash

Parameter

hSession Session Handle

pData Pointer to Data to be hashed

ulDataLen Length of Data to be hashed

pDigest Pointer to Digest Data Buffer

pulDigestLen Pointer to Length of Digest Data Buffer

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.31 Hash Update

Function CK_RVC_DigestUpdate(CK_SESSION_HANDLE hSession,

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD91

Prototype CK_BYTE_PTRpPart,

CK_ULONG ulPartLen);

Description Hash Update

Parameter

hSession Session Handle

pPart Pointer to Additional Data Buffer to be hashed

ulPartLen Length of Data Buffer to be hashed

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.32 Hash Finalization

Function

Prototype

CK_RVC_DigestFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pDigest,

CK_ULONG_PTR pulDigestLen);

Description Hash Finalizaion

Parameter

hSession Session Handle

pDigest Pointer to Last Digest Data

pulDigestLen Pointer to Length of Last Digest Data

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_MECHANISM mechanism = {

CKM_SM3, NULL_PTR, 0

};

CK_BYTE data[] = {... };

CK_BYTE digest[32];

CK_ULONG ulDigestLen;

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD92

CK_RV rv;

rv = C_DigestInit(hSession, &mechanism);

if (rv != CKR_OK) {

}

rv = C_DigestUpdate(hSession, data, sizeof(data));

if (rv != CKR_OK) {

}

rv = C_DigestKey(hSession, hKey);

if (rv != CKR_OK) {

}

ulDigestLen = sizeof(digest);

rv = C_DigestFinal(hSession, digest, &ulDigestLen);

5.2.33 Signing Initialization

Function

Prototype

CK_RVC_SignInit(CK_SESSION_HANDLE hSession, CK_MECHANISM_PTR

pMechanism,

CK_OBJECT_HANDLE hKey);

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD93

Description Signing Initialization

Parameter

hSession Session Handle

pMechanism Pointer to Mechanism

hKey Key Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.34 Signing

Function

Prototype

CK_RVC_Sign(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,

CK_ULONG ulDataLen, CK_BYTE_PTR pSignature,

CK_ULONG_PTR pulSignatureLen);

Description Signing

Parameter

hSession Session Handle

pData Pointer to Data to be signed

ulDataLen Length of Data to be signed

pSignature Pointer to Signed Data

pulSignatureLen Pointer to Length of Signed Data Buffer

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.35 Signing Update

Function

Prototype

CK_RVC_SignUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pPart,

CK_ULONG ulPartLen);

Description Signing Update

Parameter hSession Session Handle

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD94

pPart Pointer to Additional Data Buffer to be signed

ulPartLen Length of Data Buffer to be signed

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.36 Signing Finalization

Function

Prototype

CK_RVC_SignFinal(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pSignature,

CK_ULONG_PTR pulSignatureLen);

Description Signing Finalization

Parameter

hSession Session Handle

pSignature Pointer to Last Signed Data

pulSignatureLen Pointer to Length of Last Signed Data

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hKey;

CK_MECHANISM mechanism = {

CKM_RSA, NULL_PTR, 0

};

CK_BYTE data[] = {... };

CK_BYTE mac[64];

CK_ULONG ulMacLen;

CK_RV rv;

rv = C_SignInit(hSession, &mechanism, hKey);

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD95

if (rv == CKR_OK) {

rv = C_SignUpdate(hSession, data, sizeof(data));

..ulMacLen = sizeof(mac);

rv = C_SignFinal(hSession, mac, &ulMacLen);

}

5.2.37 Verification Initialization

Function

Prototype

CK_RVC_VerifyInit(CK_SESSION_HANDLE hSession,

CK_MECHANISM_PTR pMechanism,

CK_OBJECT_HANDLE hKey);

Description Initialize Verification

Parameter

hSession Session Handle

pMechanism Pointer to Mechanism

hKey Key Handle

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.38 Verification

Function

Prototype

CK_RVC_Verify(CK_SESSION_HANDLE hSession, CK_BYTE_PTR pData,

CK_ULONG ulDataLen, CK_BYTE_PTR pSignature,

CK_ULONG ulSignatureLen);

Description Verification

Parameter hSession Session Handle

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD96

pData Pointer to Source Datato be verified

ulDataLen Length of Source Data to be verified

pSignature Pointer to Signed Data Buffer to be verified

ulSignatureLen Length of Signed Data Buffer to be verified

Return

Val ue

CKR_OK Success，Verification Passed

CKR_SIGNATURE_INVALID Success，Signature Invalid

Non-CKR_OK Fail, return error code.

5.2.39 Verification Update

Function

Prototype

CK_RVC_VerifyUpdate(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pPart,

CK_ULONG ulPartLen);

Description Verification Update

Parameter

hSession Session Handle

pPart Pointer to Additional Data Buffer to be verified

ulPartLen Length of Data Buffer to be verified

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.40 Verification Finalization

Function

Prototype

CK_RVC_VerifyFinal(CK_SESSION_HANDLE hSession,

CK_BYTE_PTRpSignature,

CK_ULONG ulSignatureLen);

Description Verification Finalization

Parameter hSession Session Handle

pSignature Pointer to Last Data to be verified

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD97

ulSignatureLen Length of Last Data to be verified

Return

Val ue

CKR_OK Success，Verification Passed

CKR_SIGNATURE_INVALID Success，Signature Invalid

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_OBJECT_HANDLE hKey;

CK_MECHANISM mechanism = {

CKM_RSA, NULL_PTR, 0

};

CK_BYTE data[] = {... };

CK_BYTE mac[64];

CK_RV rv;

rv = C_VerifyInit(hSession, &mechanism, hKey);

if (rv == CKR_OK) {

rv = C_VerifyUpdate(hSession, data, sizeof(data));

..rv = C_VerifyFinal(hSession, mac, sizeof(mac));

}

5.2.41 Take Random number as Seed

Function

Prototype

CK_RVC_SeedRandom(CK_SESSION_HANDLE hSession, CK_BYTE_PTR

pSeed,

CK_ULONG ulSeedLen);

Description Take Random number as Seed

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD98

Parameter

hSession Session Handle

pSeed Pointer to Seed

ulSeedLen Length of Seed

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

5.2.42 Generate Random Number

Function

Prototype

CK_RVC_GenerateRandom(CK_SESSION_HANDLE hSession,

CK_BYTE_PTR pRandomData,

CK_ULONG ulRandomLen);

Description Generate Random Number

Parameter

hSession Session Handle

pRandomData Pointer to Random Number

ulRandomLen Length of Random Number

Return

Val ue

CKR_OK Success

Non-CKR_OK Fail, return error code.

Example

CK_SESSION_HANDLE hSession;

CK_BYTE seed[] = {... };

CK_BYTE randomData[] = {... };

CK_RV rv;

rv = C_SeedRandom(hSession, seed, sizeof(seed));

if (rv != CKR_OK) {

}

HSM‐ZJ2014GuidanceDocumentation

ZanjiaElectronicScience&Technology(Beijing)Co.,LTD99

rv = C_GenerateRandom(hSession, randomData, sizeof(randomData));

if (rv == CKR_OK) {

}

Zanjia Electronic Science and Technology HSM-ZJ2014 Hardware Security Module User Manual HSM ZJ2014 x

Zanjia Electronic Science & Technology (Beijing) Co., Ltd. Hardware Security Module HSM ZJ2014 x

2ADTB-HSM-ZJ2014 user manual

Navigation menu

Namespaces

Views

Navigation