Luna Minimal Client Install for Linux - Overview

Minimal client install is intended for container instances to interact with Luna HSM partitions, and contains the minimum run-time libraries required for a cryptography application to connect to Luna Network HSM using PKCS#11 or Java APIs, in addition to some configuration tools. The Luna Minimal Install is provided as a tarball that you can unpack where desired, and choose the files that you need.

Mandatory files for configuration and secure communication, where to get them and where to keep them

The Luna Minimal Client, when installed on minimalist or micro-service containers, requires that you have the appropriate files and folders available

>Chrystoki.conf configuration file (includes settings, and pointers to resources),

>certificates folders (for secure communications protocols, NTLS or STC)

>libraries and plugins required for secure communications protocols.

The Luna Minimal Client tarball includes a "template" version of the Chrystoki.conf file that you can edit for any non-default settings needed by your application, and to reflect the actual paths to resources.

Alternatively, you might already have a configured Chrystoki.conf file that you can copy into the Docker container with the minimal client, or that you can leave at an external location that is mountable from within the Docker container.

Similarly, the Docker container with the minimal client must have access to the certificates (local host certificate, and certificates from any registered application partitions or Thales Data Protection on Demand (DPoD) Luna Cloud HSM services) for secure communication. Those can reside inside the container, or can reside on an external mountable drive - either way, the paths in the Chrystoki.conf file must point to their location.

Configure and link, inside your Docker container

You will need to untar the Minimal Client tarball in your container, or open it elsewhere and copy the desired files to your container.

If you already have a Chrystoki.conf file with most, or all, of your desired settings, you can copy it into the container and edit it manually.

If you do not have suitable Chrystoki.conf file, the minimal client tarball contains a config template file that you can modify with the configurator utility.

At the same time, you can create and exchange certificates by means of the included vtl utility. Ensure that the resulting certificates are pointed-to in Chrystoki.conf file. For example instructions, see Installing Luna Minimal Client on Linux Using Docker.

Configure and link, exterior to your Docker container

To configure Chrystoki.conf and to establish an NTLS or STC link outside your Docker container, for later use by one-or-more Docker containers, you can

>Untar the Luna Minimal Client tarball at the desired staging location, use configurator or manually edit the Chrystoki.conf file, and use vtl to establish the secure link to Luna Network HSM appliance.

OR

>Install the full Luna HSM Client, and follow the instructions to create/update the Chrystoki.conf file, and create and exchange certificates for a secure link to a Network HSM appliance.

The above could be done before the Docker container is created, or after one exists.

Whether you elect to pre-configure externally, with a full Luna HSM Client Installation or with a copy of the Luna Minimal Client, or from inside each Docker container after it is created (and populated and configured with the Luna Minimal Client), two general networking approaches are possible:

[Network OPTION] Dynamic private IP address per container

If each Docker container (default) has a private IP address dynamically assigned to the container at run time:

•A single set of configuration file and certificate folders is needed, that will apply to any container within that hidden/translated subnet.

•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, you must disable ntls ipchecking on the Luna Network HSM appliance.

[Network OPTION] Unique public IP address per container

If a unique public IP address is assigned to each Docker container, visible to the Luna Network HSM appliance:

•A separate NTLS configuration is performed, either externally on the host computer, for each proposed container IP, with the resulting configuration file and certificates folders saved to unique mountable locations on the host file system, OR configuration and certificate exchange is performed from the minimal client within each container after it is created.

•Each container gets its own configuration file and unique certificates whether mounted externally or residing inside the container.

•Because each container has its own unique public IP address, and is considered its own client, keep ntls ipcheck enabled on the Luna Network HSM appliance.

DPoD

With the additional tools included in the minimal install archive, as of release 7.6, the expanded minimal client has the needed tools for local (in-container) configuration. If you intend to connect with DPoD's HSM-on-Demand services, see From Linux Minimal Client Create a Docker Container to Access a DPOD Luna Cloud HSM Service for additional steps.

Included in the Minimal Client

The following components are included in the Luna Minimal Client tar ball:

