Database

All persistent data for KeySafe 5 is stored in the database.

For the Kubernetes deployment of KeySafe 5, MongoDB is used as the database.

For the Local deployment of KeySafe 5, SQLite is used as the database. For more information on the Local Deployment, see KeySafe 5 Local

MongoDB database

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

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

Key Description Default value

codesafe_mgmt.dbName

Name of the database to use for storing persistent CodeSafe data

codesafe-mgmt-db

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 related data in the following collections:

  • hsms

  • hsmoperations

  • pools

  • hosts

  • hardservers

  • features

  • config

  • images

Security World Management database

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

  • worlds

  • versions

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

  • <id>_secrets

  • <id>_kcmconnection

CodeSafe Management database

KeySafe 5 stores nShield CodeSafe related data in the following collections:

  • images

  • machines

  • certificates

  • certificatestatus

  • operations

  • steps

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:

  • createIndex

  • find

  • insert

  • remove

  • update

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

use admin
db.createRole(
  {
    role: "hsm-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "hsm-mgmt-db", "collection": ""},
          "actions": ["createIndex", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)

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

  • dropCollection

  • find

  • insert

  • remove

  • update

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

use admin
db.createRole(
  {
    role: "sw-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "sw-mgmt-db", "collection": ""},
          "actions": ["createIndex", "dropCollection", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)

CodeSafe Management database

The following actions are required by KeySafe 5 for the operation of MongoDB for the CodeSafe Management collections:

  • createIndex

  • find

  • insert

  • remove

  • update

The MongoDB administrator will configure the CodeSafe Management database with the following actions and privileges for KeySafe 5 codesafe-mgmt-db-user role:

use admin
db.createRole(
  {
    role: "codesafe-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "codesafe-mgmt-db", "collection": ""},
          "actions": ["createIndex", "find", "insert", "remove", "update"]
        },
      ],
    roles: []
  }
)

Creating a MongoDB user with the user-defined roles

The MongoDB administrator may create a user for the KeySafe 5 application to access the KeySafe 5 databases by using the db.createUser command in the MongoDB shell.

ks5_user = {
   "user" : "ks5username",
   "roles" : [
     {"role": "codesafe-mgmt-db-user", "db": "admin" },
     {"role": "hsm-mgmt-db-user", "db": "admin" },
     {"role": "sw-mgmt-db-user", "db": "admin" },
   ]
 }
> db.createUser(ks5_user)

Note that when using TLS authentication for MongoDB, the username needs to match the subject of the client certificate.

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.