Chapter 38. Creating and managing certificate profiles in Identity Management

Certificate profiles are used by the Certificate Authority (CA) when signing certificates to determine if a certificate signing request (CSR) is acceptable, and if so what features and extensions are present on the certificate. A certificate profile is associated with issuing a particular type of certificate. By combining certificate profiles and CA access control lists (ACLs), you can define and control access to custom certificate profiles.

In describing how to create certificate profiles, the procedures use S/MIME certificates as an example. Some email programs support digitally signed and encrypted email using the Secure Multipurpose Internet Mail Extension (S/MIME) protocol. Using S/MIME to sign or encrypt email messages requires the sender of the message to have an S/MIME certificate.

38.1. What is a certificate profile?

You can use certificate profiles to determine the content of certificates, as well as constraints for issuing the certificates, such as the following:

  • The signing algorithm to use to encipher the certificate signing request.
  • The default validity of the certificate.
  • The revocation reasons that can be used to revoke a certificate.
  • If the common name of the principal is copied to the subject alternative name field.
  • The features and extensions that should be present on the certificate.

A single certificate profile is associated with issuing a particular type of certificate. You can define different certificate profiles for users, services, and hosts in IdM. IdM includes the following certificate profiles by default:

  • caIPAserviceCert
  • IECUserRoles
  • KDCs_PKINIT_Certs (used internally)

In addition, you can create and import custom profiles, which allow you to issue certificates for specific purposes. For example, you can restrict the use of a particular profile to only one user or one group, preventing other users and groups from using that profile to issue a certificate for authentication. To create custom certificate profiles, use the ipa certprofile command.

Additional resources

  • For information on the ipa certprofile command, run the ipa help certprofile command.

38.2. Creating a certificate profile

This procedure describes how to create a certificate profile through the command line by creating a profile configuration file for requesting S/MIME certificates.

Procedure

  1. Create a custom profile by copying an existing default profile:

    $ ipa certprofile-show --out smime.cfg caIPAserviceCert
    ------------------------------------------------
    Profile configuration stored in file 'smime.cfg'
    ------------------------------------------------
      Profile ID: caIPAserviceCert
      Profile description: Standard profile for network services
      Store issued certificates: TRUE
  2. Open the newly created profile configuration file in a text editor.

    $ vi  smime.cfg
  3. Change the Profile ID to a name that reflects the usage of the profile, for example smime.

    Note

    When you are importing a newly created profile, the profileId field, if present, must match the ID specified on the command line.

  4. Update the Extended Key Usage configuration. The default Extended Key Usage extension configuration is for TLS server and client authentication. For example for S/MIME, the Extended Key Usage must be configured for email protection:

    policyset.serverCertSet.7.default.params.exKeyUsageOIDs=1.3.6.1.5.5.7.3.4
  5. 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

Verification steps

  • Verify the new certificate profile has been imported:

    $ ipa certprofile-find
    
    ------------------
    4 profiles matched
    ------------------
      Profile ID: caIPAserviceCert
      Profile description: Standard profile for network services
      Store issued certificates: TRUE
    
      Profile ID: IECUserRoles
      Profile description: User profile that includes IECUserRoles extension from request
      Store issued certificates: TRUE
    
      Profile ID: KDCs_PKINIT_Certs
      Profile description: Profile for PKINIT support by KDCs
      Store issued certificates: TRUE
    
      Profile ID: smime
      Profile description: S/MIME certificates
      Store issued certificates: TRUE
    ----------------------------
    Number of entries returned 4
    ----------------------------

Additional resources

  • For details on the certprofile plug-in, run the ipa help certprofile command.
  • For more information on the Extended Key Usage extension, see RFC 5280, section 4.2.1.12.

38.3. What is a CA access control list?

Certificate Authority access control list (CA ACL) rules define which profiles can be used to issue certificates to which principals. You can use CA ACLs to do this, for example:

  • Determine which user, host, or service can be issued a certificate with a particular profile
  • Determine which IdM certificate authority or sub-CA is permitted to issue the certificate

For example, using CA ACLs, you can restrict use of a profile intended for employees working from an office located in London only to users that are members of the London office-related IdM user group.

The ipa caacl utility for management of CA ACL rules allows privileged users to add, display, modify, or delete a specified CA ACL.

Additional resources

  • For information on the ipa caacl command, run the ipa help caacl command.

38.4. Defining a CA ACL to control access to certificate profiles

This procedure describes how to use the caacl utility to define a CA Access Control List (ACL) rule to allow users in a group access to a custom certificate profile. In this case, the procedure describes how to create an S/MIME user’s group and a CA ACL to allow users in that group access to the smime certificate profile.

Prerequisites

  • Make sure that you have obtained IdM administrator’s credentials.

