Installing Luna Minimal Client on Linux Using Docker

The following procedure allows you to install the Luna Minimal Client in a Docker container on Linux, so that applications in that container can access Luna Network HSM 7 partitions. For an overview description of Luna Minimal Client and its prerequisites, see Luna Minimal Client Install for Linux - Overview.

To install the Luna Minimal Client software on a Linux 64-bit Docker instance:

This example uses NTLS. The use of STC is optional. This example is based on CentOS 7; other operating systems might require adjustments to the commands and to the docker file.

1.Create a directory. In this example:

$HOME/luna-docker

The name is not important, only that you use it consistently.

2.Create the following subdirectories under that first directory:

$HOME/luna-docker/config
$HOME/luna-docker/config/certs

additionally, if you are configuring STC:

$HOME/luna-docker/config/stc
$HOME/luna-docker/config/stc/client_identities
$HOME/luna-docker/config/stc/partition_identities
$HOME/luna-docker/config/stc/token/001

and create an empty file:

•for Luna HSM Firmware 7.4.2 and older:

$HOME/luna-docker/config/stc/token/001/token.db

•for Luna HSM Firmware 7.7.0 and newer:

$HOME/luna-docker/config/stc/token/001/token_v2.db     

The contents of the config directory are needed by the Docker containers.

3.Copy the Luna Minimal Client tarball to $HOME/luna-docker.

4.Untar the Luna Minimal Client tarball.

>tar -xf $HOME/luna-docker/LunaClient-Minimal-<release_version>.x86_64.tar -C $HOME/luna-docker

5.Copy the Chrystoki.conf file from the Minimal Client directory to $HOME/luna-docker/config.

>cp $HOME/luna-docker/LunaClient-Minimal-<release_version>.x86_64/Chrystoki-template.conf $HOME/luna-docker/config/Chrystoki.conf

6.Define the following environment variable:

>export ChrystokiConfigurationPath=$HOME/luna-docker/config

7.[Optional] If you choose to use STC, review the Luna Network HSM 7 documentation and modify the following instructions. The goal is to have an HSM partition created and registered with the full Luna HSM Client before you create the Docker image and containers.

8.Update the Chrystoki.conf file paths so the tools work as expected

>MIN_CLIENT_DIR=$HOME/luna-docker/LunaClient-Minimal-<release_version>.x86_64  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s Chrystoki2 -e LibUNIX -v $MIN_CLIENT_DIR/libs/64/libCryptoki2.so  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s Chrystoki2 -e LibUNIX64 -v $MIN_CLIENT_DIR/libs/64/libCryptoki2_64.so  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s Misc -e ToolsDir -v $MIN_CLIENT_DIR/bin/64  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "LunaSA Client" -e SSLConfigFile -v $MIN_CLIENT_DIR/openssl.cnf  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "LunaSA Client" -e ClientPrivKeyFile -v $HOME/luna-docker/config/certs/dockerlunaclientKey.pem  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "LunaSA Client" -e ClientCertFile -v $HOME/luna-docker/config/certs/dockerlunaclient.pem  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "LunaSA Client" -e ServerCAFile -v $HOME/luna-docker/config/certs/CAFile.pem  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "Secure Trusted Channel" -e ClientTokenLib -v $MIN_CLIENT_DIR/libs/64/libSoftToken.so  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "Secure Trusted Channel" -e SoftTokenDir -v $HOME/luna-docker/config/stc/token  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "Secure Trusted Channel" -e ClientIdentitiesDir -v $HOME/luna-docker/config/stc/client_identities  

>$MIN_CLIENT_DIR/bin/64/configurator setValue -s "Secure Trusted Channel" -e PartitionIdentitiesDir -v $HOME/luna-docker/config/stc/partition_identities  

9.Create a Luna HSM Client certificate for the Docker containers.

>$MIN_CLIENT_DIR/bin/64/vtl createCert -n <cert_name>

10.Copy the client certificate to the Luna Network HSM 7 appliance.

>scp $HOME/luna-docker/config/certs/<cert_name>.pem admin@<Network_HSM_IP>:

11.Copy the appliance server certificate (server.pem) to $HOME/luna-docker/config/certs

>scp admin@<Network_HSM_IP>:server.pem $HOME/luna-docker/config/certs

12.Register the appliance server certificate with the Client.

>$MIN_CLIENT_DIR/bin/64/vtl addServer -c $HOME/luna-docker/config/certs/server.pem -n <Network_HSM_IP>

13.Connect via SSH to the Luna Network HSM 7 appliance and log in to LunaSH.

