Skip to main content
This section describes the installation of Dogtag Certificate System on Fedora Linux 28. It demonstrates installing a CA subsystem by using a self-signed CA signing certificate, with the certificates and their corresponding keys securely stored on the Vectera Plus HSM. The following sections cover these tasks:
  1. Install the Dogtag packages.
    1. Create the directory server instance for the Dogtag Internal DB.
    2. Run the pkispawn script to create and configure a subsystem instance.
  2. View the keys and certificates that Dogtag created on the HSM.
  3. Import the CA Administrator PKCS #12 file into the browser.
    1. Access the new CA subsystem in the browser.

​
Install the Dogtag packages

Perform the following steps to install the Dogtag packages:
1
Install the Dogtag packages by using the following command:
Shell
sudo dnf install pki-ca pki-kra 389-ds-base

​
Create the directory server instance

The Dogtag CA and KRA subsystems use a 389 Directory Server as an internal database. To configure a directory server instance for the Dogtag Internal DB, perform the following steps:
1
Run the following command to log in as the root user:
Shell
sudo su
2
Set a fully qualified domain name (FQDN) 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.
Shell
vim /etc/hosts
None
127.0.0.1   pki.example.com
::1         pki.example.com
3
Run the following command to update the hostname in /etc/hostname.
Shell
hostnamectl set-hostname pki.example.com
4
Create a directory for storing the 389 Directory Server configuration file:
Shell
mkdir -p /etc/389-ds
5
Create a configuration file in the new directory with the [General] and [slapd] sections configured as follows:
Shell
vim /etc/389-ds/setup.inf
None
[General] 
FullMachineName= pki.example.com
SuiteSpotUserID= nobody
SuiteSpotGroup= nobody
 
[slapd] 
ServerPort= 389
ServerIdentifier= pki-tomcat
Suffix= dc=example,dc=com
RootDN= cn=Directory Manager
RootDNPwd= Password
6
Run the directory server installation script, selecting the defaults or customizing as needed:
Shell
setup-ds.pl --silent --file=/etc/389-ds/setup.inf

​
Run the pkispawn script to create and configure a subsystem instance

You can use the pkispawn command line tool to install and configure a new PKI instance. It eliminates the need for separate installation and configuration steps, and you can run it either interactively, as a batch process, or as 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.
We strongly recommend that you read the full documentation to understand the purpose of every parameter in the /etc/pki/default.cfg file. This enables you to customize your PKI environment to your specific needs.
Dogtag recommends spawning a subsystem that uses an HSM by creating an override configuration file that contains only the parameters necessary for using the HSM as its token. Any parameter settings in this file override the parameter settings in the default.cfg file. You can spawn any of the various Dogtag PKI subsystems (CA, KRA, OCSP, TKS, TPS) to use the HSM, but this integration guide focuses solely on the Certificate Authority (CA) for brevity.

​
Prepare an override configuration file

Perform the following steps to prepare an override configuration file with the required HSM parameters:
1
Create the override configuration file for the CA subsystem.
Shell
sudo vim ca.cfg
You can use the following example override file for spawning a CA subsystem with the HSM:
You should set all values within angle brackets to specific values for your system. Set all other values exactly as shown.
The pki\ds\password value must match the password set for the directory manager when you installed 389 Directory Server.
None
[DEFAULT]
##########################
# Provide HSM parameters #
##########################
pki_hsm_enable=True
pki_hsm_libfile=<path_to_fxpkcs11_libfile>
pki_hsm_modulename=FxPKCS11
pki_token_name=Futurex
pki_token_password=<hsm_identity_password>

########################################
# Provide PKI-specific HSM token names #
########################################
pki_audit_signing_token=Futurex
pki_ssl_server_token=Futurex
pki_subsystem_token=Futurex

##################################
# Provide PKI-specific passwords #
##################################
pki_admin_password=<pki_admin_password>
pki_client_pkcs12_password=<pki_client_pkcs12_password>
pki_ds_password=<pki_ds_password>

#####################################
# Provide non-CA-specific passwords #
#####################################
pki_client_database_password=<pki_client_database_password>