Procedure

  1. Create a new group for the users of the certificate profile:

    $ ipa group-add smime_users_group
    ---------------------------------
    Added group "smime users group"
    ---------------------------------
      Group name: smime_users_group
      GID: 75400001
  2. Create a new user to add to the smime_user_group group:

    $ ipa user-add smime_user
    First name: smime
    Last name: user
    ----------------------
    Added user "smime_user"
    ----------------------
      User login: smime_user
      First name: smime
      Last name: user
      Full name: smime user
      Display name: smime user
      Initials: TU
      Home directory: /home/smime_user
      GECOS: smime user
      Login shell: /bin/sh
      Principal name: smime_user@IDM.EXAMPLE.COM
      Principal alias: smime_user@IDM.EXAMPLE.COM
      Email address: smime_user@idm.example.com
      UID: 1505000004
      GID: 1505000004
      Password: False
      Member of groups: ipausers
      Kerberos keys available: False
  3. Add the smime_user to the smime_users_group group:

    $ ipa group-add-member smime_users_group --users=smime_user
      Group name: smime_users_group
      GID: 1505000003
      Member users: smime_user
    -------------------------
    Number of members added 1
    -------------------------
  4. Create the CA ACL to allow users in the group to access the certificate profile:

    $ ipa caacl-add smime_acl
    ------------------------
    Added CA ACL "smime_acl"
    ------------------------
      ACL name: smime_acl
      Enabled: TRUE
  5. Add the user group to the CA ACL:

    $ ipa caacl-add-user smime_acl --group smime_users_group
      ACL name: smime_acl
      Enabled: TRUE
      User Groups: smime_users_group
    -------------------------
    Number of members added 1
    -------------------------
  6. Add the certificate profile to the CA ACL:

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

Verification steps

  • View the details of the CA ACL you created:

    $ ipa caacl-show smime_acl
      ACL name: smime_acl
      Enabled: TRUE
      Profiles: smime
      User Groups: smime_users_group
    ...

Additional resources

  • See ipa man page.
  • For further details about the ipa caacl command, refer to the ipa help caacl command.

38.5. Using certificate profiles and CA ACLs to issue certificates

You can request certificates using a certificate profile when permitted by the Certificate Authority access control lists (CA ACLs). This procedure describes how to request an S/MIME certificate for a user using a custom certificate profile which has been granted access through a CA ACL.

Prerequisites

  • Your certificate profile has been created.
  • An CA ACL has been created which permits the user to use the required certificate profile to request a certificate.
Note

You can bypass the CA ACL check if the user performing the cert-request command:

  • Is the admin user.
  • Has the Request Certificate ignoring CA ACLs permission.

Procedure

  1. Generate a certificate request for the user. For example, using OpenSSL:

    $ openssl req -new -newkey rsa:2048 -days 365 -nodes -keyout private.key -out cert.csr -subj '/CN=smime_user'
  2. Request a new certificate for the user from the IdM CA:

    $ ipa cert-request cert.csr --principal=smime_user --profile-id=smime

    Optionally pass the --ca sub-CA_name option to the command to request the certificate from a sub-CA instead of the root CA.

Verification steps

  • Verify the newly-issued certificate is assigned to the user:

    $ ipa user-show user
      User login: user
      ...
      Certificate: MIICfzCCAWcCAQA...
      ...

Additional resources

  • See ipa(a) man page.
  • For further details about the ipa user-show command, refer to the ipa help user-show command.
  • For further details about the ipa cert-request command, refer to the ipa help cert-request command.
  • See openssl(lssl) man page.

38.6. Modifying a certificate profile

This procedure describes how to modify certificate profiles directly through the command line using the ipa certprofile-mod command.

Procedure

  1. Determine the certificate profile ID for the certificate profile you are modifying. To display all certificate profiles currently stored in IdM:

    # ipa certprofile-find
    
    ------------------
    4 profiles matched
    ------------------
      Profile ID: caIPAserviceCert
      Profile description: Standard profile for network services
      Store issued certificates: TRUE
    
      Profile ID: IECUserRoles
      ...
    
      Profile ID: smime
      Profile description: S/MIME certificates
      Store issued certificates: TRUE
    --------------------------
    Number of entries returned
    --------------------------
  2. Modify the certificate profile description. For example, if you created a custom certificate profile for S/MIME certificates using an existing profile, change the description in line with the new usage:

    # ipa certprofile-mod smime --desc "New certificate profile description"
    ------------------------------------
    Modified Certificate Profile "smime"
    ------------------------------------
        Profile ID: smime
        Profile description: New certificate profile description
        Store issued certificates: TRUE
  3. Open your customer certificate profile file in a text editor and modify to suit your requirements:

    # vi smime.cfg

    For details on the options which can be configured in the certificate profile configuration file, see Certificate profile configuration parameters.

  4. Update the existing certificate profile configuration file:

    # ipa certprofile-mod _profile_ID_ --file=smime.cfg

Verification steps

  • Verify the certificate profile has been updated:

    $ ipa certprofile-show smime
      Profile ID: smime
      Profile description: New certificate profile description
      Store issued certificates: TRUE

Additional resources

  • See ipa(a) man page.
  • For further details about the ipa certprofile-mod command, refer to the ipa help certprofile-mod command.

38.7. Certificate profile configuration parameters

