Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Launch the Terminal.
  2. Change Directory (cd) to [ADSS Server Home]\util\bin\

Type the following command to run the utility according to the syntax: ./genkek_pkcs11 [Name] [PKCS#11 module library] [Slot id] [PIN] [FIPS mode] [Log file path] [Key label] 

Code Block
./ LunaHSM 0 password false /home/adss/pkcs11.log TestKEK

How to import a PFX/PKCS#12 file into a Luna HSM for use by ADSS Server?

This technote describes how to import a PFX file into a Luna HSM for use by ADSS Server.  This description only details the HSM operations. Once completed, refer to the standard ADSS Server manual for instructions on how to search and use the key and associated certificate.   

To import a PFX into Luna HSM, there are three parts: (1) private key import, (2) certificate import, and (3) binding the two objects together.

A PFX contains a private key and associated public certificate. Once the information has been imported into Luna HSM, it is important to either securely delete or store the PFX. The HSM should have a suitable backup option.

  1.  Import Private Key 

On the ADSS Server host, open a command prompt with suitable privileges and change the folder/directory to the SafeNet Luna Client home directory. On Windows the default is C:\Program Files\SafeNet\LunaClient, for example. Once you're at the SafeNet Luna Client home directory, run the following command:

Code Block
titleCommand Prompt
cmu importkey -PKCS12 -in <PFX file name>.pfx -keyalg RSA

2. Import the public certificate

First export the certificate from the PFX file. There are numerous ways to achieve this, which are not documented here. One example is to import the PFX into the Windows Security Store. Note upon doing this remember to securely delete the entry as to prevent unauthorized access to the private key.

From the same command prompt as used in point one above, run the following command:

Code Block
titleCommand Prompt
cmu import -inputFile=<Certificate file name>.cer

The import operation creates the new object inside the HSM partition with the “CKR_PRIVATE” attribute set to “true”. This must be set to “false”. To do this use the CKDEMO application (found in the same directory as cmu utility):

a. Start CKDEMO and open a session as a normal user (option 1)
b. Log in as the crypto officer (option 3)
c. Find objects (26) and search for the public key (option 4)
d. Copy the public key (option 21) with the handle from step 3
e. Select add attribute and change CKR_PRIVATE from 01 (true) to 00 (false)
f. Destroy the old object (option 22).

3. Bind the imported objects 

To bind the two objects inside the HSM for ADSS Server, you must set the ID attribute of both the private key and public certificate. Remember to bind the new object created in step two above with CKDEMO.

First, check for a unique number to set this ID attribute to. You can do this by selecting a random number for use and checking no current object has this value assigned. Do this by running the command “cmu list -id=<id number>”. If the command returns no results, then the ID number tested is not currently used.

Proceed to bind the private key and public certificate. From the command line set the ID attribute to the random number just tested, by running following command for both objects

Code Block
titleCommand Prompt
cmu setAttribute -handle=<object handle number> -id=<id number>

The key and certificate are now ready for use by ADSS Server. Remember to add the necessary chain of trust of CA certificates to ADSS Server Trust Manager before the key is used.

Initializing the Utimaco CryptoServer 4 Simulator

The following are the instructions to configure and initialize the Utimaco CryptoServer 4 simulator on Windows:

  1. Install the Utimaco CryptoServer 4 using its installer
  2. Go to location C:\Program Files\Utimaco\CryptoServer\Lib and edit the cs_pcs11_R2.cfg file in a text editor:
    1. change the IP under Device = 3001@ (This is the IP where Utimaco is running. It is running on the localhost, you can even set the value 3001@127.0.01)
    2. change the ConnectionTimeout = 5000
    3. change the KeepAlive = true
  3. Start/Restart the HSM by launching the CryptoServer Simulator for the changes to take effect
  4. To initialize the HSM, launch cmd and go to C:\Program Files\Utimaco\CryptoServer\Administration and run the command p11tool2 Login=ADMIN,ADMIN.key InitToken=654321 for initialization
  5. To initialize the slot run the command: p11tool2 LoginSO=654321 InitPIN=123456
  6. Restart the machine
  7. Start the the CryptoServer Simulator
  8. To configure it in the ADSS Server, use the library name C:\Program Files\Utimaco\CryptoServer\Lib\cs_pkcs11_R2.dll

Initializing the SafeNet Emulator 5.2

The following are the instructions to configure and initialize the SafeNet Emulator 5.2 on Windows:

  1. Install the PTKcpsdk.msi from location SafeNet Emulator\610-009981-014_SW_PTK_5.2_Client_RevA\SDKs\Win64\ptkc_sdk
  2. Additionally install the following applications if the Emulator is installed on a network:
    1. Install the PTKnethsm.msi from location SafeNet Emulator\610-009981-014_SW_PTK_5.2_Client_RevA\SDKs\Win64\network_hsm_access_provider

    2. Install the PTKcprt.msi from location SafeNet Emulator\610-009981-014_SW_PTK_5.2_Client_RevA\SDKs\Win64\ptkc_runtime

  3. Once installation is completed, run the cmd
  4. To create a new slot, run the command: ctconf -c1 (where 1 is slot number)
  5. To initialize any of the created slot, run the command: ctconf -n1
  6. To re-initialize any of the created slots, run the command: ctconf -r1
  7. To change the user password of any of the created slot, run the command: ctkmu p -sx
  8. To see the details and status of the all created slots, run the command: ctstat
  9. To configure it in the ADSS Server, use the library name cryptoki.dll

Configuring the Utimaco CP5 HSM Simulator on Linux

Follow these steps to configure the Utimaco CP5 HSM Simulator on Linux. It is assumed that the simulator is already installed:

Starting HSM

  • Start the simulator using the following command:
    Note:  The simulator by default runs on 3001 port

Configure the simulator in CC mode 

  • Export the HSM public key: csadm Dev=3001@ GetHSMAuthKey>/home/Linux2/x86-64/Administration/HsmAuthKey.key 
  • Now this HSM public key & P11 config must be set inside the machine's environment variable using following commands:
    • export CS_AUTH_KEYS=/home/Linux2/x86-64/Administration/HsmAuthKey.key 
    • Create a PKCS#11 Configuration File (see below for instructions) and set it to: CS_PKCS11_R2_CFG=<FILE_PATH>/cs_pkcs11_R2.cfg i.e. export CS_PKCS11_R2_CFG=/opt/linux/x86-64/Crypto_APIs/pkcs11_r2/lib/cs_pkcs11_R2.cfg

Creating Users

Create two users and these must use a password based authentication which is then set inside ADSS Server. Here two users are added with different rights because we need admin rights on the slot to allow ADSS Server to generate keys and use them for signing.  Note: Use a strong password

  • ./csadm Dev=3001@ LogonSign=ADMIN,<FILE_PATH>/ADMIN.key AddUser=SO_0000,00000200{CXI_GROUP=SLOT_0000},hmacpwd,password
  • ./csadm Dev=3001@ LogonSign=ADMIN,<FILE_PATH>/ADMIN.key AddUser=USR_0000,00000022{CXI_GROUP=SLOT_0000},hmacpwd,password  // This password is configured in ADSS Server
  • Create a third user to allow key restore: ./csadm Dev=3001@ LogonSign=ADMIN,<FILE_PATH>/ADMIN.key AddUser=USR1_0000,00000022{CXI_GROUP=SLOT_0000},hmacpwd,password
    Note: The restore key function of Utimaco requires two login on the slot hence we create another user and assign admin rights to it. This user is also configured inside ADSS Server. 

Testing the Simulator/HSM

 Once the Simulator is running in CC mode you can test its commands:

  • ./csadm Dev=3001@ GetState   // Tally this with Appendix below
  • ./csadm Dev=3001@ ListUser    //The above 3 users will be shown here
  • ./csadm  Dev=3001@ LogonSign=ADMIN, /home/Linux2/x86-64/Administration/key/ADMIN.key (Note: This command confirms that the simulator or HSM is running in CC mode)


Some times the simulator gets stuck or not performing as intended. In this case run the following commands:

  • ./csadm Dev=3001@ ResetToBL
  • ./csadm Dev=3001@
  • ./csadm Dev=3001@ LogonSign=ADMIN,/home/Linux2/x86-64/Administration/key/ADMIN.key ClearAuditLog

To get the P11 log, see the CFG file Logpath parameter and check those logs. If required, change the Log level to get more details. Most of the time you can find the root cause looking at this file.

You can also get more logs from the simulator/HSM. To get the audit log for debugging run this command:

  • ./csadm Dev=3001@ LogonSign=ADMIN,./home/Linux2/x86-64/Administration/key/ADMIN.key GetAuditLog > ./auditlog.txt
    Important: As HSM/Simulator runs, it generates audit logs. CP5 creates 10 files with 240000 bytes. Log rotation is off and can't be turned ON. This means administrator must export these logs to avoid HSM returning error. See CryptoServer Se-Series Gen2 CP5 Administration Manual > 8.12  - see the 3rd command above

Configuration File

The cs_pkcs11_R2.cfg file is important for Utimaco P11 library to communicate with the HSM. This must be placed any where on the machine and referenced by pointed by CS_PKCS11_R2_CFG env variable, as mentioned above:


Code Block
# Path to the logfile (name of logfile is attached by the API)
# For unix:
Logpath = /tmp
# For windows:
#Logpath = D:/HSMLogs
# Loglevel (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE)
Logging = 1
# Maximum size of the logfile in bytes (file is rotated with a backupfile if full)
Logsize = 100mb
# Created/Generated keys are stored in an external or internal database
KeysExternal = false
# If true, every session establishs its own connection
SlotMultiSession = true
# if true, key handles of created/generated keys are random
RandomizeKeyHandles = true
# Maximum number of slots that can be used
SlotCount = 10
# If true, leading zeroes of decryption operations will be kept
KeepLeadZeros = false
# Configures load balancing mode ( == 0 ) or failover mode ( > 0 )
FallbackInterval = 0
# Prevents expiring session after inactivity of 15 minutes
KeepAlive = true
# Timeout of the open connection command in ms
ConnectionTimeout = 120000
# Timeout of command execution in ms
CommandTimeout = 60000
# Device specifier (here: CryptoServer is CSLAN with IP address
Device = TCP:3001@
# Slotsection for slot with number 0
#SlotNumber = 0



administrator@localhost p11]$ ./p11tool2 Version

