Application Programming Interface (API) Overview

The major API provided with Luna Product Software Development Kit conforms to RSA Laboratories' Public-Key Cryptography Standards #11 (PKCS #11) v2.20, as described in PKCS#11 Support. A set of API services (called PKCS #11 Extensions) designed by Thales, augments the services provided by PKCS#11, as described in Extensions to PKCS#11. The extensions to each API enable optimum use of Luna hardware for commonly used calls and functions, where the unaugmented API would tend to use software, or to make generic, non-optimized use of available HSMs.

In addition, support is provided for Microsoft’s cryptographic APIs (CAPI/CNG) (see Microsoft Interfaces and Oracle’s Java Security API (see Java Interfaces).

The API is a library – a DLL in Windows, a shared object in Solaris, AIX and Linux – called Chrystoki. Applications wanting to use token services must connect with Chrystoki.

NOTE   Luna HSM Client 10.1.0 and newer includes libraries for 64-bit operating systems only.

Table 1: Luna libraries by platform
Platform Key name Libraries
Windows LibNT

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

C:\Program Files\SafeNet\LunaClient\cklog201.dll

C:\Program Files\SafeNet\LunaClient\shim.dll

C:\Program Files\SafeNet\LunaClient\LunaCSP\LunaCSP.dll

C:\WINDOWS\system32\SafeNetKSP.dll

Solaris (32-bit) LibUNIX /opt/safenet/lunaclient/lib/libCryptoki2.so
/opt/safenet/lunaclient/lib/libcklog2.so
/opt/safenet/lunaclient/lib/libshim.so
Solaris (64-bit) LibUNIX64 /opt/safenet/lunaclient/lib/libCryptoki2_64.so
/opt/safenet/lunaclient/lib/libcklog2.so
/opt/safenet/lunaclient/lib/libshim_64.so
Linux (32-bit) LibUNIX /usr/safenet/lunaclient/lib/libCryptoki2.so
/usr/safenet/lunaclient/lib/libcklog2.so
/usr/safenet/lunaclient/lib/libshim.so
Linux (64-bit) LibUNIX64

/usr/safenet/lunaclient/lib/libCryptoki2_64.so

/usr/safenet/lunaclient/lib/libcklog2.so

/usr/safenet/lunaclient/lib/libshim_64.so
AIX (32- and 64-bit) LibAIX /usr/safenet/lunaclient/lib/libCryptoki2.so
/usr/safenet/lunaclient/lib/libCryptoki2_64.so
/usr/safenet/lunaclient/lib/libcklog2.so
/usr/safenet/lunaclient/lib/libshim.so

Sample Application

Included with Luna Product Software Development Kit is a sample application – and the source code – to accelerate integration of Thales’s cryptographic engine into your system.

NOTE   To reduce development or adaptation time, you may re-distribute the salogin program to customers who use Luna PCIe HSM 7, in accordance with the terms of the End User License Agreement. However, you may not re-distribute the Luna Software Development Kit itself.

A Note About RSA Key Attributes ‘p’ and ‘q’

When RSA keys are generated, ‘p’ and ‘q’ components are generated which, theoretically, could be of considerably different sizes.

Unwrapping

The Luna PCIe HSM 7 allows RSA private keys to be unwrapped onto the HSM where the lengths of the ‘p’ and ‘q’ components are unequal.  Because the effective strength of an RSA key pair is determined by the length of the shorter component, choosing ‘p’ and ‘q’ to be of equal length provides the maximum strength from the generated key pair.  If your application is designed to generate key pairs that will be unwrapped onto the HSM, care should be taken in choosing the lengths of the 'p' and 'q' components such that they differ by no more than 15%.

Generation

Where you are generating RSA private keys within the HSM, the HSM enforces that ‘p’ and ‘q’ be equal in size, to the byte level.

A Note About the Shim

The Client install includes a shim library to support PKCS#11 integration with various third-party products. You should have no need for this shim library in your development. If for some reason you determine that you need the shim, Chrystoki supports it.