Tag Archives: Dogtag

Demystifying the Certificate Authority component in FreeIPA

When I joined the FreeIPA team, I wanted to start by getting more familiar with the product from a user perspective and the first step was to install FreeIPA server.

I opened the Linux Domain Identity, Authentication, and Policy Guide, tried to figure out which options would be useful and… I froze when I reached the section Determining which CA configuration to use. I had literally no idea what the documentation meant by “Server with an integrated IdM CA” or “Server without a CA“. But I had to choose something to start with.
In this blog post, I will explain what this choice really means, and what are the consequences of picking one over the other.

Basic requirement: HTTP and LDAP server certificates

First of all, FreeIPA is composed of many services accessed through the network, among which a LDAP server and an HTTP server. These 2 services can be accessed through a standard port (in clear) or through a SSL port, meaning that they both need a server certificate.

The HTTP and LDAP server certificates are needed during the installation, because the installer will put them in the right NSS database and configure their nickname and location for the HTTP and LDAP servers to find them. There are multiple ways to obtain server certificates, but one needs to understand first the basic notions around Public Key Infrastructure (PKI).

I will use a comparison with the delivery of a passport: in order to have a passport issued with your name, you need to provide official documents (for instance a birth certificate and a photo) to the government agency that will validate the documents, make sure that you are who you claim to be, and then issue the passport. The server certificate can be compared to the passport, that will later prove your identity to whoever trusts the government agency, and the government agency can be compared to the Certificate Authority.

So in order to obtain server certificates, it is possible to:

  • request certificates to an official Certificate Authority. Many commercial or non-profit companies provide this type of service (Verisign, Let’sEncrypt, GoDaddy etc…)
  • request certificates to a home-made Certificate Authority. It is possible to create a home-made self-signed Certificate Authority with tools such as certutil or openssl. The main difference with the previous method is that people are less likely to trust your home-made CA (it’s like asking them to accept a passport that was issued by a newly founded country not recognized yet by the rest of the world). Self-signed here means that the Certificate Authority passport  is delivered by… the Certificate Authority itself!
  • install your own Certificate Authority with FreeIPA, that will sign the certificates needed by the HTTP and LDAP server.

The last option corresponds to a “Server with an integrated IdM CA” and has many advantages over the first options:

  • certificates have a limited lifetime and need to be renewed before they expire (otherwise the HTTP/LDAP servers stop working). The renewal process is time-consuming but also can be forgotten if the sysadmin does not carefully track the dates, leaving the deployment in a state where some services become unavailable.
    When FreeIPA is installed with an embedded Certificate Authority, FreeIPA automatically monitors the expiry dates of the certificates and triggers a renewal a few weeks before expiration, ensuring service continuity. This is the first advantage of the embedded CA, but not the only one.
  • FreeIPA with an embedded CA is also able to deliver certificates for the users, the hosts or the services managed by FreeIPA. Various certificates profiles can be defined, populating specific fields in each type of certificate (for instance extensions with the OCSP responder URL…)
    For more information on the embedded Certificate Authority, you can refer to Dogtag Certificate System documentation (the embedded CA in FreeIPA is a tailored version of Dogtag).

At this point, if you decide to install FreeIPA with an embedded Certificate Authority, there are 2 possible choices. The embedded CA can either be:

  • a self-signed CA: the Certificate Authority is created “from scratch” without the need for any external authority. It is the root CA, meaning that its own certificate was not delivered by anyone else but signed by itself.
  • a CA subordinate to an external CA. This means that FreeIPA CA certificate was signed by another CA, a sort of parent CA.


Corresponding installation options

CA-less installation

As said above, we need one certificate for the HTTP server and one for the LDAP server.  They have to be provided to ipa-server-install or ipa-replica-install with the options:

  • –http-cert-file / –http-pin: file containing the HTTP server certificate + private key and password protecting the file
  • –dirsrv-cert-file / –dirsrv-pin: file containing the LDAP server certificate + private key and password protecting the file

