Tags: , ,

User certificates and custom profiles with FreeIPA 4.2

The FreeIPA 4.2 release introduces some long-awaited certificate management features: user certificates and custom certificate profiles. In this blog post, we will examine the background and motivations for these features, then carry out a real-world scenario where both these features are used: user S/MIME certificates for email protection.

Custom profiles §

FreeIPA uses the Dogtag Certificate System PKI for issuance of X.509 certificates. Although Dogtag ships with many certificate profiles, and could be configured with profiles for almost any conceivable use case, FreeIPA only used a single profile for the issuance of certificates to service and host principals. (The name of this profile was caIPAserviceCert, but it hardcoded and not user-visible).

The caIPAserviceCert profile was suitable for the standard TLS server authentication use case, but there are many use cases for which it was not suitable; especially those that require particular Key Usage or Extended Key Usage assertions or esoteric certificate extensions, to say nothing of client-oriented profiles.

It was possible (and remains possible) to use the deployed Dogtag instance directly to accomplish almost any certificate management goal, but Dogtag lacks knowledge of the FreeIPA schema so the burden of validating requests falls entirely on administrators. This runs contrary to FreeIPA’s goal of easy administration and the expectations of users.

The certprofile-import command allows new profiles to be imported into Dogtag, while certprofile-mod, certprofile-del, certprofile-show and certprofile-find do what they say on the label. Only profiles that are shipped as part of FreeIPA (at time of writing only caIPAserviceCert) or added via certprofile-import are visible to FreeIPA.

An important per-profile configuration that affects FreeIPA is the ipaCertprofileStoreIssued attribute, which is exposed on the command line as --store=BOOL. This attribute tells the cert-request command what to do with certificates issued using that profile. If TRUE, certificates are added to the target principal’s userCertificate attribute; if FALSE, the issued certificate is delievered to the client in the command result but nothing is stored in the FreeIPA directory (though the certificate is still stored in Dogtag’s database). The option to not store issued certificates is desirable in uses cases that involve the issuance of many short-lived certificates.

Finally, cert-request learned the --profile-id option to specify which profile to use. It is optional and defaults to caIPAserviceCert.

User certificates §

Prior to FreeIPA 4.2 certificates could only be issued for host and service principals. The same capability now exists for user principals. Although cert-request treats user principals in substantially the same way as host or service principals there are a few important differences:


With support for custom certificate profiles, there must be a way to control which profiles can be used for issuing certificates to which principals. For example, if there was a profile for Puppet masters, it would be sensible to restrict use of that profile to hosts that are members of a some Puppet-related group. This is the purpose of CA ACLs.

CA ACLs are created with the caacl-add command. Users and groups can be added or removed with the caacl-add-user and caacl-remove-user commands. Similarly, caacl-{add,remove}-host for hosts and hostgroups, and caacl-{add,remove}-service.

If you are familiar with FreeIPA’s Host-based Access Control (HBAC) policy feature these commands might remind you of the hbacrule commands. That is no coincidence! The hbcarule commands were my guide for implementing the caacl commands, and the same underlying machinery - libipa_hbac via pyhbac - is used by both plugins to enforce their policies.

Putting it all together §

Let’s put these features to use with a realistic scenario. A certain group of users in your organisation must use S/MIME for securing their email communications. To use S/MIME, these users must be issued a certificate with emailProtection asserted in the Extended Key Usage certificate extension. Only the authorised users should be able to have such a certificate issued.

To address this scenario we will:

  1. create a new certificate profile for S/MIME certificates;
  2. create a group for S/MIME users and a CA ACL to allow members of that group access to the new profile;
  3. generate a signing request and issue a cert-request command using the new profile.

Let’s begin.

Creating an S/MIME profile §

We export the default profile to use as a starting point for the S/MIME profile:

% ipa certprofile-show --out smime.cfg caIPAserviceCert

Inspecting the profile, we find the Extended Key Usage extension configuration containing the line:


The Extended Key Usage extension is defined in RFC 5280 § The two OIDs in the default profile are for TLS WWW server authentication and TLS WWW client authentication respectively. For S/MIME, we need to assert the Email protection key usage, so we change this line to:


We also remove the profileId=caIPAserviceCert and set an appropriate value for the desc and name fields. Now we can import the new profile:

% ipa certprofile-import smime --file smime.cfg \
  --desc "S/MIME certificates" --store TRUE
Imported profile "smime"
Profile ID: smime
Profile description: S/MIME certificates
Store issued certificates: TRUE

Defining the CA ACL §

We will define a new group for S/MIME users, and a CA ACL to allow users in that group access to the smime profile:

% ipa group-add smime_users
Added group "smime_users"
  Group name: smime_users
  GID: 1148600006

% ipa caacl-add smime_acl
Added CA ACL "smime_acl"
  ACL name: smime_acl
  Enabled: TRUE

% ipa caacl-add-user smime_acl --group smime_users
  ACL name: smime_acl
  Enabled: TRUE
  User Groups: smime_users
Number of members added 1

% ipa caacl-add-profile smime_acl --certprofile smime
  ACL name: smime_acl
  Enabled: TRUE
  Profiles: smime
  User Groups: smime_users
Number of members added 1

Creating and issuing a cert request §

Finally we need to create a PKCS #10 certificate signing request (CSR) and issue a certificate via the cert-request command. We will do this for the user alice. Because this certificate is for email protection Alice’s email address should be in the Subject Alternative Name (SAN) extension; we must include it in the CSR.

The following OpenSSL config file can be used to generate the certificate request:

[ req ]
prompt = no
encrypt_key = no

distinguished_name = dn
req_extensions = exts

