Dogtag Certificate System installation and subsystem deployment
This section will guide you through the installation process of Dogtag Certificate System on Fedora Linux 28. Our example will demonstrate the installation of a CA subsystem using a self-signed CA signing certificate, with the certificates and their corresponding keys being securely stored on the Futurex Vectera Plus HSM.
Install the Dogtag packages using the following command:
The Dogtag CA and KRA subsystems use a 389 Directory Server as an internal database. To configure one, follow the steps below:
Run the following command to login as the root user:
Set a FQDN (Fully qualified domain name) as the hostname for your Fedora 28 system. First, edit the /etc/hosts file as follows:
You can set any valid FQDN. It does not need to be set to pki.example.com.
You must also run the command below to update the hostname in the /etc/hostname file.
Create a directory for storing the 389 Directory Server configuration file:
Create a configuration file in the new directory with the [General] and [slapd] sections configured as follows:
Run the directory server installation script, selecting the defaults or customizing as desired:
The pkispawn command line tool is used to install and configure a new PKI instance. It eliminates the need for separate installation and configuration steps, and may be run either interactively, as a batch process, or a combination of both (batch process with prompts for passwords). Refer to the pkispawn man page for detailed information about all supported options by running "man pkispawn".
The pkispawn command reads in its default installation and configuration values from a plain text configuration file (/etc/pki/default.cfg). This file consists of name=value pairs divided into [DEFAULT], [Tomcat], [CA], [KRA], [OCSP], [TKS], and [TPS] sections.
It is strongly recommended that you read the full documentation to understand the purpose of every parameter in the /etc/pki/default.cfg file. This will allow you to customize your PKI environment to your specific needs.
Dogtag's recommended procedure for spawning a subsystem that uses an HSM is to create an override configuration file that contains only the parameters necessary for using the HSM as its token. Any parameter settings in this file will override the parameter settings in the default.cfg file.
Any of the various Dogtag PKI subsystems (CA, KRA, OCSP, TKS, TPS) can be spawned to use the HSM, but this integration guide will focus solely on the Certificate Authority (CA) for brevity.
Create the override configuration file for the CA subsystem.
The following is an example override file that can be used for spawning a CA subsystem with the HSM:
All values contained within angle brackets need to be set to a specific value by the user. All other values should be set exactly as shown.
The pki_ds_password value must match the password set for the directory manager when 389 Directory Server was installed.
After you have finished editing, save the file.
In a terminal, run the following command to deploy a CA subsystem using the Vectera Plus HSM:
The full path to the ca.cfg file is required if you are not running the command from the directory where the ca.cfg file is saved.
You will most likely see a warning message about manually adding a module while p11-kit is enabled. You can disregard this warning and press [ Enter ] to continue.
If the deployment is successful, an installation summary similar to the following will be presented after the command completes:
If the pkispawn command fails, you need to run the following command to delete the subsystem instance that was only partially created before re-attempting to run pkispawn.
To view the keys and certificates that Dogtag created on the HSM, we will use the PKCS11Manager utility packaged with the Futurex PKCS #11 module.
In a terminal, navigate to the directory where the FXPKCS11 module is installed (e.g., /usr/local/bin/fxpkcs11) and run PKCS11Manager using the following command:
This will present the following main menu:
Type 2 to login, then press Enter.
Type 1, then press Enter.
Type the password of the identity that is defined in the FXPKCS11 configuration file, then press Enter.
If successful, you will receive confirmation that you are logged in.
Type 5 to find objects, then press Enter.
Type 1 to find all objects, then press Enter.
Information will be printed for all keys and certificates that the connecting identity has access to.
Dogtag PKI creates 15 objects on the HSM for a CA subsystem deployment.
The following steps were completed using a Firefox web browser. There may be some differences in the steps when using a different browser, but the overall intent of the process is the same.
In Firefox, navigate to Preferences > Privacy & Security > Certificates and click the View Certificates button.
Under the Your Certificates tab, select Import to import the CA Administrator PKCS #12 file (i.e., ca_ admin_cert.p12). When it prompts for a password, enter the value that was configured for the pki_client_pkcs12_password define in the ca.cfg file in section Prepare an override configuration file with required HSM parameters.
The location of the ca_admin_cert.p12 file was included in the installation summary for the CA subsystem deployment.
Access the Dogtag Certificate System subsystem console by navigating to the URL below:
https://<fully qualified domain name>:8443/pki/ui/
When submitting Certificate Signing Requests (CSRs) in Dogtag Certificate System, the Common Name and UID fields are both required. If you submit a request with only the Common Name field completed, the request will fail, and you will receive an error stating that the Subject Name does not match.
This completes the Dogtag Certificate System integration with the Futurex Vectera Plus HSM. All CA subsystem keys are secured within an application partition on the Vectera Plus and available to Dogtag Certificate System when required.