Libraries and Applications

This section explains how to make the Chrystoki library available to the other components of the Luna 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.

Luna SDK Applications General Information

All applications provided in Luna Cloud 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).

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\Cryptovisor\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

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/safenet/cryptovisor/client/p11/lib.i686/libCryptoki2.so;
LibUNIX64=/usr/safenet/cryptovisor/client/p11/lib/libCryptoki2.so;
}
Luna = {
DefaultTimeOut=500000;
PEDTimeout1=100000;
PEDTimeout2=200000;
PEDTimeout3=10000;
KeypairGenTimeOut=2700000;
CloningCommandTimeOut=300000;
}
CardReader = {
RemoteCommand=1;
}

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 crystoki.ini (Windows) or crystoki.conf (UNIX) file.

Compiler Tools

Tools used for Luna development are platform specific tools/development environments, where applicable. Current version information is provided in the Customer Release Notes.

NOTE   Contact Thales for information about the availability of newer versions of compilers.

Using CKlog

NOTE   If you have a Data Protection on Demand Luna Cloud HSM service deployment, and you wish to obtain CKLog, please contact customer support to obtain the necessary files.

Luna Software Development Kit provides a facility which can record all interactions between an application and the 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. Cklog is a shim library that an application accesses when seeking our PKCS#11 library. When cklog 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. Configuration consists of redirecting the LibNT (Windows) or LibUNIX (Linux/UNIX) library locations, and setting some additional configuration options as summarized after the examples, below.

To configure CkLog:

Perform these steps:

1.Direct the application to use the cklog library instead of the regular Chrystoki library. Do this by modifying the configuration file to instruct CkBridge to load the Cklog library.

Windows

[Chrystoki2]
LibNT=c:\Program Files\SafeNet\Cryptovisor\cklog201.dll

Linux/UNIX

Chrystoki2 = {
LibUNIX=/usr/safenet/cryptovisor/client/p11/lib.i686/libcklog2.so;
LibUNIX64=/usr/safenet/cryptovisor/client/p11/lib/libcklog2.so;

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

Windows

[CkLog2]
LibNT=c:\Program_Files\SafeNet\Cryptovisor\cryptoki.dll

Linux/UNIX

CkLog2 = {
LibUNIX=/usr/safenet/cryptovisor/client/p11/lib.i686/libcklog2.so;
LibUNIX64=/usr/safenet/cryptovisor/client/p11/lib/libCryptoki2.so;
}

3.Add appropriate entries to the CkLog2 section for the desired level of operation. See the examples and explanations of entries, below.

Windows Example

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

[Chrystoki2]
LibNT=c:\Program Files\SafeNet\Cryptovisor\cklog201.dll
[CkLog2]
LibNT=c:\Program Files\SafeNet\Cryptovisor\cryptoki.dll
Enabled=1
File=c:\Program Files\SafeNet\Cryptovisor\\cklog2.txt
Error=c:\Program Files\SafeNet\Cryptovisor\\error.txt

FileSize=100
NewFormat=1
LoggingMask=ALL_FUNC

UNIX Example

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

Chrystoki2 = {
LibUNIX64=/usr/safenet/cryptovisor/client/p11/lib/libcklog2.so;
}
CkLog2 = {
LibUNIX=/usr/safenet/cryptovisor/client/p11/lib.i686/libCryptoki2.so;
LibUNIX64=/usr/safenet/cryptovisor/client/p11/lib/libCryptoki2.so;
Enabled=1;
File=/tmp/cklog.txt;
FileSize=100
Error=/tmp/error.txt;
NewFormat=1;
LoggingMask=ALL_FUNC;
}

Here are descriptions of entries that might be applicable:

>LibNT - references to a Cryptoki library for Windows.

>LibUNIX - references to a Cryptoki library for 32-bit UNIX.

>LibUNIX64 - references to a Cryptoki library for 64-bit UNIX.

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

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

>FileSize - in MB is the size that triggers log-file rotation - when the file reaches the indicated value, it is renamed to indicate the current date and time (like cklog.txt-<YYMMDD-hhmmss>), and a new cklog.txt file begins accumulating log entries.

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

>NewFormat - affects the log output format. Possible values:

•0: standard log output format

•1 (default): compact output format preferred by Thales Customer Support

2023-06-27 15:38:48 07724--424540352:FINIInitialize CKR_OK(10ms) {}

•2: compact output format, including the amount of real time that HSM Client took to process the request (operation latency, in ms). This option requires HSM Client 10.6.0 or newer.

2023-06-27 15:38:48 07724--424540352:FINIInitialize CKR_OK(10ms) (operation latency: 40ms) {}

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:

Flag	Description
GEN_FUNC	General functions
SLOT_TOKEN_FUNC	Slot/Token related functions
SESSION_FUNC	Session related functions
OBJ_MNGMNT_FUNC	Object Management functions
ENC_DEC_FUNC	Encrypt/Decrypt related functions
DIGEST_FUNC	Digest Related functions
SIGN_VERIFY_FUNC	Signing/Verifying related functions
KEY_MNGMNT_FUNC	Key Management related functions
MISC_FUNC	Misc functions
CHRYSALIS_FUNC	Luna Extensions functions
ALL_FUNC	All functions logged;

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.