Dogtag Setup - User Guide¶

Dogtag is the Open Source upstream community version of the Red Hat Certificate System, an enterprise certificate management system that has been deployed in some of the largest PKI deployments worldwide. RHCS is FIPS 140-2 and Common Criteria certified.

The Dogtag Certificate Authority (CA) subsystem issues, renews and revokes many different kinds of certificates. It can be used as a private CA back-end to barbican, and interacts with barbican through the Dogtag CA plugin.

The Dogtag KRA subsystem is used to securely store secrets after being encrypted by storage keys that are stored either in a software NSS database or in an HSM. It can serve as a secret store for barbican, and interacts with barbican core through the Dogtag KRA plugin.

In this guide, we will provide instructions on how to set up a basic Dogtag instance containing a CA and a KRA, and how to configure barbican to use this instance for a secret store. Much more detail about Dogtag, its deployment options and its administration are available in the RHCS documentation.

Note: The code below is taken from the devstack Barbican-Dogtag gate job. You can extract this code by looking at the Dogtag functions in contrib/devstack/lib/barbican.

Installing the Dogtag Packages¶

Dogtag packages are available in Fedora/RHEL/Centos and on Ubuntu/Debian distributions. This guide will include instructions applicable to Fedora/RHEL/Centos.

If installing on a Fedora platform, use at least Fedora 21. To install the required packages:

yum install pki-ca pki-kra 389-ds-base

Creating the Directory Server Instance for the Dogtag Internal DB¶

The Dogtag CA and KRA subsystems use a 389 directory server as an internal database. Configure one as follows:

mkdir -p /etc/389-ds

cat > /etc/389-ds/setup.inf <<EOF

[General]
FullMachineName= localhost.localdomain
SuiteSpotUserID= nobody
SuiteSpotGroup= nobody

[slapd]
ServerPort= 389
ServerIdentifier= pki-tomcat
Suffix= dc=example,dc=com
RootDN= cn=Directory Manager
RootDNPwd= PASSWORD
EOF

setup-ds.pl --silent --file=/etc/389-ds/setup.inf

Creating the Dogtag CA¶

The following bash code sets up a Dogtag CA using some reasonable defaults to run in an Apache Tomcat instance on ports 8373 and 8370. Detailed version-specific documentation is packaged and installed with the Dogtag packages as Linux man pages. For more details on how to customize a Dogtag instance, see the man pages for pkispawn or consult the RHCS documentation.

mkdir -p /etc/dogtag

cat > /etc/dogtag/ca.cfg <<EOF

[CA]
pki_admin_email=caadmin@example.com
pki_admin_name=caadmin
pki_admin_nickname=caadmin
pki_admin_password=PASSWORD
pki_admin_uid=caadmin
pki_backup_password=PASSWORD
pki_client_database_password=PASSWORD
pki_client_database_purge=False
pki_client_pkcs12_password=PASSWORD
pki_clone_pkcs12_password=PASSWORD
pki_ds_base_dn=dc=ca,dc=example,dc=com
pki_ds_database=ca
pki_ds_password=PASSWORD
pki_security_domain_name=EXAMPLE
pki_token_password=PASSWORD
pki_https_port=8373
pki_http_port=8370
pki_ajp_port=8379
pki_tomcat_server_port=8375
EOF

pkispawn -v -f /etc/dogtag/ca.cfg -s CA

Creating the Dogtag KRA¶

The following bash code sets up the Dogtag KRA in the same Apache Tomcat instance as above. In this simple example, it is required to set up the CA even if only the KRA is being used for a secret store.

Note that the actual hostname of the machine should be used in the script (rather than localhost) because the hostname is used in the subject name for the SSL server certificate for the KRA.

mkdir -p /etc/dogtag

hostname=$(hostname)
cat > /etc/dogtag/kra.cfg <<EOF

[KRA]
pki_admin_cert_file=/root/.dogtag/pki-tomcat/ca_admin.cert
pki_admin_email=kraadmin@example.com
pki_admin_name=kraadmin
pki_admin_nickname=kraadmin
pki_admin_password=PASSWORD
pki_admin_uid=kraadmin
pki_backup_password=PASSWORD
pki_client_database_password=PASSWORD
pki_client_database_purge=False
pki_client_pkcs12_password=PASSWORD
pki_clone_pkcs12_password=PASSWORD
pki_ds_base_dn=dc=kra,dc=example,dc=com
pki_ds_database=kra
pki_ds_password=PASSWORD
pki_security_domain_name=EXAMPLE
pki_security_domain_user=caadmin
pki_security_domain_password=PASSWORD
pki_token_password=PASSWORD
pki_https_port=8373
pki_http_port=8370
pki_ajp_port=8379
pki_tomcat_server_port=8375
pki_security_domain_hostname=$hostname
pki_security_domain_https_port=8373
EOF

pkispawn -v -f /etc/dogtag/kra.cfg -s KRA

Configuring Barbican to Communicate with the Dogtag CA and KRA¶

In order for barbican to interact with the Dogtag CA and KRA, a PEM file must be created with trusted agent credentials.

PASSWORD=password
USER=barbican
BARBICAN_CONF_DIR=/etc/barbican
openssl pkcs12 -in /root/.dogtag/pki-tomcat/ca_admin_cert.p12 -passin pass:PASSWORD \
    -out $BARBICAN_CONF_DIR/kra_admin_cert.pem -nodes
chown $USER $BARBICAN_CONF_DIR/kra_admin_cert.pem

The barbican config file (/etc/barbican/barbican.conf) needs to be modified. The modifications below set the Dogtag plugins as the only enabled secret store. Makee sure to restart barbican once these changes are made.

Note that the actual hostname of the machine should be used in the script (rather than localhost) because the hostname is used in the subject name for the SSL server certificate for the CA.

[dogtag_plugin]
pem_path = '/etc/barbican/kra_admin_cert.pem'
dogtag_host = $(hostname)
dogtag_port = 8373
nss_db_path = '/etc/barbican/alias'
nss_db_path_ca = '/etc/barbican/alias-ca'
nss_password = 'password'
simple_cmc_profile = 'caOtherCert'
approved_profile_list = 'caServerCert'

[secretstore]
namespace = barbican.secretstore.plugin
enabled_secretstore_plugins = dogtag_crypto

Testing the Setup¶

TODO

Dogtag Setup - User Guide