[ dn ]
commonName = "alice"

[ exts ]

We create and then inspect the CSR (the genrsa step can be skipped if you already have a key):

% openssl genrsa -out key.pem 2048
Generating RSA private key, 2048 bit long modulus
e is 65537 (0x10001)
% openssl req -new -key key.pem -out alice.csr -config alice.conf
% openssl req -text < alice.csr
Certificate Request:
        Version: 0 (0x0)
        Subject: CN=alice
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (1024 bit)
                Exponent: 65537 (0x10001)
        Requested Extensions:
            X509v3 Subject Alternative Name: 
    Signature Algorithm: sha1WithRSAEncryption

Observe that the common name is the user’s name alice, and that alice@ipa.local is present as an rfc822Name in the SAN extension.

Now let’s request the certificate:

% ipa cert-request alice.req --principal alice --profile-id smime
ipa: ERROR: Insufficient access: Principal 'alice' is not
  permitted to use CA '.' with profile 'smime' for certificate

Oops! The CA ACL policy prohibited this issuance because we forgot to add alice to the smime_users group. (The not permitted to use CA '.' part is a reference to the upcoming sub-CAs feature). Let’s add the user to the appropriate group and try again:

% ipa group-add-member smime_users --user alice
  Group name: smime_users
  GID: 1148600006
  Member users: alice
Number of members added 1

% ipa cert-request alice.req --principal alice --profile-id smime
  Certificate: MIIEJzCCAw+gAwIBAgIBEDANBgkqhkiG9w0BAQsFADBBMR...
  Subject: CN=alice,O=IPA.LOCAL 201507271443
  Issuer: CN=Certificate Authority,O=IPA.LOCAL 201507271443
  Not Before: Thu Aug 06 04:09:10 2015 UTC
  Not After: Sun Aug 06 04:09:10 2017 UTC
  Fingerprint (MD5): 9f:8e:e0:a3:c6:37:e0:a4:a5:e4:6b:d9:14:66:67:dd
  Fingerprint (SHA1): 57:6e:d5:07:8f:ef:d6:ac:36:b8:75:e0:6c:d7:4f:7d:f9:6c:ab:22
  Serial number: 16
  Serial number (hex): 0x10

Success! We can see that the certificate was added to the user’s userCertificate attribute, or export the certificate to inspect it (parts of the certificate are elided below) or import it into an email program:

% ipa user-show alice
  User login: alice
  First name: Alice
  Last name: Able
  Home directory: /home/alice
  Login shell: /bin/sh
  Email address: alice@ipa.local
  UID: 1148600001
  GID: 1148600001
  Certificate: MIIEJzCCAw+gAwIBAgIBEDANBgkqhkiG9w0BAQsFADBBMR...
  Account disabled: False
  Password: True
  Member of groups: smime_users, ipausers
  Kerberos keys available: True

% ipa cert-show 16 --out alice.pem >/dev/null
% openssl x509 -text < alice.pem
        Version: 3 (0x2)
        Serial Number: 16 (0x10)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=IPA.LOCAL 201507271443, CN=Certificate Authority
            Not Before: Aug  6 04:09:10 2015 GMT
            Not After : Aug  6 04:09:10 2017 GMT
        Subject: O=IPA.LOCAL 201507271443, CN=alice
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Authority Key Identifier: 

            Authority Information Access: 
                OCSP - URI:http://ipa-ca.ipa.local/ca/ocsp

            X509v3 Key Usage: critical
                Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment
            X509v3 Extended Key Usage: 
                E-mail Protection
            X509v3 CRL Distribution Points: 

                Full Name:
                CRL Issuer:
                  DirName: O = ipaca, CN = Certificate Authority

            X509v3 Subject Key Identifier: 
            X509v3 Subject Alternative Name: 
    Signature Algorithm: sha256WithRSAEncryption

Conclusion §

The ability to define and control access to custom certificate profiles and the extension of FreeIPA’s certificate management features to user principals open the door to many use cases that were previously not supported. Although the certificate management features available in FreeIPA 4.2 are a big step forward, there are still several areas for improvement, outlined below.

First, the Dogtag certificate profile format is obtuse. Documentation will make it bearable, but documentation is no substitute for good UX. An interactive profile builder would be a complex feature to implement but we might go there. Alternatively, a public, curated, searchable (even from FreeIPA’s web UI) repository of profiles for various use cases might be a better use of resources and would allow users and customers to help each other.

Next, the ability to create and use sub-CAs is an oft-requested feature and important for many use cases. Work is ongoing to bring this to FreeIPA soon. See the Sub-CAs design page for details.

Thirdly, the FreeIPA framework currently has authority to perform all kinds of privileged operations on the Dogtag instance. This runs contrary to the framework philosophy which advocates for the framework only having the privileges of the current user, with ACIs (and CA ACLs) enforced in the backends (in this case Dogtag). Ticket #5011 was filed to address this discrepancy.

Finally, the request interface between FreeIPA and Dogtag is quite limited; the only substantive information conveyed is whatever is in the CSR. There is minimal capability for FreeIPA to convey additional data with a request, and any time we (or a user or customer) want to broaden the interface to support new kinds of data (e.g. esoteric certificate extensions containing values from custom attributes), changes would have to be made to both FreeIPA and Dogtag. This approach does not scale.

I have a vision for how to address this final point in a future version of FreeIPA. It will be the subject of future blog posts, talks and eventually - hopefully - design proposals and patches! For now, I hope you have enjoyed this introduction to some of the new certificate management capabilities in FreeIPA 4.2 and find them useful. And remember that feedback, bug reports and help with development are always appreciated!

Creative Commons License
Except where otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License .