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
NOTE Luna HSM Client 10.1.0 and newer includes libraries for 64-bit operating systems only.
| 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 Network 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 Network 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.
Shim Library
Luna Shim library, included in Luna Client, is used to support third-party integrations that involve customized crypto requests that the PKCS #11 Cryptoki library does not support. Some integrations that formerly required Shim are now able to use the Cryptoki library. These include IBM TAM, IBM MQ, and IBM WAS. Here are some examples of integrations that currently use the Luna Shim library:
>Oracle TDE integration uses Shim for an auto-reconnect feature that helps Oracle DB recover from network outages.
>Citrix FAS integration uses Shim for SKS key storage when the amount of keys that need to be stored cannot be accommodated by a Luna HSM partition.
>Luna PQC FM uses Shim to support PQC keys for Luna firmware versions that do not support them.
There may be other integrations that use the Shim library, so refer to your individual integration guide which will tell you whether your integration requires its support.
