Quick Start Guide

Overview and prerequisites

The following steps provide a quick-start guide to installing Keysafe 5 and its dependencies using the provided deploy script.

The script is designed to be run on UNIX/Linux based systems by a non-root user. The script may call sudo as required.

These steps install Keysafe 5 and its dependencies. The included deploy script (deploy.sh) will provide a substitute installation for the various dependencies but they are only suitable for evaluation purposes, and should not be used for production environments.

Please see Hardening The Deployment for steps to harden the deployment. Entrust recommends these steps as a minimum and that additional hardening may be required dependent on your own requirements.

A production deployment will have as a minimum the following:

  • Maintained and patched versions of all the dependencies

  • A secure CA with TLS v1.3 support for certificates. The deploy script can provide a local insecure CA.

  • A secure Kubernetes installation. The deploy script can install K3s locally.

  • A secure MongoDB database. The deploy script can provide a replicated MongoDB with X.509 authentication running in Kubernetes.

  • A secure RabbitMQ message broker. The deploy script can provide a RabbitMQ with X.509 authentication running in Kubernetes.

  • HTTPS secured by a trusted certificate for the Keysafe 5 endpoints. The deploy script will enable HTTPS connections with a self-signed insecure certificate.

  • Require authentication to access Keysafe 5. OIDC & OAUTH2 are currently supported in Keysafe 5. The deploy script will not set up authenticated access.

This release includes Docker images that need to be pushed to a Docker registry. If you have a private registry you may push the images from a different machine.

Hardware Requirements

Entrust recommends the following hardware specification to ensure smooth running of Keysafe 5.

  • CPU: 2 minimum (4 recommended)

  • RAM: 8GB minimum

  • Disk Storage: 64GB minimum

    • For optimal performance Entrust recommends use of an SSD.

Requirements will vary depending on the size of the nShield estate being managed and if services, such as MongoDB and RabbitMQ, are being hosted on the same machine as the Kubernetes cluster or externally.

Unpack the release

$ mkdir keysafe5-install
$ tar -xf nshield-keysafe5-1.1.1.tar.gz -C keysafe5-install
$ cd keysafe5-install

Existing infrastructure

This section describes the interaction with infrastructure that you may like to use when installing Keysafe 5 via the deployment script. Otherwise skip to Authentication.

Docker images

If you have a private registry you may push the images to it like so:

# Load the Docker images to your local Docker
$ docker load < docker-images/hsm-mgmt.tar
$ docker load < docker-images/sw-mgmt.tar
$ docker load < docker-images/ui.tar

# We need to use a private registry in many places
$ export DOCKER_REGISTRY=private.registry.local

# Tag the Docker images for a private registry
$ docker tag hsm-mgmt:1.1.1 $DOCKER_REGISTRY/keysafe5/hsm-mgmt:1.1.1
$ docker tag sw-mgmt:1.1.1 $DOCKER_REGISTRY/keysafe5/sw-mgmt:1.1.1
$ docker tag mgmt-ui:1.1.1 $DOCKER_REGISTRY/keysafe5/mgmt-ui:1.1.1

# Log in to ensure pushes succeed
$ docker login $DOCKER_REGISTRY

# And push
$ docker push $DOCKER_REGISTRY/keysafe5/hsm-mgmt:1.1.1
$ docker push $DOCKER_REGISTRY/keysafe5/sw-mgmt:1.1.1
$ docker push $DOCKER_REGISTRY/keysafe5/mgmt-ui:1.1.1

By setting the DOCKER_REGISTRY environment variable the deploy script will pull images from that registry. Otherwise the deploy script will set up a local insecure Docker registry. In this case, ensure that Docker is installed.

Kubernetes

If you have a Kubernetes cluster available, ensure that kubectl points to it, and that kubectl get pods -A returns a list of pods. Otherwise the deploy script will install K3s locally to /usr/local/bin and create a ~/.kube/config to point to it. If you want to use the K3s installed by the script, the environment variable KUBECONFIG will need to be set to ~/.kube/config. For this setting to persist it needs to be added to your shell’s configuration file.

Istio

If you have Istio installed, ensure that istioctl is on your path. Otherwise the deploy script will download a local copy of istioctl, and install Istio as required.

RabbitMQ

Entrust recommends that you use your standard secure RabbitMQ installation, along with your policies for authentication and virtual hosts on your production system; this is only a demo system.

If you have an existing RabbitMQ environment:

  • Set the environment variable RABBIT_URL to point to the RabbitMQ server, port, and vhost like: rabbitmq.example.com:5671/keysafe5.

  • You will also need to create a Kubernetes generic secret in the nshieldkeysafe5 namespace with ca.crt, tls.crt, and tls.key for a user that has full access to the vhost. Set RABBIT_SECRETS to the name of this generic secret.

  • If you set the environment variable AGENT_USER to a value, and create another set of credentials ca.crt, $AGENT_USER.crt and $AGENT_USER.key then the deploy script will create an agent-config.tar.gz with a configuration for deploying an agent.

If you do not have an existing RabbitMQ server, the deploy script will set one up on the Kubernetes cluster along with the secrets for both the server and agents. By default, neither RabbitMQ’s management interface nor peer discovery interface for Kubernetes will be enabled. Should either of these be required, set the environment variable RABBITMQ_PLUGINS. To enable both, set it to "rabbitmq_management rabbitmq_peer_discovery_k8s". To enable only one, set it to the appropriate value. For example, to enable just the management interface, set it to "rabbitmq_management".