p11tool2 2.0.14
p11adm_R2 2.1.14
CryptoServer PKCS#11 R2 CP5 #02 2.50 (Sep 4 2018)
cxi_api 1.7.8 (Sep 4 2018)
csadm_lib (global) 3.4.5
csapi 1.10.3 (Sep 4 2018)
csxapi 1.8.5 (Sep 4 2018)
pp_api 1.7.3 (Sep 4 2018)
yacl 1.10.3
sdb 2.1.4 (Sep 4 2018 14:42:31)
copa 1.1.4
sl 1.1.3

[administrator@localhost Administration]$ ./csadm ListUser
Name Permission Mechanism Attributes
ADMIN 22000000 RSA sign Z[0]
ADMIN01 00000030 HMAC passwd A[CXI_GROUP=SLOT_0000]
ADMIN1 03000000 HMAC passwd A[CXI_GROUP=SLOT_0000]
ADMIN3 02000000 HMAC passwd Z[0]A[CXI_GROUP=SLOT_0000]
ADMIN4 02000000 HMAC passwd Z[0]A[CXI_GROUP=SLOT_0000]
ADMIN_INST 22000000 RSA sign Z[0]
SO_0000 00000200 HMAC passwd A[CXI_GROUP=SLOT_0000]
USR1_0000 00000022 HMAC passwd A[CXI_GROUP=SLOT_0000]
USR_0000 00000022 HMAC passwd A[CXI_GROUP=SLOT_0000]