Installation with an embedded self-signed CA

FreeIPA CA is created during FreeIPA installation, and generates the HTTP and LDAP certificates. There is no need to provide any cert file! No options!

Installation with an externally-signed embedded CA

The installation is a 2-step process. In the first step, ipa-server-install must be called with –external-ca and generates a CSR file (Certificate Signing Request). This CSR file needs to be sent to the external CA that will perform a bunch of validations to authenticate the recipient of the certificate and issue a certificate for FreeIPA Certificate Authority.

In the second step, ipa-server-install is called with –external-cert-file to provide the certificate obtained from the external CA. The installer then configures FreeIPA certificate authority as a subCA of the external CA, and FreeIPA CA can issue the HTTP and LDAP server certificates.


What if…

I installed FreeIPA without any embedded CA but I change my mind?

FreeIPA allows to install an embedded CA at a later time, using ipa-ca-install. The tool provides the same options as ipa-server-install: you can either install a self-signed CA or an externally signed CA.

Important: installing an embedded CA with ipa-ca-install does not replace the HTTP and LDAP server certificates. If they were initially delivered by an external CA, they will not be automatically renewed.

I installed FreeIPA with a self-signed CA but I’d rather have an externally-signed CA?

FreeIPA allows to switch from self-signed CA to externally-signed CA using ipa-cacert-manage renew –external-ca. This is a 2-step process similar to ipa-server-install –external-ca, where the 1st step produces a CSR that needs to be supplied to an external CA. The external CA then issues a CA cert that is provided back to ipa-cacert-manage renew through the –external-cert-file option.

I installed FreeIPA with an externally signed CA but I’d rather have a self-signed CA?

FreeIPA allows to switch from externally signed CA to self-signed CA using ipa-cacert-manage renew –self-signed.

I want to replace HTTP and LDAP certificates with certificates signed by a third-party Certificate Authority?

FreeIPA provides the ipa-server-certinstall tool that will replace the current HTTP or LDAP certificates with the certs provided in the file.
Important: ipa-server-certinstall can be called to install externally signed certificates for HTTP and LDAP even if FreeIPA is installed with an embedded CA. In this case, FreeIPA CA still has the capability to issue certificates for users, hosts or services. The only difference is that HTTP and LDAP certificates are not issued by IPA CA.


Other FreeIPA commands related to certificates

When an embedded CA is installed, its certificate must be present in various files or NSS databases on all the FreeIPA hosts (master, replicas and clients) so that any FreeIPA machine trusts the certificates delivered by the embedded CA.

In addition to that, the HTTP and LDAP server certificates can be issued either by IPA CA or by an external CA, and the issuer can even be changed over time. In the external CA case, this means that the external CA needs to be trusted by all the FreeIPA machines for the IPA commands to work (the CLI communicates with the HTTP server using the https port, and this requires to trust the CA that issued the HTTP server certificate). Yet another CA certificate to add to files and databases on all the FreeIPA machines…

To ease this configuration, the tool ipa-certupdate is able to retrieve the CA certificates stored in LDAP (the embedded FreeIPA CA or the external CA certs), and install them in all the relevant files and NSS databases. It needs to be called when the CA cert is manually renewed or when a new external CA cert is added.

ipa-cacert-manage install is used to add a new external CA certificate in the LDAP store. It does not replace FreeIPA embedded CA but rather declares another certificate authority as trusted. This is useful when the HTTP and LDAP server certificates need to be replaced by certs signed by a new CA, not yet known by FreeIPA. After calling ipa-cacert-manage install (that puts the new CA in LDAP store), you need to call ipa-certupdate on all FreeIPA machines (to get the CA from the LDAP store and put it in the local NSS databases).

ipa cert-request is used to request new certificates for users, hosts or services. The certificate is signed by FreeIPA embedded CA (meaning that this command is available only when an embedded CA is configured).


