Keysafe 5 v1.4 Quick Start Guide
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 ( 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:
|
The script requires a local installation of Docker or Podman.
When using podman
on Red Hat Enterprise Linux, you should install the podman-docker
package to provide the Docker alias.
The user executing the deploy script must be able to successfully execute docker info
.
If this is not the case, please consult the appropriate documentation for your platform, Docker Documentation or Podman Documentation.
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.
Unpack the release
mkdir keysafe5-install
tar -xf nshield-keysafe5-1.4.0.tar.gz -C keysafe5-install
cd keysafe5-install
The user executing the deploy.sh
script must have permission to read and write files within the keysafe5-install
directory.
This will automatically be the case if the user extracting the release package is the same user that executes the deploy script.
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/codesafe-mgmt.tar
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/my_space/keysafe5
# Tag the Docker images for a private registry
docker tag codesafe-mgmt:1.4.0 $DOCKER_REGISTRY/codesafe-mgmt:1.4.0
docker tag hsm-mgmt:1.4.0 $DOCKER_REGISTRY/hsm-mgmt:1.4.0
docker tag sw-mgmt:1.4.0 $DOCKER_REGISTRY/sw-mgmt:1.4.0
docker tag mgmt-ui:1.4.0 $DOCKER_REGISTRY/mgmt-ui:1.4.0
# Log in to ensure pushes succeed
docker login private.registry.local
# And push
docker push $DOCKER_REGISTRY/codesafe-mgmt:1.4.0
docker push $DOCKER_REGISTRY/hsm-mgmt:1.4.0
docker push $DOCKER_REGISTRY/sw-mgmt:1.4.0
docker push $DOCKER_REGISTRY/mgmt-ui:1.4.0
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 ${HOME}/.kube/config
to point to it.
Kubernetes tools use the KUBECONFIG
environment variable for the location of its configuration file, but when unset this defaults to ${HOME}/.kube/config
.
For this setting to persist it needs to be added to your shell’s configuration file.
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 withca.crt
,tls.crt
, andtls.key
for a user that has full access to the vhost. SetRABBIT_SECRETS
to the name of this generic secret.
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 runningecho $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 withca.crt
,tls.crt
, andtls.key
for a user that has readWrite roles on the databases:codesafe-mgmt-db
,hsm-mgmt-db
andsw-mgmt-db
. SetMONGO_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.
MongoDB 5.0 and newer requires use of the AVX instruction set for processors. For more information, see MongoDB Production Notes |
Object Storage
If you do not have an existing Kubernetes cluster, or if your cluster contains only 1 worker node, the deploy script will use local storage on the single worker node.
If you would like to use an NFS for large object storage, set the environment variable NFS_IP
to the NFS server address, and NFS_PATH
to the path of the directory being exported from the NFS server.
To set the user and group IDs used by the KeySafe 5 application when accessing the object storage, configure the podSecurityContext.runAsUser
, podSecurityContext.runAsGroup
and podSecurityContext.fsGroup
Chart parameters.
To do this, specify the environment variable KEYSAFE_BACKEND_CHART_EXTRA_ARGS
.
For example, KEYSAFE_BACKEND_CHART_EXTRA_ARGS="--set podSecurityContext.runAsUser=2000 --set podSecurityContext.runAsGroup=3000"
.
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 the Helm Chart Installation section of the KeySafe 5 Installation Guide.
Install KeySafe 5
It is now possible to run the deploy script.
Do not run the deploy script under |
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.
The script will create a local insecure Certificate Authority to be used by the agentcert.sh
and updateinternalcerts.sh
scripts.
This directory should be preserved to allow this.
The script will also produce two archives, agent-config.tar.gz
(for Unix) and agent-config.zip
(for Windows), that contains the agent configuration file and CA certificates for TLS authentication to RabbitMQ.
The contents are used for configuring nShield client machines below.
K3s
If the deploy.sh
script has installed K3s, you should configure kubectl
access for the current user account by running:
mkdir -p $\{HOME}/.kube
sudo /usr/local/bin/k3s kubectl config view --raw > $\{HOME}/.kube/config
chmod 600 $\{HOME}/.kube/config
export KUBECONFIG=$\{HOME}/.kube/config
This step is necessary for any user account on this machine that will be required to administrate the KeySafe 5 central platform.
You may append the export KUBECONFIG=${HOME}/.kube/config
to your shell’s configuration file.
Configure nShield client machines
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. |
In summary, to configure your nShield client 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.
-
Extract the
agent-config.tar.gz
oragent-config.zip
archive on the nShield client machine alongside the KeySafe 5 agent. -
Generate a unique private key and client CSR using the provided
ampqtls
for each individual KeySafe 5 agent. -
Copy the client CSR to the central platform and sign it with the CA.
-
Copy the certificate to the nShield client machine, and place it alongside the KeySafe 5 agent configuration.
The steps to install and configure vary depending on the client.
The deploy script will output a tar archive called agent-config.tar.gz
, and a zip archive called agent-config.zip
that contains the agent configuration file and CA certificate for TLS authentication to RabbitMQ.
A tool is provided for generating a unique private key and client CSR for each individual KeySafe 5 agent.
Please see below.
Install on Linux
-
On a machine with a supported Security World installation installed, run:
sudo tar -xf keysafe5-install/keysafe5-agent/keysafe5-1.4.0-Linux-keysafe5-agent.tar.gz -C /opt/nfast/keysafe5/ sudo tar -xf agent-config.tar.gz -C /opt/nfast/keysafe5/
-
Generate a TLS private key and CSR for this KeySafe 5 agent.
/opt/nfast/keysafe5/bin/ks5agenttls -keypath=/opt/nfast/keysafe5/conf/messagebus/tls/tls.key -keygen /opt/nfast/keysafe5/bin/ks5agenttls -keypath=/opt/nfast/keysafe5/conf/messagebus/tls/tls.key -csrgen
-
Transfer the resulting CSR to the central platform.
-
Follow the instructions in Signing the Agent CSR to sign the CSR, then transfer the resulting certificate and the
cacert.pem
to this computer. -
Place the files (renaming the certificate to
tls.crt
andcacert.pem
toca.crt
) into the tls directory alongside the original key.sudo cp ks5agent_demohost.crt /opt/nfast/keysafe5/conf/messagebus/tls/tls.crt sudo cp cacert.pem /opt/nfast/keysafe5/conf/messagebus/tls/ca.crt
-
If the hardserver is already running, use the KeySafe 5 install script to start the KeySafe 5 Agent without restarting the hardserver:
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
-
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.
-
Populate the KeySafe 5 agent configuration using the files from the generated
agent-config.zip
-
Generate a TLS private key and CSR for this KeySafe 5 agent.
%NFAST_HOME%\bin\amqptls.exe -keypath=%NFAST_DATA_HOME%\keysafe5\conf\amqp\tls\tls.key -keygen %NFAST_HOME%\bin\amqptls.exe -keypath=%NFAST_DATA_HOME%\keysafe5\conf\amqp\tls\tls.key -csrgen
-
Transfer the resulting CSR to the central platform.
-
Follow the instructions in Signing the Agent CSR to sign the CSR, then transfer the resulting certificate and the
cacert.pem
to this computer. -
Place the files (renaming the certificate to
tls.crt
andcacert.pem
toca.crt
) into the tls directory alongside the original key.%NFAST_DATA_HOME%\keysafe5\conf\amqp\tls\tls.crt %NFAST_DATA_HOME%\keysafe5\conf\amqp\tls\ca.crt
-
Start the nShield KeySafe 5 agent service using the Windows Service Manager.
Signing the Agent CSR
-
Use the
agentcert.sh
script to create a client TLS certificate for this KeySafe 5 agent using the CSR from the Agent, and the CA created by the deploy script. -
Using the username printed in the output of the previous command, configure the RabbitMQ server to allow access for this X.509 user in the appropriate virtual host.
export x509user=ks5agent_demohost export RUN_RABBIT="kubectl -n rabbitns exec rabbit-chart-rabbitmq-0 -c rabbitmq -- " ${RUN_RABBIT} rabbitmqctl add_user $x509user "ephemeralpw" ${RUN_RABBIT} rabbitmqctl set_permissions -p $RABBIT_VHOST $x509user ".*" ".*" ".*" ${RUN_RABBIT} rabbitmqctl clear_password $x509user
-
Copy the client TLS certificate output from the
agentcert.sh
command to the nShield host machine with the KeySafe 5 agent. -
Also copy over the CA certificate
internalCA/cacert.pem
Configure an nShield Connect
A KeySafe 5 agent is installed on the nShield Connect for nShield Connect images released with Security World v13.4 and later software. This agent allows an nShield Connect to be monitored and managed without, or in addition to, the Connect being enrolled to a nShield host machine (a machine with nShield Security World software installed) which also has a KeySafe 5 agent installed.
Output of certificate/CSR data is truncated in these examples. |
To configure an nShield Connect to be managed and monitored by your KeySafe 5 central platform:
-
On the nShield Connect Serial Console, generate a certificate signing request (CSR) for the KeySafe 5 agent using the
ks5agent amqpcsr
command.(cli)ks5agent amqpcsr -----BEGIN CERTIFICATE REQUEST----- MII... -----END CERTIFICATE REQUEST-----
-
On the machine where the KeySafe 5 central platform was installed, copy and paste the generated CSR to a new file in the directory where the
deploy.sh
script was executed. -
Generate a TLS certificate for this agent using
agentcert.sh
script, specifying how many days the generated certificate should be valid for.$ ./agentcert.sh connect_AAAA_AAAA_AAAA.csr 365 Certificate generated to connect_AAAA_AAAA_AAAA.crt. Valid for 365 days CA Certificate available at /path/to/keysafe5-install/internalCA/cacert.pem RabbitMQ will need to be configured to allow access for the user 'ks5agent_nshield_module_AAAA_AAAA_AAAA': export RUN_RABBIT="kubectl -n rabbitns exec rabbit-chart-rabbitmq-0 -c rabbitmq -- " ${RUN_RABBIT} rabbitmqctl add_user ks5agent_nshield_module_AAAA_AAAA_AAAA ephemeralpw ${RUN_RABBIT} rabbitmqctl set_permissions -p nshieldvhost ks5agent_nshield_module_AAAA_AAAA_AAAA '.*' '.*' '.*' ${RUN_RABBIT} rabbitmqctl clear_password ks5agent_nshield_module_AAAA_AAAA_AAAA
-
On the machine where the KeySafe 5 central platform was installed, configure the deployed RabbitMQ server to allow access for this agent.
The output of the agentcert.sh
script contains the exact commands to run for the specific agent username. The username has the formatks5agent_nshield_module_<connect_esn>
. In the provided examples, the ESN of the Connect is AAAA-AAAA-AAAA.export RUN_RABBIT="kubectl -n rabbitns exec rabbit-chart-rabbitmq-0 -c rabbitmq -- " ${RUN_RABBIT} rabbitmqctl add_user ks5agent_nshield_module_AAAA_AAAA_AAAA ephemeralpw ${RUN_RABBIT} rabbitmqctl set_permissions -p nshieldvhost ks5agent_nshield_module_AAAA_AAAA_AAAA '.*' '.*' '.*' ${RUN_RABBIT} rabbitmqctl clear_password ks5agent_nshield_module_AAAA_AAAA_AAAA
-
Install the agent TLS certificate on the Connect.
-
On the machine where the TLS certificate was generated,
base64
encode the certificate.$ base64 --wrap=0 connect_AAAA_AAAA_AAAA.crt Q2VydGlmaW...
-
On the nShield Connect Serial Console, load the TLS certificate for the agent using the
ks5agent amqptls
command.(cli) ks5agent amqptls tls.crt <base64_encoded_crt> Saved tls.crt
-
-
Install the CA certificate on the Connect.
-
On the machine where the TLS certificate was generated,
base64
encode the certificate of the Certificate Authority. After running thedeploy.sh
script this certificate can be found atinternalCA/cacert.pem
.$ base64 --wrap=0 internalCA/cacert.pem LS0t...
-
On the nShield Connect Serial Console, load the CA certificate using the
ks5agent amqptls
command.(cli) ks5agent amqptls ca.crt <base64_encoded_crt> Saved ca.crt
-
-
On the nShield Connect Serial Console, configure the agent AMQP URL to point to the deployed RabbitMQ server. The correct URL can be found in the generated
agent-config.tar.gz
on the machine where the KeySafe 5 central platform was installed.The deploy.sh
script creates a dedicated virtual host callednshieldvhost
in the deployed RabbitMQ server, for KeySafe 5 to use.(cli) ks5agent cfg amqp.url=<central_platform_ip>:5671/nshieldvhost
-
On the nShield Connect Serial Console, enable the agent using the
ks5agent enable
command.(cli) ks5agent enable
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 internalCA/cacert.pem https://$(hostname -f)/mgmt/v1/hsms | jq
curl -s --cacert internalCA/cacert.pem 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