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 Luna PCIe 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\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 crystoki.ini (Windows) or crystoki.conf (UNIX) file.
Compiler Tools
Tools used for SafeNet development are platform specific tools/development
environments, where applicable
NOTE Contact SafeNet for information about the availability of newer versions of compilers.
Using CKlog
SafeNet 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.
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\LunaClient\cklog201.dll
Linux/UNIX
Chrystoki2 = {LibUNIX=/usr/lib/libcklog2.so;
2.Instruct the cklog library where to access the regular cryptoki library.
Windows
[CkLog2]
LibNT=c:\Program Files\SafeNet\LunaClient\cryptoki.dll
Linux/UNIX
CkLog2 = {LibUNIX=/usr/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\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;
}
Here are descriptions of entries that might be applicable:
>LibNT - references to a Cryptoki library for Windows.
>LibUNIX - references to a Cryptoki library for UNIX (meaning Solaris, Linux, and AIX).
>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
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_FUNCS |
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 |
SafeNet 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.
