nShield® Container Option Pack v1.1.

1
User Guide
Version: 1.1.1
Date: 6 May 2021

Copyright © 2021 nCipher Security Limited. All rights reserved.

Copyright in this document is the property of nCipher Security Limited. It is not to be reproduced modified,
adapted, published, translated in any material form (including storage in any medium by electronic means
whether or not transiently or incidentally) in whole or in part nor disclosed to any third party without the prior
written permission of nCipher Security Limited neither shall it be used otherwise than for the purpose for which
it is supplied.
Words and logos marked with ® or ™ are trademarks of nCipher Security Limited or its affiliates in the EU and
other countries.
Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States
and/or other countries.
Information in this document is subject to change without notice.
nCipher Security Limited makes no warranty of any kind with regard to this information, including, but not
limited to, the implied warranties of merchantability and fitness for a particular purpose. nCipher Security
Limited shall not be liable for errors contained herein or for incidental or consequential damages concerned
with the furnishing, performance or use of this material.
Where translations have been made in this document English is the canonical language.
nCipher Security Limited
Registered Office: One Station Square,
Cambridge, CB1 2GA, United Kingdom
Registered in England No. 11673268

Copyright in this document is the property of nCipher Security Limited. It is not to be reproduced, modified,
adapted, published, translated in any material form (including storage in any medium by electronic means
whether or not transiently or incidentally) in whole or in part nor disclosed to any third party without the prior
written2 permission
Page of 16 of nCipher Security Limited neither shall it be used otherwise
nShieldthan for the purpose
Container for which
Option Pack v1.1.1
it is supplied.
Contents
1 Introduction ...................................................................................................................................4
2 Software Prerequisites .................................................................................................................5
3 Installation .....................................................................................................................................7
3.1 Install the nShield Container Option Pack ..............................................................................7
3.2 Uninstall the nShield Container Option Pack ..........................................................................7
4 Deployment Architecture..............................................................................................................8
5 The Hardserver Container ............................................................................................................9

5.1 Create nshield-hwsp .........................................................................................................9

5.1.1 Users and Groups .......................................................................................................9

5.2 Configure nshield-hwsp .....................................................................................................9

5.3 Run nshield-hwsp............................................................................................................ 10

6 Application Containers ............................................................................................................... 12

6.1 nShield base container......................................................................................................... 12
6.1.1 API Support: CHIL, Java, and PKCS #11 .................................................................. 13
6.1.2 Java applications ...................................................................................................... 13
6.2 Derive a container with Security World from application containers...................................... 14
6.3 Example applications ........................................................................................................... 14
Contact Us .......................................................................................................................................... 15

nShield Container Option Pack v1.1.1 Page 3 of 16

1 Introduction
The nShield Container Option Pack (nSCOP) provides application developers, in a container-based
environment, the ability to access the cryptographic functionality of an nShield Connect HSM. This
release of nSCOP has been tested with Docker containers.

The nShield Container Option Pack is installed on top of your existing Security World Software
installation, allowing you to continue using your existing Security World and keys.

Page 4 of 16 nShield Container Option Pack v1.1.1

2 Software Prerequisites
The nShield Container Option Pack requires nShield Security World Software and Docker to be
installed prior to the use of the nShield Container Option Pack scripts.

We have successfully tested the following configurations:

nShield HSM Security World Software nSCOP Version Container Product

Version
Connect + v12.40 v1.1.1 Docker Engine 19.03
Connect XC v12.60
v12.70

When you are using podman on RedHat Enterprise Linux, you should install podman-
docker to provide the Docker alias. nSCOP has been tested with podman-docker
v1.6.4.

nShield application containers have been tested with the following base images:

 RedHat UBI 7 and UBI 8 (including minimal)

 CentOS 6, 7, and 8

 Ubuntu Bionic 18.04

 Ubuntu Focal 20.04

 Apline (frolvlad/alpine-glibc)

 Debian Stretch 9 (including slim)

 Debian Buster 10 (including slim)

 OpenSUSE 15.1 and 15.2

 Nginx 1.18

 Apache 2.4.43
Other base images may work but are untested.

Before you can begin using nSCOP you must complete the following steps:

1. Set up the HSM(s). For instructions, see the Installation Guide of your HSM(s).
2. Using its IP address, configure your container host machine as a client of the HSM(s).
The container host machine is the machine on which you will run the nShield hardserver and
application containers.
3. To access and use cryptographic keys from a Security World, load or create a Security World
on the HSM, and map the key management data folder (kmdata) from your container host
machine into the running application containers.

nShield Container Option Pack v1.1.1 Page 5 of 16

For further information on configuring and managing nShield HSMs, Security Worlds, and Remote File
Systems, see the User Guide supplied with your Security World software.

Page 6 of 16 nShield Container Option Pack v1.1.1

3 Installation
3.1 Install the nShield Container Option Pack
1. Create the directory where you wish to install nSCOP, for example:
mkdir -p /opt/nscop.

2. Untar the option pack to this directory:

tar xf nscop-1.1.1.tar –C /opt/nscop.

All users who will use the nShield Container Option Pack scripts need execute permission to
the installed scripts and need to be able to run Docker.

The following Bash scripts are provided in this Option Pack.

Script Purpose
make-nshield-hwsp Makes an nShield hardserver Docker image.
make-nshield-hwsp-config Generates a hardserver configuration file for an nshield-hwsp
container.
make-nshield-application Creates a new Docker image with the nShield support
software installed.
extend-nshield-application Installs the nShield support software to an existing Docker
image.

3.2 Uninstall the nShield Container Option Pack

Delete the directory that contains the nShield Container Option Pack from your system.

You should remove any built Docker images or containers from your system if they are no longer
needed. For instructions on how to delete Docker images and containers, see the documentation for
Docker.

nShield Container Option Pack v1.1.1 Page 7 of 16

4 Deployment Architecture

Figure 1 nSCOP deployment architecture

The nshield-hwsp container runs the hardserver. It is supplied with configuration to connect to one
or more network HSMs. It exposes the hardserver via an AF_UNIX socket.

Access to the hardserver socket must be restricted to trusted users.

Application instances are any containers that include applications that use the nShield software stack.
They are supplied with the socket used to connect to the hardserver and access to the key
management data files to use the World and associated cryptographic keys.

The key management data files, including encrypted copies of keys, are located in kmdata. A container
mounting kmdata as a volume will be able to spoof the HSM client. Therefore, access to files in
kmdata must be controlled and restricted to trusted users.

Page 8 of 16 nShield Container Option Pack v1.1.1

5 The Hardserver Container
The hardserver container, nshield-hwsp, controls communication between the configured HSM(s)
and application containers. Only one hardserver container is required per deployment, regardless of the
number of HSM(s) or application containers.

5.1 Create nshield-hwsp

Run make-nshield-hwsp to create the hardserver container. The only required argument is the path
to a mounted nShield Security World ISO.

For example:

$ mkdir SecWorld-12.70.4
$ sudo mount -o loop SecWorld_Lin64-12.70.4.iso SecWorld-12.70.4
mount: /dev/loop0 is write-protected, mounting read-only
$ make-nshield-hwsp SecWorld-12.70.4
[...]
Successfully tagged nshield-hwsp:12.70.4

The default base image for nShield hardserver containers is RedHat UBI7. The default tag reflects the
version of nShield Security World software that the container was built from.

If you want to use a different base image, or specify a different tag, use the --from and –tag options.
See make-nshield-hwsp --help for more information.

5.1.1 Users and Groups

By default, the nfast user and group in the container match those on the host machine, and you
should create them if they do not exist. If this is not a fit for deployment, use the --uid and --gid
options to set them.

5.2 Configure nshield-hwsp

Run make-nshield-hwsp-config to create the hardserver container's configuration. This is the
config component in Figure 1 nSCOP deployment architecture.

 Use the --output option to specify the filename.

 List the IP addresses of the HSMs on the command line.

nShield Container Option Pack v1.1.1 Page 9 of 16

Different configuration files can be used for different container deployments.

Running the following example requires the nShield support software installed on the host. You can
also create the configuration file based on the template below by filling in the remote_esn,
remote_ip, remote_port, and keyhash values in the nethsm_imports section.

For example:

$ sudo mkdir -p /opt/nscop/config1

$ sudo make-nshield-hwsp-config --output
/opt/nscop/config1/config 192.168.0.10
$ cat /opt/nscop/config1/config
syntax-version=1

[nethsm_imports]
local_module=1
remote_esn=1111-2222-3333
remote_ip=192.168.0.10
remote_port=9004
keyhash=000102030405060708090a0b0c0d0e0f10111213
privileged=0

Module numbers are assigned in order.

Key hash values are retrieved from remote HSMs without any trust. The generated
configuration file should be compared against values recorded from the front panel, or some
other trusted path.

5.3 Run nshield-hwsp

To run the hardserver container, you must:

 Supply the generated hardserver configuration to the container.

 Mount a volume for the /opt/nfast/sockets folder.

 Mount a volume for the /opt/nfast/sockets-priv folder, if required.

This can be done with the -v option.

For example, using a Docker volume for the /opt/nfast/sockets folder:

$ docker volume create socket1

$ docker run \
-v /opt/nscop/config1:/opt/nfast/kmdata/config:ro \
-v socket1:/opt/nfast/sockets \
nshield-hwsp:12.70.4

Page 10 of 16 nShield Container Option Pack v1.1.1

 Hardserver INIT: Notice: Hardserver using priority class queueing
algorithm: 0 classes and 0 modules total.
[...]

This makes the hardserver of nshield-hwsp available via the sockets in the Docker volume
socket1. If the nShield support software is installed, this can be tested from the host.

First obtain the mount point for the Docker volume and use this for the NFAST_SERVER environment
variable:

$ docker volume inspect --format '{{ .Mountpoint }}' socket1