administrator@localhost Administration]$ ./csadm GetState

mode = Operational Mode
state = INITIALIZED (0x00100004)
temp = 44.1 [C]
alarm = OFF
bl_ver = (Model: Se-Series Gen2)
hw_ver =
uid = 9f00001a aceed701 | 
adm1 = 53653135 30302020 43533637 30313135 | Se1500 CS670115
adm2 = 43727970 746f5320 43503520 54657374 | CryptoS CP5 Test
adm3 = 494e5354 414c4c45 44202020 20202020 | INSTALLED


[root@localhost Administration]# ./csadm Version
csadm 2.3.2
csadm_lib (global) 3.4.5
csapi 1.10.3 (Sep 4 2018)
pp_api 1.7.3 (Sep 4 2018)
sl 1.1.3
yacl 1.10.3

[root@localhost Administration]# ./csadm Dev=/dev/cs2.0 GetBootLog

SMOS CP5 Ver. (Sep 4 2018) started [0]
Hardware Rev.
Compiler Ver. 7.4.8
AIS31 compliant TRNG [strict]
Sensory Controller Ver. [0/0]
Real Random Number Generator initialized with:
Pseudo Random Number Generator initialized with:
Signed Licence File found: se1500.slf
CMDS: no TPS limit
module 0x89 (HASH) initialized successfully
module 0x83 (CMDS) initialized successfully
module 0x86 (UTIL) initialized successfully
module 0x81 (VDES) initialized successfully
module 0x0d (EXAR) initialized successfully
Exar Hardware Crypto Engine detected
module 0x0a (HCE) initialized successfully
module 0x8e (LNA) initialized successfully
module 0x84 (VRSA) initialized successfully
module 0x91 (ASN1) initialized successfully
module 0x8f (ECA) initialized successfully
module 0x8b (AES) initialized successfully
module 0x88 (DB) initialized successfully
module 0x96 (MBK) initialized successfully
module 0x9c (ECDSA) initialized successfully
module 0x68 (CXI) initialized successfully
module 0x04 (POST) initialized successfully
module 0x87 (ADM) initialized successfully
CMDS: verified approved firmware
POST: DSA Cryptographic Algorithm Test skipped

