FreeIPA
Draft version. Content is hallucinated. Do not use!
certificates

Certificate Management

Manage X.509 certificates including issuance, renewal, revocation, and retrieval. Integrates with Dogtag Certificate Authority for certificate lifecycle management. Features include certificate requests with various profiles, certificate holds and releases, revocation with reason codes, certificate retrieval by serial number, and support for service and host certificates with automatic renewal via certmonger.

6 commands
certificates
x509 pki ssl-tls

Overview

FreeIPA provides integrated X.509 certificate management through its embedded Dogtag Certificate System certificate authority. This integration enables automated certificate issuance, renewal, and revocation for services, hosts, and users without requiring external PKI infrastructure or manual certificate handling. Certificates issued by IPA’s CA are automatically trusted by all IPA clients, simplifying TLS/SSL deployment and enabling strong authentication mechanisms.

Certificate management in IPA centers on service principals - certificates are associated with Kerberos principals representing services (HTTP/, LDAP/, etc.) or hosts (host/). This binding ensures certificates are issued only to authorized entities and enables automatic renewal through certmonger on IPA clients. The CA tracks certificate lifecycle including issuance dates, expiration dates, revocation status, and ownership relationships.

IPA’s certificate infrastructure supports both internal services (IPA web UI, LDAP servers, Kerberos KDC) and user-managed services requiring TLS certificates. Certificate profiles control what types of certificates can be issued, certificate access control lists (CA ACLs) determine who can request certificates, and sub-CAs enable isolation of certificate issuance for different purposes or security domains.

Certificate Request Prerequisites

Certificate requests require specific IPA objects to exist before submission. This prerequisite structure ensures certificates are associated with properly registered services and prevents unauthorized certificate issuance.

Host Entry: The host where the service runs must exist in IPA. For a certificate requested for HTTP/web.example.com, the host web.example.com must be enrolled or pre-created. Host entries establish ownership and enable delegation of certificate management.

Service Principal: The service principal must exist in IPA unless the --add option automatically creates it during the request. Service principals define which services are authorized to run on specific hosts and track certificate associations.

CA ACL Authorization: The requesting principal (user, host, or service) must be authorized by a CA ACL to request certificates from the specified CA using the specified profile. Default CA ACLs permit hosts to request certificates for their own service principals.

These prerequisites create an authorization chain: the requester must be authorized (CA ACL), the service must be registered (service principal), and the host must be legitimate (host entry). This multi-layer validation prevents unauthorized certificate issuance.

Certificate Signing Requests (CSRs)

Certificate requests are submitted as PEM-formatted Certificate Signing Requests generated by the requester’s key management system. The CSR contains the public key to be certified and subject information identifying the certificate holder. IPA’s CA validates the CSR and, if authorized, issues a signed certificate.

The Dogtag CA enforces IPA-configured subject formatting. While the CSR includes subject fields like CN (common name), O (organization), and OU (organizational unit), the CA overwrites most fields with values configured in the certificate profile. This ensures consistent subject formatting and prevents requesters from arbitrarily setting subject fields that might conflict with IPA policy.

The CN (common name) value from the CSR is preserved and typically matches the service principal. For example, a certificate for HTTP/web.example.com would have CN=web.example.com. Other subject fields are derived from the IPA domain configuration and certificate profile settings.

CSR generation typically occurs on the system requiring the certificate using tools like openssl req, ipa-getcert request (via certmonger), or application-specific certificate request mechanisms. The private key corresponding to the CSR’s public key never leaves the requesting system, maintaining key confidentiality.

Certificate Profiles

Certificate profiles define templates for certificate issuance, specifying certificate characteristics including key usage extensions, validity period, subject DN formatting, and certificate type. Different profiles support different use cases: services requiring server authentication, users needing client authentication, or specialized applications with specific certificate requirements.

IPA ships with default profiles for common scenarios:

  • caIPAserviceCert: Standard service certificates for TLS/SSL servers
  • IECUserRoles: User certificates with role information
  • caIPAserviceCert: Certificates for IPA infrastructure services

Custom profiles can be created for organizational-specific requirements, enabling certificate customization while maintaining CA policy control. Profile selection during certificate request (--profile-id) determines which template governs certificate issuance.

Certificate profiles integrate with CA ACLs to create authorization policies. A CA ACL specifies which principals can use which profiles from which CAs, enabling fine-grained control over certificate issuance capabilities.