/var/lib/docker/volumes/socket1/_data
$ NFAST_SERVER=/var/lib/docker/volumes/socket1/_data/nserver
/opt/nfast/bin/enquiry -m0
Server:
enquiry reply flags none
enquiry reply level Six
serial number 1111-2222-3333
mode operational
version 12.70.4
[...]

nShield Container Option Pack v1.1.1 Page 11 of 16

6 Application Containers
An nShield application container is a container with the nShield Security World software installed.

Two strategies are supported for creating nShield application containers:

 Create an nShield base container, and derive application containers from it.

 Derive a container with nShield Security World software from an existing application container.

6.1 nShield base container

You can run make-nshield-application to create the base container. The only required argument
is the path to a mounted Security World ISO.

$ make-nshield-application SecWorld-12.70.4
[...]
Successfully tagged nshield-ubi7:12.70.4

To run the base application container:

 Supply a kmdata folder, if you want to perform operations that require a Security World.

 Mount a volume for the sockets folder.

Both can be done with the -v option.

Different application containers can use different kmdata folders. For example, you could create a new
folder:

$ mkdir –p /opt/nscop/app1/kmdata/local

You can then copy the desired Security world and module files for your application into this folder.

Using this folder and the Docker volume created for the hardserver container in section 5.3, this
container can be run directly:

$ docker run -it \

-v /opt/nscop/app1/kmdata:/opt/nfast/kmdata:ro \
-v socket1:/opt/nfast/sockets \
nshield-ubi7:12.70.4
[root@075c41761e0f /]# /opt/nfast/bin/enquiry
Server:
enquiry reply flags none
enquiry reply level Six
serial number 1111-2222-3333
[...]

Page 12 of 16 nShield Container Option Pack v1.1.1

It can also be used as the base for an application container, see examples/nfkminfo. The default
base image for nShield application containers is RedHat UBI8. The default tag reflects the version of
nShield Security World software that the container was built from.

If you want to use a different base image, or specify a different tag, use the --from and --tag
options. See make-nshield-application --help for more information.

6.1.1 API Support: CHIL, Java, and PKCS #11

Depending on the application's requirements, additional components may be installed. The possible
options are --chil, --java and --pkcs11. Any combination is allowed.

$ make-nshield-application --java SecWorld-12.70.4

[...]
Successfully tagged nshield-ubi7:12.70.4-java

The set of supported APIs is appended to the nShield software version in the container tag.

API support depends on the nShield software version:

Before v12.60 From v12.60

All combinations of APIs are supported and PKCS #11 is included by default and is not configurable
configurable with the nSCOP scripts
CHIL is not supported

6.1.2 Java applications

Java applications expect to connect to localhost:9000. This must therefore be forwarded to the
hardserver socket.

/opt/nfast/sbin/nshield-forward implements this forwarding and is included in any container

built using the make-nshield-application or extend-nshield-application scripts. This
utility depends on socat being installed in the application container. The nShield base container
includes socat but extend-nshield-application will not install it. You must install it yourself.

nShield Container Option Pack v1.1.1 Page 13 of 16

6.2 Derive a container with Security World from application
containers
You can also build the application container and then install the nShield support software into it by
running extend-nshield-application. This strategy might be preferred if the application
container already exists or if it supports several cryptographic back ends, with nShield being one of the
choices.

For an example use of extend-nshield-application, see examples/nfkmverify.

6.3 Example applications

A set of example application containers are provided in the examples directory. For more information
on building and running the examples, see the Readme in each example directory.

Example Description
nfkminfo Simple example of running an nShield application in an
application container that was created using make-
nshield-application.
javaenquiry Example Java application in which the application container
is derived from the nShield Java container using make-
nshield-application.
nfkmverify Example in which the application container is extended from
an existing container to add nShield Container using
extend-nshield-application.
nfweb Example web server that exposes basic information about
the connected nShield modules.

Page 14 of 16 nShield Container Option Pack v1.1.1

Contact Us
Web site: https://www.ncipher.com
Help Centre: https://help.ncipher.com
Email Support: [email protected]
Contact Support Numbers: https://www.ncipher.com/services/support/contact-support

nShield Container Option Pack v1.1.1 Page 15 of 16

About nCipher Security

nCipher Security, an Entrust Datacard company, is a leader in the general-purpose hardware

security module (HSM) market, empowering world-leading organizations by delivering trust, integrity
and control to their business critical information and applications. Today’s fast-moving digital
environment enhances customer satisfaction, gives competitive advantage and improves operational
efficiency – it also multiplies the security risks. Our cryptographic solutions secure emerging
technologies such as cloud, IoT, blockchain, and digital payments and help meet new compliance
mandates. We do this using our same proven technology that global organizations depend on today
to protect against threats to their sensitive data, network communications and enterprise
infrastructure. We deliver trust for your business critical applications, ensure the integrity of your data
and put you in complete control – today, tomorrow, always. www.ncipher.com

Search: nCipherSecurity

TRUST. INTEGRITY. CONTROL.