V4/Certificate Profiles
Contents
- 1 Overview
- 2 Use Cases
- 3 Design
- 4 Implementation
- 5 Feature Management
- 5.1 UI
- 5.2 CLI
- 5.2.1 ipa certprofile-import ID [options]
- 5.2.2 ipa certprofile-mod ID [options]
- 5.2.3 ipa certprofile-del ID
- 5.2.4 ipa certprofile-find [CRITERIA] [options]
- 5.2.5 ipa certprofile-show ID [options]
- 5.2.6 ipa caacl-find
- 5.2.7 ipa caacl-show NAME
- 5.2.8 ipa caacl-add NAME
- 5.2.9 ipa caacl-mod NAME
- 5.2.10 ipa caacl-del NAME
- 5.2.11 ipa caacl-enable NAME
- 5.2.12 ipa caacl-disable NAME
- 5.2.13 ipa caacl-add-profile NAME
- 5.2.14 ipa caacl-remove-profile NAME
- 5.2.15 ipa caacl-add-user NAME
- 5.2.16 ipa caacl-remove-user NAME
- 5.2.17 ipa caacl-add-host NAME
- 5.2.18 ipa caacl-remove-host NAME
- 5.2.19 ipa caacl-add-service NAME
- 5.2.20 ipa caacl-remove-service NAME
- 5.2.21 ipa cert-request
- 5.3 Configuration
- 6 Upgrade
- 7 How to Use
- 8 Test Plan
- 9 Dependencies
Overview
FreeIPA currently only supports host and service certificates and has a single, hard-coded certificate profile. This proposal introduces the ability to define new certificate profiles and control which subject principals or principal types (users, hosts or services) they can be used for.
Use Cases
Custom extension values
The current certificate profile sets both TLS Server Authentication and TLS Client Authentication in the Extended Key Usage extension. This is not appropriate for most uses. Profile support will allow the appropriate profile(s) to be defined.
Furthermore, wherever there is a use case that requires specific values in certificate fields or extensions, it will be possible to import a profile that supports that use case as long as Dogtag supports the certificate extension(s) to be included.
DNP3 SAv5
The DNP3 Secure Authentication version 5 (SAv5) standard uses the IEC 62351-8 certificate authentication to carry authorization data for the DNP3 smart-grid technology. A specialised certificate profile would be needed to support DNP3.
Design
Profiles will be stored in Dogtag. A small amount of metadata will be stored in FreeIPA's directory to track these profiles, provide a description and store whether certificates issued using the profile will be stored in the FreeIPA directory.
IPA must be modified to respect the profile parameter in requests from Certmonger (currently ignored).
Rich profile management (use of a command-line tool or Web UI to build new profiles for use with FreeIPA, rather than the presuppose the existence of a profile) can be implemented on top of the basic profiles support, if there is demand. At a minimum, there should be tutorials and improved documentation in Dogtag for how to define certificate profiles.
Terminology
- included profile
- Any profile that is shipped as part of FreeIPA and available in a default installation.
- custom profile
- Any profile that has been imported by an administrator.
- FreeIPA-managed profile
- A profile that was added via FreeIPA and has an associated object in the FreeIPA directory, containing FreeIPA-specific configuration, distinguishing it from other profiles in Dogtag.
Profile backend
A new backend will be implemented to provide the profile management behaviours while abstracting the Dogtag integration. The profile management plugin shall invoke the profile backend to do the work of communicating with Dogtag.
Profile formats
There are two profile formats used by Dogtag: an XML representation, and the "raw" property list format which is also (at the current time) the internal storage format. Initial work will focus on the raw format, but it should be simple to distinguish between and support both formats.
Listing profiles
The list of all Dogtag profiles is retrieved via the Dogtag REST API:
GET /ca/rest/profiles
Profile import
(This section is about importing new profiles individually. For initial import of profiles during installation or upgrade, see the Configuration and Upgrade sections.)
New profiles can be imported via CLI (specify profile filename) or Web UI (paste file content). Interactive "profile builder" functionality is a future feature (see Dogtag ticket #1331.)
Having obtained the profile content, FreeIPA will import import the profile into Dogtag using the Dogtag REST API:
PUT /ca/rest/profiles/<profileId> (XML format) PUT /ca/rest/profiles/<profileId>/raw (raw format)
Failure modes:
- Profile ID already in use
- Bad profile content
Retrieve profile
Profile data can be retrieved from Dogtag using the REST API:
GET /ca/rest/profiles/<profileId> (XML format) GET /ca/rest/profiles/<profileId>/raw (raw format)
The XML or property list (whatever is used) can be parsed to determine name, enabled/disabled state, and other data. It is not an initial requirement that FreeIPA provide a detailed breakdown of the profile (inputs, policy constraints and defaults, etc), but the basic information should be available.
Failure modes:
- Profile ID unknown
Delete profile
Profiles can be deleted from Dogtag using the REST API:
DELETE /ca/rest/profiles/<profileId>
Failure modes:
- Profile ID unknown
- Profile enabled (profiles must be disabled before deletion)
If a profile is enabled and a FreeIPA admin attempts to delete it, we shall raise StillActive
or a similar exception.
Enable/disable profile
Enabling or disabling a profile in Dogtag is accomplished via the REST API:
POST /ca/rest/profiles/<profileId>?action=enable POST /ca/rest/profiles/<profileId>?action=disable
Failure modes:
- Profile ID unknown
- Profile already enabled/disabled
It may be useful to record the enabled/disabled state of a profile in the FreeIPA directory, so that the state is visible and decisions can be made based on the profile state without requiring a round-trip to Dogtag to find out and to avoid blind attempts of operations that could fail according to profile enabled/disabled state (e.g. profile deletion).
Certificate Profiles plugin
The certprofile
plugin will be created for the management of FreeIPA profiles. It will allow privileged users to import, modify or remove FreeIPA-managed profiles in Dogtag and manage the FreeIPA-specific profile configuration.
Enabling or disabling profiles
IPA will not provide a direct way to enable or disable profiles in Dogtag. Separate CA ACL rules will govern whether a particular profile can be used to issue a certificate to a particular subject princpial. These rules can be created, modified, disabled or enabled by privileged users. See the CA ACL section below.
Storing issued certificates
Support for multiple profiles means that principals (including user principals) may now have multiple certificates. The proposed schema and implications are discussed in the V4/User Certificates design page.
The FreeIPA profile object class includes a boolean attribute ipaCertProfileStoreIssued
that controls whether certificate issued using that profile are stored in the subject principal's userCertificate
attribute. For use cases that involve issuance of many, possibly short-lived certificates, setting this attribute to FALSE
ensures that these certificates to not accumulate in the principal's entry.
When issuing a certificate via ipa cert-request
, the semantics of ipaCertProfileStoreIssued
is:
- when
TRUE
, add the full certificate to the userCertificate attribute; - when
FALSE
, store nothing at all and merely deliver the issued certificate in the command result.
The cert-request command will be updated to act accordingly.
Permissions
The following new permissions will be added, as will the CA Administrator role which is initially granted these permissions.
System: Read Certificate Profiles
(all principals may read)System: Import Certificate Profile
System: Delete Certificate Profile
System: Modify Certificate Profile
Schema
FreeIPA will store data about the certificate profiles that are managed via FreeIPA (including the included profiles). This will:
- enable fast query of which profiles are available for FreeIPA principals to use (Dogtag does not have to be contacted);
- allow storage of additional profile-related configuration that is specific to FreeIPA;
- avoid exposing all of the profiles available in Dogtag to FreeIPA (only those managed by FreeIPA will be visible to FreeIPA users);
The data stored for each profile are:
- Profile ID (used by Dogtag)
- Profile summary (short description)
- Profile certificate storage configuration (explained above)
Certificate profile entries will be stored under a new DN: cn=certprofiles,cn=ca,$SUFFIX
.
Schema:
dn: cn=schema attributeTypes: ( 2.16.840.1.113730.3.8.19.1.1 NAME 'ipaCertProfileStoreIssued' DESC 'Store certificates issued using this profile' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE X-ORIGIN 'IPA v4.2' ) objectClasses: ( 2.16.840.1.113730.3.8.19.2.1 NAME 'ipaCertProfile' SUP top STRUCTURAL MUST ( cn $ description $ ipaCertProfileStoreIssued ) X-ORIGIN 'IPA v4.2' )
CA ACLs plugin
Custom profile use cases involve the issuance of certificates for specific, unrelated purposes. It is necessary to be able to define rules that control which profiles can be used to issue certificates to which principals. ACLs will be used to associate profiles, subject principals and groups with a CA (initially just the top-level CA, but this provision is made for forward-compatibility with Lightweight CAs). Specifically:
- An ACL can permit access to multiple CAs.
- An ACL can permit access to multiple profiles.
- An ACL can have multiple users, services, hosts, (user) groups and hostgroups associated with it.
- The interpretation of the ACL is: these principals (or groups) are permitted as the subject of certificates issued using these profiles, by these CAs.
Note that the principal performing the certificate request is not necessarily the subject principal.
See also the ipa caacl-*
commands in the CLI section below.
Permissions
The following permissions will be created. All permissions are intially granted to the CA Administrator role.
System: Read CA ACLs
- All may read all attributes.
System: Add CA ACL
- Add a new CA ACL.
System: Delete CA ACL
- Delete an existing CA ACL.
System: Modify CA ACL
- Modify the name or description, or enable/disable the CA ACL.
System: Manage CA ACL membership
- Manage CA, profile, user, host and service membership.
Schema
CA ACL objects shall be stored in the container cn=caacls,cn=ca,$SUFFIX
.
New attributes are defined for CA and profile membership and categories ("all CAs / profiles"). The ipaCaAcl
object class extends ipaAssociation
uses these new attributes as well as existing member and category attributes.
Note that the memberCa
and caCategory
attributes are unused by this design. They will be used by the Sub-CAs feature.
attributeTypes: (2.16.840.1.113730.3.8.21.1.2 NAME 'memberCa' DESC 'Reference to a CA member' SUP distinguishedName EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 X-ORIGIN 'IPA v4.2' ) attributeTypes: (2.16.840.1.113730.3.8.21.1.3 NAME 'memberProfile' DESC 'Reference to a certificate profile member' SUP distinguishedName EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 X-ORIGIN 'IPA v4.2' ) attributeTypes: (2.16.840.1.113730.3.8.21.1.4 NAME 'caCategory' DESC 'Additional classification for CAs' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'IPA v4.2' ) attributeTypes: (2.16.840.1.113730.3.8.21.1.5 NAME 'profileCategory' DESC 'Additional classification for certificate profiles' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'IPA v4.2' ) objectClasses: (2.16.840.1.113730.3.8.21.2.2 NAME 'ipaCaAcl' SUP ipaAssociation STRUCTURAL MUST cn MAY ( caCategory $ profileCategory $ userCategory $ hostCategory $ serviceCategory $ memberCa $ memberProfile $ memberService ) X-ORIGIN 'IPA v4.2' )
Default CA ACL
During installation we must create a default CA ACL that grants use of caIPAserviceCert on the top-level CA to all hosts and services:
dn: ipauniqueid=autogenerate,cn=caacls,cn=ca,$SUFFIX changetype: add objectclass: ipaassociation objectclass: ipacaacl ipauniqueid: autogenerate cn: hosts_services_caIPAserviceCert ipaenabledflag: TRUE memberprofile: cn=caIPAserviceCert,cn=certprofiles,cn=ca,$SUFFIX hostcategory: all servicecategory: all
Implementation
ipa-pki-proxy.conf
had to be updated to allow access to the /ca/rest/profiles
endpoint and to allow either certificate authentication or password authentication for logging into the REST API.
As part of this feature, FreeIPA now manages its own profiles. Previously, the default profile was provided by Dogtag itself. (Currently, it still is, but FreeIPA overrides it, and its removal from Dogtag should now be considered). FreeIPA profile templates (which have variables that are substituted before they are imported into Dogtag) are stored in /usr/share/ipa/profiles/
.
The CA ACL enforcement functions use the existing HBAC machinery from the pyhbac
module.
Feature Management
UI
Profile management UI
A grid UI shall be provided that lists FreeIPA-managed profiles and allows editing of their FreeIPA-specific configuration.
CA ACL management UI
A web UI allowing creation and management of CA ACLs will be added. It will work similarly to the HBAC UI.
Certificate management UI
There are existing UI elements for requesting a certificate for, and displaying the certificate issued to a service principal. These aspects of the UI must be enhanced to support multiple certificates.
For certificate requests, a drop-down list of FreeIPA-managed profiles will be suitable for selecting a profile.
For viewing certificates, a list of certificates should be presented. Each should identify the profile that was used to issue that certificate, and perhaps other important information such as a certificate fingerprint. Upon selecting a certificate the existing dialog showing the Base-64 encoded certificate and providing options for renewal or revocation will be shown.
CLI
ipa certprofile-import ID [options]
Add a profile to FreeIPA and Dogtag. Profiles will be enabled by default.
Options:
--desc=STR
- Brief description of this profile
--store=BOOL
- Whether to store certs issued using this profile
--file=FILE
- Name of file containing profile data (Dogtag raw format)
ipa certprofile-mod ID [options]
--desc=STR
- Edit the description
--store=BOOL
- Edit the "store issued certificates" policy for this profile
--file=FILE
- Name of file containing profile data (Dogtag raw format) with which to update Dogtag.
ipa certprofile-del ID
Delete the specified profile. This command will disable the profile in Dogtag prior to deletion.
Certificates issued using the profile will be kept around; no special action is taken in this regard.
ipa certprofile-find [CRITERIA] [options]
Search for Certificate Profiles.
--id=STR
- Profile ID
--desc=STR
- Brief description of the profile
--store=BOOL
- Search for profiles with the given store-issued setting.
Case insensitive substring or keyword match on the description is desirable, to aid users in locating the right profile for a particular purpose.
ipa certprofile-show ID [options]
Display the properties of a Certificate Profile.
--out=FILE
- Write the Dogtag profile data (Dogtag raw format) to the named file.
ipa caacl-find
Search for CA ACLs.
--name=STR
- CA ACL name
--desc=STR
- Description
--profilecat=['all']
- Profile category. Mutually exclusive to profile members.
--usercat=['all']
- User category. Mutually exclusive with user members.
--hostcat=['all']
- Host category. Mutually exclusive with host members.
--servicecat=['all']
- Service category. Mutually exclusive with service members.
ipa caacl-show NAME
Show details of named CA ACL.
ipa caacl-add NAME
Create a CA ACL. New CA ACLs are initially enabled.
--desc=STR
- Description
--profilecat=['all']
- Profile category. Mutually exclusive to profile members.
--usercat=['all']
- User category. Mutually exclusive with user members.
--hostcat=['all']
- Host category. Mutually exclusive with host members.
--servicecat=['all']
- Service category. Mutually exclusive with service members.
ipa caacl-mod NAME
Modify the named CA ACL.
--desc=STR
- Description
--profilecat=['all']
- Profile category. Mutually exclusive to profile members.
--usercat=['all']
- User category. Mutually exclusive with user members.
--hostcat=['all']
- Host category. Mutually exclusive with host members.
--servicecat=['all']
- Service category. Mutually exclusive with service members.
--setattr
,--addattr
,--delattr
- As per other IPA framework commands.
ipa caacl-del NAME
Delete the CA ACL.
ipa caacl-enable NAME
Enable the named CA ACL.
ipa caacl-disable NAME
Disabled the named CA ACL.
ipa caacl-add-profile NAME
Add profile(s) to the CA ACL.
--certprofiles=STR
- Certificate Profiles to add.
ipa caacl-remove-profile NAME
Remove profile(s) from the CA ACL.
--certprofiles=STR
- Certificate Profiles to remove.
ipa caacl-add-user NAME
--users
- Add user(s)
--groups
- Add user group(s)
ipa caacl-remove-user NAME
--users
- Remove user(s)
--groups
- Remove user group(s)
ipa caacl-add-host NAME
--hosts
- Add host(s)
--hostgroups
- Add host group(s)
ipa caacl-remove-host NAME
--hosts
- Remove host(s)
--hostgroups
- Remove host group(s)
ipa caacl-add-service NAME
--services
- Add service(s)
ipa caacl-remove-service NAME
--services
- Remove service(s)
ipa cert-request
Modify command to add optional --profile-id ID
argument to specify which profile to use. If not given, the default caIPAserviceCert
profile will be used.
Configuration
FreeIPA must be deployed with the Dogtag RA in order to use these features. No other configuration is required.
There is no configuration in FreeIPA to enable or disable profiles in Dogtag. FreeIPA-managed profiles are automatically enabled in Dogtag upon import.
Essential profiles (if any beyond the default set in Dogtag) will be added and enabled on server installation. Other "pre-canned" profiles can be introduced by FreeIPA in the future, as required.
Upgrade
The upgrade process ensures that included profiles are imported and enabled.
Dogtag instances must be configured to use LDAP-based profiles, so that they are replicated. This involves setting subsystem.1.class=com.netscape.cmscore.profile.LDAPProfileSubsystem
in Dogtag's CS.cfg
and importing profiles.
Upgrading default profiles
If an included profile (i.e., a profile supplied by FreeIPA) needs to be updated, an upgrade script can call invoke the profile backend to update it. Any changes to the behaviour of included profiles should be adequately documented in release notes.
Handling inconsistent profiles
We take a "first upgrade wins" approach - whichever replica is upgraded first, its profiles are imported. On other replica, the presence of LDAP profiles will be detected and no import or conflict resolution is attempted. This behaviour must be clearly explained and administrators who have custom profiles encouraged to check for inconsistencies prior to upgrade.
Adding default CA ACL
On upgrade, a default CA ACL added that permits host and service principals to use the default profile, ensuring that current capabilities are maintained.
How to Use
See https://blog-ftweedal.rhcloud.com/2015/08/user-certificates-and-custom-profiles-with-freeipa-4-2/
Test Plan
http://www.freeipa.org/page/V4/Certificate_Profiles/Test_Plan
Dependencies
- Dogtag with LDAP profile replication enabled.