Database Management Tool

Introduction

As described previously, in the current WSOP release the keys and tokens are stored in a database.

Older WSOP versions (WSOP2.1 and older) store the keys in file in /opt/nfast/kmdata/local folder.

The Database Management Tool (DBMT) is part of WSOP installation package and must be used for database collection initialisation. It can also be used for migration and integrity checking. For more advanced database operations please contact your database administrator.
The Database Management Tool is implemented as a Python3 package. Specify the path of the package in the PYTHONPATH environment variable.
The Database Management Tool imports pkcs11 objects using an external pkcs11 library specified in PKCS11_MODULE environment variable or --library argument
The log file is generated in the local directory as nshieldlogs/database_management_tool.log

To see the help text of the Database Management Tool you can run the tool with --help option.

Installation

Prerequisites

  • Security World 12.80+ installed and running

  • Mongo DB

  • Root access

Install in local system by unpacking and running the install script:

tar -xf dbmt-X.X.X.tar.gz
cd opt/nfast/wsop/dbmt-X.X.X
./install.sh

The dbmt is installed to the PYTHONPATH directory. (e.g. /opt/nfast/python3/bin/dbmt)

Install script must be called with correct user permissions.
An empty configuration file is supplied in the DBMT package: opt/nfast/wsop/dbmt-X.X.X/config_example.yaml

Configuration file

The database migration tool requires a configuration file which provides details about the destination database. The name and location of the configuration file is passed as the value of --config command line argument. The configuration file is in yml format.

This subchapter describes the sections and the fields in the configuration file.

Database hostname

The db_host field specifies the name or the IP address of the host where the database is currently running.

# Database hostname (ip address)
db_host: localhost

Database port number

The db_port field specifies the port number of the database.

# Database port number
db_port : 30001

Database name

The db_name field specifies the name of the database. This field is mandatory, meaning that running the migration tool will fail if a name is not provided.

# Name of the database
db_name : nshield-corecrypto

Database type

The db field specifies the type of the database management system. Currently the only supported value is mongodb.

# Database Management System. Valid values: [mongodb]
db : mongodb

MongoDB settings

The following settings are under mongodb section of the configuration file.

Disable TLS

The disable_tls field specifies if TLS for database connection is on or off as follows:

  • true: TLS is not used.

  • false: TLS is used.

  # Transport Layer Security. Default is enabled
  disable_tls: false

Authentication method

The auth_type field specifies one of the possible authentication methods:

  • none

  • username, password, and authentication database.

  • TLS

The possible values are none, pwd, and tls.

For details about each of these options see section Authentication Methods from this chapter.

  #
  # Authentication method with database. Valid values: [none, pwd, tls]
  auth_type: none

Username and password file

In case the authentication is performed by username and password, then auth_pwd_file field specifies the file where the username and password are stored.

  auth_pwd_file: /path_to/config-pwd-auth.yaml

Authentication database

The auth_source field specifies the name of the authentication database. The username and password provided by the file name specified by the auth_pwd_file field are verified against the username and password stored in the authentication database.

  auth_source: userdb

Certificate Authority (CA) files for TLS

When TLS option is used as an authentication method, then db_ca_file, db_cert_file and db_key_file fields specify the Certificate Authority files for TLS.

  # Certificate Authority files to use for TLS
  db_ca_file: /path_to/db_ca.crt
  db_cert_file: /path_to/db_client.pem
  db_key_file: /path_to/db_client.key

Virtual Partitioning database and collection

To enable Virtual Partitioning the user must define the Virtual Partitioning database and collection that contains the client mappings. For more information about Virtual Partitioning see the Virtual Partitioning section of this User Guide.

  # WSOP Corecrypto Segregation (WCS) Options
  # The segregation database and collection must be defined in order
  # to enable WCS. When enabled, corecrypto objects
  # will be segregated based on the mappings defined in the collection.
  # If the segregation database and collection are not defined,
  # WCS is disabled.
  #
  segregations_db_name: segregation_db
  segregations_collection_name: segregations