[root@localhost Administration]# ./csadm Dev=/dev/cs2.0 ListFirmware

ID name type version initialization level
88 DB C64 INIT_OK 
91 ASN1 C64 INIT_OK 

Gemalto SafeNet Luna HSM connection problem with physical partition, RSA key generation mechanism with Luna 7.x

Followings are the changes required in crystoki.ini file to remove latency while working with Gemalto 7.x HSM in PED authenticated mode.

  1. Change ProtectedAuthenticationPathFlagStatus equal to “1” from “0” if a PED is used.
  2. Add RSAKeyGenMechRemap under the miscellaneous section and set to a value of “1”.

Advantages of Key Wrapping

HSMs normally struggle with internal limits to store more than a few hundred or a few thousand user keys. The key wrapping approach makes it more practical to manage many thousands or even millions of user keys. This is the only practical way of supporting large user bases.

The HSM are generally expensive, and if all the user keys are to be stored within the HSM, then multiple HSMs would be needed to work together, hence the overall solution cost would be much higher, plus it would be a very complex system to manage and administer many different HSMs. With the key wrapping approach, the dependence on HSM storage is minimized hence two HSMs for high-availability are sufficient. In addition the required storage capacity, management and administration effort for these HSMs will be lower.

Not all HSMs support the key wrapping functionality. The ADSS Server’s built-in PKCS#11 test utility can be used to verify if the underlying HSM supports the key wrapping functionality. Ensure your HSM has the ability to export keys.

The security of wrapped user keys depends on the security of the Key Encryption Key (KEK), i.e. its key length and algorithm used. The industry standard is to use a AES 256-bit key. This is considered secure and the only option against this algorithm is a brute force attack, which is not practical given the 256-bit key size. The KEK is generated, stored and used inside the HSM so there is no potential for an attacker to get it through any other means. Therefore this approach provides almost the same security level for the user keys.