[CA]
#######################################
# Provide CA-specific HSM token names #
#######################################
pki_ca_signing_token=Futurex
pki_ocsp_signing_token=Futurex
2
After you finish, save the file.

​
Run the pkispawn utility

Perform the following steps to run the pkispawn utility:
1
In a terminal, run the following command to deploy a CA subsystem by using the Vectera Plus HSM:
You need the full path to the ca.cfg file if you are not running the command from the directory where you saved the ca.cfg.
Shell
sudo pkispawn -f ca.cfg -s CA -vvv
If you see a warning about manually adding a module while p11-kit is enabled, disregard this warning and select [ Enter ] to continue.
2
If the deployment is successful, an installation summary similar to the following displays after the command completes:
Shell
==========================================================================
                                INSTALLATION SUMMARY
==========================================================================

    Administrator's username:             caadmin
    Administrator's PKCS #12 file:
        /root/.dogtag/pki-tomcat/ca_admin_cert.p12

    To check the status of the subsystem:
        systemctl status pki-tomcatd@pki-tomcat.service

    To restart the subsystem:
        systemctl restart pki-tomcatd@pki-tomcat.service

    The URL for the subsystem is:
        https://pki.example.com:8443/ca

    PKI instances will be enabled upon system boot

==========================================================================
If the pkispawn command fails, run the following command to delete the subsystem instance that was only partially created before re-attempting to run pkispawn.
Shell
sudo pkidestroy -s CA -i pki-tomcat

​
View the keys and certificates

To view the keys and certificates that Dogtag created on the HSM, use the PKCS11Manager utility packaged with the Futurex PKCS #11 module.
1
In a terminal, go to the directory where the FXPKCS11 module is installed (such as /usr/local/bin/fxpkcs11) and run PKCS11Manager by using the following command:
Shell
./PKCS11Manager
This displays the following main menu:
None
Main Menu
    1. Print Library/Token Info

    2. Login
    3. Logout

    4. Generate Key

    5. Find Objects
    6. Modify Objects
    7. Delete Objects

    8. Generate Random Data

    9. Sign Data
    10. Verify Data

    11. Wrap Key
    12. Unwrap Key

    13. Import public key

    0. Exit
2
Enter 2 to log in, and select the Enter key.
3
Enter 1, and select the Enter key.
4
Type the password of the identity defined in the FXPKCS11 configuration file, and select the Enter key.
If successful, you receive confirmation that you are logged in.
5
Enter 5 to find objects, and select the Enter key.
6
Enter 1 to find all objects, and select the Enter key.
Information displays for all keys and certificates that the connecting identity can access.
Dogtag PKI creates 15 objects on the HSM for a CA subsystem deployment.

​
Import the PKCS #12 file

Perform the following steps to import the CA Administrator PKCS #12 file into the browser:
The following example assumes you use a Firefox web browser. There might be some differences in the steps when using a different browser, but the overall process is the same.
1
In Firefox, go to Preferences > Privacy & Security > Certificates and select View Certificates.
2
Under the Your Certificates tab, select Import to import the CA Administrator PKCS #12 file (ca_ admin_cert.p12). When it prompts for a password, enter the value that you configured for the pki_client_pkcs12_password define in the ca.cfg file in the Prepare an override configuration file with required HSM parameters section of this guide.
You can find the location of the caadmincert.p12 file in the installation summary for the CA subsystem deployment.

​
Access the new CA subsystem

Perform the following steps to access the new CA subsystem in the browser:
1
Access the Dogtag Certificate System subsystem console by going to the following URL:https://<fully qualified domain name>:8443/pki/ui/
When submitting Certificate Signing Requests (CSRs) in Dogtag Certificate System, you must specify both the Common Name and UID fields. If you submit a request with only the Common Name field completed, the request fails, and you get an error stating that the Subject Name does not match.
This completes the Dogtag Certificate System integration with the Futurex Vectera Plus HSM. An application partition on the Vectera Plus secures all CA subsystem keys and makes them available to Dogtag Certificate System as needed.