>ssh admin@<Network_HSM_IP>

From this point it is assumed that the appliance already has a valid server.pem. If not, then generate a new one via the lunash:> sysconf regenCert command.

14.Create a partition, if one does not already exist on the HSM.

lunash:>partition create -partition <partition_name>

The HSM must already have been initialized, via lunash:> hsm init command, and the HSM SO must log in via hsm login command, for application partitions to be created.
For HSMs at Luna HSM Firmware 7.7.0 or newer, any new partition defaults to version zero (V0), unless you specify V1 in the partition create command.

15.Register the full Luna HSM Client with the appliance, and assign the partition to the client.

lunash:> client register -client <client_name> {-ip <client_IP> | -hostname <client_hostname>}

lunash:> client assignPartition -client <client_name> -partition <partition_name>

lunash:> ntls ipcheck disable

lunash:> exit

16.On the Client workstation, run LunaCM, set the active slot to the registered partition, and initialize it.

>$MIN_CLIENT_DIR/bin/64/lunacm

lunacm:> slot set -slot <slotnum>

lunacm:> partition init -label <partition_label>

lunacm:> exit

17.Update the paths of the libraries, certs and general fields to their future Docker image locations within the $ChrystokiConfigurationPath/Chrystoki.conf.

>sed -i -e 's#'$HOME'/luna-docker/config#/usr/local/luna/config#g' -e 's#'$HOME'/luna-docker/LunaClient-Minimal-\([0-9\.-]\+\)x86_64#/usr/local/luna#g' $ChrystokiConfigurationPath/Chrystoki.conf

Create a Luna HSM Client Docker image

The minimal client tarball includes files necessary for basic operation, and some tools; copy any additional files you want to include in the docker image to $HOME/luna-docker/. This example includes the entire Luna Minimal Client.

1.Create a file named Dockerfile with the following contents:

FROM ubuntu:xenial
#FROM centos:centos7

ARG MIN_CLIENT
COPY $MIN_CLIENT.tar /tmp
RUN mkdir -p /usr/local/luna
RUN tar xvf /tmp/$MIN_CLIENT.tar --strip 1 -C /usr/local/luna
ENV ChrystokiConfigurationPath=/usr/local/luna/config
ENV PATH="/usr/local/luna/bin/64:${PATH}"

# The package below is necessary for One-Step NTLS if you want to setup NTLS within the Docker container.
# The only requirement beyond glibc.i686 (required by plink and pscp) would be a configured Chrystoki.conf
# The minimal client documentation section 8 has example commands, you should modify the value parameter ("-v")
#    to point to desired files/directories.
# One-Step NTLS uses the section “Misc” entry “ToolsDir” to find the plink/pscp binaries,
# The Chrystoki.conf needs the following entries to be updated for One-Step NTLS to work:
# Section         | Entry
# --------------------------
# Chrystoki2      | LibUNIX
# Chrystoki2      | LibUNIX64
# Misc            | ToolsDir
# "LunaSA Client" | SSLConfigFile
# "LunaSA Client" | ClientPrivKeyFile
# "LunaSA Client" | ClientCertFile
# "LunaSA Client" | ServerCAFile
# Syntax: configurator setValue –s <Section> -e <Entry> -v <value>
# Example: configurator setValue -s Misc -e ToolsDir -v /usr/local/luna/bin/64
# Ubuntu:
#RUN dpkg --add-architecture i386
#RUN apt-get update
#RUN apt-get -y install libc6:i386
# Centos:
#RUN yum install -y glibc.i686

ENTRYPOINT  /bin/bash
#End of the Dockerfile

2.Build a Docker image.

>docker build . --build-arg MIN_CLIENT=LunaClient-Minimal-<release_version>.x86_64 -t lunaclient-image

3.Use the following command to verify the Docker image has been created:

>docker images

Run the Docker container

1.Make the contents of the config directory available to the Containers when you create them, by mounting the config directory as a volume.

>docker run -it --name lunaclient -v $PWD/config:/usr/local/luna/config lunaclient-image

2.From the Docker container, verify that the container has a connection to the Luna Network HSM 7 partition.

Functionality Modules (FMs) with Luna Minimal Client

To use FMs with the minimal client, see Create a Luna HSM Client Docker image for use with Functionality Modules.

Thales Data Protection on Demand Luna Cloud HSM Service with Luna Minimal Client

To connect to Thales Data Protection on Demand (DPoD) Luna Cloud HSM services with the minimal client, see From Linux Minimal Client Create a Docker Container to Access a DPOD Luna Cloud HSM Service.