By now you should be able to pick a deployment option and understand the differences between CA-less or with embedded CA, and self-signed CA or externally-signed CA.

You should also be aware that your choice is not definitive and that it is possible to install a CA at a later time or change your certificate chain from self-signed to externally-signed and vice-versa.


Using a Dogtag instance as external CA for FreeIPA installation

A FreeIPA user recently had issues installing FreeIPA with an external CA. He was using Dogtag certificate system as external CA and FreeIPA installation was failing, complaining about the certificate provided by Dogtag.

So I decided to try the same deployment and share my findings in this post.

A little background…

FreeIPA server can be configured to act as a Certificate Authority inside FreeIPA IDM domain. It will then be able to create the certificates used by the LDAP server, the Apache server used for the Web GUI or the users and hosts.

This CA can be set-up in different ways:

  • The CA is a root CA, meaning that its certificate is self-signed
  • or the CA is subordinate to an external, 3rd-party CA, meaning that its certificate is signed by the 3rd party CA.

There are a wide range of products that can be used as 3rd-party CAs, among which Dogtag certificate system. In this blog post, I will explain how Dogtag can provide the certificate for IPA CA.


The following instructions apply to Fedora 24. They will:

  1. run the 1st step of ipa-server-install to generate a CSR
  2. submit the CSR to Dogtag and have Dogtag issue a certificate for FreeIPA server
  3. run the 2nd step of ipa-server-install with the certificate obtained in step 2.

For instructions to setup the Dogtag server, you can refer to this post: Dogtag installation.


FreeIPA server installation – step 1

In order to install FreeIPA with an externally-signed CA, we must use the –external-ca option of ipa-server-install. The installation is then a multi-step install, where:

  • ipa-server-install produces a CSR
  • we need to submit this CSR to the external CA, that will in return provide a certificate and certificate chain
  • we need to run ipa-server-install a 2nd time, with different options and providing the certificates obtained in the previous step.

So let’s run the first step of ipa-server-install:

root@ipaserver$ ipa-server-install --setup-dns \
 --auto-forwarders \
 --auto-reverse \
 -n ipadomain.com \
 -p Secret123 -a Secret123 \
 --external-ca \
Configuring certificate server (pki-tomcatd). Estimated time: 3 minutes 30 seconds
 [1/8]: creating certificate server user
 [2/8]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as:
/sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate


Generation of the certificate using Dogtag

We then need to copy this CSR on the Dogtag instance and submit the CSR, approve it and export the certificate.

The submission is an important step as it allows to specify a profile. Basically, if we pick caCACert profile, we signal our intent to use the produced certificate as a Certificate Authority in our FreeIPA deployment, and the resulting certificate will contain the required extensions:

root@dogtag$ pki ca-cert-request-submit --profile caCACert --request-type pkcs10 --csr-file ipa.csr
Submitted certificate request
 Request ID: 7
 Type: enrollment
 Request Status: pending
 Operation Result: success

Note the Request ID as we will need it in order to approve the submission:

root@dogtag$ pki -c Secret123 -d /root/.dogtag/nssdb/ -n "PKI Administrator for example.com" cert-request-review 7 --action approve
Approved certificate request 7
 Request ID: 7
 Type: enrollment
 Request Status: complete
 Operation Result: success
 Certificate ID: 0x7

Note the Certificate ID as we will need it to export the certificate into a file ipa.cert:

root@dogtag$ pki -c Secret123 -d /root/.dogtag/nssdb/ -n "PKI Administrator for example.com" cert-show 7 --encoded --output ipa.cert

We will also need the dogtagca certificate chain:

root@dogtag$ pki ca-cert-show 1 --encoded --output dogtagca.cert

At this point, we have a new certificate and chain (ipa.cert and dogtagca.cert), that we need to copy on FreeIPA server. We can resume FreeIPA installation.

FreeIPA server installation – step 2