Certificate Revocation

Certificate revocation invalidates certificates before their natural expiration, necessary when private keys are compromised, service principals are decommissioned, or certificates were issued in error. IPA supports standard RFC 5280 revocation reasons providing context for why certificates were revoked.

Revocation is immediate and permanent (except for reason code 6, certificateHold). Once revoked, the certificate’s serial number is added to the CA’s Certificate Revocation List (CRL) and marked revoked in OCSP (Online Certificate Status Protocol) responses. Clients checking revocation status will reject revoked certificates.

Common Revocation Reasons:

  • keyCompromise (1): Private key was exposed or stolen
  • superseded (4): Certificate replaced by a newer certificate
  • cessationOfOperation (5): Service no longer operational
  • certificateHold (6): Temporary revocation, reversible with cert-remove-hold
  • privilegeWithdrawn (9): Authorization to hold certificate removed

Reason code 6 (certificateHold) uniquely allows reversal. Certificates placed on hold can be removed from hold status if the security concern is resolved. All other revocation reasons are permanent.

Certificate Hold and Release

The certificate hold mechanism enables temporary suspension of certificate validity without permanent revocation. This is useful when investigating potential key compromise, temporarily suspending services, or responding to security incidents where permanent revocation may be premature.

Certificates on hold appear as revoked in CRL and OCSP responses. Clients validating these certificates will reject them as revoked. However, unlike permanent revocation, hold status can be reversed using cert-remove-hold, returning the certificate to valid status.

Use certificate hold judiciously - repeatedly placing certificates on and off hold can cause operational confusion and may not be supported consistently across all client implementations. For long-term service suspension, consider permanent revocation and reissuing a new certificate when service resumes.

Certificate Storage and Association

Certificates are stored in the Dogtag Certificate System database and associated with IPA principals (services, hosts, users) through LDAP entries. The IPA LDAP directory stores certificate metadata including serial number, subject, issuer, validity period, and principal association.

Service and host entries can store multiple certificates simultaneously, supporting certificate renewal transitions and certificate type diversity. For example, a web service might have both RSA and ECDSA certificates to support different client capabilities.

User entries can store certificates for smart card authentication, enabling passwordless login using certificates on smart cards or hardware tokens. These certificates are discovered by IPA clients during authentication, matching presented certificates against stored certificates.

Automatic Renewal with Certmonger

IPA clients use certmonger to automatically renew certificates before expiration. Certmonger tracks certificates, monitors expiration dates, and automatically requests renewals from the IPA CA when certificates approach expiration (typically 28 days before expiry).

Automatic renewal prevents certificate expiration outages and eliminates manual renewal processes. Services using certificates managed by certmonger receive renewed certificates transparently, with certmonger handling CSR generation, submission, retrieval, and local certificate file updates.

Certmonger integrates with service management to automatically reload services after certificate renewal. For example, after renewing an HTTP certificate, certmonger can trigger httpd reload to activate the new certificate without service interruption.

External Certificates

While IPA primarily manages certificates issued by its own CA, it can also track externally-issued certificates. External certificates (from public CAs, organizational PKI, or other sources) can be imported into service, host, or user entries for tracking and management purposes.

External certificate tracking enables IPA to serve as a centralized certificate inventory even when issuance occurs elsewhere. Administrators can search for certificates, view expiration dates, and track certificate-to-principal associations regardless of the issuing CA.

External certificates don’t receive automatic renewal through IPA’s certmonger integration (unless separately configured) and IPA cannot revoke them (revocation must occur at the issuing CA). However, tracking external certificates provides visibility and management consistency.

Certificate Search Capabilities

Certificates can be searched using multiple criteria enabling administrators to locate specific certificates, audit certificate issuance, track expirations, and investigate security incidents. Search parameters include certificate attributes, ownership, dates, and revocation status.

Subject Searching: Locate certificates by common name or subject DN components. The --subject parameter searches the CN field, while --exactly requires exact CN matching rather than substring matching.

Serial Number Ranges: Search for certificates by serial number ranges using --min-serial-number and --max-serial-number. Serial numbers can be specified in decimal or hexadecimal (prefix with 0x).

Date-Based Searches: Filter certificates by validity dates (notBefore, notAfter), issuance dates, or revocation dates. Date ranges use --*-from (>=) and --*-to (<=) parameters in YYYY-mm-dd format. All dates are interpreted as GMT matching certificate encoding.