MongoDB

Entrust recommends that you use your standard secure MongoDB Replica Set installation.

If you have an existing MongoDB deployment:

  • Set the environment variable MONGODB to a backslash-comma separated list of servers, along with their port numbers in the form: mongo-1.example.com:27017\,mongo-2.example.com:27017 The backslash should be visible when running echo $MONGODB. A quick tip: using single-quotes ' will prevent the bash command line acting on the backslash you have typed.

  • You will also need to create a Kubernetes generic secret in the nshieldkeysafe5 namespace with ca.crt, tls.crt, and tls.key for a user that has readWrite roles on the databases: hsm-mgmt-db and sw-mgmt-db. Set MONGO_SECRETS to the name of this generic secret.

If you do not have an existing MongoDB deployment, the deploy script will set one up on the Kubernetes cluster along with the secrets for both the server and backend services.

Authentication

To disable OIDC authentication, set the environment variable DISABLE_AUTHENTICATION to yes, and you may move on to Install Keysafe 5.

To configure authentication for Istio, the environment variable AUTH_ISSUER_URL needs to point at the issuer URL. Additionally, either AUTH_JWKS (for the payload) or AUTH_JWKS_URL (for the URL) also needs to be set. AUTH_AUDIENCES should be a comma-delimited list. The deploy script will automatically add the fully qualified domain name for the host to this list if not already present.

For UI authentication the deploy script requires an OIDCProviders.json file. Its location should be set in the environment variable OIDC_PROVIDERS_FILE_LOCATION.

Further details on configuring authentication for Keysafe 5 can be found in Helm Chart Installation.

Install Keysafe 5

It is now possible to run the deploy script.

Do not run the deploy script under sudo. If sudo permissions are required it will be called by the script and you will be prompted for your credentials.

The deploy script must be run from inside the directory to which it is extracted. Running with the -n flag will perform a set of pre-flight checks and show what will happen then exit without taking any action.

$ ./deploy.sh -n

To disable authentication set the environment variable DISABLE_AUTHENTICATION to yes. Otherwise you may follow the instructions in the Authentication section.

You may now perform the deployment with the -y flag.

$ ./deploy.sh -y

The script will take a few minutes to run, showing what actions are taking place. You may be prompted for your password by sudo, for example when installing K3s.

Configure nShield client machines

To configure a host machine to be managed and monitored by this deployment, install the Keysafe 5 agent on the nShield client machine containing the relevant Security World or HSMs.

Ensure no firewall rules are blocking the AMQP port communication between the machine exposing the AMQP port from Kubernetes and the machine running the agent.

The deploy script will output a tar archive called agent-config.tar.gz that contains the agent configuration file and TLS certificates for authentication to RabbitMQ.

Install on Linux

On a machine with a supported Security World installation installed:

$ sudo tar -xf keysafe5-install/keysafe5-agent/keysafe5-1.1.1-Linux-keysafe5-agent.tar.gz -C /
$ sudo tar -xf agent-config.tar.gz -C /opt/nfast/keysafe5/

If the hardserver is already running, use the Keysafe 5 install script to not restart it:

$ sudo /opt/nfast/keysafe5/sbin/install

Otherwise use the nShield install script which will start all the services:

$ sudo /opt/nfast/sbin/install

Install on Windows

  1. Run the Keysafe5-agent.msi installer if the Keysafe 5 agent is not already installed.

    This creates the nShield Keysafe 5 agent service but does not start it.

  2. Populate the Keysafe 5 agent configuration using the files from the generated agent-config.tar.gz

    The generated config.yaml sets the log file location for the agent (log.file.path) to a Unix filepath. You will need to manually update the path to a file in %NFAST_LOGDIR%, e.g. C:\ProgramData\nCipher\Log Files\KeySafe5-agent.log.

  3. Start the nShield Keysafe 5 agent service using Windows Service Manager.

Access Keysafe 5

You can now access Keysafe 5 through the URL provided by the deploy script. For example, you could send curl requests:

$ curl -s --cacert ca.crt https://$(hostname -f)/mgmt/v1/hsms | jq
$ curl -s --cacert ca.crt https://$(hostname -f)/mgmt/v1/pools | jq

You can access the Management UI in a web browser at https://$(hostname -f).

Uninstall

If Kubernetes was not provided and K3s was installed by the deploy script, you may simply uninstall K3s which will clear up all the installed helm charts.

/usr/local/bin/k3s-uninstall.sh

This will request sudo permissions.

If a private Docker Registry was not provided, the deploy script will have created a local one and it will be removed when the script finishes. Should this fail, you may uninstall it manually by running:

docker stop registry
docker rm registry

If a Kubernetes installation was provided then the helm charts will need to be uninstalled individually.

helm --namespace nshieldkeysafe5 uninstall keysafe5-istio
helm --namespace nshieldkeysafe5 uninstall keysafe5-backend
helm --namespace nshieldkeysafe5 uninstall keysafe5-ui

If an existing RabbitMQ installation was not provided, then the deploy script will have installed a RabbitMQ helm chart that should be uninstalled. The same is also true for MongoDB.

helm --namespace rabbitns uninstall rabbit-chart
helm --namespace mongons uninstall mongo-chart

If Istio was installed by the deploy script, it may be uninstalled by running:

keysafe5-install/istioctl uninstall --purge

To uninstall the Keysafe 5 agent, run the Keysafe 5 uninstaller:

$ sudo /opt/nfast/keysafe5/sbin/install -u