Jump to: navigation, search

PKI

The integrated PKI Service is provided via the Dogtag project. PKI signs and publishes certificates for FreeIPA hosts and services. It also provides CRL and OCSP services for all software validating the published certificate. FreeIPA management framework provides API to request, show and find certificates.

As the certificates used by FreeIPA client hosts and services have limited validity, the infrastructure also needs to handle reliable renewal of the certificates. For that purpose, a Certmonger daemon is running on all clients and handles the renewal in a transparent way for the services using it.

Blending in PKI infrastructure

FreeIPA server PKI can be configured in several configurations to fit into potentially existing PKI infrastructure (related training materials):

  • Self-signed: the default option, PKI uses a self-signed CA certificate
  • External CA: when --external-ca option is used, ipa-server-install produces a certificate certificate request for it's CA certificate so that it can be properly chained in existing PKI infrastructure.
  • CA-less: FreeIPA with CA-less configuration does not set up PKI server at all and only accepts signed certificates for the Web Server and Directory Server components.

Chaining with Windows Server 2012

FreeIPA is capable to chain with external CA authorities, including Windows Server 2012 (and it's other versions). Note that there is an existing issue (Bug 1129558 in FreeIPA 4.0 and older in the certificate request produced by ipa-server-install which causes Windows Server 2012 Certificate Authority UI to reject signing the certificate.

This can be worked around by signing the certificate via command line utility certreq.exe using following command:

certreq.exe -submit -attrib "CertificateTemplate:SubCA" ipa.csr mkad2012-ipa-ca

Communication with PKI

FreeIPA clients and their services are neither expected nor allowed to communicate with PKI directly. They are supposed to utilize the FreeIPA server API instead, using the standard Kerberos authentication. FreeIPA web service then validates the request and passes it to the PKI service, authenticating with an own agent certificate (ipaCert stored in /etc/httpd/alias/)

Requesting a new certificate

Certificate can be requested either manually by a privileged user who is then able to request it for any chosen hostname (cn) or by the host itself, which can request a certificate for it's own hostname, ideally via Certmonger.

Manual certificate requests

On a FreeIPA client, run the following commands to request a new certificate which can then be used by a mod_nss Apache module to secure a HTTPS traffic with a certificate published by FreeIPA CA:

  1. Create a Kerberos principal for the service that will use/own the certificate:
    # ipa service-add HTTP/`hostname`
  2. Create NSS certificate database which will hold the certificate
    # mkdir -p /etc/httpd/nssdb; cd /etc/httpd/nssdb
    # certutil -N -d .
  3. Set correct directory ownership and SELinux context (on platforms running on SELinux):
    # chown :apache *.db && chmod g+rw *.db
    # semanage fcontext -a -t cert_t "/etc/httpd/nssdb(/.*)?"
    # restorecon -FvvR /etc/httpd/nssdb/
  4. Add FreeIPA CA certificate
    # certutil -A -d . -n 'EXAMPLE.COM IPA CA' -t CT,, -a < /etc/ipa/ca.crt
  5. Request a signed certificate for the service
    # certutil -R -d . -a -g 2048 -s CN=`hostname`,O=EXAMPLE.COM > web.csr
    # ipa cert-request --principal=HTTP/`hostname` web.csr
    # ipa cert-show $SERIAL_NUMBER --out=web.crt
    # certutil -A -d . -n Server-Cert -t u,u,u -i web.crt
  6. Optionally show and validate the certificate
    # certutil -L -d . -n Server-Cert
    # certutil -V -u V -d . -n Server-Cert

Obviously, this procedure has a disadvantage of the certificate not being tracked by the Certmonger and thus not being automatically renewed before it's validity ends.

Automated certificate requests with Certmonger

To request a new (HTTP) certificate for a FreeIPA client, the procedure is slightly easier. The biggest benefit is that the certificate is automatically renewed before the validation ends:

  1. Create a Kerberos principal for the service that will use/own the certificate:
    # ipa service-add HTTP/`hostname`
  2. Create NSS certificate database which will hold the certificate
    # mkdir -p /etc/httpd/nssdb; cd /etc/httpd/nssdb
    # certutil -N -d .
  3. In case you created the database with a PIN (asked interactively in the previous step), remember it or store it to text file:
    # echo $PIN > pwdfile.txt
    # chmod o-rwx pwdfile.txt
  4. Set correct directory ownership and SELinux context (on platforms running on SELinux):
    # chown :apache *.db && chmod g+rw *.db
    # semanage fcontext -a -t cert_t "/etc/httpd/nssdb(/.*)?"
    # restorecon -FvvR /etc/httpd/nssdb/
  5. Add FreeIPA CA certificate
    # certutil -A -d . -n 'EXAMPLE.COM IPA CA' -t CT,, -a < /etc/ipa/ca.crt
  6. Request a signed certificate for the service and see the entry in Certmonger. In case you created a NSS database with a PIN (see the step 3.), use -P $PIN or -p /etc/httpd/nssdb/pwdfile.txt option to tell certmonger about it:
    # ipa-getcert request -d /etc/httpd/nssdb -n Server-Cert -K HTTP/`hostname` -N CN=`hostname`,O=EXAMPLE.COM -g 2048 -p /etc/httpd/nssdb/pwdfile.txt
    • SAN names: in FreeIPA 4.0 and later, you can add optional SAN DNS names to your request with -D. Note that you need to first create respective host or service objects and configure that given host can manage them with service-add-host or host-add-managedby command. These objects are being verified when FreeIPA cert-req command authorizes the SAN names.
  7. Check the status of the requested certificate. If request succeeded, it will be in a MONITORING state:
    # ipa-getcert list -d /etc/httpd/nssdb/ -n Server-Cert
  8. Optionally show and validate the certificate
    # certutil -L -d . -n Server-Cert
    # certutil -V -u V -d . -n Server-Cert

Documentation

Designs

HOWTOs