Ownership Searches: Find certificates associated with specific users (--users), hosts (--hosts), or services (--services). This enables auditing what certificates are held by specific principals.

Revocation Status: Search for revoked certificates by revocation reason or revocation date range. This supports incident investigation and compliance auditing.

Certificate File Examination: The --file parameter accepts a certificate file (PEM format) and searches for it in the IPA database, returning metadata and ownership information.

Examples

Certificate Requests

Request a certificate for an existing service principal:

ipa cert-request --principal=HTTP/web.example.com web.csr

Request a certificate and automatically create the service principal:

ipa cert-request --add --principal=HTTP/web.example.com web.csr

Request a certificate using a specific profile:

ipa cert-request --principal=HTTP/web.example.com --profile-id=caIPAserviceCert web.csr

Request a certificate and retrieve the full chain:

ipa cert-request --principal=HTTP/web.example.com --chain web.csr

Request from a specific sub-CA:

ipa cert-request --principal=HTTP/web.example.com --ca=subca web.csr

Certificate Retrieval

Retrieve a certificate by serial number:

ipa cert-show 1032

Retrieve certificate and save to file:

ipa cert-show 1032 --out=cert.pem

Retrieve certificate with full chain:

ipa cert-show 1032 --chain

Retrieve certificate from specific CA:

ipa cert-show 1032 --ca=subca

Display all certificate attributes:

ipa cert-show 1032 --all

Certificate Revocation

Revoke a certificate (unspecified reason):

ipa cert-revoke 1032 --revocation-reason=0

Revoke due to key compromise:

ipa cert-revoke 1032 --revocation-reason=1

Revoke due to service cessation:

ipa cert-revoke 1032 --revocation-reason=5

Place certificate on hold (temporary revocation):

ipa cert-revoke 1032 --revocation-reason=6

Remove certificate from hold status (reactivate):

ipa cert-remove-hold 1032

Search by subject common name:

ipa cert-find --subject=web.example.com

Search with exact CN matching:

ipa cert-find --subject=web.example.com --exactly

Search for certificates owned by a specific user:

ipa cert-find --user=jsmith

Search for certificates for a specific host:

ipa cert-find --host=web.example.com

Search for certificates for a specific service:

ipa cert-find --service=HTTP/web.example.com

Search for certificates issued in a specific date range:

ipa cert-find --issuedon-from=2024-01-01 --issuedon-to=2024-12-31

Search for certificates expiring soon:

ipa cert-find --validnotafter-from=2024-01-01 --validnotafter-to=2024-03-31

Search for revoked certificates:

ipa cert-find --status=revoked

Search by revocation reason:

ipa cert-find --revocation-reason=1

Search for certificates revoked in a date range:

ipa cert-find --revokedon-from=2024-01-01 --revokedon-to=2024-01-31

Search by serial number range:

ipa cert-find --min-serial-number=1000 --max-serial-number=2000

Examine a certificate file to see if it’s in IPA:

ipa cert-find --file=cert.pem --all

Verify certificate ownership:

ipa cert-find --file=cert.pem --user=jsmith

Search certificates from specific CA:

ipa cert-find --ca=subca

Request Status Checking

Check status of a certificate request (rarely used - IPA issues immediately):

ipa cert-status 10

Revocation Reason Codes

The following RFC 5280 revocation reasons are supported:

  • 0 - unspecified: No specific reason provided
  • 1 - keyCompromise: Private key was compromised or stolen
  • 2 - cACompromise: CA’s private key was compromised
  • 3 - affiliationChanged: Certificate holder changed affiliation
  • 4 - superseded: Certificate replaced by a newer certificate
  • 5 - cessationOfOperation: Service or entity ceased operations
  • 6 - certificateHold: Temporary hold (reversible with cert-remove-hold)
  • 8 - removeFromCRL: Remove from CRL (administrative use)
  • 9 - privilegeWithdrawn: Privileges granted by certificate withdrawn
  • 10 - aACompromise: Attribute authority compromised

Note: Reason code 7 is unused in RFC 5280. Reason code 6 (certificateHold) is the only reversible revocation reason.

Best Practices

Certificate Request Management

Pre-create service principals: Create service principals before requesting certificates rather than relying on --add. This enables proper access control configuration and principal attribute setting before certificate issuance.

