Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Sv translation
languageen_US

Software installation and startup of the QR-CERT Server involves taking the following steps:


Info
titleInfo

The QR-CERT Server software installation procedure does not contain steps related to the preparation of the selected environment, i.e. operating system, database and cryptographic module (by default, the software HSM emulator – softHSM is configured). Before attempting the installation of QR-CERT Server software, install the required components of the environment, in accordance with the appropriate documentation for the selected versions.

Note
titleNote

Examples of system commands used in the documentation are typical for the CentOS/RedHat Linux systems. The syntax of some of the commands can vary slightly in other Linux system distributions.

System account
Anchor
systemaccount
systemaccount

The creation of an mca account and mca group is required in the target system where the server software will be installed. All installation, configuration and operation actions should be performed from the level of this account (mca).

The creation of the group and account in the system should be performed after logging in as root:

Code Block
languagetext
# groupadd -g 250 mca
# useradd -u 250 -g 250 -c MCA -m mca
# passwd mca
Changing password for mca.
New password: <password>
Retype new password: <password>
passwd: all authentication tokens updated successfully.

QR-CERT Server software installation
Anchor
installation
installation

The QR-CERT Server software is distributed in the form of an archive file with the name:

Code Block
languagetext
qrcert-server-<ver>-<os>-<arch>-<db>-setup.tar.gz

Where:

  • <ver> — software version number,
  • <os> — name and version of the operating system,
  • <arch> — architecture version (32-bit, 64-bit),
  • <db> — database type.

Install the software after logging in to the server as root. Assuming that the installation file were copied to the server to folder /var/tmp/sw, execute:

Code Block
languagetext
# cd /var/tmp/sw
# tar zxvf mca-server-<ver>-<os>-<arch>-<db>-setup.tar.gz
# ./install.sh mca-server-<ver>-<os>-<arch>-<db>.tar.gz /opt/mca /var/opt/mca
Tip
titleTip

The execution parameters — paths to installation folders /opt/mca and /var/opt/mca can be changed to others. The paths included in this documentation are defaults paths.

The confirmation of successful execution of the installation command should be similar to:

Code Block
languagetext
Installing MCA...
Archive file:     mca-server-5.0.1-centos7-x64-pgsql93-setup.tar.gz
User:             mca
Group:            mca
Home directory:   /opt/mca
Shared directory: /var/opt/mca
Port base:        4500
Checking group...
OK
Checking user...
OK
Checking home directory...
OK
Checking shared directory...
OK
Extracting archive...
OK
Copying files...
OK
Updating configuration...
OK
Done

The folder structure of the installed software is as follows:

Code Block
languagetext
/opt/mca
     bin
     cert
     demo
     etc
     key
     lib
     man
     schema

/var/opt/mca
     backup
     etc
     logs
     repository

Where:

  • bin — folder containing executable files for server modules, utility software and support scripts (e.g. initiating mcactl.sh),
  • cert — folder containing certificates required for the correct operation of the server (empty after installation),
  • demo - folder containing demo configuration,
  • etc — folder containing server configuration files,
  • key — folder containing keys for softHSM — software HSM module emulator (empty after installation),
  • lib — folder containing dynamic libraries used by the QR-CERT software,
  • man — folder containing the help system file (i.e. manpages),
  • schema — folder containing the definition of the database structure.

Support scripts in the bin folder:

  • mcaenv.sh — script setting the shell environment parameters, used when starting utility software and other scripts,
  • mcactl.sh — script for starting and stopping the installed QR-CERT Server instance,
  • logserverctl.sh — script for starting and stopping the LOG-SERVER module,
  • kg-init.sh — script for starting KG-INIT,
  • p11tool.sh — script for starting the P11TOOL utility software,
  • update.sh — script for updating the QR-CERT Server software.

Configuration files in the etc folder:

  • mca.conf — main file with the configuration of all server modules,
  • mca-console.conf — optional configuration file with a list of administrator accounts for the HSM console (may not be present if the HSM console is inactive),
  • mca-auth.conf — optional configuration file with the authorization rules for clients of CA services (i.e.: TSA, OCSP, SCEP). May not be present if these services are inactive,
  • logserver-regs.conf — LOG-SERVER module configuration file with the definition of available logs,
  • logserver-acl.conf — LOG-SERVER module configuration file with the server module authorization rules,
  • tsa-policy.conf — optional configuration file for the TS-SERVER module with the time stamping authority policies parameters’ definitions (may not be present if the service is inactive),
  • mpkcs11.conf — optional configuration file for the HSM module software emulator (may not be present if the emulator is not used).

Detailed description of the configuration can be found in the section devoted to configuration.

Backup copy files, log files and log server repository will be created in the /var/opt/mca folder after system initialization.

Language selection

First, decide on the target language for the installed instance of the QR-CERT Server software. The following languages are available:

  • en - English (default language),
  • pl - Polish.

This setting determines user interface language, including defined dictionary values, error messages, etc. The code for the selected language should be provided as the value of the mca.lang parameter in the mca.conf configuration file:

Code Block
languagetext
# su - mca
$ vi /opt/mca/etc/mca.conf
[...]
mca.lang = en
[...]
Note
titleNote

Due to the fact that it is recommended to make all configuration changes and file modifications on the mca user account, the command reminding to change the user (su - mca) was included at the beginning of every script and command.

Database creation
Anchor
createdb
createdb

After the installation of the selected type of database, the preparation of the database for operation with the QR-CERT system requires the following:

  • creating a database named mca,
  • creating an mca user in the mca database,
  • creating a QR-CERT system database structure.

The mca database must belong to the mca user structure, the user must have full access to their structure. All processes of the QR-CERT Server will connect to database via this account.

