# 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:

    dnf 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

this page last updated: 2026-04-01 16:51:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug