Prerequisites

The following table contains the required software version that this release of KeySafe 5 has been tested on and any minimum version requirements.

Software	Minimum version	Tested version
Kubernetes	1.27	1.29.2
MongoDB	6.0.14	7.0.7
A message bus server, either:
RabbitMQ	3.0	3.12.13
NATS	2.10	2.10.14

In addition to the set of required software, this release of KeySafe 5 requires:

A location for storing large objects (for example CodeSafe machines)
An external identity provider that supports OIDC and OAuth2 for user and machine authentication.

Optional Software

KeySafe 5 is shipped with a Helm chart that configures an Istio Ingress Gateway to provide external access to the KeySafe 5 application running in Kubernetes. Other Ingress Gateways can be used, see Configure a custom ingress provider.

Software	Minimum version	Tested version
Istio	1.20	1.21

Software

Minimum version

Tested version

Istio

1.20

1.21

Hardware Requirements

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

CPU: 4 minimum (8 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.

Kubernetes cluster

KeySafe 5 has been tested on Kubernetes version 1.29.

Using namespaces

When deploying an application to a Kubernetes cluster that is shared with many users spread across multiple teams, Entrust recommends using Namespaces to isolate groups of resources.

To create a namespace for the KeySafe 5 application:

kubectl create namespace nshieldkeysafe5
namespace/nshieldkeysafe5 created

To set the namespace for a current request, use the --namespace flag. For example:

helm install --namespace=nshieldkeysafe5 my-release helm-keysafe5-backend/
kubectl --namespace=nshieldkeysafe5 get pods

If you are using Istio in your Kubernetes cluster, beyond acting as an API Gateway for KeySafe 5, you might also want to configure Istio injection for this Kubernetes namespace to take advantage of other Istio features. This step is not required for KeySafe 5 to function.

kubectl label namespace nshieldkeysafe5 istio-injection=enabled
namespace/nshieldkeysafe5 labeled

MongoDB

MongoDB is the persistent data store for the KeySafe 5 application data. Any sensitive Security World data stored in the database is stored in standard nShield encrypted blobs. You should restrict access to this database in the same way that you would normally restrict access to the Key Management Data directory on an nShield client machine.

The MongoDB used must be a Replica Set.

If you have an existing MongoDB database you can configure the application to use this, otherwise you must securely deploy a MongoDB instance.

Entrust recommend that you configure MongoDB with authentication enabled and TLS enabled and with RBAC configured. The database user for KeySafe 5 should be given the minimum capabilities required, see Database: User Roles.

Bitnami MongoDB Helm chart

To install MongoDB in the same Kubernetes cluster as the KeySafe 5 application, you can install the Bitnami MongoDB Helm chart.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install mongo-chart \
 --set image.tag=7.0.7-debian-12-r0 \
 --set architecture=replicaset \
 --set auth.enabled=true \
 --set tls.enabled=true \
 --set tls.existingSecret=my-mongo-tls-secret \
bitnami/mongodb --version 15.0.2

KeySafe 5 has been tested with version 15.0.2 of the Bitnami MongoDB Helm Chart.

MongoDB 5.0 and newer requires use of the AVX instruction set on processors. For more information, see MongoDB Production Notes

Monitor MongoDB for security vulnerabilities and regularly update the version of MongoDB installed to apply any required updates.

Message Bus

A message bus server is required for the interprocess communication between the KeySafe 5 backend services and KeySafe 5 agent instances running on nShield client machines.

KeySafe 5 supports the follow message bus servers:

RabbitMQ

If you have an existing RabbitMQ instance you can configure the application to use this, otherwise you must securely deploy a RabbitMQ instance.

The RabbitMQ instance should have a sufficient maximum channel count to support the number of resources managed by KeySafe 5. Use the following table to estimate the number of channels required for each resource:

Resource	Required channels
Replica count in KeySafe 5 backend Helm Chart (default value 3)	8
KeySafe 5 Agent	6
Managed HSM	2

Entrust recommend that you configure RabbitMQ with authentication enabled and TLS enabled. If the RabbitMQ instance being used is shared with other applications, then a dedicated virtual host should be created for the KeySafe 5 application. RabbitMQ users created for KeySafe 5 should only have access to that specific virtual host.

Bitnami RabbitMQ Helm chart

To install RabbitMQ in the same Kubernetes cluster as the KeySafe 5 application, you can install the Bitnami RabbitMQ Helm chart.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install rabbit-chart \
 --set image.tag=3.12.13-debian-12-r1 \
 --set auth.username=user \
 --set auth.existingPasswordSecret=my-password-secret \
 --set auth.tls.enabled=true \
 --set auth.tls.existingSecret=my-rabbitmq-tls-secret \
 --set extraConfiguration='
   channel_max = 4095
   listeners.ssl.default = 5671
   ssl_options.versions.1 = tlsv1.3
   ssl_options.depth=0
   ssl_options.verify = verify_peer
   ssl_options.fail_if_no_peer_cert = true
   auth_mechanisms.1 = EXTERNAL
   ssl_cert_login_from = subject_alternative_name
   ssl_cert_login_san_type = dns
   ssl_cert_login_san_index = 0' \
 --set plugins="" \
 --set extraPlugins="rabbitmq_auth_mechanism_ssl" \
bitnami/rabbitmq --version 12.13.1

KeySafe 5 has been tested with version 12.13.1 of the Bitnami RabbitMQ Helm Chart.

Monitor RabbitMQ for security vulnerabilities and regularly update the version of RabbitMQ installed to apply any required updates.

RabbitMQ TLS authentication

If using TLS authentication between the KeySafe 5 agent and RabbitMQ, the RabbitMQ server will extract the username for incoming connections from the client’s TLS certificate. For use with KeySafe 5, RabbitMQ must be configured to extract the username from the TLS certificate using one of the following options:

The first DNS field in the SAN (ssl_cert_login_from=subject_alternative_name, san_type=dns and san_index=0)
Common Name (ssl_cert_login_from=common_name)
Distinguished Name (ssl_cert_login_from=distinguished_name)

NATS

If you have an existing NATS server you can configure the application to use this, otherwise you must securely deploy a NATS instance.

Entrust recommend that you configure NATS with authentication enabled and TLS enabled.

Bitnami NATS Helm chart

To install NATS in the same Kubernetes cluster as the KeySafe 5 application, you can install the Bitnami NATS Helm chart.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install nats-chart \
  --set image.repository=bitnami/nats \
  --set image.tag=2.10.4-debian-11-r0 \
  --set service.type=LoadBalancer \
bitnami/nats --version 7.10.0

KeySafe 5 has been tested with version 7.10.0 of the Bitnami NATS Helm Chart.

Monitor NATS for security vulnerabilities and regularly update the version of NATS installed to apply any required updates.

Large Object Storage

A location for storing objects that are too large for a traditional database, such as CodeSafe machines, is required. This storage can be located either within the Kubernetes cluster, or externally.

To configure this storage you must specify a Persistent Volume Claim (PVC) for the helm-keysafe5-backend Helm Chart to use via the objectStore.pvc Chart parameter. If a Kubernetes namespace has been created for the KeySafe 5 application, then the PVC must be in the same namespace as the application. The PVC may use any type of storage supported by Persistent Volumes in your Kubernetes Cluster (for example, NFS). See Persistent Volumes for supported storage types.

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.

You should ensure that the size of the configured storage is sufficient to meet the application’s needs. For this release of KeySafe 5 that should include:

All CodeSafe 5 machine images that will be managed by KeySafe 5.

NFS Object Storage Configuration

To use an NFS for object storage you must know the NFS server address and the path of the directory being exported from the NFS server.

Create a Persistent Volume containing the configuration of your NFS.

cat << EOF | kubectl -n nshieldkeysafe5 apply -f -
  apiVersion: v1
  kind: PersistentVolume
  metadata:
    name: nfs-pv
    labels:
      application: keysafe5
  spec:
    capacity:
      storage: 2Gi
    volumeMode: Filesystem
    accessModes:
      - ReadWriteMany
    persistentVolumeReclaimPolicy: Recycle
    storageClassName: nfs
    nfs:
      path: ${NFS_PATH}
      server: ${NFS_IP}
EOF

Create a Persistent Volume Claim to use that Persistent Volume.

cat << EOF | kubectl -n nshieldkeysafe5 apply -f -
  apiVersion: v1
  kind: PersistentVolumeClaim
  metadata:
    name: data-nshield-keysafe5
  spec:
    storageClassName: nfs
    accessModes:
      - ReadWriteMany
    resources:
      requests:
        storage: 2Gi
    selector:
      matchLabels:
        application: keysafe5
EOF

External identity provider (IdP)

You need an external identity provider that supports OIDC and OAuth2 to provide user and machine authentication to KeySafe 5. This is required to gain access to the UI and authenticate commands sent to the backend services.

At the IdP, Entrust typically expects the following to be configured:

A single OIDC public client application

This provides user identity information and an id_token for use by the UI.
Multiple OAuth2 private client application

This provides machine-to-machine credentials. Typically you would want an instance of this per application identity required to limit the sharing of the client_secret value.

For more information, refer to Client Types.

OIDC public client

The OIDC public client application provides user identity information and an id_token for use by the UI in its calls to the backend services. It is a public client due to the UI being a client side application, and as such cannot be trusted with the client_secret like a server side application would be.

Entrust recommends the following settings:

Setting	Value
Grant Types	Authorization Code with PKCE
Refresh Token
Authorization Code PKCE Code Challenge Method	S256
Scopes	openid

Setting

Value

Grant Types

Authorization Code with PKCE

Refresh Token

Authorization Code PKCE Code Challenge Method

S256

Scopes

openid

For more information, refer to Authorization Code flow with PKCE.

OAuth2 private client

The OAUTH2 private client provides client credentialing for machine-to-machine authentication by applications that do not hold user identification. This requires the use of the client_secret value, which must be securely held.

You would typically want a separate private client instance for each application for which you provide access, resulting in a separate client_id and client_secret for each application. This eases management of the client_secret by reducing the number of applications that have knowledge of it. It also provides easy identification of which application is doing what at the KeySafe 5 end.

Entrust recommend the following settings:

Setting	Value
Grant Type	Client Credentials

Setting

Value

Grant Type

Client Credentials

For more information, refer to Client Credentials.