PostgreSQL

Creating the mca user role and mca database:

Code Block
languagetext
# su - postgres
$ psql -d template1
template1=# CREATE USER mca WITH ENCRYPTED PASSWORD 'password';
template1=# CREATE DATABASE mca OWNER mca ENCODING 'UTF8';
template1=# \q
Ctrl+D 

Creating a QR-CERT system database structure:

Code Block
languagetext
# su - mca
$ cd /opt/mca/schema
$ psql -h localhost -d mca -U mca -f ./mca_schema.sql >log 2>&1
$ psql -h localhost -d mca -U mca -f ./mca_lang_en.sql >>log 2>&1
Tip
titleTip
The example above assumes database structure in English. If there is a need to create the database structure in other language, execute a corresponding script mca_lang_xx.sql. It is important that the language of the created database structure corresponds to the selected instance language specified in the configuration.

The correct structure creation can be verified with the command:

Code Block
languagetext
 $ cat log | grep ERROR

If executing the command does not return any errors, it means that the structure was correctly created.

Configuration of the cryptographic module (HSM)
Anchor
configurehsm
configurehsm

The QR-CERT software communicates with the HSM module via the PCKS#11 interface. The method for further installation of the QR-CERT Server software varies depending on the used HSM module.

Software HSM module emulator (softHSM)

The default HSM emulator is a software implementation of the PKCS#11 interface supplied with the installation version of the QR-CERT Server software. The HSM emulator stores the generated private keys in a file saved in the operating system. Access to keys is protected with a PIN code.

Note
titleNote

Due to the insufficient level of the offered protection, the default HSM emulator is not recommended for storing production keys.


The default configuration of the emulator defines three PKCS#11 slots:

  • slot 0 — slot dedicated for the QR-CERT system infrastructure keys,
  • slot 1 — operating slot emulating the HSM module,
  • slot 2 — operating slot emulating the HSM module.

After the installation of server software, the slots described above should be initialized. The initialization process involves adding new SO PIN and PIN numbers and creating files emulating HSM modules:

Code Block
languagetext
# su - mca
$ cd /opt/mca/bin
$ ./p11tool.sh -init -lib libmpkcs11.so -slot 0 -sopin 2222 -pin 1111
$ ./p11tool.sh -init -lib libmpkcs11.so -slot 1 -sopin 2222 -pin 1111
$ ./p11tool.sh -init -lib libmpkcs11.so -slot 2 -sopin 2222 -pin 1111

If PIN numbers other than default are used during the initialization procedure, their values should be modified in appropriate places in the configuration (HSM definitions).

Thales

nCipher

HSM

After the installation of the dedicated nCipher HSM module software, as part of module preparation, the space for saving cryptographic keys should be created (security world) together with the related sets of administrator cards (ACS — Administrator Card Set) and operator cards (OCS — Operator Card Set).

The OCS can be divided as desired but it is recommended to use the persistent option during the creation of this set — this will enable the removal of the last card after module initialization. If the OCS requires more than one card to log in to HSM, it will be necessary to include the HSM console in the QR-CERT Server software configuration.

The detailed description of the cryptographic module configuration is provided in the HSM module documentation.

After the correct preparation of the module for operation, the next step is adding the PKCS#11 library location to the QR-CERT Server environment:

Code Block
languagetext
# su - mca
$ vi /opt/mca/bin/mcaenv.sh
[...]
SHLIB_PATH=$SHLIB_PATH:/opt/nfast/toolkits/pkcs11
[...]

And the definition of the HSM module to the mca.conf configuration file:

Code Block
languagetext
# su - mca
$ vi /opt/mca/etc/mca.conf
[...]
$infhsm = Infrastructure HSM,libcknfast.so,1,console
[...]
keyhsm.1 = nShield HSM1,libcknfast.so,1,console

Additionally, the mca user should be added to the nfast group:

Code Block
languagetext
# usermod -G nfast mca
# id mca
uid=250(mca) gid=250(mca) groups=250(mca),2001(nfast)

Utimaco

CryptoServer

HSM

After the installation of the dedicated software for the SafeGuard CryptoServer HSM module, module preparation requires the generation of the Master Backup Key (MBK) and configuration of at least one PKCS#11 slot.

The detailed description of the module configuration is provided in the module documentation.

After the correct preparation of the module for operation, the next step is adding the PKCS#11 library location and its configuration file to the QR-CERT Server environment:

Code Block
languagetext
# su - mca
$ vi /opt/mca/bin/mcaenv.sh
[...]
SHLIB_PATH=$SHLIB_PATH:/opt/utimaco/x86-64/Crypto_APIs/PKCS11_R2/lib
[...]
CS_PKCS11_R2_CFG=/opt/utimaco/x86-64/Crypto_APIs/PKCS11_R2/lib/cs_pkcs11_R2.cfg
[...]
export CS_PKCS11_R2_CFG

And the definition of the HSM module to the mca.conf configuration file:

Code Block
languagetext
# su - mca
$ vi /opt/mca/etc/mca.conf
[...]
$infhsm = Infrastructure HSM,libcs_pkcs11_R2.so,0,console
[...]
keyhsm.1 = nShieldUtimaco HSM1,libcs_pkcs11_R2.so,0,console

After configuring HSM module, the procedure of new instance creation can be started.

Note
titleNote
In some situations, depending on the environment, there may be a need to additionally modify the default configuration before starting the procedure for the initialization of the newly created instance.
Scroll Ignore
Panel
bgColor#F1F1F1
titleBGColor#F7F7F7
titleOn this page
Table of Content Zone
Table of Contents
excludeSearch documentation

Search documentation

Livesearch
spaceKeyqrcert
placeholderSearched phrase
typepage