If the user key is wrapped and stored in the database, then at the time of signing, it requires additional calls to retrieve the key from database and unwrap in the HSM. Although database and HSM operations are very fast but it would still not provide the same performance in absolute terms when compared to if the user key was already in the HSM. However from a user perspective this small difference in time will not be visible – you can judge this in your test environment. Furthermore in a bulk signing scenario, for the first signing operation the key is retrieved from the database and unwrapped to HSM, but for subsequent signing operations the key is already in HSM hence the overall performance would almost be same for both modes.

Standards and Regulations
It is important to look at whether the key wrapping approach is acceptable according to local regulations. Most countries we know of allow this approach. The most common example of this is in the EU and the new eIDAS Regulation. This allows for this approach as long as it is done in a secure manner, e.g. the keys are protected by a certified HSM which acts as a Qualified Signature Creation Device, and furthermore there is a front-end Signature Activation Module (SAM) which authenticates the user fully and seeks their authorization to use the key protected by the HSM for signing a particular identified data item. Within eIDAS this approach is allowed for both advanced and Qualified Signatures – which is the highest level of trust. In terms of standards, the key wrapping technique is well known and defined in PKCS#11 standard as being supported by HSM vendors – our solution follows the PKCS#11 standard approach rather than a particular HSM vendors proprietary approach.

How to configure Gemalto/Thales Luna SA and Luna PCI HSMs using Physical Slots with the ADSS Server?

To make ADSS Server work with a Luna Physical Slot when you're using a PED based HSM, please add "ProtectedAuthenticationPathFlagStatus=1" (without quotes) in the crystoki.ini file. It should be added under the Misc section of the configuration file. 

To make ADSS Server work with a Luna Physical Slot when you're using a PED based HSM, please add "ProtectedAuthenticationPathFlagStatus=1" (without quotes) in the crystoki.conf file. It should be added under the Misc section of the configuration file.

What if RSA Keys are not being created in Safenet Luna SA Network HSM (FIPS Mode)?

ADSS Server is currently using ‘RSA X/9.31’ mechanism for RSA key generation in HSM. This mechanism works perfectly when HSM (Safenet Luna HSM) is operating in normal mode. However, when HSM starts operating in FIPS mode, the mechanism becomes unsupportive and throws the following exception:

iaik.pkcs.pkcs11.provider.IAIKPkcs11Exception: iaik.pkcs.pkcs11.wrapper.PKCS11Exception: CKR_MECHANISM_INVALID

This issue will come with every SafeNet Luna HSM having firmware 6.x or higher which is configured in FIPS mode.

In between ADSS Server and Safenet Luna HSM, there is a client normally known as Luna Client that receives API requests and proposed mechanisms from ADSS Server and interacts with Safenet Luna HSM accordingly. In order to resolve this issue, we need to activate mechanism mapping via property named “RSAKeyGenMechRemap” in misc section of Luna Client configuration file named “crystoki.ini”. This property is OFF by default.

The details for this property are as:


Controls what happens on newer firmware, when calls are made to specific older mechanisms that are now discouraged due to weakness.

When this item is set to 0, no re-mapping is performed.

When the value is set to 1, the following re-mapping occurs if the HSM firmware permits:

Thales documentation reference:

Pre-requisite to connect the ADSS Server on the physical slot of Safenet Luna SA Network HSMs

In order to connect the ADSS Server on the physical slot, you need to add the property named ProtectedAuthenticationPathFlagStatus=1 in the [Misc] section of the Luna Client configuration file named “crystoki.ini”. This property is OFF by default. 

The following are the instructions for this configuration (must be done before creating the Crypto Source with the physical slot of the HSM, in the ADSS Server Console):

  1. Launch Notepad (or any other text editing tool) with Administrative rights (Run as Administrator option)
  2. Open the “crystoki.ini” file from folder: C:\Program Files\SafeNet\LunaClient\
  3. Add property ProtectedAuthenticationPathFlagStatus=1 in [Misc] section and save the file