As previously stated, to enable Virtual Partitioning, both fields, segregation_db_name and segregations_collection_name, must be defined. If one of the fields is defined and the other is undefined, then the migration with virtual partitions will raise an error.

Environment variables

Hardserver environment variables which might be needed for migration

  • To import Softcards:

    :# export CKNFAST_LOADSHARING=1

  • To use alternative kmdata local directory:

    :# export NFAST_KMLOCAL=/opt/nfast/kmdata/local_custom/

You can also define these environment variables in the hardserver configuration file: /etc/nfast.conf.

Database Initialisation

Initialises the database with an initial structure and default domains and groups.

Usage

dbmt db-init [-h] --config CONFIG -n HOSTNAME -p PORT [-d DB] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--dry-run [DRY_RUN]]

Optional arguments

Arg Description

-h, --help

Shows this help message and exit.

--config <CONFIG>

Specifies the YAML configuration file used to configure the Database Management Tool.

-n <HOSTNAME>, --hostname <HOSTNAME>

The hostname of the database server. Overrides the value in config.yaml.

-p <PORT>, --port <PORT>

The port of the database server. Overrides the value in config.yaml.

-d <DB>, --db <DB>

The database type to use. Available types: mongodb (default)

--log-level

The severity level to log. One of:

  • DEBUG

  • INFO (default)

  • WARNING

  • ERROR

  • CRITICAL

--dry-run [<DRY_RUN>]

Dry run to file without committing to database.

Examples

  • Database initialisation:

    :# dbmt db-init --config  config.yaml

Migration

Imports kmdata using nfast to the MongoDB server.

Usage

dbmt migrate [-h] --config CONFIG -n HOSTNAME -p PORT [-d DB] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-A APPNAME] [-K KEY_IDENT | --softcard SOFTCARD | --module | --wellknown] [--dry-run [DRY_RUN]] [--library LIBRARY] [--segregate CERT]

Optional arguments

Arg Description

-h, --help

Shows this help message and exit.

--config <CONFIG>

Specifies the YAML configuration file used to configure the Database Management Tool.

-n <HOSTNAME>, --hostname <HOSTNAME>

The hostname of the database server. Overrides the value in config.yaml.

-p <PORT>, --port <PORT>

The port of the database server. Overrides the value in config.yaml.

-d <DB>, --db <DB>

The database type to use. Available types: mongodb (default)

--log-level

The severity level to log. One of:

  • DEBUG

  • INFO (default)

  • WARNING

  • ERROR

  • CRITICAL

-A <APPNAME>, --appname <APPNAME>

Appname to apply to subsequent --key-ident option.

-K <KEY_IDENT>, --key-ident <KEY_IDENT>

Filter the keys to import by key-ident.

--softcard <SOFTCARD>

Only add specified Softcard.

--module

Only add Module protected keys.

--wellknown

Only add Well-Known public keys.

--dry-run [<DRY_RUN>]

Dry run to file without committing to database.

--library <LIBRARY>

PKCS #11 library path

--segregate <CERT>

Migrate objects with segregation using the supplied CERT file for issuer and subject information.

Requires WSOP segregation to be enabled in the config file.

Examples

  • Simple migration:

    :# dbmt migrate --config  config.yaml --library /opt/nfast/bin/libcknfast.so

  • Migration of Module protected keys:

    :# dbmt migrate --config  config.yaml --module --library /opt/nfast/bin/libcknfast.so

  • Migration of Softcard protected keys:

    :# dbmt migrate --config  config.yaml --softcard <SOFTCARD> --library /opt/nfast/bin/libcknfast.so

  • Migration with segregation:

    :# dbmt migrate --config  config.yaml --library /opt/nfast/bin/libcknfast.so --segregate cert.pem

  • Dry run with logs:

    :# dbmt migrate --config  config.yaml --log-level DEBUG --library /opt/nfast/bin/libcknfast.so --dry-run dry.log
The password must be entered for every password protected Softcard. If incorrect password is entered migration is aborted. Migration data is only uploaded to MongoDB after all the passwords are entered correctly.

DB check

Checks the data integrity of the WSOP database in the Mongo DB server.

Usage:

dbmt db-check [-h] --config CONFIG -n HOSTNAME -p PORT [-d DB] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Optional arguments:

Arg Description

-h, --help

Shows this help message and exit.

--config <CONFIG>

Specifies the YAML configuration file used to configure the Database Management Tool.

-n <HOSTNAME>, --hostname <HOSTNAME>

The hostname of the database server. Overrides the value in config.yaml.

-p <PORT>, --port <PORT>

The port of the database server. Overrides the value in config.yaml.

-d <DB>, --db <DB>

The database type to use. Available types: mongodb (default).

--log-level

The severity level to log. One of:

  • DEBUG

  • INFO (default)

  • WARNING

  • ERROR

  • CRITICAL

Examples

To perform a database integrity check:

:# dbmt db-check --config config.yaml

Migration For Virtual Partitioning

The Database Management Tool migration also supports Virtual Partitioning. This can be used to maintain RFS directory partitions of Softcards and Key grouping in the standalone database.

Entrust recommends that you use a separate machine for the migration. This migration machine must have Security World 12.80+ installed, as well as the DBMT utility. Set NFAST_KMLOCAL to the directory containing the keys to be migrated.

Prerequisites

  • The Database Management Tool is installed.

  • MongoDB servers are running.

  • Security World of version at least 12.80 is installed.

  • Address of MongoDB is defined in the Database Management Tool config.yaml .

  • Virtual Partitioning is enabled in the Database Management Tool config.yaml.

  • The client’s mapping is defined in Virtual Partitioning Collection.

  • NFAST_KMLOCAL is defined to be the directory containing the keys to be migrated for this client.

Example of successful migration

This is the example output for a successful migration with Virtual Partitioning.

:# export NFAST_KMLOCAL=/opt/nfast/kmdata/local_custom/
:# dbmt migrate --config config.yaml --segregate cert.crt
Starting migration of the database...
Establishing connection to hardserver
TLS enabled
No Authentication specified
WSOP Client segregation ENABLED (segregation_db.segregations)
Establishing mongo connection to: mongo1:30001
Creating database name: nshield-corecrypto
Creating database with name: nshield-corecrypto
Setting indices on collections: nshield-corecrypto
Retrieving segregation information from TLS certificate cert.crt
Looking up subject: CN=CommonName,OU=OrganizationalUnit,O=Organization,C=Country
Migrating using segregation label 'VirtualPartitionLabel'
Collecting kmdata artifacts...

Examples of migrations with setup errors

This is the example output when Virtual Partitioning has not been enabled in the Database Management Tool config.yaml but migration with Virtual Partitioning is attempted.

:# dbmt migrate --config config.yaml --segregate cert.crt
Starting migration of the database...
Establishing connection to hardserver
TLS enabled
No Authentication specified
Establishing mongo connection to: mongo1:30001
Creating database name: nshield-corecrypto
Creating database with name: nshield-corecrypto
Setting indices on collections: nshield-corecrypto
Segregation is not enabled. Please set segregation_db and segregation_collection_name in config

This is the example output when Virtual Partitioning is enabled and configured in the Database Management Tool config.yaml but Virtual Partitioning database and collection have not been created.

:# dbmt migrate --config config.yaml --segregate cert.crt
Starting migration of the database...
Establishing connection to hardserver
TLS enabled
No Authentication specified
WSOP Client segregation ENABLED (segregation_db.segregations)
Establishing mongo connection to: mongo1:30001
Creating database name: nshield-corecrypto
Creating database with name: nshield-corecrypto
Setting indices on collections: nshield-corecrypto
Retrieving segregation information from TLS certificate cert.crt
Looking up subject: CN=CommonName,OU=OrganizationalUnit,O=Organization,C=Country
Segregation database is empty or does not exist

PKCS #11 Object Migration

The Database Management Tool migration support matches the PKCS #11 library. Please refer to the Objects table in the PKCS #11 chapter of this user guide for the full list of supported objects.