Use appropriate certificate profiles: Select certificate profiles that match certificate purpose. Service certificates should use service-specific profiles, user certificates should use user profiles. Incorrect profile selection can result in certificates lacking necessary extensions.

Validate CSR content: Before submitting CSRs, verify they contain correct public keys and subject information. Incorrect CSRs result in certificates that don’t match private keys or have unexpected subject fields.

Document certificate purposes: Maintain records of why certificates were issued, which services use them, and expected lifecycle. This documentation aids troubleshooting and prevents accidental revocation of active certificates.

Renewal and Lifecycle

Leverage certmonger for automatic renewal: Configure all IPA-issued service certificates in certmonger for automatic renewal. This prevents expiration outages and eliminates manual renewal processes.

Monitor certificate expiration: Even with automatic renewal, monitor certificate expiration dates to detect renewal failures. Alert on certificates expiring within 14 days.

Test certificate renewal in non-production: Verify automatic renewal works correctly before deploying to production. Renewal failures often surface during the first renewal attempt.

Plan for certificate rollover: When renewing certificates, ensure both old and new certificates work during the transition period. Some services support multiple simultaneous certificates for smooth rollover.

Revocation Practices

Revoke promptly when compromise suspected: If private key compromise is suspected, revoke immediately. Delaying revocation extends the window for potential misuse.

Use appropriate revocation reasons: Select revocation reasons accurately. This information aids security audits and incident investigation. keyCompromise and cessationOfOperation are most commonly appropriate.

Consider certificateHold for investigations: When investigating potential compromise, use certificateHold rather than permanent revocation. If investigation clears the certificate, it can be removed from hold.

Communicate revocations: When revoking service certificates, ensure service owners are notified. Revocation causes immediate service disruption if not coordinated.

Security Considerations

Protect private keys: Never share private keys across systems. Each service should have its own private key and certificate. Shared keys multiply compromise impact.

Implement CRL/OCSP checking: Configure clients to check certificate revocation status via CRL or OCSP. Without revocation checking, revoked certificates remain usable by attackers.

Audit certificate issuance regularly: Review certificate issuance logs to detect unauthorized requests or unusual patterns. Regular audits help identify compromised credentials.

Use strong key algorithms: Generate CSRs with strong key algorithms (RSA 2048+ bits, ECDSA P-256+). Weak keys reduce certificate security regardless of CA strength.

Limit CA ACL scope: CA ACLs should grant minimal necessary certificate issuance privileges. Overly broad CA ACLs enable unauthorized certificate issuance.

Operational Practices

Maintain certificate inventory: Track all issued certificates, their purposes, and owners. IPA provides this inventory through cert-find, but supplement with organizational documentation.

Establish certificate naming conventions: Use consistent service principal naming conventions. This simplifies certificate searches and prevents naming conflicts.

Test certificate deployment before production: Verify new certificates work correctly in test environments before deploying to production services. Certificate errors can be difficult to diagnose in production.

Plan for CA migration: If migrating to new CAs or changing certificate hierarchies, plan transition carefully. Services may need dual certificates during migration periods.

Document emergency revocation procedures: Establish clear procedures for emergency certificate revocation including authorization, communication, and execution. Delayed revocation during incidents multiplies damage.

Integration with Other IPA Components

Service Principals

Every certificate is associated with a service principal. Service principal management (service-* commands) creates the principals that certificates are issued to. Service principals track all certificates issued to that principal.

Host Entries

Certificates for host principals (host/hostname) and services on hosts require the host to exist in IPA. Host management (host-* commands) creates the hosts that certificates are associated with.

Certificate Profiles

Certificate profiles (certprofile-* commands) define templates for certificate issuance. Profile selection during certificate requests determines certificate characteristics including validity period and extensions.

CA ACLs

Certificate Access Control Lists (caacl-* commands) determine who can request certificates using which profiles from which CAs. CA ACL evaluation occurs before certificate issuance.

Sub-CAs

Sub-CAs (ca-* commands) provide separate certificate issuance hierarchies within IPA. Certificates can be requested from specific sub-CAs using --ca parameter, enabling certificate issuance isolation.

Certmonger

Certmonger on IPA clients automates certificate renewal, monitoring expiration and requesting renewals from the IPA CA. Certmonger integration eliminates manual certificate lifecycle management.

Smart Card Authentication

User certificates enable smart card authentication. Certificates stored in user entries (user-add-cert) are matched against certificates presented from smart cards during authentication.

