Linux Minimal Luna Client Install - Overview
Minimal client install is intended for container instances to interact with SafeNet Luna HSM partitions, and contains the minimum run-time libraries required for a cryptography application to connect to SafeNet Luna Network HSM using PKCS#11 or Java APIs. The minimal client does not include tools necessary to register Docker clients and to initialize partitions (example: LunaCM or vtl).
NOTE If you require those tools and need to include them in your docker image, copy the additional files to a directory where your dockerfile can grab them during creation of the image.
The SafeNet Luna Minimal Client, when installed on minimalist or microservice containers, requires that you have the appropriate configuration file and certificates folders (for NTLS or STC) available. Two general approaches are possible:
>If each Docker container (default) has a private IP address dynamically assigned to the container at run time:
• You have separately performed a full Luna HSM Client installation on the host system, configured it, and registered with the intended SafeNet Luna Network HSM partition(s) - this creates a single set of configuration file and certificate folders.
•A container image is created, using the SafeNet Luna Minimal Client package.
•Containers are created from that image.
•Each container can mount the needed configuration from the one location on the host.
•Because all containers have the same IP address and appear as the same client, disable ntls ipchecking on the SafeNet Luna Network HSM appliance.
OR
>If a unique public IP address is assigned to each Docker container, visible to the SafeNet Luna Network HSM appliance:
•A separate NTLS configuration is performed at the full Luna HSM Client on the host computer, for each proposed container IP, and the resulting configuration file and certificates folders are saved to unique mountable locations on the host file system.
•A container image is created, using the SafeNet Luna Minimal Client package.
•Containers are created from the image.
•Each container gets its own configuration file and unique certificates by mounting the corresponding directory structure from the host.
•Because each container has its own unique public IP address, and is considered its own client, keep ntls ipcheck enabled on the SafeNet Luna Network HSM appliance.
Included in the Minimal Client Installation
The following components are included in the SafeNet Luna Minimal Client installation:
>Cryptoki library, cklog library, and soft token (for STC) library
>JCProv library and jar file
>JSP library and jar file
>Configuration template file (Chrystoki.conf)
>Openssl configuration file
>End-User License Agreement PDF
The configuration template file is included, in case you wish to populate it via direct editing (perhaps by script). Otherwise, a configuration file is created and modified when you perform a full (non-minimal) installation and configuration elsewhere, and you can simply have your Docker containers mount the external location.
Installation Prerequisites
Ensure that you have the following prerequisites before installing the SafeNet Luna Minimal Client:
> A Linux host system with Docker installed (see https://www.docker.com/ for Docker download and install) and with Luna HSM Client installed (see Installing the Client Software )
>A copy of the Luna Minimal Client tarball package
>A SafeNet Luna Network HSM 7.x appliance, already initialized and ready to use
>A working knowledge of Docker
Summary of SafeNet Luna Minimal Client Installation with Docker on Linux
>Perform a full Luna HSM Client installation onto a Linux system (see Installing the Client Software). This is the full client with tools to customize the configuration file and prepare the certificates that will later be needed by Minimal Client instances. Follow the instructions in the Configuration Guide (see Planning Your Configuration) to perform any of the actions not already done:
•Configure the SafeNet Luna Network HSM network settings.
•Initialize the HSM.
•Create an application partition on the Network HSM.
•Exchange host certificates between Luna HSM Client and the SafeNet Luna Network HSM and register each with the other (On the client side, add the Network HSM's certificate to the server certs folder and to the CAFile. On the Network HSM, register the client with lunash:>client register).
•Start the NTLS service on the appliance with lunash:>service restart ntls, and assign the client to the application partition with lunash:>client assign partition.
•On the client side, use LunaCM to configure the application partition (see Configure Application Partitions), initializing the partition and creating roles as appropriate.
•After configuring Luna HSM Client on a host system, edit the Chrystoki.conf file for use in containers, as described in .
•If all the eventual Docker containers will reside at a single IP address, use lunash:>ntls ipcheck disable to switch off client source IP address validation at the SafeNet Luna Network HSM appliance; the containers can reference the single configuration and certificates set, as a mounted volume.
If each of the eventual Docker containers will reside at its own unique IP address, visible to the SafeNet Luna Network HSMs, then [re-]perform the configuration, certificate exchange, and client-partition registration as many times as necessary to have cert sets and registration for every IP address that your containers will use. Ensure that the appropriate set of config and cert files is included within each respective container. Leave ipcheck enabled on the SafeNet Luna Network HSM appliance.
>Create and build a Docker image containing the untarred Luna Minimal Client files.
>Launch a container, using the image.
For multiple containers at one address, make the contents of the config directory available to the Container by mounting the config directory as a volume (see above, includes the Chrystoki.conf file and the certs directories from the installed and configured full Luna HSM Client).
Example:
docker run -it --name lunaclient -v $PWD/config:/usr/local/luna/config lunaclient-image
Preparing the Configuration File for Use with Luna Minimal Client and Docker
After configuring the full Luna HSM Client on a host computer, make the following edits to the Chrystoki.conf file before using it in the containers:
1.Change all the library paths (for example LibUNIX64) to /usr/local/luna/libs/64
2.Change the certificate and client token paths to the the directory you are making available to the containers at run-time (for example /usr/local/luna/config/certs)
3.Use an editor or a Linux tool like sed (example Linux Minimal Install - sed example to modify the config file) to make the required changes to the Chrystoki.conf file to be used by the containers:
| Entry in Chrystoki.conf | Value in the host system | Value in the containers |
|---|---|---|
| ClientPrivKeyFile | /usr/safenet/lunaclient/cert/client | /usr/local/luna/config/certs |
| ClientCertFile | /usr/safenet/lunaclient/cert/client | /usr/local/luna/config/certs |
| ServerCAFile | /usr/safenet/lunaclient/cert/server | /usr/local/luna/config/certs/ |
| PartitionPolicyTemplatePath | /usr/safenet/lunaclient/data/partition_policy_templates | /usr/local/luna/config/ppt/partition_policy_templates |
| LibUNIX64 | /usr/safenet/lunaclient/lib/libCryptoki2_64.so | /usr/local/luna/libs/64/libCryptoki2.so |
| ClientTokenLib | /usr/safenet/lunaclient/lib/libSoftToken.so | /usr/local/luna/libs/64/libSoftToken.so |
| SoftTokenDir | /usr/safenet/lunaclient/configData/token | /usr/local/luna/config/stc/token |
| ClientIdentitiesDir | /usr/safenet/lunaclient/data/client_identities | /usr/local/luna/config/stc/client_identities |
| PartitionIdentitiesDir | /usr/safenet/lunaclient/data/psrtition_identities | /usr/local/luna/config/stc/partition_identities |
NOTE Replace "64" with "32" if you use 32-bit containers.
Ready to Install Minimal Client
For detailed instructions, see Installing Luna Minimal Client on Linux Using Docker.
