Integrate Entrust KeySafe 5 with the KeyControl Compliance Manager server

Prerequisites

KeyControl Compliance Manager server has been deployed and configured (Install and configure KCM and KeySafe 5).
KeySafe 5 has been deployed and configured (Install and configure KCM and KeySafe 5).
A KeySafe 5 client has been deployed and configured with the HSM (Install and configure KCM and KeySafe 5).

Create the KCM tenant

To be able to use the KeyControl Compliance Manager you must create a tenant that can be used for the integration.

Point your browser to the KeyControl Compliance Manager (KCM) URL: https://<kcm-server-ip>/kcm.

Sign in using the secroot credentials setup during the KCM installation.
Select the Create Tenant button.
fill out the Create Tenant form:
Select Create Tenant.
When the tenant creation completes, a message is displayed:

A temporary password is emailed to the administrator’s email address. This is the password for signing in for the first time to the tenant space in KCM. In a closed-gap environment where email is not available, the password for the user is displayed when you first create the vault, then it can be copied and sent to the user.
Select Close.

The new tenant is displayed in the Vault dashboard.
To view the details on the tenant, select View Details when you mouse over the tenant.

Select the URL to access the tenant’s page.

https://<kcm-server-ip>/login/kcm/75f226ec-4730-42eb-85b3-157fc8b3467a/

Sign in with the password that was copied when you created the tenant or the password that was emailed to you.
The system makes you change the temporary password and to sign back in.

The KeyControl Compliance Manager Dashboard is displayed:

Create the KeySafe 5 app link token key

To connect KeySafe 5 and KCM, you need an app link token key, which you have to create on the KeySafe 5 client server.

Generate the key.

In this example, we create the key in the HSM, using module protection:

% sudo /opt/nfast/bin/generatekey simple module=1 protect=module type=AES size=256 ident=cmapplinktokenprot plainname=applinktokenprot nvram=no

Output:

key generation parameters:
 operation    Operation to perform       generate
 application  Application                simple
 protect      Protected by               module
 verify       Verify security of key     yes
 type         Key type                   AES
 size         Key size                   256
 ident        Key identifier             cmapplinktokenprot
 plainname    Key name                   applinktokenprot
 nvram        Blob in NVRAM (needs ACS)  no

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_simple_cmapplinktokenprot

If you are using a FIPS Level 3 security world, you will need to provide an OCS card for FIPS authorization during the key creation.

Capture the KCM TLS Certificate chain and load in the KeySafe 5 server

To connect KeySafe 5 and KCM, you have to capture the KCM TLS certificate chain and load in the KeySafe 5 server.

On the KeySafe 5 server, create a secret with the KCM TLS certificate chain.

Change to the install keysafe5-install folder:
```
% cd keysafe5-install
```

Capture the KCM TLS certificate chain (Issuer + Root) certificates, for example using OpenSSL, and store it in compliance-ca.pem:

% openssl s_client -connect <kcm-server-ip>:443 -showcerts

Output:

CONNECTED(00000003)
Can't use SSL_get_servername
depth=1 C = US, O = Hytrust Inc., CN = KeyControl Compliance Manager Certificate Authority
verify error:num=19:self-signed certificate in certificate chain
verify return:1
depth=1 C = US, O = Hytrust Inc., CN = KeyControl Compliance Manager Certificate Authority
verify return:1
depth=0 C = US, O = HyTrust Inc., CN = kcm-1031.interop.local
verify return:1
---
Certificate chain
 0 s:C = US, O = HyTrust Inc., CN = kcm-1031.interop.local
   i:C = US, O = Hytrust Inc., CN = KeyControl Compliance Manager Certificate Authority
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Jun  1 00:00:00 2011 GMT; NotAfter: Dec 31 23:59:59 2049 GMT
-----BEGIN CERTIFICATE-----
MII
...
gFFAjK0g=
-----END CERTIFICATE-----
 1 s:C = US, O = Hytrust Inc., CN = KeyControl Compliance Manager Certificate Authority
   i:C = US, O = Hytrust Inc., CN = KeyControl Compliance Manager Certificate Authority
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Jun  1 00:00:00 2011 GMT; NotAfter: Dec 31 23:59:59 2049 GMT
-----BEGIN CERTIFICATE-----
MIIEG
...
8jYM6yT+w=
-----END CERTIFICATE-----
---
Server certificate
subject=C = US, O = HyTrust Inc., CN = kcm-1031.interop.local
issuer=C = US, O = Hytrust Inc., CN = KeyControl Compliance Manager Certificate Authority
---
No client certificate CA names sent
Peer signing digest: SHA512
Peer signature type: RSA
Server Temp Key: ECDH, prime256v1, 256 bits
---
SSL handshake has read 2718 bytes and written 421 bytes
Verification error: self-signed certificate in certificate chain
---
New, TLSv1.2, Cipher is ECDHE-RSA-AES256-GCM-SHA384
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES256-GCM-SHA384
    Session-ID: 165B25EF141F15205AABFA039C4E7CEEB81EFFDDF63C5EA6058E2BC479F5CB18
    Session-ID-ctx:
    Master-Key: E9D4E199127778CC3118AF5681CB3E33131E15219A045B9BD48BCDC88EC59F4E9C1FB03D49CA64039F093E14A1506050
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    TLS session ticket lifetime hint: 300 (seconds)
    TLS session ticket:
    0000 - 34 91 0d 87 a6 91 b5 a7-da ba e1 b0 4d f4 1c 10   4...........M...
    0010 - ef 7a 1b cf 80 42 ff 5f-0c 8a 68 24 38 7c ec 76   .z...B._..h$8|.v
    0020 - d2 66 c6 a0 63 e7 2d 28-91 c9 b3 07 c8 c6 2c 81   .f..c.-(......,.
    0030 - 20 18 15 cc 81 8e fb f9-25 62 b8 7d 7e 54 7d 53    .......%b.}~T}S
    0040 - 0a 6f 22 3f f6 5d 91 fc-c6 a0 41 32 cd 5a 84 e8   .o"?.]....A2.Z..
    0050 - d6 12 cc 8e a5 69 ac f4-e0 1d d0 ae 01 c7 fe 9e   .....i..........
    0060 - 4d 4f a1 80 bd a4 75 11-db 55 71 35 cb f0 87 ab   MO....u..Uq5....
    0070 - a4 41 2d f0 2a e5 13 9b-b9 52 0a 10 fd 5e 71 2e   .A-.*....R...^q.
    0080 - 39 8f 88 57 45 9d b9 da-8b 0d 7f 05 a4 40 e7 ad   9..WE........@..
    0090 - f1 bd 67 bf 80 74 55 74-8a 17 64 07 88 03 62 cf   ..g..tUt..d...b.
    00a0 - 60 53 06 fb dd 50 fc 2c-18 8b 99 db 14 14 94 dd   `S...P.,........
    00b0 - 55 0d 71 5a 64 73 89 98-a2 76 02 3a cd 1a 45 d6   U.qZds...v.:..E.

    Start Time: 1730470418
    Timeout   : 7200 (sec)
    Verify return code: 19 (self-signed certificate in certificate chain)
    Extended master secret: no
---
closed

You want to use the server CA certificate which in this case is the second certificate in the output above. Save this certificate in a file named compliance-ca.pem.

-----BEGIN CERTIFICATE-----
MII
...
8jYM6fvyT+w=
-----END CERTIFICATE-----

Create a Kubernetes configmap for the KCM TLS certificate:

% kubectl -n nshieldkeysafe5 create configmap compliance-ca --from-file=ca.pem=/path/to/compliance-ca.pem

Output:

configmap/compliance-ca created

Generate the KeySafe 5 back-end values and store them into a file named keysafe5-backend-values.yaml:

% helm -n nshieldkeysafe5 get values --all --output yaml keysafe5-backend > keysafe5-backend-values.yaml
% cat keysafe5-backend-values.yaml

Output:

appLabel: keysafe5-backend-app
cache:
  itemTTL: 168h
  peers: keysafe5-headless:3322
  replicaCount: 3
codesafe_mgmt:
  dbName: codesafe-mgmt-db
  image: localhost:5000/keysafe5/codesafe-mgmt:1.4.0
  livenessProbe:
    failureThreshold: 3
    initialDelaySeconds: 5
    periodSeconds: 60
    successThreshold: 1
  pullPolicy: IfNotPresent
  readinessProbe:
    failureThreshold: 3
    initialDelaySeconds: 5
    periodSeconds: 10
    successThreshold: 1
database:
  mongo:
    auth:
      authDatabase: authdb
      existingSecret: ""
      type: tls
    connectTimeout: 30s
    hosts: mongo-chart-mongodb-0.mongo-chart-mongodb-headless.mongons.svc.cluster.local:27017,mongo-chart-mongodb-1.mongo-chart-mongodb-headless.mongons.svc.cluster.local:27017
    maxPoolSize: 100
    minPoolSize: 1
    replicaSet: rs0
    selectionTimeout: 30s
    socketTimeout: 30s
    tls:
      cipherSuites:
      - ECDHE-ECDSA-AES128-GCM-SHA256
      - ECDHE-RSA-AES128-GCM-SHA256
      - ECDHE-ECDSA-AES256-GCM-SHA384
      - ECDHE-RSA-AES256-GCM-SHA384
      - ECDHE-ECDSA-CHACHA20-POLY1305
      - ECDHE-RSA-CHACHA20-POLY1305
      enabled: true
      existingSecret: mongodb-demo-client-certificates
      minProtocolVersion: TLSV1_2
  timeout: 30s
  type: mongo
global:
  imagePullSecrets: []
health:
  allowedClockSkew: 2m
  internalHealthTimeoutPeriod: 10s
  internalHealthUpdatePeriod: 30s
  livenessFailurePeriod: 5m
hsm_mgmt:
  dbName: hsm-mgmt-db
  image: localhost:5000/keysafe5/hsm-mgmt:1.4.0
  livenessProbe:
    failureThreshold: 3
    initialDelaySeconds: 5
    periodSeconds: 60
    successThreshold: 1
  pullPolicy: IfNotPresent
  readinessProbe:
    failureThreshold: 3
    initialDelaySeconds: 5
    periodSeconds: 10
    successThreshold: 1
httpServer:
  cleanupTimeout: 30s
  maxHeaderBytes: "1048576"
  readTimeout: 5m
  writeTimeout: 8m
integrations:
  kcm:
    caConfigMap: ""
logging:
  format: JSON
  level: INFO
messageBus:
  URL: rabbit-chart-rabbitmq.rabbitns.svc.cluster.local:5671/nshieldvhost
  auth:
    existingSecret: ""
    type: tls
  tls:
    cipherSuites:
    - ECDHE-ECDSA-AES256-GCM-SHA384
    - ECDHE-RSA-AES256-GCM-SHA384
    - ECDHE-ECDSA-AES128-GCM-SHA256
    - ECDHE-RSA-AES128-GCM-SHA256
    - ECDHE-ECDSA-CHACHA20-POLY1305
    - ECDHE-RSA-CHACHA20-POLY1305
    enabled: true
    existingSecret: rabbit-client-secret-20241029141648
    minProtocolVersion: TLSV1_2
  type: amqp
objectStore:
  pvc: data-nshield-keysafe5
podSecurityContext:
  fsGroup: 1001
  runAsGroup: 1001
  runAsUser: 1001
replicaCount: 3
sw_mgmt:
  dbName: sw-mgmt-db
  image: localhost:5000/keysafe5/sw-mgmt:1.4.0
  livenessProbe:
    failureThreshold: 3
    initialDelaySeconds: 5
    periodSeconds: 60
    successThreshold: 1
  pullPolicy: IfNotPresent
  readinessProbe:
    failureThreshold: 3
    initialDelaySeconds: 5
    periodSeconds: 10
    successThreshold: 1

Upgrade the KeySafe 5 backend:

Ensure that the nshield-keysafe5-backend-1.X.X.tgz is correct version.

% helm upgrade --install keysafe5-backend --namespace=nshieldkeysafe5 --values keysafe5-backend-values.yaml --set integrations.kcm.caConfigMap=compliance-ca helm-charts/nshield-keysafe5-backend-1.4.0.tgz

Output:

Release "keysafe5-backend" has been upgraded. Happy Helming!
NAME: keysafe5-backend
LAST DEPLOYED: Fri Nov  1 10:42:21 2024
NAMESPACE: nshieldkeysafe5
STATUS: deployed
REVISION: 3
TEST SUITE: None
NOTES:
nShield KeySafe 5 backend services

The installed nshield-keysafe5-backend release is named keysafe5-backend in namespace nshieldkeysafe5.

To view configuration values used for this install:
    helm --namespace nshieldkeysafe5 get values keysafe5-backend

Configuring External Access
----------------------------
This helm chart installs the KeySafe 5 services into a Kubernetes cluster but
does not configure external access to the services. To access the services you
will need to configure ingress to your cluster and routing of requests to the
`keysafe5-headless` Kubernetes Service.

To configure an Istio Ingress Controller, use the KeySafe 5 Istio Helm chart:
  1. Install the KeySafe 5 Istio helm chart. This chart contains pre-defined
     routes to the ClusterIP services described above (see chart README.md
     for configuration options)
  > helm install keysafe5-istio helm-keysafe5-istio/

  2. Determine the external IP address of the Istio Ingress Gateway
  > INGRESS_IP=$(kubectl get svc -n istio-system -l app=istio-ingressgateway -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')

  The backend services would then be accessible at:
                  HSM Management:  https://$INGRESS_IP/mgmt/v1/hsms
                 Host Management:  https://$INGRESS_IP/mgmt/v1/hosts
                 Pool Management:  https://$INGRESS_IP/mgmt/v1/pools
  Feature Certificate Management:  https://$INGRESS_IP/mgmt/v1/feature-certificates
       Security World Management:  https://$INGRESS_IP/mgmt/v1/worlds
             CodeSafe Management:  https://$INGRESS_IP/codesafe/v1

To configure other Kubernetes Ingress Controllers you must configure routing to
the `keysafe5-headless` service in `nshieldkeysafe5`
namespace, and any authentication or authorization to access the services.

Alternatively, for local testing:
  To access the HSM/Pool Management API:
    kubectl port-forward --namespace nshieldkeysafe5 svc/keysafe5-headless 18080:18080
    curl -X GET http://127.0.0.1:18080/mgmt/v1/hsms
    curl -X GET http://127.0.0.1:18080/mgmt/v1/hosts
    curl -X GET http://127.0.0.1:18080/mgmt/v1/pools
    curl -X GET http://127.0.0.1:18080/mgmt/v1/feature-certificates

  To access the Security World Management API:
    kubectl port-forward --namespace nshieldkeysafe5 svc/keysafe5-headless 18081:18081
    curl -X GET http://127.0.0.1:18081/mgmt/v1/worlds

  To access the CodeSafe Management API:
    kubectl port-forward --namespace nshieldkeysafe5 svc/keysafe5-headless 18082:18082
    curl -X GET http://127.0.0.1:18082/codesafe/v1/machines

Enable the connection between the KeySafe 5 and KCM

The connection between KeySafe 5 and KCM is based on a Security World basis. This allows a direct mapping one-to-one between the security world and nShield and a vault in KCM. That will allow in KCM for a customer to apply specific policies and documentation template on a vault by vault (security world by security world) basis. This allows for each security world to have its own compliance policy.

Make sure you have the following information from the KeyControl Compliance Manager:
- KeyControl Compliance Manager ID
- KeyControl Compliance Manager Token
Point your browser to the KeySafe 5 deployment URL:
```
https://<keysafe5-server-ip>
```
Select Security Worlds in the top bar, then select the Security Worlds menu option.
The list of security worlds is displayed:
Select the security world listed that you will use to connect to Entrust KeyControl Compliance Manager.
Select Compliance Manager >> Configure to configure the connection with KCM.
Enter the following information:
- KeyControl Compliance Manager ID
- KeyControl Compliance Manager Token
Navigate to the KeyControl Compliance Manager tenant URL created earlier and sign in:
```
https://<kcm-server-ip>/login/kcm/75f226ec-4730-42eb-85b3-157fc8b3467a/
```
In the main page, select Settings in the left pane.
In Settings, select App Links.
Select Create App Link and enter the information about the app:
Select Create.

This generates the token and the ID that KeySafe 5 needs.
Copy the Token and paste it back in the Setup KeyControl Compliance Manager Connection page in KeySafe 5:
```
Mz...FENw==
```
Copy the Compliance Manager ID and paste it back in the Setup KeyControl Compliance Manager Connection page in KeySafe 5:
```
10.194.XXX.XXX
```
Back in the Setup KeyControl Compliance Manager Connection page in KeySafe 5, then select Next Step.
In Token Encryption, select the App Link Token Key that you created earlier, then select Next Step.
In Configure, select the synchronization time and the size, then select Next Step.
In Complete, review the configuration settings, then select Complete Setup.

The system should connect to KeyControl Compliance Manager and display the connection status.

Now a vault has been created in KCM and the secrets metadata in keysafe5 has been pushed out to the KCM vault. The display above shows the time of the last sync and when the next sync will occur.

Validate the integration

The secrets have been pushed to the KeyControl Compliance Manager. We can check them there.

Navigate to the KeyControl Compliance Manager tenant URL that you created earlier and sign in:
```
https://<kcm-server-ip>/login/kcm/75f226ec-xxxx-xxxx-xxxx-xxxxxxxxxx/
```
Select Vaults on the left pane to list the vaults and you should see one for the world we selected in KeySafe 5.
Select the vault for the security world.

You should see the vault details, when it was connected, the last time it was sync and so on.
Select the Security Objects tab to view the secret key we created earlier in the world.

Now that you have the security objects in KCM, you can apply specific policies and documentation template on a vault by vault (security world by security world) basis. This way each security world has its own compliance policy.

For information on how to use the compliance policies, see the KeyControl Compliance Manager online documentation.