Commands

Command Description

cert-find Search for existing certificates.

cert-remove-hold Take a revoked certificate off hold.

cert-request Submit a certificate signing request.

cert-revoke Revoke a certificate.

cert-show Retrieve an existing certificate.

cert-status Check the status of a certificate signing request.

cert-find

Usage: ipa [global-options] cert-find [CRITERIA] [options]

Search for existing certificates.

For certificates not issued by IPA CA,
only --certificate option is supported.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option Description

--certificate CERTIFICATE Base-64 encoded certificate.

--issuer ISSUER Issuer DN

--revocation-reason REVOCATION-REASON Reason for revoking the certificate (0-10). Type “ipa help cert” for revocation reason details.

--ca CA Name of issuing CA

--subject SUBJECT Match cn attribute in subject

--min-serial-number MIN-SERIAL-NUMBER minimum serial number

--max-serial-number MAX-SERIAL-NUMBER maximum serial number

--exactly match the common name exactly

--validnotafter-from VALIDNOTAFTER-FROM Valid not after from this date (YYYY-mm-dd)

--validnotafter-to VALIDNOTAFTER-TO Valid not after to this date (YYYY-mm-dd)

--validnotbefore-from VALIDNOTBEFORE-FROM Valid not before from this date (YYYY-mm-dd)

--validnotbefore-to VALIDNOTBEFORE-TO Valid not before to this date (YYYY-mm-dd)

--issuedon-from ISSUEDON-FROM Issued on from this date (YYYY-mm-dd)

--issuedon-to ISSUEDON-TO Issued on to this date (YYYY-mm-dd)

--revokedon-from REVOKEDON-FROM Revoked on from this date (YYYY-mm-dd)

--revokedon-to REVOKEDON-TO Revoked on to this date (YYYY-mm-dd)

--status STATUS Status of the certificate

--pkey-only Results should contain primary key attribute only (“certificate”)

--timelimit TIMELIMIT Time limit of search in seconds (0 is unlimited)

--sizelimit SIZELIMIT Maximum number of entries returned (0 is unlimited)

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--users USERS Search for certificates with these owner users.

--no-users NO-USERS Search for certificates without these owner users.

--hosts HOSTS Search for certificates with these owner hosts.

--no-hosts NO-HOSTS Search for certificates without these owner hosts.

--services SERVICES Search for certificates with these owner services.

--no-services NO-SERVICES Search for certificates without these owner services.

cert-remove-hold

Usage: ipa [global-options] cert-remove-hold SERIAL-NUMBER [options]

Take a revoked certificate off hold.

Arguments

Argument Required Description

SERIAL-NUMBER yes Serial number in decimal or if prefixed with 0x in hexadecimal

Options

Option Description

--ca CA Name of issuing CA

cert-request

Usage: ipa [global-options] cert-request CSR-FILE [options]

Submit a certificate signing request.

Arguments

Argument Required Description

CSR-FILE yes CSR

Options

Option Description

--profile-id PROFILE-ID Certificate Profile to use

--ca CA Name of issuing CA

--principal PRINCIPAL Principal for this certificate (e.g. HTTP/test.example.com)

--add automatically add the principal if it doesn’t exist (service principals only)

--chain Include certificate chain in output

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

cert-revoke

Usage: ipa [global-options] cert-revoke SERIAL-NUMBER [options]

Revoke a certificate.

Arguments

Argument Required Description

SERIAL-NUMBER yes Serial number in decimal or if prefixed with 0x in hexadecimal

Options

Option Description

--revocation-reason REVOCATION-REASON Reason for revoking the certificate (0-10). Type “ipa help cert” for revocation reason details.

--ca CA Name of issuing CA

cert-show

Usage: ipa [global-options] cert-show SERIAL-NUMBER [options]

Retrieve an existing certificate.

Arguments

Argument Required Description

SERIAL-NUMBER yes Serial number in decimal or if prefixed with 0x in hexadecimal

Options

Option Description

--ca CA Name of issuing CA

--out OUT File to store the certificate in.

--chain Include certificate chain in output

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

cert-status

Usage: ipa [global-options] cert-status REQUEST-ID [options]

Check the status of a certificate signing request.

Arguments

Argument Required Description

REQUEST-ID yes Request id

Options

Option Description

--ca CA Name of issuing CA

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

Related Topics

certprofile ca caacl