Component	Used or needed for...
JCPROV
LunaClient-Minimal-<release_version>.x86_64/jcprov/jcprov.jar	JCPROV jar file
LunaClient-Minimal-<release_version>.x86_64/jcprov/64/libjcprov.so	JCPROV library
JSP
LunaClient-Minimal-<release_version>.x86_64/jsp/LunaProvider.jar	JSP jar file
LunaClient-Minimal-<release_version>.x86_64/jsp/64/libLunaAPI.so	JSP library
LIBRARIES
LunaClient-Minimal-<release_version>.x86_64/libs/64/libCryptoki2.so	Library to address cryptographic functions of the HSM
LunaClient-Minimal-<release_version>.x86_64/libs/64/libCryptoki2_64.so	Symbolic link pointing to libCryptoki2.so, needed for FM hostapps compiled against libCryptoki2_64.so
LunaClient-Minimal-<release_version>.x86_64/libs/64/libethsm.so	Library to interact with Functionality Modules
LunaClient-Minimal-<release_version>.x86_64/libs/64/libSoftToken.so	Library for STC connection (alternative to NTLS)
LunaClient-Minimal-<release_version>.x86_64/libs/64/libcklog2.so	Logging library - invoked by vtl cklog enable command to log commands before passing them to the cryptoki library and the HSM.
PLUG-INS
LunaClient-Minimal-<release_version>.x86_64/plugins/libdpod.plugin	Enable connection protocol with DPoD services (See also the related XTC and REST sections of chrystoki.conf file)
CONFIGURATION FILES
LunaClient-Minimal-<release_version>.x86_64/Chrystoki-template.conf	Chrystoki.conf template in case you don't already have a conf file.
LunaClient-Minimal-<release_version>.x86_64/openssl.cnf	Configuration file for OpenSSL.
BINARIES/TOOLS
LunaClient-Minimal-<release_version>.x86_64/bin/64/mkfm	Allow client to connect to Functionality Modules (if you have installed any in the HSM)
LunaClient-Minimal-<release_version>.x86_64/bin/64/configurator	Configuration file management tool
LunaClient-Minimal-<release_version>.x86_64/bin/64/ckdemo	Demonstrates individual, atomic, PKCS#11 operations in the HSM
LunaClient-Minimal-<release_version>.x86_64/bin/64/lunacm	Partition administration tool
LunaClient-Minimal-<release_version>.x86_64/bin/64/cmu	Certificate Management Utility
LunaClient-Minimal-<release_version>.x86_64/bin/64/multitoken	Perform multiple crypto commands on multiple slots
LunaClient-Minimal-<release_version>.x86_64/bin/64/pscp   LunaClient-Minimal-<release_version>.x86_64/bin/64/plink	Used for One Step NTLS
LunaClient-Minimal-<release_version>.x86_64/bin/64/salogin	Persistent application connection tool
LunaClient-Minimal-<release_version>.x86_64/bin/64/vtl	Configuration tool (certificate creation and exchange, registration of clients with partitions, logging, etc.)
LICENSE AGREEMENT
LunaClient-Minimal-<release_version>.x86_64/008-010068-001 _EULA_HSM7_SW_revB.pdf
LunaClient-Minimal-<release_version>.x86_64/008-010068-001 _EULA_HSM7_SW_revB.txt

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 to make use of the resulting chrystoki.conf file and certificate folders.

Installation Prerequisites

Ensure that you have the following prerequisites before installing the Luna Minimal Client:

> A Linux host system with Docker installed (see https://www.docker.com/ for Docker download and install)

>A copy of the Luna Minimal Client tarball package

>A Luna Network HSM 7.x appliance, already initialized and ready to use (or an account for access to DPoD Luna Cloud HSM services) -- perform any of the actions not already done:

•Configure the 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 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 Initializing an Application Partition), 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 Preparing the Configuration File for Use with Luna Minimal Client and Docker below.

>A working knowledge of Docker.

Preparing the Configuration File for Use with Luna Minimal Client and Docker

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)

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/partition_identities	/usr/local/luna/config/stc/partition_identities
ToolsDir	/usr/safenet/lunaclient/bin	/usr/local/luna/bin/64
SSLConfigFile	/usr/safenet/lunaclient/bin/openssl.cnf	/usr/local/luna/openssl.cnf

Ready to Install Minimal Client

For detailed instructions, see Installing Luna Minimal Client on Linux Using Docker.

For additional instructions on using the minimal client with Functionality Modules, see Create a Luna HSM Client Docker image for use with Functionality Modules.

For additional instructions on using the minimal client with DPoD Luna Cloud HSM services, see From Linux Minimal Client Create a Docker Container to Access a DPOD Luna Cloud HSM Service.