Certificate profile configuration parameters are stored in a profile_name.cfg file in the CA profile directory, /var/lib/pki/pki-tomcat/ca/profiles/ca. All of the parameters for a profile - defaults, inputs, outputs, and constraints - are configured within a single policy set. A policy set for a certificate profile has the name policyset.policyName.policyNumber. For example, for policy set serverCertSet:

policyset.list=serverCertSet
policyset.serverCertSet.list=1,2,3,4,5,6,7,8
policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl
policyset.serverCertSet.1.constraint.name=Subject Name Constraint
policyset.serverCertSet.1.constraint.params.pattern=CN=[^,]+,.+
policyset.serverCertSet.1.constraint.params.accept=true
policyset.serverCertSet.1.default.class_id=subjectNameDefaultImpl
policyset.serverCertSet.1.default.name=Subject Name Default
policyset.serverCertSet.1.default.params.name=CN=$request.req_subject_name.cn$, OU=pki-ipa, O=IPA
policyset.serverCertSet.2.constraint.class_id=validityConstraintImpl
policyset.serverCertSet.2.constraint.name=Validity Constraint
policyset.serverCertSet.2.constraint.params.range=740
policyset.serverCertSet.2.constraint.params.notBeforeCheck=false
policyset.serverCertSet.2.constraint.params.notAfterCheck=false
policyset.serverCertSet.2.default.class_id=validityDefaultImpl
policyset.serverCertSet.2.default.name=Validity Default
policyset.serverCertSet.2.default.params.range=731
policyset.serverCertSet.2.default.params.startTime=0

Each policy set contains a list of policies configured for the certificate profile by policy ID number in the order in which they should be evaluated. The server evaluates each policy set for each request it receives. When a single certificate request is received, one set is evaluated, and any other sets in the profile are ignored. When dual key pairs are issued, the first policy set is evaluated for the first certificate request, and the second set is evaluated for the second certificate request. You do not need more than one policy set when issuing single certificates or more than two sets when issuing dual key pairs.

Table 38.1. Certificate profile configuration file parameters

ParameterDescription

desc

A free text description of the certificate profile, which is shown on the end-entities page. For example, desc=This certificate profile is for enrolling server certificates with agent authentication.

enable

Enables the profile so it is accessible through the end-entities page. For example, enable=true.

auth.instance_id

Sets the authentication manager plug-in to use to authenticate the certificate request. For automatic enrollment, the CA issues a certificate immediately if the authentication is successful. If authentication fails or there is no authentication plug-in specified, the request is queued to be manually approved by an agent. For example, auth.instance_id=AgentCertAuth.

authz.acl

Specifies the authorization constraint. This is predominantly used to set the group evaluation Access Control List (ACL). For example, the caCMCUserCert parameter requires that the signer of the CMC request belongs to the Certificate Manager Agents group:

authz.acl=group="Certificate Manager Agents

In directory-based user certificate renewal, this option is used to ensure that the original requester and the currently-authenticated user are the same. An entity must authenticate (bind or, essentially, log into the system) before authorization can be evaluated.

name

The name of the certificate profile. For example, name=Agent-Authenticated Server Certificate Enrollment. This name is displayed on the end users enrollment or renewal page.

input.list

Lists the allowed inputs for the certificate profile by name. For example, input.list=i1,i2.

input.input_id.class_id

Indicates the java class name for the input by input ID (the name of the input listed in input.list). For example, input.i1.class_id=certReqInputImpl.

output.list

Lists the possible output formats for the certificate profile by name. For example, output.list=o1.

output.output_id.class_id

Specifies the java class name for the output format named in output.list. For example, output.o1.class_id=certOutputImpl.

policyset.list

Lists the configured certificate profile rules. For dual certificates, one set of rules applies to the signing key and the other to the encryption key. Single certificates use only one set of certificate profile rules. For example, policyset.list=serverCertSet.

policyset.policyset_id.list

Lists the policies within the policy set configured for the certificate profile by policy ID number in the order in which they should be evaluated. For example, policyset.serverCertSet.list=1,2,3,4,5,6,7,8.

policyset.policyset_id.policy_number.constraint.class_id

Indicates the java class name of the constraint plug-in set for the default configured in the profile rule. For example, policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl.

policyset.policyset_id.policy_number.constraint.name

Gives the user-defined name of the constraint. For example, policyset.serverCertSet.1.constraint.name=Subject Name Constraint.

policyset.policyset_id.policy_number.constraint.params.attribute

Specifies a value for an allowed attribute for the constraint. The possible attributes vary depending on the type of constraint. For example, policyset.serverCertSet.1.constraint.params.pattern=CN=.*.

policyset.policyset_id.policy_number.default.class_id

Gives the java class name for the default set in the profile rule. For example, policyset.serverCertSet.1.default.class_id=userSubjectNameDefaultImpl

policyset.policyset_id.policy_number.default.name

Gives the user-defined name of the default. For example, policyset.serverCertSet.1.default.name=Subject Name Default

policyset.policyset_id.policy_number.default.params.attribute

Specifies a value for an allowed attribute for the default. The possible attributes vary depending on the type of default. For example, policyset.serverCertSet.1.default.params.name=CN=(Name)$request.requestor_name$.