Database

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

The KeySafe 5 Service Deployment supports SQLite and MongoDB as its database options.

SQLite

SQLite is the default database used by KeySafe 5 Service Deployment. Please refer to KeySafe 5 Service Configuration for details on how to configure SQLite as the database.

MongoDB database

KeySafe 5 stores data in multiple different databases within MongoDB.

The names of the databases used within MongoDB can be controlled via the product’s configuration options.

Collections

Agent Management database

KeySafe 5 stores nShield agent data in the following collections:

  • agents

HSM Management database

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

  • config

  • features

  • hardservers

  • hosts

  • hsms

  • hsmoperations

  • images

  • pools

  • tenancies

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:

  • certificates

  • certificatestatus

  • images

  • machines

  • operations

  • steps

Licence Management database

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

  • licences

Monitoring Management database

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

  • alerts

  • methods

  • triggers

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.

Agent Management database

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

  • createIndex

  • dropCollection

  • find

  • insert

  • remove

  • update

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

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

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: []
  }
)

Licence Management database

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

  • createIndex

  • find

  • insert

  • remove

  • update

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

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

Monitoring Management database

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

  • createIndex

  • find

  • insert

  • remove

  • update

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

use admin
db.createRole(
  {
    role: "monitoring-mgmt-db-user",
    privileges: [
        {
          "resource": {"db": "monitoring-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": "agent-mgmt-db-user", "db": "admin" },
     {"role": "codesafe-mgmt-db-user", "db": "admin" },
     {"role": "hsm-mgmt-db-user", "db": "admin" },
     {"role": "licence-mgmt-db-user", "db": "admin" },
     {"role": "monitoring-mgmt-db-user", "db": "admin" },
     {"role": "sw-mgmt-db-user", "db": "admin" },
   ]
 }
> db.createUser(ks5_user)

Note that when using X.509 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 in the product’s configuration.

No authentication

Entrust does not recommend this for production.

SCRAM

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

X.509 certificate authentication

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

Backup

To be able to restore the KeySafe 5 application, Entrust recommends regular backups of the MongoDB database following the guidance provided in the MongoDB documentation.

When restoring a MongoDB backup, ensure that the application is stopped before performing the restore operation and restarted once the restore is complete.

Maintenance

KeySafe 5 does not support having database collections removed while the application is running.

When deleting collections, or replacing the MongoDB server that KeySafe 5 uses, then stop the application before performing database maintenance and restart the application once the database maintenance is complete.