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.31	1.33
MongoDB	7.0.14	8.0.13

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, are being hosted on the same machine as the Kubernetes cluster or externally.

Kubernetes cluster

KeySafe 5 has been tested on Kubernetes version 1.33.

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.

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.