Database

All persistent data for Keysafe 5 is stored in the MongoDB database.

Databases

Keysafe 5 stores data in two different databases within MongoDB. One database for storing HSM Management related data, and one database for storing Security World Management related data.

The names of the databases used within MongoDB are defined by the helm-keysafe5-backend Helm chart.

Key Description Default value

hsm_mgmt.dbName

Name of the database to use for storing persistent HSM data

hsm-mgmt-db

sw_mgmt.dbName

Name of the database to use for storing persistent Security World data

sw-mgmt-db

Collections

HSM Management database

Keysafe 5 stores nShield HSM data in the following collections:

  • hsms

  • pools

Security World Management database

Keysafe 5 stores nShield Security World data in the following collections:

  • worlds

For each Security World known to Keysafe 5, the following collections are automatically created, where each collection name is prefixed by the ID of the Security World database record that the collection corresponds to:

  • <id>_actions

  • <id>_authorizations

  • <id>_authorized_pools

  • <id>_cards

  • <id>_cardsets

  • <id>_domains

  • <id>_groups

  • <id>_keys

  • <id>_module_certs

  • <id>_operations

  • <id>_p11objects

  • <id>_softcards

User Roles

MongoDB has the notion of roles, where each role has a defined set of allowed actions. A user of a MongoDB database can be given a role which then determines what the user can and cannot do to the data.

For details about MongoDB roles, see the MongoDB documentation.

From a security point of view we want to give Keysafe 5 as a user of the MongoDB database the least privileges which suffice for the functionality it requires from the MongoDB database.

The documentation below details the minimum privileges required for a Keysafe 5 MongoDB user for each database created by Keysafe 5.

HSM Management database

The following actions are required by Keysafe 5 for the operation of MongoDB for the HSM Management collections:

  • find

  • insert

  • update

  • remove

  • createIndex

The MongoDB administrator will configure the HSM Management database with the following actions and privileges for Keysafe 5 hsm-mgmt-db-user role:

dbname = hsm-mgmt-db
actions = ["find", "insert", "update", "remove", "createIndex"]
privileges=[
  {"resource" : {"db": dbname, "collection": "hsms"}, "actions": actions},
  {"resource" : {"db": dbname, "collection": "pools"}, "actions": actions},
]

Security World Management database

As Keysafe 5 creates new collections in the Security World Management Database as new Security Worlds are introduced to the system, RBAC (Role-based access control) must be applied at the database level rather than individual collections.

The following actions are required by Keysafe 5 for the operation of MongoDB for the Security World Management collections:

  • createIndex

  • find

  • insert

  • remove

  • update

  • dropCollection

The MongoDB administrator will configure the Security World Management database with the following actions and privileges for Keysafe 5 sw-mgmt-db-user role:

privileges=[
  {
    "resource": {"db": "sw-mgmt-db", "collection": ""},
    "actions": ["createIndex", "find", "insert", "remove", "update", "dropCollection"]
  },
]

Authentication Methods

Keysafe 5 supports the following authentication mechanisms for access to the MongoDB server:

  • No authentication

  • SCRAM

  • X.509 certificate authentication

The type of authentication is specified by database.mongo.auth.type value in the helm-keysafe5-backend Helm chart.

No Authentication

This option is used during development. It should not be used during production.

SCRAM

Using Salted Challenge Response Authentication Mechanism (SCRAM), MongoDB verifies the supplied credentials against the MongoDB’s username, password and authentication database.

In the helm-keysafe5-backend Helm chart:

  • database.mongo.auth.type must be set to pwd.

  • database.mongo.auth.existingSecret must be set to the name of an existing Kubernetes Secret that contains the username and password to use (the Secret must contain a value for username and password keys).

  • database.mongo.auth.authDatabase must be set to the name of MongoDB’s authentication database.

X.509 Certificate Authentication

Keysafe 5 can use X.509 certificates instead of usernames and passwords to authenticate to the MongoDB database.

In the helm-keysafe5-backend Helm chart:

  • database.mongo.auth.type must be set to tls.

  • database.mongo.tls.enabled must be set to true.

  • database.mongo.tls.existingSecret must be set to the name of an existing Kubernetes Secret that contains the TLS certificates to use (the Secret must contain the keys tls.crt, tls.key and ca.crt).

Backup

To be able to restore the Keysafe 5 application, Entrust recommends that you regularly backup the MongoDB database as suggested in the MongoDB documentation.

Maintenance

The Keysafe 5 application (helm-keysafe5-backend Helm chart) does not support having database collections removed while the application is running.

If deleting collections, or replacing the MongoDB server that Keysafe 5 uses, then please stop the helm-keysafe5-backend Helm chart before performing database maintenance and restart the application once the database maintenance is complete.