Libraries and Applications

This section explains how to make the Chrystoki library available to the other components of the SafeNet Software Development Kit.

An application has no knowledge of which library is to be loaded nor does the application know the library's location.  For these reasons, a special scheme must be employed to tell the application, while it is running, where to find the library.  The next paragraphs describe how applications connect to Chrystoki.

SafeNet SDK Applications General Information

All applications provided in SafeNet Network HSM Software Development Kit have been compiled with a component called CkBridge, which uses a configuration file to find the library it is intended to load. Ckbridge first uses the environment variable "ChrystokiConfigurationPath" to locate the corresponding configuration file. If this environment variable is not set, it attempts to locate the configuration file in a default location depending on the product platform (/etc on Unix, and c:\Program Files\SafeNet\LunaClient on Windows).

Configuration files differ from one platform to the next - refer to the appropriate sub-section for the operating system and syntax applicable to your development platform.

Windows

In Windows, an initialization file called crystoki.ini specifies which library is to be loaded. The syntax of this file is standard to Windows.

The following example shows proper configuration files for Windows:

[Chrystoki2]

LibNT=C:\Program Files\SafeNet\LunaClient\cryptoki.dll 

[LunaSA Client] 

SSLConfigFile=C:\Program Files\SafeNet\LunaClient\openssl.cnf 

ReceiveTimeout=20000

NetClient=1

ServerCAFile=C:\Program Files\SafeNet\LunaClient\cert\server\CAFile.pem

ClientCertFile=C:\Program Files\SafeNet\LunaClient\cert\client\ClientNameCert.pem

ClientPrivKeyFile=C:\Program Files\SafeNet\LunaClient\cert\client\ClientNameKey.pem

[Luna]

DefaultTimeOut=500000

PEDTimeout1=100000

PEDTimeout2=200000 

PEDTimeout3=10000

[CardReader]

RemoteCommand=1

CAUTION:  NEVER insert TAB characters into the crystoki.ini (Windows) or chrystoki.conf (UNIX) file.

UNIX

In UNIX, a configuration file called "Chrystoki.conf" is used to guide CkBridge in finding the appropriate library.  

The configuration file is a regular text file with a special format. It is made up of a number of sections, each section containing one or multiple entries.  The following example shows a typical UNIX configuration file:

Chrystoki2 = {

LibUNIX=/usr/lib/libCryptoki2.so;

}

Luna = {

DefaultTimeOut=500000;

PEDTimeout1=100000;

PEDTimeout2=200000;

PEDTimeout3=10000;

KeypairGenTimeOut=2700000;

CloningCommandTimeOut=300000;

}

CardReader = {

RemoteCommand=1;

}

LunaSA Client = {

NetClient = 1;

ServerCAFile = /usr/safenet/lunaclient/cert/server/CAFile.pem;

ClientCertFile = /usr/safenet/lunaclient/cert/client/ClientNameCert.pem;

ClientPrivKeyFile = /usr/safenet/lunaclient/cert/client/ClientNameKey.pem;

SSLConfigFile = /usr/safenet/lunaclient/bin/openssl.cnf;

ReceiveTimeout = 20000;

}

The shared object "libcrystoki2.so" is a library supporting version 2.2.0 of the PKCS#11 standard.

CAUTION:  NEVER insert TAB characters into the chrystoki.ini (Windows) or crystoki.conf (UNIX) file.

Compiler Tools

Tools used for SafeNet development are platform specific tools/development environments, where applicable (e.g., Visual C++ on Windows 2008 and Windows 2012, or Workshop on Solaris, or aCC on HP-UX). Current version information is provided in the Customer Release Notes.

Note:  Contact SafeNet for information about the availability of newer versions of compilers.

The Applications

CKlog

SafeNet Software Development Kit provides a facility which can record all interactions between an application and our PKCS#11-compliant library.  It allows a developer to debug an application by viewing what the library receives.

This tool is known as the Cryptoki Logging Facility or cklog.  In fact, cklog is a library which replaces our PKCS#11 library.  However, when it receives a call it does not service the request. Instead, it logs the call to a file and passes the request to the originally intended library.

For cklog to function properly, perform these two steps:

1.Direct the application to use the cklog library instead of the regular Chrystoki library.

2.Instruct the cklog library where to access the regular library.

The first step is achieved by modifying the configuration files to instruct CkBridge to load the Cklog library.  How to achieve this redirection is described in the next sub-section.  The second step involves different blocks in the configuration file.

Here are descriptions of entries that may be applicable:

•LibNT - references to a Cryptoki library for Windows 2008 and Windows 2012.

•LibUNIX - references to a Cryptoki library for UNIX (meaning Solaris, Linus and AIX).

•LibHPUX - references to a Cryptoki library specific to HP-UX.

•Enabled - 0 or 1. Allows turning the logging facility off or on.

•File - references the file to which the requests should be logged.

•Error - references a file where the logging facility can record fatal errors.

•NewFormat - 0 or 1 disables/enables a more compact output format, which is the format preferred by SafeNet Customer Support.

Windows Example

The following example shows a typical initialization file under Windows where cklog is in use:

[Chrystoki2]

LibNT=c:\Program Files\SafeNet\LunaClient\cklog201.dll

[CkLog2]

LibNT=c:\Program Files\SafeNet\LunaClient\cryptoki.dll

Enabled=1

File=c:\Program Files\SafeNet\LunaClient\cklog2.txt

Error=c:\Program Files\SafeNet\LunaClient\error2.txt

NewFormat=1

LoggingMask=ALL_FUNC

UNIX Example

The following example shows a typical configuration file under UNIX where cklog is in use:

Chrystoki2 = {

LibUNIX=/usr/lib/libcklog2.so;

}

CkLog2 = {

LibUNIX=/usr/lib/libCryptoki2.so;

Enabled=1;

File=/tmp/cklog.txt;

Error=/tmp/error.txt;

NewFormat=1;

LoggingMask=ALL_FUNC;

}

Selective Logging

When logging is turned on, all functions are logged, by default. If you wish to restrict logging to particular functions of interest only, you can edit the “LoggingMask=” parameter in the crystoki.ini [Windows] or Chrystoki.conf [UNIX] file to include flags for the desired logging.

LoggingMask= Flags

Here is the list of possible flags for cklog:

You can mix and match any or all of the flags, using the “|” operator. For example, the following:

LoggingMask=GEN_FUNC | SLOT_TOKEN_FUNC | ENC_DEC_FUNC | SIGN_VERIFY_FUNC;

would be valid.

Note:  You can use the flags in any order. Using the ALL_FUNC flag overrides any other flag. 
If you have the “LoggingMask=” parameter, with NO flags set, then nothing is logged. If logging capability is enabled (cklog), but there is no “LoggingMask=” line, then default behavior prevails and everything is logged.

SafeNet PCI-E HSM 6.2 Product Documentation
007-011329-009 Rev. A 18 December 2015 Copyright 2015 Gemalto NV All rights reserved.