In order to resume FreeIPA installation, we will follow the instructions provided in step 1:

root@ipaserver$ /sbin/ipa-server-install --external-cert-file=ipa.cert --external-cert-file=dogtagca.cert


The installation will resume and use the ipa.cert for IPA Certificate Authority. That’s it!

Dogtag installation

Dogtag Certificate System is an open-source Certificate Authority. It allows to issue certificates,  generate Certificate Revocation Lists and much more. In this post, I am mainly interested in the installation of the Certificate Authority (to see why, you can refer to this other post, Using a Dogtag instance as external CA for FreeIPA installation).


Installation of the Dogtag server

First you need to get the packages for Dogtag and 389-ds (the LDAP server used by Dogtag):

root@dogtag$ dnf install -y 389-ds-base dogtag-pki


Dogtag relies on the LDAP server to store its data. So the installation begins with the setup of the LDAP server. It will create an instance named pki-tomcat with the suffix dc=example,dc=com:

root@dogtag$ setup-ds.pl --silent\
 slapd.RootDN="cn=Directory Manager"\
Your new DS instance 'pki-tomcat' was successfully created.
Exiting . . .
Log file is '/tmp/setupjVm7VR.log

Once the LDAP server is ready, we can proceed with the Dogtag server. The installation is an interactive process, where we will pick to install the CA subsystem and provide a password for caadmin user:

root@dogtag$ pkispawn


Interactive installation currently only exists for very basic deployments!

For example, deployments intent upon using advanced features such as:

* Cloning,
 * Elliptic Curve Cryptography (ECC),
 * External CA,
 * Hardware Security Module (HSM),
 * Subordinate CA,
* etc.,

must provide the necessary override parameters in a separate
 configuration file.

Run 'man pkispawn' for details.

Subsystem (CA/KRA/OCSP/TKS/TPS) [CA]:

 Instance [pki-tomcat]:
 HTTP port [8080]:
 Secure HTTP port [8443]:
 AJP port [8009]:
 Management port [8005]:

 Username [caadmin]:
 Password: Secret123
 Verify password: Secret123
 Import certificate (Yes/No) [N]?
 Export certificate to [/root/.dogtag/pki-tomcat/ca_admin.cert]:

Directory Server:
 Hostname [dogtag.example.com]:
 Use a secure LDAPS connection (Yes/No/Quit) [N]?
 LDAP Port [389]:
 Bind DN [cn=Directory Manager]:
 Password: Secret123
 Base DN [o=pki-tomcat-CA]:

Security Domain:
 Name [example.com Security Domain]:

Begin installation (Yes/No/Quit)? Yes

Log file: /var/log/pki/pki-ca-spawn.20160802152151.log
Installing CA into /var/lib/pki/pki-tomcat.
Storing deployment configuration into /etc/sysconfig/pki/tomcat/pki-tomcat/ca/deployment.cfg.
Notice: Trust flag u is set automatically if the private key is present.
Created symlink from /etc/systemd/system/multi-user.target.wants/pki-tomcatd.target to /usr/lib/systemd/system/pki-tomcatd.target.


Administrator's username: caadmin
 Administrator's PKCS #12 file:
 Administrator's certificate database:

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:

 PKI instances will be enabled upon system boot


Your Dogtag server is now up and running, ready to handle certificate requests.


Dogtag client configuration

In order to submit certificate requests, approve csr or export certificates, you can use Dogtag client but need first to create a NSS DB for the client. This NSSDB (by default located in ~/.dogtag/nssdb) will store the certificate that the client is using to communicate with Dogtag server:

root@dogtag$ pki -c Secret123 client-init
root@dogtag$ pk12util -i /root/.dogtag/pki-tomcat/ca_admin_cert.p12 -d /root/.dogtag/nssdb/
Enter Password or Pin for "NSS Certificate DB":
Enter password for PKCS12 file:

At this point, your client is able to interact with the server using the pki CLI.