WSOP 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/webservices/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/webservices/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
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 Authentication Methods.
#
# 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 |
---|---|
|
Shows this help message and exit. |
|
Specifies the YAML configuration file used to configure the Database Management Tool. |
|
The hostname of the database server.
Overrides the value in |
|
The port of the database server.
Overrides the value in |
|
The database type to use.
Available types: |
|
The severity level to log. One of:
|
|
Dry run to file without committing to database. |
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 | ||
---|---|---|---|
|
Shows this help message and exit. |
||
|
Specifies the YAML configuration file used to configure the Database Management Tool. |
||
|
The hostname of the database server.
Overrides the value in |
||
|
The port of the database server.
Overrides the value in |
||
|
The database type to use.
Available types: |
||
|
The severity level to log. One of:
|
||
|
Appname to apply to subsequent |
||
|
Filter the keys to import by key-ident. |
||
|
Only add specified Softcard. |
||
|
Only add Module protected keys. |
||
|
Only add Well-Known public keys. |
||
|
Dry run to file without committing to database. |
||
|
PKCS #11 library path |
||
|
Migrate objects with segregation using the supplied CERT file for issuer and subject information.
|
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 |
---|---|
|
Shows this help message and exit. |
|
Specifies the YAML configuration file used to configure the Database Management Tool. |
|
The hostname of the database server.
Overrides the value in |
|
The port of the database server.
Overrides the value in |
|
The database type to use.
Available types: |
|
The severity level to log. One of:
|
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
Upgrade
Upgrades the key records betweeen versions of the database management tool.
Usage:
dbmt upgrade [-h] --config CONFIG -n HOSTNAME -p PORT [-d DB] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--dry-run [DRY_RUN]]
Optional arguments:
Arg | Description |
---|---|
|
Shows this help message and exit. |
|
Specifies the YAML configuration file used to configure the Database Management Tool. |
|
The hostname of the database server.
Overrides the value in |
|
The port of the database server.
Overrides the value in |
|
The database type to use.
Available types: |
|
The severity level to log. One of: * |
|
Dry run without upgrading the database. |