Red Hat Certificate System 8.0

Admin Guide

Installing, configuring, and managing Red Hat Certificate System 8.0 subsystems

Edition 8.0.22

Legal Notice

Copyright © 2009 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
July 22, 2009, updated on January 6, 2011

Abstract

This manual covers all aspects of installing, configuring, and managing Certificate System subsystems. It also covers management tasks such as adding users; requesting, renewing, and revoking certificates; publishing CRLs; and managing smart cards. This guide is intended for Certificate System administrators.
About This Guide
1. Recommended Concepts
2. What Is in This Guide
3. Supported Platforms, Hardware, and Programs
3.1. Supported Platforms
3.2. Supported Web Browsers
3.3. Supported Smart Cards
3.4. Supported HSM
3.5. Supported Charactersets
4. Examples and Formatting
4.1. Formatting for Examples and Commands
4.2. Tool Locations
4.3. Guide Formatting
5. Additional Reading
6. Giving Feedback
7. Document History
1. Overview of Red Hat Certificate System Subsystems
1.1. How Certificates Are Used
1.1.1. Uses for Certificates
1.1.2. Types of Certificates
1.2. A Review of Certificate System Subsystems
1.2.1. Certificate Manager
1.2.2. Registration Authority
1.2.3. Data Recovery Manager
1.2.4. Online Certificate Status Manager
1.2.5. Token Processing System
1.2.6. Token Key Service
1.2.7. Enterprise Security Client
1.3. A Look at Managing Certificates
1.4. A Look at the Token Management System
1.5. Red Hat Certificate System Services
1.5.1. Interfaces for Administrators
1.5.2. Agent Interfaces
1.5.3. End User Pages
1.5.4. Enterprise Security Client
I. Setting up Certificate Services
2. Making Rules for Issuing Certificates
2.1. About Certificate Profiles
2.1.1. The Profile
2.1.2. Certificate Extensions: Defaults and Constraints
2.1.3. Inputs and Outputs
2.2. Setting up Certificate Profiles
2.2.1. Creating Certificate Profiles through the CA Console
2.2.2. Editing Certificate Profiles in the Console
2.2.3. Creating and Editing Certificate Profiles through the Command Line
2.2.4. Defining Key Defaults in Profiles
2.2.5. Configuring Cross-Pair Profiles
2.2.6. List of Certificate Profiles
2.3. Configuring Custom Enrollment Profiles to Use with an RA
2.3.1. Default RA Profiles
2.3.2. Creating RA Enrollment Forms
2.3.3. Configuring the Request Queues
2.4. Managing Smart Card CA Profiles
2.4.1. Editing Enrollment Profiles for the TPS
2.4.2. Creating Custom TPS Profiles
2.4.3. Using the Windows Smart Card Logon Profile
2.5. Setting the Signing Algorithms for Certificates
2.5.1. Setting the CA's Default Signing Algorithm
2.5.2. Setting the Signing Algorithm Default in a Profile
2.6. Managing CA-Related Profiles
2.6.1. Setting Restrictions on CA Certificates
2.6.2. Changing the Restrictions for CAs on Issuing Certificates
2.7. Managing Subject Names and Subject Alternative Names
2.7.1. Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name
2.7.2. Changing DN Attributes in CA-Issued Certificates
2.7.3. Customizing the Subject DN in a Certificate Request Issued by an RA
3. Setting up Key Archival and Recovery
3.1. About Key Archival and Recovery
3.2. Setting up Key Archival
3.3. Setting up Agent-Approved Key Recovery Schemes
3.4. Testing the Key Archival and Recovery Setup
4. Requesting, Enrolling, and Managing Certificates
4.1. About Enrolling and Renewing Certificates
4.2. Configuring Internet Explorer to Enroll Certificates
4.3. Requesting and Receiving Certificates
4.3.1. Requesting and Receiving a User or Agent Certificate through the End-Entities Page
4.3.2. Requesting Certificates Using certutil
4.4. Enrolling a Certificate on a Cisco Router
4.4.1. Enabling SCEP Enrollments
4.4.2. Configuring Security Settings for SCEP
4.4.3. Configuring a Router for SCEP Enrollment
4.4.4. Generating the SCEP Certificate for a Router
4.4.5. Working with Subordinate CAs
4.4.6. Re-enrolling a Router
4.4.7. Enabling Debugging
4.5. Performing Bulk Issuance
4.6. Configuring and Using the Auto Enrollment Proxy
4.6.1. About Auto Enrollment
4.6.2. Installing and Setting up the Auto Enrollment Proxy
4.6.3. Managing Auto Enrollment Proxy Settings
4.6.4. Manually Requesting Domain Certificates
4.7. Renewing Certificates
4.7.1. About Renewal
4.7.2. Creating Custom Renewal Profiles
4.7.3. Renewing Certificates
5. Using and Configuring the Token Management System: TPS, TKS, and Enterprise Security Client
5.1. Configuring TPS Smart Card Operations
5.1.1. Configuring Format Operations
5.1.2. Configuring TPS Enrollment Operations
5.1.3. Configuring TPS Renewal Operations
5.1.4. Configuring the PIN Reset Operation
5.1.5. Configuring the Applet Update Operation
5.2. Allowing Token Renewal
5.3. Changing the Token Policy
5.4. Setting Token Types for Specified Smart Cards
5.4.1. Default Token Types
5.4.2. Mapping Token Types to Smart Card Operation Profiles
5.4.3. Example: Token Mapping with Two Different Token Types
5.5. Setting Token Status Transitions
5.6. Automating Encryption Key Recovery
5.6.1. Configuring Enrollment for Replacement Tokens
5.6.2. Configuring Key Generation for Temporary Tokens
5.7. Managing Shared Keys
5.7.1. Generating Master Keys
5.7.2. Generating and Transporting Wrapped Master Keys
5.7.3. Using HSM for Generating Keys
5.7.4. Updating Master Key Versions and Associating the Master Key with Its Version
5.7.5. Configuring Symmetric Key Changeover
5.8. Configuring the TPS
5.8.1. Enabling SSL for TPS-Enterprise Security Client Connections
5.8.2. Configuring the Channels between the TPS and Tokens
5.8.3. Configuring or Disabling LDAP Authentication
5.8.4. Configuring the Token Database
5.8.5. Configuring Server-Side Key Generation and Archival of Encryption Keys
5.8.6. Configuring IPv6 Support
5.9. Scaling the TPS and Its Support Subsystems
5.9.1. Configuring Failover Support
5.9.2. Configuring Multiple Support Subsystem Instances for Different Functions
5.10. Potential Token Operation Errors
6. Revoking Certificates and Issuing CRLs
6.1. About Revoking Certificates
6.1.1. User-Initiated Revocation
6.1.2. Reasons for Revoking a Certificate
6.1.3. CRL Issuing Points
6.1.4. Delta CRLs
6.1.5. Publishing CRLs
6.1.6. Certificate Revocation Pages
6.2. CMC Revocation
6.2.1. Setting up CMC Revocation
6.2.2. Testing CMC Revoke
6.3. Issuing CRLs
6.3.1. Configuring Issuing Points
6.3.2. Configuring CRLs for Each Issuing Point
6.3.3. Setting CRL Extensions
6.3.4. Setting a CA to Use a Different Certificate to Sign CRLs
6.4. Setting Full and Delta CRL Schedules
6.4.1. Configuring Extended Updated Intervals for CRLs in the Console
6.4.2. Configuring Extended Updated Intervals for CRLs in CS.cfg
6.5. Enabling Automatic Revocation Checking for Agent Certificates
7. Using the Online Certificate Status Protocol Responder
7.1. Setting up the OCSP Responder
7.2. Identifying the CA to the OCSP Responder
7.2.1. Verify Certificate Manager and Online Certificate Status Manager Connection
7.2.2. Configure the Revocation Info Stores
7.2.3. Testing the OCSP Service Setup
7.3. Enabling the Certificate Manager's Internal OCSP Service
7.4. Enabling Revocation Checking for the TPS and RA
7.5. Enabling Certificate Revocation Checking for DRM and TKS Users
7.6. Submitting OCSP Requests Using the GET Method
7.7. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier
II. Additional Configuration to Manage CA Services
8. Publishing Certificates and CRLs
8.1. About Publishing
8.1.1. Publishers
8.1.2. Mappers
8.1.3. Rules
8.1.4. Publishing to Files
8.1.5. OCSP Publishing
8.1.6. LDAP Publishing
8.2. Setting up Publishing
8.2.1. Configuring Publishing to a File
8.2.2. Configuring Publishing to an OCSP
8.2.3. Configuring Publishing to an LDAP Directory
8.2.4. Creating Rules
8.2.5. Enabling Publishing
8.3. Publishing CRLs over HTTP
8.3.1. Configuring CRL Publishing to Resume after Interrupted Downloads
8.3.2. Retrieving CRLs Using wget
8.3.3. Retrieving Partial CRLs
8.4. Publishing Cross-Pair Certificates
8.5. Testing Publishing to Files
8.6. Viewing Certificates and CRLs Published to File
8.7. Updating Certificates and CRLs in a Directory
8.7.1. Manually Updating Certificates in the Directory
8.7.2. Manually Updating the CRL in the Directory
8.8. Registering and Deleting Mapper and Publisher Plug-in Modules
9. Authentication for Enrolling Certificates
9.1. Configuring Agent-Approved Enrollment
9.2. Automated Enrollment
9.2.1. Setting up Directory-Based Authentication
9.2.2. Setting up PIN-Based Enrollment
9.2.3. Using Certificate-Based Authentication
9.2.4. Configuring Flat File Authentication
9.3. Setting up CMC Enrollment
9.3.1. Setting up the Server for Multiple Requests in a Full CMC Request
9.3.2. Testing CMCEnroll
9.4. Testing Enrollment
9.5. Managing Authentication Plug-ins
10. Using Automated Notifications
10.1. About Automated Notifications for the CA
10.1.1. Types of Automated Notifications
10.1.2. Determining End-Entity Email Addresses
10.1.3. About RA Notifications
10.2. Setting up Automated Notifications for the CA
10.2.1. Setting up Automated Notifications in the Console
10.2.2. Configuring Specific Notifications by Editing the CS.cfg File
10.2.3. Testing Configuration
10.3. Customizing Notification Messages
10.3.1. Customizing CA Notification Messages
10.3.2. Customizing RA Notification Messages
10.4. Configuring a Mail Server for Certificate System Notifications
10.5. Creating Custom Notifications for the CA
11. Setting Automated Jobs
11.1. About Automated Jobs
11.1.1. Setting up Automated Jobs
11.1.2. Types of Automated Jobs
11.2. Setting up the Job Scheduler
11.3. Setting up Specific Jobs
11.3.1. Configuring Specific Jobs Using the Certificate Manager Console
11.3.2. Configuring Jobs by Editing the Configuration File
11.3.3. Configuration Parameters of certRenewalNotifier
11.3.4. Configuration Parameters of requestInQueueNotifier
11.3.5. Configuration Parameters of publishCerts
11.3.6. Configuration Parameters of unpublishExpiredCerts
11.3.7. Frequency Settings for Automated Jobs
11.4. Registering or Deleting a Job Module
III. Managing the Subsystem Instances
12. Editing Configuration in the CS.cfg File
12.1. Default File and Directory Locations for Certificate System Subsystems
12.1.1. Default CA Instance Information
12.1.2. Default RA Instance Information
12.1.3. Default DRM Instance Information
12.1.4. Default OCSP Instance Information
12.1.5. Default TKS Instance Information
12.1.6. Default TPS Instance Information
12.1.7. Shared Certificate System Subsystem File Locations
12.2. CS.cfg Files
12.2.1. Locating the CS.cfg File
12.2.2. Overview of the CS.cfg Configuration File
12.2.3. Editing the Configuration File
12.3. System Passwords
12.3.1. Configuring the password.conf
12.3.2. Protecting the password.conf File
12.3.3. Requiring System Password Prompts
12.3.4. Changing System Passwords
12.3.5. Password-Quality Checker
12.4. Configuration Files for Web Services
13. Basic Subsystem Management
13.1. Starting and Stopping Subsystem Instances
13.1.1. Starting and Stopping a Subsystem Server Instance
13.1.2. Restarting a Subsystem after a Machine Restart
13.1.3. Checking the Subsystem Instance Status
13.1.4. Managing Subsystem Processes with chkconfig
13.2. Opening Subsystem Consoles and Services
13.2.1. Finding the Subsystem Web Services Pages
13.2.2. Starting the Certificate System Administrative Console
13.3. Customizing Web Services Pages
13.3.1. Customizing CA End-Entities Pages
13.3.2. Customizing RA End-Entities Pages
13.3.3. Setting Limits on Searches through the CA End-Entities Pages
13.4. Configuring Ports
13.4.1. Changing a Port Number
13.4.2. Using a Single SSL Port
13.4.3. Updating Existing CAs to Use End-Entity Client Authentication Ports (Avoiding TLS-Related Man-in-the-Middle Attacks)
13.5. Configuring the LDAP Database
13.5.1. Changing the Internal Database Configuration
13.5.2. Enabling SSL Client Authentication with the Internal Database
13.5.3. Restricting Access to the Internal Database
13.6. Searching the SQLite Database
13.7. Viewing Security Domain Configuration
13.8. Managing the SELinux Policies for Subsystems
13.8.1. About SELinux
13.8.2. Viewing SELinux Policies for Subsystems
13.9. Backing up and Restoring Certificate System
13.10. Self-Tests
13.10.1. Self-Test Logging
13.10.2. Configuring Self-Tests
13.10.3. Modifying Self-Test Configuration
14. Managing Certificate System Users and Groups
14.1. About Authorization
14.2. Default Groups
14.2.1. Administrators
14.2.2. Auditors
14.2.3. Agents
14.2.4. Enterprise Groups
14.3. Managing Users and Groups for a CA, OCSP, DRM, or TKS
14.3.1. Managing Groups
14.3.2. Managing Users
14.4. Creating and Managing Users and Groups for an RA
14.4.1. Managing RA Groups
14.4.2. Managing RA Users
14.5. Creating and Managing Users for a TPS
14.5.1. Searching for Users
14.5.2. Adding Users
14.5.3. Setting Profiles for Users
14.5.4. Changing Roles for Users
14.5.5. Renewing TPS Agent and Administrator Certificates
14.5.6. Deleting Users
14.6. Configuring Access Control for Users for the CA, OCSP, DRM, and TKS
14.6.1. About Access Control
14.6.2. Editing ACLs
15. Configuring Subsystem Logs
15.1. An Overview of Log Settings
15.1.1. Services That Are Logged
15.1.2. Log Levels (Message Categories)
15.1.3. Buffered and Unbuffered Logging
15.1.4. Log File Rotation
15.2. Certificate System Logs
15.2.1. System Log
15.2.2. Transactions Log
15.2.3. Debug Logs
15.2.4. Error Log
15.2.5. Installation Logs
15.2.6. Apache and Tomcat Error and Access Logs
15.2.7. Self-Tests Log
15.3. Configuring Logs Using the UI
15.3.1. Configuring Logs in the Console (for the CA, OCSP, DRM, and TKS)
15.3.2. Configuring TPS Audit Logs in the Admin Services Page
15.4. Configuring Logs in the CS.cfg File
15.4.1. Configuring Logs in the CS.cfg File for the CA, OCSP, DRM, and TKS
15.4.2. Configuring RA Logging
15.4.3. Configuring TPS Logging
15.5. Managing Signed Audit Logs
15.5.1. Configuring a Signed Audit Log for a CA, OCSP, DRM, or TKS
15.5.2. Configuring TPS Signed Audit Logging
15.5.3. Handling Audit Logging Failures
15.5.4. Signing Log Files
15.6. Viewing Logs
15.7. Smart Card Error Codes
15.8. Managing Log Modules
15.8.1. Registering a Log Module
15.8.2. Deleting a Log Module
16. Managing Subsystem Certificates
16.1. Required Subsystem Certificates
16.1.1. Certificate Manager Certificates
16.1.2. RA Certificates
16.1.3. Online Certificate Status Manager Certificates
16.1.4. Data Recovery Manager Certificates
16.1.5. TKS Certificates
16.1.6. TPS Certificates
16.1.7. Using an HSM to Store Subsystem Certificates
16.2. Requesting a Subsystem, Server, or Signing Certificate through the Console
16.3. Renewing Subsystem Certificates
16.4. Using Cross-Pair Certificates
16.4.1. Installing Cross-Pair Certificates
16.4.2. Searching for Cross-Pair Certificates
16.5. Managing the Certificate Database
16.5.1. Installing Certificates in the Certificate System Database
16.5.2. Viewing Database Content
16.5.3. Deleting Certificates from the Database
16.6. Changing the Trust Settings of a CA Certificate
16.6.1. Changing Trust Settings through the Console
16.6.2. Changing Trust Settings Using certutil
16.7. Managing Tokens Used by the Subsystems
16.7.1. Detecting Tokens
16.7.2. Viewing Tokens
16.7.3. Changing a Token's Password
IV. References
A. Certificate Profile Input and Output Reference
A.1. Input Reference
A.1.1. Certificate Request Input
A.1.2. CMC Certificate Request Input
A.1.3. Dual Key Generation Input
A.1.4. File-Signing Input
A.1.5. Image Input
A.1.6. Key Generation Input
A.1.7. nsHKeyCertRequest (Token Key) Input
A.1.8. nsNKeyCertRequest (Token User Key) Input
A.1.9. Serial Number Renewal Input
A.1.10. Subject DN Input
A.1.11. Subject Name Input
A.1.12. Submitter Information Input
A.2. Output Reference
A.2.1. Certificate Output
A.2.2. PKCS #7 Output
A.2.3. CMMF Output
B. Defaults, Constraints, and Extensions for Certificates and CRLs
B.1. Defaults Reference
B.1.1. Authority Info Access Extension Default
B.1.2. Authority Key Identifier Extension Default
B.1.3. Basic Constraints Extension Default
B.1.4. CRL Distribution Points Extension Default
B.1.5. Extended Key Usage Extension Default
B.1.6. Freshest CRL Extension Default
B.1.7. Issuer Alternative Name Extension Default
B.1.8. Key Usage Extension Default
B.1.9. Name Constraints Extension Default
B.1.10. Netscape Certificate Type Extension Default
B.1.11. Netscape Comment Extension Default
B.1.12. No Default Extension
B.1.13. OCSP No Check Extension Default
B.1.14. Policy Constraints Extension Default
B.1.15. Policy Mappers Extension Default
B.1.16. Signing Algorithm Default
B.1.17. Subject Alternative Name Extension Default
B.1.18. Subject Directory Attributes Extension Default
B.1.19. Subject Key Identifier Extension Default
B.1.20. Subject Name Default
B.1.21. Token Supplied Subject Name Default
B.1.22. User Supplied Extension Default
B.1.23. User Key Default
B.1.24. User Signing Algorithm Default
B.1.25. User Subject Name Default
B.1.26. User Validity Default
B.1.27. Validity Default
B.2. Constraints Reference
B.2.1. Basic Constraints Extension Constraint
B.2.2. Extended Key Usage Extension Constraint
B.2.3. Extension Constraint
B.2.4. Key Constraint
B.2.5. Key Usage Extension Constraint
B.2.6. No Constraint
B.2.7. Netscape Certificate Type Extension Constraint
B.2.8. Renewal Grace Period Constraint
B.2.9. Signing Algorithm Constraint
B.2.10. Subject Name Constraint
B.2.11. Unique Subject Name Constraint
B.2.12. Validity Constraint
B.3. Standard X.509 v3 Certificate Extension Reference
B.3.1. authorityInfoAccess
B.3.2. authorityKeyIdentifier
B.3.3. basicConstraints
B.3.4. certificatePoliciesExt
B.3.5. CRLDistributionPoints
B.3.6. extKeyUsage
B.3.7. issuerAltName Extension
B.3.8. keyUsage
B.3.9. nameConstraints
B.3.10. OCSPNocheck
B.3.11. policyConstraints
B.3.12. policyMappings
B.3.13. privateKeyUsagePeriod
B.3.14. subjectAltName
B.3.15. subjectDirectoryAttributes
B.3.16. subjectKeyIdentifier
B.4. CRL Extensions
B.4.1. About CRL Extensions
B.4.2. Standard X.509 v3 CRL Extensions Reference
B.4.3. Netscape-Defined Certificate Extensions Reference
C. Publishing Module Reference
C.1. Publisher Plug-in Modules
C.1.1. FileBasedPublisher
C.1.2. LdapCaCertPublisher
C.1.3. LdapUserCertPublisher
C.1.4. LdapCrlPublisher
C.1.5. LdapDeltaCrlPublisher
C.1.6. LdapCertificatePairPublisher
C.1.7. OCSPPublisher
C.2. Mapper Plug-in Modules
C.2.1. LdapCaSimpleMap
C.2.2. LdapDNExactMap
C.2.3. LdapSimpleMap
C.2.4. LdapSubjAttrMap
C.2.5. LdapDNCompsMap
C.3. Rule Instances
C.3.1. LdapCaCertRule
C.3.2. LdapXCertRule
C.3.3. LdapUserCertRule
C.3.4. LdapCRLRule
D. ACL Reference
D.1. About ACL Configuration Files
D.2. Common ACLs
D.2.1. certServer.acl.configuration
D.2.2. certServer.admin.certificate
D.2.3. certServer.admin.request.enrollment
D.2.4. certServer.auth.configuration
D.2.5. certServer.clone.configuration
D.2.6. certServer.general.configuration
D.2.7. certServer.log.configuration
D.2.8. certServer.log.configuration.fileName
D.2.9. certServer.log.configuration.signedAudit.expirationTime
D.2.10. certServer.log.content
D.2.11. certServer.log.content.signedAudit
D.2.12. certServer.registry.configuration
D.2.13. certServer.usrgrp.administration
D.3. Certificate Manager-Specific ACLs
D.3.1. certServer.admin.ocsp
D.3.2. certServer.ca.certificate
D.3.3. certServer.ca.certificates
D.3.4. certServer.ca.clone
D.3.5. certServer.ca.configuration
D.3.6. certServer.ca.connector
D.3.7. certServer.ca.connectorInfo
D.3.8. certServer.ca.crl
D.3.9. certServer.ca.directory
D.3.10. certServer.ca.group
D.3.11. certServer.ca.ocsp
D.3.12. certServer.ca.profile
D.3.13. certServer.ca.profiles
D.3.14. certServer.ca.registerUser
D.3.15. certServer.ca.request.enrollment
D.3.16. certServer.ca.request.profile
D.3.17. certServer.ca.requests
D.3.18. certServer.ca.systemstatus
D.3.19. certServer.ee.certchain
D.3.20. certServer.ee.certificate
D.3.21. certServer.ee.certificates
D.3.22. certServer.ee.crl
D.3.23. certServer.ee.profile
D.3.24. certServer.ee.profiles
D.3.25. certServer.ee.request.enrollment
D.3.26. certServer.ee.request.ocsp
D.3.27. certServer.ee.request.revocation
D.3.28. certServer.ee.requestStatus
D.3.29. certServer.job.configuration
D.3.30. certServer.kra.configuration
D.3.31. certServer.ocsp.configuration
D.3.32. certServer.policy.configuration
D.3.33. certServer.profile.configuration
D.3.34. certServer.publisher.configuration
D.3.35. certServer.ra.configuration
D.3.36. certServer.securitydomain.domainxml
D.4. Data Recovery Manager-Specific ACLs
D.4.1. certServer.job.configuration
D.4.2. certServer.kra.certificate.transport
D.4.3. certServer.kra.configuration
D.4.4. certServer.kra.connector
D.4.5. certServer.kra.GenerateKeyPair
D.4.6. certServer.kra.getTransportCert
D.4.7. certServer.kra.group
D.4.8. certServer.kra.key
D.4.9. certServer.kra.keys
D.4.10. certServer.kra.registerUser
D.4.11. certServer.kra.request
D.4.12. certServer.kra.request.status
D.4.13. certServer.kra.requests
D.4.14. certServer.kra.systemstatus
D.4.15. certServer.kra.TokenKeyRecovery
D.5. Online Certificate Status Manager-Specific ACLs
D.5.1. certServer.ca.ocsp
D.5.2. certServer.ee.crl
D.5.3. certServer.ee.request.ocsp
D.5.4. certServer.ocsp.ca
D.5.5. certServer.ocsp.cas
D.5.6. certServer.ocsp.certificate
D.5.7. certServer.ocsp.configuration
D.5.8. certServer.ocsp.crl
D.5.9. certServer.ocsp.group
D.5.10. certServer.ocsp.info
D.5.11. certServer.ocsp.systemstatus
D.6. Token Key Service-Specific ACLs
D.6.1. certServer.tks.encrypteddata
D.6.2. certServer.tks.group
D.6.3. certServer.tks.importTransportCert
D.6.4. certServer.tks.keysetdata
D.6.5. certServer.tks.registerUser
D.6.6. certServer.tks.sessionkey
D.6.7. certServer.tks.systemstatus
Glossary
Index

About This Guide

This guide explains how to install, configure, and maintain the Red Hat Certificate System and how to use it for issuing and managing certificates to end entities such as web browsers, users, servers, and virtual private network (VPN) clients.
This guide is intended for experienced system administrators planning to deploy the Certificate System. Certificate System agents should refer to the Certificate System Agent's Guide for information on how to perform agent tasks, such as handling certificate requests and revoking certificates.

1. Recommended Concepts

Before reading this guide, be familiar with the following concepts:
  • Intranet, extranet, and Internet security and the role of digital certificates in a secure enterprise, including the following topics:
    • Encryption and decryption
    • Public keys, private keys, and symmetric keys
    • Significance of key lengths
    • Digital signatures
    • Digital certificates, including different types of digital certificates
    • The role of digital certificates in a public-key infrastructure (PKI)
    • Certificate hierarchies
  • LDAP and Red Hat Directory Server
  • Public-key cryptography and the Secure Sockets Layer (SSL) protocol, including the following:
    • SSL cipher suites
    • The purpose of and major steps in the SSL handshake

2. What Is in This Guide

Administering certificates relates to the setup and configuration of the individual subsystems, the processes for issuing certificates, and the ways certificates are stored (in software databases or in tokens). This administration guide, then, is divided into several functional areas, listed in Table 1, “Content Overview”.

3. Supported Platforms, Hardware, and Programs

3.1. Supported Platforms

The Certificate System subsystems (CA, RA, DRM, OCSP, RA, TKS, and TPS) are supported on the following platforms:
  • Red Hat Enterprise Linux 5.3 (x86, 32-bit)
  • Red Hat Enterprise Linux 5.3 (x86_64, 64-bit)
The Enterprise Security Client, which manages smart cards for end users, is supported on the following platforms:
  • Red Hat Enterprise Linux 5.3 (x86, 32-bit)
  • Red Hat Enterprise Linux 5.3 (x86_64, 64-bit)
  • Microsoft Windows Vista 32-bit
  • Microsoft Windows Vista 64-bit
  • Microsoft Windows XP 32-bit
  • Microsoft Windows XP 64-bit
  • Apple Mac OS X 10.5.8 and higher (Leopard)

3.2. Supported Web Browsers

The services pages for the subsystems require a web browser that supports SSL. It is strongly recommended that users such as agents or administrators use Mozilla Firefox to access the agent services pages. Regular users should use Mozilla Firefox or Microsoft Internet Explorer.

NOTE

The only browser that is fully-supported for the HTML-based instance configuration wizard is Mozilla Firefox.

Table 2. Supported Web Browsers by Platform

Platform Agent Services End User Pages
Red Hat Enterprise Linux Firefox 3.x Firefox 3.x
Windows Vista Firefox 2.x
Firefox 2.x
Internet Explorer 7 and higher
Windows XP Firefox 2.x
Firefox 2.x
Internet Explorer 6.0 and and higher
Mac OS 10.5.8 and higher Agent services are not supported for Mac Firefox 2.x

3.3. Supported Smart Cards

The Enterprise Security Client supports Global Platform 2.01-compliant smart cards and JavaCard 2.1 or higher.
The Certificate System subsystems have been tested using the following tokens:
  • Gemalto TOP IM FIPS CY2 64K token, both as a smart card and GemPCKey USB form factor key
  • Gemalto Cyberflex e-gate 32K token
  • Safenet 330J Java smart card
Smart card testing was conducted using the SCM SCR331 CCID reader.
The only card manager applet supported with Certificate System is the CoolKey applet which ships with Red Hat Enterprise Linux 5.3.

3.4. Supported HSM

Red Hat Certificate System supports two hardware security modules (HSM), Safenet Chrysalis-ITS LunaSA and nCipher netHSM 2000.
HSM Firmware Appliance Software Client Software
Safenet Chrysalis-ITS LunaSA 4.5.2 3.2.4 3.2.4
nCipher netHSM 2000 2.33.60 11.10

3.5. Supported Charactersets

Red Hat Certificate System fully supports UTF-8 characters in the CA end users forms for specific fields. This means that end users can submit certificate requests with UTF-8 characters in those fields and can search for and retrieve certificates and CRLs in the CA and retrieve keys in the DRM when using those field values as the search parameters.
Four fields fully-support UTF-8 characters:
  • Common name (used in the subject name of the certificate)
  • Organizational unit (used in the subject name of the certificate)
  • Requester name
  • Additional notes (comments appended by the agent to the certificate)

NOTE

This support does not include supporting internationalized domain names, like in email addresses.

4. Examples and Formatting

Each of the examples used in this guide, such as file locations and commands, have certain defined conventions.

4.1. Formatting for Examples and Commands

All of the examples for Red Hat Certificate System commands, file locations, and other usage are given for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands and files for your platform.

Example 1. Example Command

To start the Red Hat Certificate System:
service pki-ca start

4.2. Tool Locations

All of the tools for Red Hat Certificate System are located in the /usr/bin directory. These tools can be run from any location without specifying the tool location.

4.3. Guide Formatting

Certain words are represented in different fonts, styles, and weights. Different character formatting is used to indicate the function or purpose of the phrase being highlighted.
Formatting Style Purpose
Monospace font Monospace is used for commands, package names, files and directory paths, and any text displayed in a prompt.
Monospace 
with a
background
This type of formatting is used for anything entered or returned in a command prompt.
Italicized text Any text which is italicized is a variable, such as instance_name or hostname. Occasionally, this is also used to emphasize a new term or other phrase.
Bolded text Most phrases which are in bold are application names, such as Cygwin, or are fields or options in a user interface, such as a User Name Here: field or Save button.
Other formatting styles draw attention to important text.

NOTE

A note provides additional information that can help illustrate the behavior of the system or provide more detail for a specific issue.

IMPORTANT

Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.

WARNING

A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.

5. Additional Reading

The documentation for Certificate System includes the following guides:
  • Certificate System Deployment Guide describes basic PKI concepts and gives an overview of the planning process for setting up Certificate System.
    This manual is intended for Certificate System administrators.
  • Certificate System Installation Guide covers the installation process for all Certificate System subsystems.
    This manual is intended for Certificate System administrators.
  • Certificate System Administrator's Guide explains all administrative functions for the Certificate System. Administrators maintain the subsystems themselves, so this manual details backend configuration for certificate profiles, publishing, and issuing certificates and CRLs. It also covers managing subsystem settings like port numbers, users, and subsystem certificates.
    This manual is intended for Certificate System administrators.
  • Certificate System Agent's Guide describes how agents — users responsible for processing certificate requests and managing other aspects of certificate management — can use the Certificate System subsystems web services pages to process certificate requests, key recovery, OCSP requests and CRLs, and other functions.
    This manual is intended for Certificate System agents.
  • Managing Smart Cards with the Enterprise Security Client explains how to install, configure, and use the Enterprise Security Client, the user client application for managing smart cards, user certificates, and user keys.
    This manual is intended for Certificate System administrators, agents, privileged users (such as security officers), and regular end users.
  • Using End User Services is a quick overview of the end-user services in Certificate System, a simple way for users to learn how to access Certificate System services.
    This manual is intended for regular end users.
  • Certificate System Command-Line Tools Guide covers the command-line scripts supplied with Red Hat Certificate System.
    This manual is intended for Certificate System administrators.
  • Certificate System Migration Guide covers version-specific procedures for migrating from older versions of Certificate System to Red Hat Certificate System 8.0.
    This manual is intended for Certificate System administrators.
  • Release Notes contains important information on new features, fixed bugs, known issues and workarounds, and other important deployment information for Red Hat Certificate System 8.0.
All of the latest information about Red Hat Certificate System and both current and archived documentation is available at http://www.redhat.com/docs/manuals/cert-system/.

6. Giving Feedback

If there is any error in this Administrator's Guide or there is any way to improve the documentation, please let us know. Bugs can be filed against the documentation for Red Hat Certificate System through Bugzilla. Make the bug report as specific as possible, so we can be more effective in correcting any issues:
  • Select the Red Hat Certificate System product.
  • Set the component to Doc - administration-guide.
  • Set the version number to 8.0.
  • For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct description of the problem, such as incorrect procedure or typo.
    For enhancements, put in what information needs to be added and why.
  • Give a clear title for the bug. For example, "Incorrect command example for setup script options" is better than "Bad example".
We appreciate receiving any feedback — requests for new sections, corrections, improvements, enhancements, even new ways of delivering the documentation or new styles of docs. You are welcome to contact Red Hat Content Services directly at docs@redhat.com.

7. Document History

Revision History
Revision 8.0.22-1.0.2.33.4002013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 8.0.22-1.0.2.33July 24 2012Ruediger Landmann
Rebuild for Publican 3.0
Revision 8.0.21-0January 6, 2011Ella Deon Lackey
Updating the bulk issuance procedure, per Bugzilla #662185.
Fixing typos, Bugzilla 662856.
Revision 8.0.20-0December 12, 2010Ella Deon Lackey
Removing all references to bulk issuance, per Bugzilla #662185.
Revision 8.0.19-0November 12, 2010Ella Deon Lackey, Lee Carlon
Adding new SCEP configuration parameters, per Errata RHSA-2010:0838.
Updating the serial number example, per Bugzilla #648944.
Revision 8.0.18-0September 16, 2010Ella Deon Lackey
Adding information on setting token transitions, per Errata RHBA-2010:0701.
Adding section on how to customize subject DNs for CSRs that can be processed in Internet Explorer, per Bugzilla #576302.
Removing an erroneous reference to a path to a base-64 file for configuring the OtherName element in an extension, per Bugzilla #629774.
Changing into which database a renewed user cert should be imported, per Bugzilla #630187.
Revision 8.0.17-0June 1, 2010Ella Deon Lackey
Adding back Mac support, on a new platform (10.5.8), per Errata RHBA-2010:0448.
Revision 8.0.16-0March 25, 2010Ella Deon Lackey
Adding information on new end-entities client authentication port for the CA, related to the MitM resolution in Errata RHBA-2010:0169.
Revision 8.0.15-0December 16, 2009Ella Deon Lackey
Adding section on removing password.conf and promoting for passwords, per Errata RHBA-2009:1665.
Updating supported platforms for Enterprise Security Client, per Errata RHBA-2009:1673.
Revision 8.0.14-0November 25, 2009Ella Deon Lackey
Adding the OCSP configuration section for the TKS and DRM subsystems, per Errata RHBA-2009:1602.
Revision 8.0.13-0November 19, 2009Ella Deon Lackey
Updating the OCSP configuration section for the TPS and RA subsystems, per updates from Errata RHBA-2009:1596.
Revision 8.0.12-0November 13, 2009Ella Deon Lackey
Correcting CRL scheduling screenshot, so it matches the text example.
Revision 8.0.11-0October 13, 2009Ella Deon Lackey
Tech edits to the TPS configuration chapter from Jack Magne, per Bugzilla #510610.
Revision 8.0.10-0September 30, 2009Ella Deon  Lackey
Tech edits to the TPS configuration chapter, per Bugzilla #510610.
Revision 8.0.9-0September 9, 2009Ella Deon  Lackey
Updating chapter 4 on managing certificates for the tech review, per Bugzilla #510988.
Tech edits to the ACL reference, per Bugzilla #510613.
Revision 8.0.8-0August 28, 2009Ella Deon  Lackey
Tech edits to the publishing and authentication chapters, per Bugzilla #510607 and #510622.
Revision 8.0.7-0August 26, 2009Ella Deon  Lackey
Added a section on setting search result limits for the web services pages, as indicated in Bugzilla #482935.
Revision 8.0.6-0August 22, 2009Ella Deon  Lackey
Adding a section on customizing end-entities pages per recommended changes in the agents' guide tech reviews.
Editing the notifications chapter to include information on RA notifications.
Adding information on retrieving CRLs and partial CRLs using wget, per the tech reviews in Bugzilla #510618.
Removing appendix D, pending appropriate tech review updates.
Revision 8.0.5-0August 19, 2009Ella Deon  Lackey
Adding back in the book index.
Revision 8.0.4-0August 18, 2009Ella Deon  Lackey
Removing the section on SSL/client authentication for the console, related to Bugzilla #512493.
Fixing section outline formatting for log chapter.
Revision 8.0.3-0August 12, 2009Ella Deon  Lackey
Adding parameters for configuring audit logging and signed audit logging for the TPS, per Bugzilla #502122.
Continuing tech edits, covering chapters 12, 13, 14, 15, and 16, relating to Bugzilla #511285, #510617, #510990, #510991, and #510987.
Revision 8.0.2-0August 7, 2009Ella Deon  Lackey
Beginning tech edits, covering chapters 1, 2, 3, 7, 10, and 11 and appendices A and B, according to Bugzilla #510614, #510615, #510625, #510602, #510604, #510616, #510623, and #510621.
Some edits to the subsystems overview chapter based on tech edits for the deployment guide, such as Bugzilla #510597.
Revision 8.0.1-0August 4, 2009Ella Deon  Lackey
Adding note to the TPS users section about setting "all profiles" access for administrators, per Bugzilla #484275.
Fixing typo in the op.format.tokenKey.ca.conn parameter example, per comment #5 in Bugzilla #457294.
Adding tip about certutil and clarifying the renewal profile to use for cert-based authentication.
Revision 8.0.0-0July 22, 2009Ella Deon  Lackey
Initial draft for Certificate System 1 Administrator's Guide.

Chapter 1. Overview of Red Hat Certificate System Subsystems

Every common PKI operation — issuing, renewing and revoking certificates; archiving and recovering keys; publishing CRLs and verifying certificate status — are carried out by interoperating subsystems within Red Hat Certificate System. The functions of each individual subsystem and the way that they work together to establish a robust and local PKI is described in this chapter.

1.1. How Certificates Are Used

Certificates have a purpose: to establish trust. Their usage varies depending on the kind of trust they are used to ensure. Some kinds of certificates are used to verify the identity of the presenter; others are used to verify that an object or item has not been tampered with.
The way that certificates establish identities and relationships and the processes that use certificates are described in more detail in the overview of public-key cryptography in the Red Hat Certificate System Deployment Guide.

1.1.1. Uses for Certificates

1.1.1.1. SSL

The Secure Sockets Layer (SSL) protocol governs server authentication, client authentication, and encrypted communication between servers and clients. SSL is widely used on the Internet, especially for interactions that involve exchanging confidential information such as credit card numbers.
SSL requires an SSL server certificate. As part of the initial SSL handshake, the server presents its certificate to the client to authenticate the server's identity. The authentication uses public-key encryption and digital signatures to confirm that the server is the server it claims to be. Once the server has been authenticated, the client and server use symmetric-key encryption, which is very fast, to encrypt all the information exchanged for the remainder of the session and to detect any tampering.
Servers may be configured to require client authentication as well as server authentication. In this case, after server authentication is successfully completed, the client must also present its certificate to the server to authenticate the client's identity before the encrypted SSL session can be established.

1.1.1.2. Signed and Encrypted Email

Some email programs support digitally signed and encrypted email using a widely accepted protocol known as Secure Multipurpose Internet Mail Extension (S/MIME). Using S/MIME to sign or encrypt email messages requires the sender of the message to have an S/MIME certificate.
An email message that includes a digital signature provides some assurance that it was sent by the person whose name appears in the message header, thus authenticating the sender. If the digital signature cannot be validated by the email software, the user is alerted.
The digital signature is unique to the message it accompanies. If the message received differs in any way from the message that was sent, even by adding or deleting a single character, the digital signature cannot be validated. Therefore, signed email also provides assurance that the email has not been tampered with. This kind of assurance is known as nonrepudiation, which makes it difficult for the sender to deny having sent the message. This is important for business communication.
S/MIME also makes it possible to encrypt email messages, which is important for some business users. However, using encryption for email requires careful planning. If the recipient of encrypted email messages loses the private key and does not have access to a backup copy of the key, the encrypted messages can never be decrypted.

1.1.1.3. Single Sign-on

Network users are frequently required to remember multiple passwords for the various services they use. For example, a user might have to type a different password to log into the network, collect email, use directory services, use the corporate calendar program, and access various servers. Multiple passwords are an ongoing headache for both users and system administrators. Users have difficulty keeping track of different passwords, tend to choose poor ones, and tend to write them down in obvious places. Administrators must keep track of a separate password database on each server and deal with potential security problems related to the fact that passwords are sent over the network routinely and frequently.
Solving this problem requires some way for a user to log in once, using a single password, and get authenticated access to all network resources that user is authorized to use-without sending any passwords over the network. This capability is known as single sign-on.
Both client SSL certificates and S/MIME certificates can play a significant role in a comprehensive single sign-on solution. For example, one form of single sign-on supported by Red Hat products relies on SSL client authentication. A user can log in once, using a single password to the local client's private-key database, and get authenticated access to all SSL-enabled servers that user is authorized to use-without sending any passwords over the network. This approach simplifies access for users, because they don't need to enter passwords for each new server. It also simplifies network management, since administrators can control access by controlling lists of certificate authorities (CAs) rather than much longer lists of users and passwords.
In addition to using certificates, a complete single-sign on solution must address the need to interoperate with enterprise systems, such as the underlying operating system, that rely on passwords or other forms of authentication.

1.1.1.4. Object Signing

Many software technologies support a set of tools called object signing. Object signing uses standard techniques of public-key cryptography to let users get reliable information about code they download in much the same way they can get reliable information about shrink-wrapped software.
Most important, object signing helps users and network administrators implement decisions about software distributed over intranets or the Internet-for example, whether to allow Java applets signed by a given entity to use specific computer capabilities on specific users' machines.
The objects signed with object signing technology can be applets or other Java code, JavaScript scripts, plug-ins, or any kind of file. The signature is a digital signature. Signed objects and their signatures are typically stored in a special file called a JAR file.
Software developers and others who wish to sign files using object-signing technology must first obtain an object-signing certificate.

1.1.2. Types of Certificates

The Certificate System is capable of generating different types of certificates for different uses and in different formats. Planning which certificates are required and planning how to manage them, including determining what formats are needed and how to plan for renewal, are important to manage both the PKI and the Certificate System instances.
This list is not exhaustive; there are certificate enrollment forms for dual-use certificates for LDAP directories, file-signing certificates, and other subsystem certificates. These forms are available through the Certificate Manager's end-entities page, at https://server.example.com:9444/ca/ee/ca. For more detailed information about the different certificates that can be created, see the Certificate System Agent's Guide.
When the different Certificate System subsystems are installed, the basic required certificates and keys are generated; for example, configuring the Certificate Manager generates the CA signing certificate for the self-signed root CA, the internal OCSP signing certificate, and the SSL server certificate and agent user certificate. Configuring the DRM generates the storage, transport, and agent certificates. Additional certificates can be created and installed separately.

Table 1.1. Common Certificates

Certificate Type Use Example
Client SSL certificates Used for client authentication to servers over SSL. Typically, the identity of the client is assumed to be the same as the identity of a person, such as an employee. Client SSL certificates can also be used as part of single sign-on.
A bank gives a customer an SSL client certificate that allows the bank's servers to identify that customer and authorize access to the customer's accounts.
A company gives a new employee an SSL client certificate that allows the company's servers to identify that employee and authorize access to the company's servers.
Server SSL certificates Used for server authentication to clients over SSL. Server authentication may be used without client authentication. Server authentication is required for an encrypted SSL session. For more information, see Section 1.1.1.1, “SSL”. Internet sites that engage in electronic commerce usually support certificate-based server authentication to establish an encrypted SSL session and to assure customers that they are dealing with the web site identified with the company. The encrypted SSL session ensures that personal information sent over the network, such as credit card numbers, cannot easily be intercepted.
S/MIME certificates Used for signed and encrypted email. As with SSL client certificates, the identity of the client is assumed to be the same as the identity of a person, such as an employee. A single certificate may be used as both an S/MIME certificate and an SSL certificate. S/MIME certificates can also be used as part of single sign-on. A company deploys combined S/MIME and SSL certificates solely to authenticate employee identities, thus permitting signed email and SSL client authentication but not encrypted email. Another company issues S/MIME certificates solely to sign and encrypt email that deals with sensitive financial or legal matters.
CA certificates Used to identify CAs. Client and server software use CA certificates to determine what other certificates can be trusted. The CA certificates stored in Mozilla Firefox determine what other certificates can be authenticated. An administrator can implement corporate security policies by controlling the CA certificates stored in each user's copy of Firefox.
Object-signing certificates Used to identify signers of Java code, JavaScript scripts, or other signed files. Software companies frequently sign software distributed over the Internet to provide users with some assurance that the software is a legitimate product of that company. Using certificates and digital signatures can also make it possible for users to identify and control the kind of access downloaded software has to their computers.

1.1.2.1. CA Signing Certificates

Every Certificate Manager has a CA signing certificate with a public/private key pair it uses to sign the certificates and CRLs it issues. This certificate is created and installed when the Certificate Manager is installed.
The Certificate Manager's status as a root or subordinate CA is determined by whether its CA signing certificate is self-signed or is signed by another CA. Self-signed root CAs set the policies they use to issue certificates, such as the subject names, types of certificates that can be issued, and to whom certificates can be issued. A subordinate CA has a CA signing certificate signed by another CA, usually the one that is a level above in the CA hierarchy (which may or may not be a root CA). If the Certificate Manager is a subordinate CA in a CA hierarchy, the root CA's signing certificate must be imported into individual clients and servers before the Certificate Manager can be used to issue certificates to them.
The CA certificate must be installed in a client if a server or user certificate issued by that CA is installed on that client. The CA certificate confirms that the server certificate can be trusted. Ideally, the certificate chain is installed.

1.1.2.2. Other Signing Certificates

Other services, such as the OCSP responder service and CRL publishing, can use signing certificates other than the CA certificate. For example, a separate CRL signing certificate can be used to sign the revocation lists that are published by a CA instead of using the CA signing certificate.

1.1.2.3. SSL Server and Client Certificates

Server certificates are used for secure communications, such as SSL, and other secure functions. Server certificates are used to authenticate themselves during operations and to encrypt data; client certificates authenticate the client to the server.

NOTE

CAs which have a signing certificate issued by a third-party may not be able to issue server certificates. The third-party CA may have rules in place which prohibit its subordinates from issuing server certificates.

1.1.2.4. User Certificates

End user certificates are a subset of client certificates that are used to identify users to a server or system. Users can be assigned certificates to use for secure communications, such as SSL, and other functions such as encrypting email or for single sign-on. Special users, such as Certificate System agents, can be given client certificates to access special services.

1.1.2.5. Dual-Key Pairs

Dual-key pairs are a set of two private and public keys, where one set is used for signing and one for encryption. These dual keys are used to create dual certificates. The dual certificate enrollment form is one of the standard forms listed in the end-entities page of the Certificate Manager.
When generating dual-key pairs, set the certificate profiles to work correctly when generating separate certificates for signing and encryption.

1.1.2.6. Cross-Pair Certificates

The Certificate System can issue, import, and publish cross-pair CA certificates. With cross-pair certificates, one CA signs and issues a cross-pair certificate to a second CA, and the second CA signs and issues a cross-pair certificate to the first CA. Both CAs then store or publish both certificates as a crossCertificatePair entry.
Bridging certificates can be done to honor certificates issued by a CA that is not chained to the root CA. By establishing a trust between the Certificate System CA and another CA through a cross-pair CA certificate, the cross-pair certificate can be downloaded and used to trust the certificates issued by the other CA.

1.2. A Review of Certificate System Subsystems

Red Hat Certificate System provides six different subsystems, each focusing on different aspects of a PKI deployment:
  • A certificate authority called a Certificate Manager. The CA is the core of the PKI; it issues and revokes all certificates. The Certificate Manager is also the core of the Certificate System. By establishing a security domain of trusted subsystems, it establishes and manages relationships between the other subsystems.
  • A key recovery authority called a data recovery manager (DRM). Certificates are created based on a specific and unique key pair. If a private key is ever lost, then the data which that key was used to access (such as encrypted emails) is also lost because it is inaccessible. The DRM stores key pairs, so that a new, identical certificate can be generated based on recovered keys, and all of the encrypted data can be accessed even after a private key is lost or damaged.
  • An online certificate status responder (OCSP). The OCSP verifies whether a certificate is valid and not revoked. This function can also be done by the CA, which has an internal OCSP service, but using an external OCSP eases the load off of the issuing CA.
  • A registration authority (RA). An RA accepts certificate requests and verifies, independently, whether that request should be approved. It then forwards approved requests to the CA to issue the certificate. Like the OCSP, this is a function that can be performed by the CA, but using a separate subsystem reduces the load on the CA.
  • A token key service (TKS). The TKS derives keys based on the token CCID, private information, and a defined algorithm. These derived keys are used by the TPS to format tokens and enroll, or process, certificates on the token.
  • A token processing system (TPS). The TPS interacts directly with external tokens, like smart cards, and manages the keys and certificates on those tokens through a local client, the Enterprise Security Client. The Enterprise Security Client contacts the TPS when there is a token operation, and the TPS interacts with the CA, DRM, or TKS, as required, then send the information back to the token by way of the Enterprise Security Client.

1.2.1. Certificate Manager

The Certificate Manager subsystem is a certificate authority. It issues, renews, revokes, and publishes a wide variety of certificates: for servers, for users, for routers, for other subsystems, and for file or object signing. The Certificate Manager also compiles and publishes CRLs.
Certificate Managers can be structured in series (hierarchy), so that one Certificate Manager sets policies and issues signing certificates to a subordinate CA. The highest Certificate Manager in the chain is a root CA.
A special kind of certificate is used by CAs to sign certificates they issue, sort of like a stamp or seal. This is called a CA signing certificate. A subordinate CA is issued a CA signing certificate by a CA higher in the hierarchy, and the parameters of the CA signing certificate are set by the superior CA. A CA which issues its own signing certificate has a self-signed certificate. There are benefits to having a self-signed CA certificate for your root CA, as well as some benefits to having the certificate signed by a third-party CA.
Additionally, a Certificate Manager is always the subsystem which works as the registry for the security domain. The very first Certificate Manager configured must create a security domain, but every Certificate Manager configured after has the option of joining an existing security domain rather than creating a new one. The configuration of your PKI deployment determines whether you need multiple security domains; for more information, see the Red Hat Certificate System Deployment Guide.

1.2.2. Registration Authority

The Registration Authority subsystem handles certain certificate issuing tasks locally, such as generating and submitting certificate requests. This effectively makes the RA a load-balancer for the CA; a local RA can receive and verify the legitimacy of a certificate request (authenticate it) and then forward valid requests to the CA to issue the certificate. Certificates can also be retrieved through the RA and the status of the request can be checked through the RA, both of which lower demand on the CA.
The RA is normally set up outside of the firewall, and the CA is set up behind the firewall so that requests can be submitted to Certificate System externally, while the CA is protected.
The RA accepts requests for a smaller number of certificate types than the CA, including user, server, and router certificates.

1.2.3. Data Recovery Manager

The Data Recovery Manager (DRM) is a key recovery authority, which means it works with the Certificate Manager when a certificate is issued and stores private encryption keys. Those private keys can be restored (in a PKCS #12 file) if a private encryption key is lost.

NOTE

The DRM only archives encryption keys, not signing keys, because that compromises the non-repudiation properties of signing keys. Non-repudiation means that a user cannot deny having performed some action, such as sending signed email, because they are the only possessor of that signing key.

1.2.4. Online Certificate Status Manager

The Online Certificate Status Manager is an OCSP service, external to the Certificate Manager. Although the Certificate Manager is configured initially with an internal OCSP service, an external OCSP responder allows the OCSP subsystem to be outside the firewall and accessible externally, while keeping the Certificate Manager behind the firewall. Like the RA, the OCSP acts as a load-balancer for requests to the Certificate Manager.
The Online Certificate Status Manager verifies the status of a certificate by checking a certificate revocation list, published by the Certificate Manager, to see if the specified certificate has been revoked. More than one Certificate Manager can publish CRLs to a single OCSP.

1.2.5. Token Processing System

The Token Processing System (TPS) is the conduit between the user-centered Enterprise Security Client, which interacts with the tokens, and the Certificate System backend subsystems, such as the Certificate Manager. The TPS is required in order to manage smart cards.
The TPS communicates with the CA and DRM for processing token operations. The TPS also communicates with the TKS to derive token-specific secret keys.

1.2.6. Token Key Service

The Token Key Service (TKS) uses a master key to derive specific, separate keys for every smart card. The TPS uses these secret keys to communicate with each smart card securely, since all communication between the TPS and the smart card is encrypted.
The only Certificate System subsystem which the TKS interacts with is the TPS.

1.2.7. Enterprise Security Client

The Enterprise Security Client is not a subsystem since it does not perform any operations with certificates, keys, or tokens. The Enterprise Security Client, as the name implies, is a user interface which allows people to manage certificates on smart cards very easily. The Enterprise Security Client sends all token operations, such as certificate requests, to the TPS, which then sends them to the CA.

1.3. A Look at Managing Certificates

Certificates are used in many applications, from encrypting email to accessing websites. There are two major stages in the lifecycle of the certificate: the point when it is issued (issuance and enrollment) and the period when the certificates are no longer valid (renewal or revocation). There are also ways to manage the certificate during its cycle. Making information about the certificate available to other applications is publishing the certificate and then backing up the key pairs so that the certificate can be recovered if it is lost.
The core of the Certificate System PKI is the Certificate Manager, a certificate authority. The CA receives certificate requests, issues all certificates, and handles revocation and publishing CRLs. If a client needs to verify whether a certificate is valid, then it can check for the certificate's status against the CA's internal online certificate status protocol (OCSP) responder.
CA Only Certificate System

Figure 1.1. CA Only Certificate System


One operation the CA cannot perform, though, is key archival and recovery. A very real scenario is that a user is going to lose a certificate — the certificate could be deleted from a browser database, a smart card could be left at home. Depending on the policies in the company, there probably has to be a way to recover the keys in order to regenerate a replacement certificate. That requires a DRM, the subsystem which specially archives and retrieves keys.
CA and DRM

Figure 1.2. CA and DRM


Another aspect of how the subsystems work together is load balancing. If a site has high traffic, then it is possible to install a lot of CAs, as clones of each other or in a flat hierarchy (where each CA is independent) or in a tree hierarchy (where some CAs are subordinate to other CAs).
Another option, though is to distribute some of the tasks of a single CA to another subsystem. For example, if Example Corp. has a manageable number of people requesting certificates for a single CA to issue. However, because of their security policies, each certificate request has to be verified in person by an agent, with supporting documentation. This creates a bottleneck for the CA agents to approve requests. A registration authority (RA) is installed at each local office; the requests are processed and approved locally, and then a central CA issues all of the certificates.
CA and RA

Figure 1.3. CA and RA


Alternatively, a site may have a significant number of client requests to verify certificate status. Example Corp. has a large web store, and each customer's browser tries to verify the validity of their SSL certificates. Again, the CA can handle issuing the number of certificates, but the high request traffic affects its performance. In this case, Example Corp. uses an external OCSP Manager to verify certificate statuses, and the Certificate Manager only has to publish updated CRLs every so often.
CA and OCSP

Figure 1.4. CA and OCSP


Even with all possible subsystems installed, the core of the Certificate System is still the CA (or CAs), since they ultimately process all certificate-related requests. The other subsystems connect to the CA or CAs likes spokes in a wheel.

1.4. A Look at the Token Management System

Certificate System creates, manages, renews, and revokes certificates, as well as archiving and recovering keys. For organizations which use smart cards, the Certificate System has a token management system — a collection of subsystems with established relationships — to generate keys and requests and receive certificates to be used for smart cards. These relationships are shown in Figure 1.5, “How Certificate System Manages Smart Cards”.
Four Certificate System subsystems are involved with managing tokens:
  • The Token Processing System (TPS) interacts with smart cards to help them generate and store keys and certificates for a specific entity, such as a user or device. Smart card operations go through the TPS and are forwarded to the appropriate subsystem for action, such as the Certificate Authority to generate certificates or the Data Recovery Manager to archive and recover keys.
  • The Token Key Service (TKS) generates, or derives, symmetric keys used for communication between the TPS and smart card. Each set of keys generated by the TKS is unique because they are based on the card's unique ID. The keys are formatted on the smart card and are used to encrypt communications, or provide authentication, between the smart card and TPS.
  • The Certificate Authority (CA) creates and revokes user certificates stored on the smart card.
  • Optionally, the Data Recovery Manager (DRM) archives and recovers keys for the smart card.
The Enterprise Security Client is the conduit through which TPS communicates with each token over a secure HTTP channel (HTTPS), and, through the TPS, with the Certificate System.
How Certificate System Manages Smart Cards

Figure 1.5. How Certificate System Manages Smart Cards


To use the tokens, the Token Processing System must be able to recognize and communicate with them. The tokens must first be enrolled to format the tokens with required keys and certificates and add the tokens to the Certificate System. The Enterprise Security Client provides the user interface for end entities to enroll tokens.
The token management system is very scalable. Multiple TPSs can be configured to work with a single CA, TKS, or DRM instance, while multiple Enterprise Security Clients can communicate with a single TPS. As additional clients are installed, they can point back to the TPS instance without having to reconfigure the TPS; likewise, as TPSs are added, they can point to the same CA, TKS, and DRM instances without having to reconfigure those subsystems.
After installation, the TPS configuration file, CS.cfg, can have additional CA, DRM, and TKS instances added for provide failover support, so if the primary subsystem is unavailable, the TPS can switch to the next available system without interrupting its token services.

1.5. Red Hat Certificate System Services

There are three different interfaces for managing certificates and subsystems, depending on the user type: administrators, agents, and end users. This section gives an overview of the different functions that are performed through each interface.

1.5.1. Interfaces for Administrators

The administrative interface is used to manage the subsystem itself. This includes adding users, configuring logs, managing profiles and plug-ins, and the internal database, among many other functions. This interface is also the only interface that does not directly deal with certificates, tokens, or keys, meaning it is not used for managing the PKI, only the servers.
There are two types of administrative consoles, Java-based and HTML-based. Although the interface is different, both are accessed using a server URL and the administrative port number.

1.5.1.1. The Java Administrative Console for CA, OCSP, DRM, and TKS Subsystems

The Java console is used by four subsystems: the CA, OCSP, DRM, and TKS. The console is accessed using a locally-installed pkiconsole utility. It can access any subsystem because the command requires the hostname, the subsystem's administrative SSL port, and the specific subsystem type.
pkiconsole https://server.example.com:admin_port/subsystem_type
This opens a console, as in Figure 1.6, “Certificate System Console”.
Certificate System Console

Figure 1.6. Certificate System Console


The Configuration tab controls all of the setup for the subsystem, as the name implies. The choices available in this tab are different depending on which subsystem type the instance is; the CA has the most options since it has additional configuration for jobs, notifications, and certificate enrollment authentication.
All subsystems have four basic options:
  • Users and groups
  • Access control lists
  • Log configuration
  • Subsystem certificates (meaning the certificates issued to the subsystem for use, for example, in the security domain or audit signing)
The Status tab shows the logs maintained by the subsystem. See Chapter 15, Configuring Subsystem Logs for more information.

1.5.1.2. The Administrative Interface for the RA and TPS

The RA and TPS subsystems use HTML-based administrative interfaces. These are accessed by entering the hostname and secure port as the URL, authenticating with the administrator's certificate, and clicking the appropriate Administrators link.

NOTE

There is a single SSL port for RA and TPS subsystems which is used for both administrator and agent services. Access to those services is restricted by certificate-based authentication. The other subsystems used separate SSL ports for the agent and administrative services, along with certificate-based authentication.
The HTML admin interface is much more limited than the Java console; the primary administrative function is managing the subsystem users; all other administrative tasks are done by manually editing the CS.cfg file.
The RA allows administrators to create and edit users and groups for the subsystem.
RA Admin Page

Figure 1.7. RA Admin Page


The TPS only allows operations to manage users for the TPS subsystem. However, the TPS admin page can also list tokens and display all activities (including normally-hidden administrative actions) performed on the TPS.
TPS Admin Page

Figure 1.8. TPS Admin Page


1.5.2. Agent Interfaces

The agent services pages are where almost all of the certificate and token management tasks are performed. These services are HTML-based, and agents authenticate to the site using a special agent certificate.
Certificate Manager's Agent Services Page

Figure 1.9. Certificate Manager's Agent Services Page


The operations vary depending on the subsystem:
  • The Certificate Manager agent services include approving certificate requests (which issues the certificates), revoking certificates, and publishing certificates and CRLs. All certificates issued by the CA can be managed through its agent services page.
  • The TPS agent services, like the CA agent services, manages all of the tokens which have been formatted and have had certificates issued to them through the TPS. Tokens can be enrolled, suspended, and deleted by agents. Two other roles (operator and admin) can view tokens in web services pages, but cannot perform any actions on the tokens.
  • DRM agent services pages process key recovery requests, which set whether to allow a certificate to be issued reusing an existing key pair if the certificate is lost.
  • The OCSP agent services page allows agents to configure CAs which publish CRLs to the OCSP, to load CRLs to the OCSP manually, and to view the state of client OCSP requests.
  • The RA agent services allows agents to list and approve certificate requests and to check the status of requests and certificates processed through the RA.
The TKS is the only subsystem without an agent services page.

1.5.3. End User Pages

The CA, RA, and TPS all process direct user requests in some way. That means that end users have to have a way to connect with those subsystems. The CA and RA both have end-user, or end-entities, HTML services. The TPS uses the Enterprise Security Client, described in Section 1.5.4, “Enterprise Security Client”.
The end-user services are accessed over standard HTTP using the server's hostname and the standard port number; they can also be accessed over HTTPS using the server's hostname and the specific end-entities SSL port.
For CAs, each type of SSL certificate is processed through a specific online submission form, called a profile. There are about two dozen certificate profiles for the CA, covering all sorts of certificates — user SSL certificates, server SSL certificates, log and file signing certificates, email certificates, and every kind of subsystem certificate. There can also be custom profiles.
Certificate Manager's End-Entities Page

Figure 1.10. Certificate Manager's End-Entities Page


End users retrieve their certificates through the CA pages when the certificates are issued. They can also download CA chains and CRLs and can revoke or renew their certificates through those pages.
The RA is a more lightweight subsystem, so it only processes four common certificate profiles. Like the CA, the enrollment forms are accessed through the End Entities URL. Users can submit certificate requests and retrieve their certificates through the RA.

1.5.4. Enterprise Security Client

The Enterprise Security Client is a tool for Red Hat Certificate System which simplifies managing smart cards. End users can use security tokens (smart cards) to store user certificates used for applications such as single sign-on access and client authentication. End users are issued the tokens containing certificates and keys required for signing, encryption, and other cryptographic functions.
The Enterprise Security Client is the third part of Certificate System's complete token management system. Two subsystems — the Token Key Service (TKS) and Token Processing System (TPS) — are used to process token-related operations. The Enterprise Security Client is the interface which allows the smart card and user to access the token management system.
After a token is enrolled, applications such as Mozilla Firefox and Thunderbird can be configured to recognize the token and use it for security operations, like client authentication and S/MIME mail. Enterprise Security Client provides the following capabilities:
  • Supports JavaCard 2.1 or higher cards and Global Platform 2.01-compliant smart cards like Safenet's 330J smart card
  • Supports Global Platform 2.01-compliant smart cards like Gemalto e-gate 32K and Gemalto TOP IM FIPS CY2 64K tokens, both the smart card and GemPCKey USB form factor key.
  • Enrolls security tokens so they are recognized by TPS.
  • Maintains the security token, such as re-enrolling a token with TPS.
  • Provides information about the current status of the token or tokens being managed.
  • Supports server-side key generation so that keys can be archived and recovered on a separate token if a token is lost.
The Enterprise Security Client is a cross-platform client for end users to register and manage keys and certificates on smart cards or tokens. This is the final component in the Certificate System token management system, with the Token Processing System (TPS) and Token Key Service (TKS).

NOTE

For more information on using the Enterprise Security Client, see the Certificate System Enterprise Security Client Guide.
The Enterprise Security Client provides the user interface of the token management system. The end user can be issued security tokens containing certificates and keys required for signing, encryption, and other cryptographic functions. To use the tokens, the TPS must be able to recognize and communicate with them. Enterprise Security Client is the method for the tokens to be enrolled.
Enterprise Security Client communicates over an SSL HTTP channel to the backend of the TPS. It is based on an extensible Mozilla XULRunner framework for the user interface, while retaining a legacy web browser container for a simple HTML-based UI.
After a token is properly enrolled, web browsers can be configured to recognize the token and use it for security operations. Enterprise Security Client provides the following capabilities:
  • Allows the user to enroll security tokens so they are recognized by the TPS.
  • Allows the user to maintain the security token. For example, Enterprise Security Client makes it possible to re-enroll a token with the TPS.
  • Provides support for two types of tokens. UserKey identifies token keys for an individual. The simpler DeviceKey identifies the key itself, without verifying an individual's identity.
  • Provides information about the current status of the tokens being managed.

Part I. Setting up Certificate Services

Table of Contents

2. Making Rules for Issuing Certificates
2.1. About Certificate Profiles
2.1.1. The Profile
2.1.2. Certificate Extensions: Defaults and Constraints
2.1.3. Inputs and Outputs
2.2. Setting up Certificate Profiles
2.2.1. Creating Certificate Profiles through the CA Console
2.2.2. Editing Certificate Profiles in the Console
2.2.3. Creating and Editing Certificate Profiles through the Command Line
2.2.4. Defining Key Defaults in Profiles
2.2.5. Configuring Cross-Pair Profiles
2.2.6. List of Certificate Profiles
2.3. Configuring Custom Enrollment Profiles to Use with an RA
2.3.1. Default RA Profiles
2.3.2. Creating RA Enrollment Forms
2.3.3. Configuring the Request Queues
2.4. Managing Smart Card CA Profiles
2.4.1. Editing Enrollment Profiles for the TPS
2.4.2. Creating Custom TPS Profiles
2.4.3. Using the Windows Smart Card Logon Profile
2.5. Setting the Signing Algorithms for Certificates
2.5.1. Setting the CA's Default Signing Algorithm
2.5.2. Setting the Signing Algorithm Default in a Profile
2.6. Managing CA-Related Profiles
2.6.1. Setting Restrictions on CA Certificates
2.6.2. Changing the Restrictions for CAs on Issuing Certificates
2.7. Managing Subject Names and Subject Alternative Names
2.7.1. Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name
2.7.2. Changing DN Attributes in CA-Issued Certificates
2.7.3. Customizing the Subject DN in a Certificate Request Issued by an RA
3. Setting up Key Archival and Recovery
3.1. About Key Archival and Recovery
3.2. Setting up Key Archival
3.3. Setting up Agent-Approved Key Recovery Schemes
3.4. Testing the Key Archival and Recovery Setup
4. Requesting, Enrolling, and Managing Certificates
4.1. About Enrolling and Renewing Certificates
4.2. Configuring Internet Explorer to Enroll Certificates
4.3. Requesting and Receiving Certificates
4.3.1. Requesting and Receiving a User or Agent Certificate through the End-Entities Page
4.3.2. Requesting Certificates Using certutil
4.4. Enrolling a Certificate on a Cisco Router
4.4.1. Enabling SCEP Enrollments
4.4.2. Configuring Security Settings for SCEP
4.4.3. Configuring a Router for SCEP Enrollment
4.4.4. Generating the SCEP Certificate for a Router
4.4.5. Working with Subordinate CAs
4.4.6. Re-enrolling a Router
4.4.7. Enabling Debugging
4.5. Performing Bulk Issuance
4.6. Configuring and Using the Auto Enrollment Proxy
4.6.1. About Auto Enrollment
4.6.2. Installing and Setting up the Auto Enrollment Proxy
4.6.3. Managing Auto Enrollment Proxy Settings
4.6.4. Manually Requesting Domain Certificates
4.7. Renewing Certificates
4.7.1. About Renewal
4.7.2. Creating Custom Renewal Profiles
4.7.3. Renewing Certificates
5. Using and Configuring the Token Management System: TPS, TKS, and Enterprise Security Client
5.1. Configuring TPS Smart Card Operations
5.1.1. Configuring Format Operations
5.1.2. Configuring TPS Enrollment Operations
5.1.3. Configuring TPS Renewal Operations
5.1.4. Configuring the PIN Reset Operation
5.1.5. Configuring the Applet Update Operation
5.2. Allowing Token Renewal
5.3. Changing the Token Policy
5.4. Setting Token Types for Specified Smart Cards
5.4.1. Default Token Types
5.4.2. Mapping Token Types to Smart Card Operation Profiles
5.4.3. Example: Token Mapping with Two Different Token Types
5.5. Setting Token Status Transitions
5.6. Automating Encryption Key Recovery
5.6.1. Configuring Enrollment for Replacement Tokens
5.6.2. Configuring Key Generation for Temporary Tokens
5.7. Managing Shared Keys
5.7.1. Generating Master Keys
5.7.2. Generating and Transporting Wrapped Master Keys
5.7.3. Using HSM for Generating Keys
5.7.4. Updating Master Key Versions and Associating the Master Key with Its Version
5.7.5. Configuring Symmetric Key Changeover
5.8. Configuring the TPS
5.8.1. Enabling SSL for TPS-Enterprise Security Client Connections
5.8.2. Configuring the Channels between the TPS and Tokens
5.8.3. Configuring or Disabling LDAP Authentication
5.8.4. Configuring the Token Database
5.8.5. Configuring Server-Side Key Generation and Archival of Encryption Keys
5.8.6. Configuring IPv6 Support
5.9. Scaling the TPS and Its Support Subsystems
5.9.1. Configuring Failover Support
5.9.2. Configuring Multiple Support Subsystem Instances for Different Functions
5.10. Potential Token Operation Errors
6. Revoking Certificates and Issuing CRLs
6.1. About Revoking Certificates
6.1.1. User-Initiated Revocation
6.1.2. Reasons for Revoking a Certificate
6.1.3. CRL Issuing Points
6.1.4. Delta CRLs
6.1.5. Publishing CRLs
6.1.6. Certificate Revocation Pages
6.2. CMC Revocation
6.2.1. Setting up CMC Revocation
6.2.2. Testing CMC Revoke
6.3. Issuing CRLs
6.3.1. Configuring Issuing Points
6.3.2. Configuring CRLs for Each Issuing Point
6.3.3. Setting CRL Extensions
6.3.4. Setting a CA to Use a Different Certificate to Sign CRLs
6.4. Setting Full and Delta CRL Schedules
6.4.1. Configuring Extended Updated Intervals for CRLs in the Console
6.4.2. Configuring Extended Updated Intervals for CRLs in CS.cfg
6.5. Enabling Automatic Revocation Checking for Agent Certificates
7. Using the Online Certificate Status Protocol Responder
7.1. Setting up the OCSP Responder
7.2. Identifying the CA to the OCSP Responder
7.2.1. Verify Certificate Manager and Online Certificate Status Manager Connection
7.2.2. Configure the Revocation Info Stores
7.2.3. Testing the OCSP Service Setup
7.3. Enabling the Certificate Manager's Internal OCSP Service
7.4. Enabling Revocation Checking for the TPS and RA
7.5. Enabling Certificate Revocation Checking for DRM and TKS Users
7.6. Submitting OCSP Requests Using the GET Method
7.7. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier

Chapter 2. Making Rules for Issuing Certificates

The Certificate System provides a customizable framework to apply policies for incoming certificate requests and to control the input request types and output certificate types; these are called certificate profiles. Certificate profiles set the required information for certificate enrollment forms in the Certificate Manager end-entities page. This chapter describes how to configure certificate profiles.

2.1. About Certificate Profiles

A certificate profile defines everything associated with issuing a particular type of certificate, including the authentication method, the authorization method, the certificate content (defaults), constraints for the values of the content, and the contents of the input and output for the certificate profile. Enrollment and renewal requests are submitted to a certificate profile and are then subject to the defaults and constraints set in that certificate profile. These constraints are in place whether the request is submitted through the input form associated with the certificate profile or through other means. The certificate that is issued from a certificate profile request contains the content required by the defaults with the information required by the default parameters. The constraints provide rules for what content is allowed in the certificate.
All of the information about a certificate profile is defined in a profile policy set entry in the profile's configuration file, and then the profile is listed in the CA's CS.cfg file.
  • Profile inputs. Profile inputs are parameters and values that are submitted to the CA when a certificate is requested. Profile inputs include public keys for the certificate request and the certificate subject name requested by the end entity for the certificate.
  • Certificate extensions. Each issued certificate defines certain information, like the name of the entity to which it is assigned (the subject name), its key fingerprint, and its validity period. What is included in a certificate is defined in the X.509 standard. A certificate extension is a way to add additional, optional, customizable information to a certificate that is not included in the certificate by the X.509 standard or a way to set rules on how the certificate can be used.
    Sometimes, including the certificate extension itself is enough to configure the certificate content, but a certificate extension can include two additional parts:
    • Profile defaults. These are predefined parameters and allowed values for information contained within the certificate. Profile defaults include the how long the certificate is valid, and what certificate extensions appear for each type of certificate issued.
    • Profile constraints. Constraints set rules or policies for issuing certificates. Profile constraints include rules like requiring the certificate subject name to have at least one CN component, setting the validity of a certificate to a maximum of 360 days, defining the allowed grace period for renewal, or requiring that the subjectaltname extension always be set to true.
  • Profile outputs. Profile outputs are parameters and values that specify the format in which to issue the certificate to the end entity. Profile outputs include base-64 encoded files, CMMF responses, and PKCS #7 output, which also includes the CA chain.

2.1.1. The Profile

A profile configures the entire set of rules around issuing a certificate: the kind of content that is required to submit the request, the way the request is processed and approved (authenticated and authorized), the information that is included in the certificate content, and how long the certificate is valid.
The profile itself is defined in a special .cfg file in the /var/lib/subsystem_name/profiles/ca directory for the CA. The parameters for this file defining the inputs, outputs, and policysets are listed in more detail in Section 2.2.3, “Creating and Editing Certificate Profiles through the Command Line”.
A profile usually contains inputs, policy sets, and outputs, as illustrated in the caUserCert profile in Example 2.1, “Example caUserCert Profile”.

Example 2.1. Example caUserCert Profile

The first part of a certificate profile is the description. This shows the name, long description, whether it is enabled, and who enabled it.
desc=This certificate profile is for enrolling user certificates.
visible=true
enable=true
enableBy=admin
name=Manual User Dual-Use Certificate Enrollment
Next, the profile lists all of the required inputs for the profile:
input.list=i1,i2,i3
input.i1.class_id=keyGenInputImpl
input.i2.class_id=subjectNameInputImpl
input.i3.class_id=submitterInfoInputImpl
For the caUserCert profile, this defines the keys to generate, the fields to use in the subject name, and the fields to use for the person submitting the certificate.
  • Key generation specifies that the key pair generation during the request submission be CRMF-based and has a drop-down menu to select the key bit size.
  • Subject name is used when distinguished name (DN) parameters need to be collected from the user; the user DN can be used to create the subject name in the certificate.
    • UID (for the user in the LDAP directory)
    • Email
    • Common name
    • Organizational unit
    • Organization
    • Country
  • Requester. This input has three form fields:
    • Requester name
    • Requester email
    • Requester phone
The profile next must define the output, meaning the format of the final certificate. There are several pre-defined outputs. More than one of these can be used, but none of the values of the output can be modified.
output.list=o1
output.o1.class_id=certOutputImpl
For caUserCert, the output displays the certificate in pretty print format. This output needs to be specified for any automated enrollment. Once a user successfully authenticates and is authorized using the automated enrollment method, the certificate is automatically generated, and this output page is returned to the user. In an agent-approved enrollment, the user can get the certificate, once it is issued, by providing the request ID in the CA end entities page.
The last — largest — block of configuration is the policy set for the profile. Policy sets list all of the settings that are applied to the final certificate, like its validity period, its renewal settings, and the actions the certificate can be used for. The policyset.list parameter identifies the block name of the policies that apply to one certificate; the policyset.userCertSet.list lists the individual policies to apply.
For example, the sixth policy populates the Key Usage Extension automatically in the certificate, according to the configuration in the policy. It sets the defaults and requires the certificate to use those defaults by setting the constraints:
policyset.list=userCertSet
policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9
...
policyset.userCertSet.6.constraint.class_id=keyUsageExtConstraintImpl
policyset.userCertSet.6.constraint.name=Key Usage Extension Constraint
policyset.userCertSet.6.constraint.params.keyUsageCritical=true
policyset.userCertSet.6.constraint.params.keyUsageDigitalSignature=true
policyset.userCertSet.6.constraint.params.keyUsageNonRepudiation=true
policyset.userCertSet.6.constraint.params.keyUsageDataEncipherment=false
policyset.userCertSet.6.constraint.params.keyUsageKeyEncipherment=true
policyset.userCertSet.6.constraint.params.keyUsageKeyAgreement=false
policyset.userCertSet.6.constraint.params.keyUsageKeyCertSign=false
policyset.userCertSet.6.constraint.params.keyUsageCrlSign=false
policyset.userCertSet.6.constraint.params.keyUsageEncipherOnly=false
policyset.userCertSet.6.constraint.params.keyUsageDecipherOnly=false
policyset.userCertSet.6.default.class_id=keyUsageExtDefaultImpl
policyset.userCertSet.6.default.name=Key Usage Default
policyset.userCertSet.6.default.params.keyUsageCritical=true
policyset.userCertSet.6.default.params.keyUsageDigitalSignature=true
policyset.userCertSet.6.default.params.keyUsageNonRepudiation=true
policyset.userCertSet.6.default.params.keyUsageDataEncipherment=false
policyset.userCertSet.6.default.params.keyUsageKeyEncipherment=true
policyset.userCertSet.6.default.params.keyUsageKeyAgreement=false
policyset.userCertSet.6.default.params.keyUsageKeyCertSign=false
policyset.userCertSet.6.default.params.keyUsageCrlSign=false
policyset.userCertSet.6.default.params.keyUsageEncipherOnly=false
policyset.userCertSet.6.default.params.keyUsageDecipherOnly=false
...

2.1.2. Certificate Extensions: Defaults and Constraints

A extension configures additional information to include in a certificate or rules about how the certificate can be used. These extensions can either be specified in the certificate request or taken from the profile default definition and then enforced by the constraints.
A certificate extension is added or identified in a profile by adding the default which corresponds to the extension and sets default values, if the certificate extension is not set in the request. For example, the Basic Constraints Extension identifies whether a certificate is a CA signing certificate, the maximum number of subordinate CAs that can be configured beneath the CA, and whether the extensions is critical (required):
policyset.caCertSet.5.default.name=Basic Constraints Extension Default
policyset.caCertSet.5.default.params.basicConstraintsCritical=true
policyset.caCertSet.5.default.params.basicConstraintsIsCA=true
policyset.caCertSet.5.default.params.basicConstraintsPathLen=-1
The extension can also set required values for the certificate request called constraints. If a request's contents do not match the set constraints, then the request is rejected. The constraints generally correspond to the extension default, though not always. For example:
policyset.caCertSet.5.constraint.class_id=basicConstraintsExtConstraintImpl
policyset.caCertSet.5.constraint.name=Basic Constraint Extension Constraint
policyset.caCertSet.5.constraint.params.basicConstraintsCritical=true
policyset.caCertSet.5.constraint.params.basicConstraintsIsCA=true
policyset.caCertSet.5.constraint.params.basicConstraintsMinPathLen=-1
policyset.caCertSet.5.constraint.params.basicConstraintsMaxPathLen=-1

NOTE

To allow user supplied extensions to be embedded in the certificate requests and ignore the system-defined default in the profile, the profile needs to contain the User Supplied Extension Default, which is described in Section B.1.22, “User Supplied Extension Default”.

2.1.3. Inputs and Outputs

Inputs set information that must be submitted to receive a certificate. This can be requester information, a specific format of certificate request, or organizational information.
The outputs configured in the profile define the format of the certificate that is issued.
In Certificate System, profiles are accessed by users through enrollment forms that are accessed through the end-entities pages. (Even clients, like the RA and TPS, submit enrollment requests through these forms.) The inputs, then, correspond to fields in the enrollment forms. The outputs correspond to the information contained on the certificate retrieval pages.

2.2. Setting up Certificate Profiles

NOTE

The old policy framework for managing certificates was deprecated in Certificate System 7.1 and was removed entirely for Certificate System 7.2, 7.3, and 8.0. Any certificate enrollments or other operations must be performed using the new profile framework.

2.2.1. Creating Certificate Profiles through the CA Console

An administrator cannot edit any certificate profile that has been approved by an agent. The agent must disapprove or disable the certificate profile before the administrator can edit that certificate profile.
Add a certificate profile and modify an existing certificate profile by doing the following:
  1. Log in to the Certificate System CA subsystem console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager, and then select Certificate Profiles.
    The Certificate Profile Instances Management tab, which lists configured certificate profiles, opens.
  3. To create a new certificate profile, click Add.
    In the Select Certificate Profile Plugin Implementation window, select the type of certificate for which the profile is being created.
  4. Fill in the profile information in the Certificate Profile Instance Editor.
    • Certificate Profile Instance ID. This is the ID used by the system to identify the profile.
    • Certificate Profile Name. This is the user-friendly name for the profile.
    • Certificate Profile Description.
    • End User Certificate Profile. This sets whether the request must be made through the input form for the profile. This is usually set to true. Setting this to false allows a signed request to be processed through the Certificate Manager's certificate profile framework, rather than through the input page for the certificate profile.
    • Certificate Profile Authentication. This sets the authentication method. An automated authentication is set by providing the instance ID for the authentication instance. If this field is blank, the authentication method is agent-approved enrollment; the request is submitted to the request queue of the agent services interface.
  5. Click OK. The plug-in editor closes, and the new profile is listed in the profiles tab.
  6. Configure the policies, inputs, and outputs for the new profile. Select the new profile from the list, and click Edit/View.
  7. Set up policies in the Policies tab of the Certificate Profile Rule Editor window. The Policies tab lists policies that are already set by default for the profile type.
    1. To add a policy, click Add.
    2. Choose the default from the Default field, choose the constraints associated with that policy in the Constraints field, and click OK.
    3. Fill in the policy set ID. When issuing dual key pairs, separate policy sets define the policies associated with each certificate. Then fill in the certificate profile policy ID, a name or identifier for the certificate profile policy.
    4. Configure any parameters in the Defaults and Constraints tabs.
      Defaults defines attributes that populate the certificate request, which in turn determines the content of the certificate. These can be extensions, validity periods, or other fields contained in the certificates. Constraints defines valid values for the defaults.
      See Section B.1, “Defaults Reference” and Section B.2, “Constraints Reference” for complete details for each default or constraint.
    To modify an existing policy, select a policy, and click Edit. Then edit the default and constraints for that policy.
    To delete a policy, select the policy, and click Delete.
  8. Set inputs in the Inputs tab of the Certificate Profile Rule Editor window. There can be more than one input type for a profile.
    1. To add an input, click Add.
    2. Choose the input from the list, and click OK. See Section A.1, “Input Reference” for complete details of the default inputs.
    3. The New Certificate Profile Editor window opens. Set the input ID, and click OK.
    Inputs can be added and deleted. It is possible to select edit for an input, but since inputs have no parameters or other settings, there is nothing to configure.
    To delete an input, select the input, and click Delete.
  9. Set up outputs in the Outputs tab of the Certificate Profile Rule Editor window.
    Outputs must be set for any certificate profile that uses an automated authentication method; no output needs to be set for any certificate profile that uses agent-approved authentication. The Certificate Output type is set by default for all profiles and is added automatically to custom profiles.
    Outputs can be added and deleted. It is possible to select edit for an output, but since outputs have no parameters or other settings, there is nothing to configure.
    1. To add an output, click Add.
    2. Choose the output from the list, and click OK.
    3. Give a name or identifier for the output, and click OK.
      This output will be listed in the output tab. You can edit it to provide values to the parameters in this output.
    To delete an output, select the output from list, and click Delete.
  10. Restart the CA to apply the new profile.
    service pki-ca start
  11. After creating the profile as an administrator, a CA agent has to approve the profile in the agent services pages to enable the profile.
    1. Open the CA's services page.
      https://server.example.com:9445/ca/services
    2. Click the Manage Certificate Profiles link. This page lists all of the certificate profiles that have been set up by an administrator, both active and inactive.
    3. Click the name of the certificate profile to approve.
    4. At the bottom of the page, click the Enable button.

NOTE

If this profile will be used with an RA, then the RA must be configured, as well, so that users can access the profile. This is in Section 2.3, “Configuring Custom Enrollment Profiles to Use with an RA”.
If this profile will be used with a TPS, then the TPS must be configured to recognized the profile type. This is in Section 2.4, “Managing Smart Card CA Profiles”.
Authorization methods for the profiles can only be added to the profile using the command line, as described in Section 2.2.3, “Creating and Editing Certificate Profiles through the Command Line”.

2.2.2. Editing Certificate Profiles in the Console

To modify an existing certificate profile, select a certificate profile, click Edit/View.
The Certificate Profile Rule Editor window appears. If necessary, enlarge the window by pulling out one of the corners of the window.

NOTE

The profile instance ID cannot be modified.
Once a certificate profile is enabled by an agent, that certificate profile is marked enabled in the Certificate Profile Instance Management tab, and the certificate profile cannot be edited in any way. To edit that certificate profile, an agent must first disable the certificate profile.
Delete any certificate profiles that will not be approved by an agent. Any certificate profile that appears in the Certificate Profile Instance Management tab also appears in the agent services interface. If a profile has already been enabled, it must be disabled by the agent before it can be deleted from the profile list.

NOTE

Restart the server after editing the profile configuration file for the changes to take effect.

2.2.3. Creating and Editing Certificate Profiles through the Command Line

The certificate profiles can be modified directly through the command line by modifying the profiles' configuration files. The certificate profiles have individual configuration files which can be modified through the command line. Default files exist for the default profiles at installation; when new profiles are created, new configuration files are also created. The configuration files are stored in the CA profile directory, instance_directory/profiles/ca/, such as /var/lib/pki-ca/profiles/ca/. The file is named profile_name.cfg. All of the parameters for profile rules set or modified through the Console, such as defaults, inputs, outputs, and constraints, are written to the profile configuration file.
The enrollment profiles for system certificates are located in the /var/lib/subsystem_name/conf directory with the name *.profile.

NOTE

Restart the server after editing the profile configuration file for the changes to take effect.

2.2.3.1. Profile Configuration Parameters

The configuration files are stored in the CA profile directory, such as /var/lib/pki-ca/profiles/ca/. The file is named profile_name.cfg. All of the parameters for a profile rule - defaults, inputs, outputs, and constraints - are configured within a single policy set. A policy set for a profile has the name policyset.policyName.policyNumber. For example:
policyset.cmcUserCertSet.6.constraint.class_id=noConstraintImpl
policyset.cmcUserCertSet.6.constraint.name=No Constraint
policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl
policyset.cmcUserCertSet.6.default.name=User Supplied Key Default
policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15
The common profile configuration parameters are described in Table 2.1, “Profile Configuration File Parameters”.
There is only one policy set processed for the profile, except for dual key pairs when two policy sets are processed. The server evaluates each policy set for each request it receives. When a single certificate is issued, 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 with the first certificate request, and the second set is evaluated with the second certificate request. There is no need for more than one policy set when issuing single certificates or more than two sets when issuing dual key pairs.

Table 2.1. Profile Configuration File Parameters

Parameter Description
desc Gives 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 Sets whether the profile is enabled, and therefore accessible through the end-entities page. For example, enable=true.
auth.instance_id Sets which authentication manager plug-in to use to authenticate the certificate request submitted through the profile. 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. Most commonly, this us used to set the group evaluation ACL. For example, this caCMCUserCert parameter requires that the signer of the CMC request belong 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 Gives the name of the profile. For example, name=Agent-Authenticated Server Certificate Enrollment. This name is displayed in the end users enrollment or renewal page.
input.list Lists the allowed inputs for the profile by name. For example, input.list=i1,i2.
input.input_id.class_id Gives 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 profile by name. For example, output.list=o1.
output.output_id.class_id Gives the java class name for the output format named in output.list. For example, output.o1.class_id=certOutputImpl.
policyset.list Lists the configured 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 profile rules. For example, policyset.list=serverCertSet.
policyset.policyset_id.list Lists the policies within the policy set configured for the 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 Gives 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$.

2.2.3.2. Modifying Certificate Extensions through the Command Line

Changing constraints changes the restrictions on the type of information which can be supplied. Changing the defaults and constraints can also add, delete, or modify the extensions which are accepted or required from a certificate request.
For example, the default caFullCMCUserCert profile is set to create a Key Usage extension from information in the request.
 policyset.cmcUserCertSet.6.constraint.class_id=keyUsageExtConstraintImpl    
 policyset.cmcUserCertSet.6.constraint.name=Key Usage Extension Constraint    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageCritical=true    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageCrlSign=false    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageDataEncipherment=false    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageDecipherOnly=false    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageDigitalSignature=true    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageEncipherOnly=false    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageKeyAgreement=false    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageKeyCertSign=false    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageKeyEncipherment=true    
 policyset.cmcUserCertSet.6.constraint.params.keyUsageNonRepudiation=true    
 policyset.cmcUserCertSet.6.default.class_id=keyUsageExtDefaultImpl
 policyset.cmcUserCertSet.6.default.name=Key Usage Default
 policyset.cmcUserCertSet.6.default.params.keyUsageCritical=true
 policyset.cmcUserCertSet.6.default.params.keyUsageCrlSign=false
 policyset.cmcUserCertSet.6.default.params.keyUsageDataEncipherment=false
 policyset.cmcUserCertSet.6.default.params.keyUsageDecipherOnly=false
 policyset.cmcUserCertSet.6.default.params.keyUsageDigitalSignature=true
 policyset.cmcUserCertSet.6.default.params.keyUsageEncipherOnly=false
 policyset.cmcUserCertSet.6.default.params.keyUsageKeyAgreement=false
 policyset.cmcUserCertSet.6.default.params.keyUsageKeyCertSign=false
 policyset.cmcUserCertSet.6.default.params.keyUsageKeyEncipherment=true
 policyset.cmcUserCertSet.6.default.params.keyUsageNonRepudiation=true
This extension can be removed so that the server accepts the key usage set in the request. In this example, the key extension constraint is removed and replaced by no constraint, and the default is updated to allow user-supplied key extensions:
 policyset.cmcUserCertSet.6.constraint.class_id=noConstraintImpl     
 policyset.cmcUserCertSet.6.constraint.name=No Constraint to keep it simple    
 policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl
 policyset.cmcUserCertSet.6.default.name=User Supplied Key Default
 policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15
This sets the server to accept the extension OID 2.5.29.15 in the certificate request.

NOTE

If the User Supplied Extension Default is used, the CA expects any extensions which are specified with the specified userExtOID parameters in the request.
Other constraints and defaults can be changed similarly. Make sure that any required constraints and included with the appropriate default, that defaults are changed when a different constraint is required, and that only allowed constraints are used with the default. For more information, see Section B.1, “Defaults Reference” and Section B.2, “Constraints Reference”.

2.2.3.3. Adding Inputs through the Command Line

The certificate profile configuration file in the CA's profiles/ca directory contains the input information for the that particular certificate profile form. Inputs are the fields in the end-entities page enrollment forms. There is a parameter, input.list, which lists the inputs included in that profile. Other parameters define the inputs; these are identified by the format input.ID. For example, this adds a generic input to a profile:
input.list=i1,i2,i3,i4
...
input.i4.class_id=genericInputImpl
input.i4.params.gi_display_name0=Name0
input.i4.params.gi_display_name1=Name1
input.i4.params.gi_display_name2=Name2
input.i4.params.gi_display_name3=Name3
input.i4.params.gi_param_enable0=true
input.i4.params.gi_param_enable1=true
input.i4.params.gi_param_enable2=true
input.i4.params.gi_param_enable3=true
input.i4.params.gi_param_name0=gname0
input.i4.params.gi_param_name1=gname1
input.i4.params.gi_param_name2=gname2
input.i4.params.gi_param_name3=gname3
input.i4.params.gi_num=4
For more information on what inputs, or form fields, are available, see Section A.1, “Input Reference”.

2.2.4. Defining Key Defaults in Profiles

There is one important thing to do when creating profiles: the Key Default must be added before the Subject Key Identifier Default. Certificate System processes the key constraints in the Key Default before creating or applying the Subject Key Identifier Default, so if the key has not been processed yet, setting the key in the subject name fails.
For example, an object-signing profile may define both defaults:
policyset.set1.p3.constraint.class_id=noConstraintImpl
policyset.set1.p3.constraint.name=No Constraint
policyset.set1.p3.default.class_id=subjectKeyIdentifierExtDefaultImpl
policyset.set1.p3.default.name=Subject Key Identifier Default
...
policyset.set1.p11.constraint.class_id=keyConstraintImpl
policyset.set1.p11.constraint.name=Key Constraint
policyset.set1.p11.constraint.params.keyType=-
policyset.set1.p11.constraint.params.keyMinLength=256
policyset.set1.p11.constraint.params.keyMaxLength=4096
policyset.set1.p11.default.class_id=userKeyDefaultImpl
policyset.set1.p11.default.name=Key Default
In the policyset list, then, the Key Default (p11) must be listed before the Subject Key Identifier Default (p3).
policyset.set1.list=p1,p2,p11,p3,p4,p5,p6,p7,p8,p9,p10

2.2.5. Configuring Cross-Pair Profiles

Bridge or cross-pair certificates are CA signing certificate that are framed as dual certificate pairs, similar to encryption and signing certificate pairs for users, only each certificate in the pair is issued by a different CA. Both partner CAs store the other CA signing certificate in its database, so all of the certificates issued within the other PKI are trusted and recognized.
Issuing cross-pair certificates requires the Certificate Policies Extension, explained in Section B.3.4, “certificatePoliciesExt”.
  1. Stop the CA server, so that you can edit the configuration files.
    service pki-ca stop
  2. Open the CA's CS.cfg file.
    vim /var/lib/pki-ca/conf/CS.cfg
  3. The Certificate Policies Extension default must be edited to specify cross-pair certificates.
     ca.Policy.rule.CertificatePoliciesExt.critical=false
     ca.Policy.rule.CertificatePoliciesExt.enable=false
     ca.Policy.rule.CertificatePoliciesExt.implName=CertificatePoliciesExt
     ca.Policy.rule.CertificatePoliciesExt.numCertPolicies=1
     ca.Policy.rule.CertificatePoliciesExt.predicate=HTTP_PARAMS.certType==fbca    
     ca.Policy.rule.CertificatePoliciesExt.certPolicy0.cpsURI=
     ca.Policy.rule.CertificatePoliciesExt.certPolicy0.noticeRefNumbers=
     ca.Policy.rule.CertificatePoliciesExt.certPolicy0.noticeRefOrganization=
     ca.Policy.rule.CertificatePoliciesExt.certPolicy0.policyId=
     ca.Policy.rule.CertificatePoliciesExt.certPolicy0.userNoticeExplicitText=
    This will set the extension to add the hidden value certType==fbca to the certificate profile enrollment form, tagging the certificate as a cross-pair certificate.
  4. Restart the CA server.
    service pki-ca start
  5. Create a new profile with the Certificate Policies Extension Default (certificatePoliciesExtDefaultImpl).
  6. As a CA agent, enable the certificate profile.

2.2.6. List of Certificate Profiles

The following pre-defined certificate profiles are ready to use when the Certificate System CA is installed. These certificate profiles have been designed for the most common types of certificates, and they provide common defaults and constraints, authentication methods, and inputs and outputs.
By default, the profile configuration files are in the /var/lib/subsystem_name/profiles/ca directory.

Table 2.2. Certificate Profiles

Profile ID Profile Name Description
caAdminCert Security Domain Administrator Certificate Enrollment Enrolls Security Domain Administrator's certificates with LDAP authentication against the internal LDAP database.
caAgentFileSigning Agent-Authenticated File Signing This certificate profile is for file signing with agent authentication.
caAgentServerCert Agent-Authenticated Server Certificate Enrollment Enrolls server certificates with agent authentication.
caCACert Manual Certificate Manager Signing Certificate Enrollment Enrolls Certificate Authority certificates.
caCMCUserCert Signed CMC-Authenticated User Certificate Enrollment Enrolls user certificates by using the CMC certificate request with CMC Signature authentication.
caDirUserCert Directory-Authenticated User Dual-Use Certificate Enrollment Enrolls user certificates with directory-based authentication.
caDirUserRenewal Directory-Authenticated User Certificate Self-Renew profile Renews user certificates through directory-based authentication. The user certificate is issued as soon as the requester successfully authenticates to the LDAP directory.

NOTE

Renewal profiles can only be used in conjunction with the profile that issued the original certificate. There are two settings that are beneficial:
  • It is important the original enrollment profile name does not change.
  • The Renew Grace Period Constraint should be set in the original enrollment profile. This defines the amount of time before and after the certificate's expiration date when the user is allowed to renew the certificate. There are only a few examples of these in the default profiles, and they are mostly not enabled by default.
caDualCert Manual User Signing & Encryption Certificates Enrollment Enrolls dual user certificates. It works only with Netscape 7.0 or later.
caDualRAuserCert RA Agent-Authenticated User Certificate Enrollment Enrolls user certificates with RA agent authentication.
caFullCMCUserCert Signed CMC-Authenticated User Certificate Enrollment Enrolls user certificates by using the CMC certificate request with CMC Signature authentication.
caInstallCACert Manual Security Domain Certificate Authority Signing Certificate Enrollment Enrolls Security Domain Certificate Authority certificates.
caInternalAuthAuditSigningCert Audit Signing Certificate Enrollment Enrolls a signing certificate to use for signing audit logs; used automatically during any subsystem configuration, with the exception of the RA.
caInternalAuthDRMstorageCert Security Domain DRM Storage Certificate Enrollment Enrolls DRM storage certificates for DRMs within a security domain; used automatically during a DRM configuration.
caInternalAuthOCSPCert Security Domain OCSP Manager Signing Certificate Enrollment Enrolls Security Domain OCSP Manager certificates.
caInternalAuthServerCert Security Domain Server Certificate Enrollment Enrolls Security Domain server certificates.
caInternalAuthSubsystemCert Security Domain Subsystem Certificate Enrollment Enrolls Security Domain subsystem certificates.
caInternalAuthTransportCert Security Domain Data Recovery Manager Transport Certificate Enrollment Enrolls Security Domain Data Recovery Manager transport certificates.
caManualRenewal Renew certificate to be manually approved by agents Renews a certificate that must be manually approved by agents.

NOTE

Renewal profiles can only be used in conjunction with the profile that issued the original certificate. There are two settings that are beneficial:
  • It is important the original enrollment profile name does not change.
  • The Renew Grace Period Constraint should be set in the original enrollment profile. This defines the amount of time before and after the certificate's expiration date when the user is allowed to renew the certificate. There are only a few examples of these in the default profiles, and they are mostly not enabled by default.
caOCSPCert Manual OCSP Manager Signing Certificate Enrollment Enrolls OCSP Manager certificates.
caOtherCert Other Certificate Enrollment Enrolls other certificates.
caRAagentCert RA Agent-Authenticated Agent User Certificate Enrollment Enrolls RA agent user certificates with RA agent authentication.
caRACert Manual Registration Manager Signing Certificate Enrollment Enrolls Registration Manager certificates.
caRARouterCert RA Agent-Authenticated Router Certificate Enrollment Enrolls router certificates after agent approval (as opposed to automatic enrollment).
caRAserverCert RA Agent-Authenticated Server Certificate Enrollment Enrolls server certificates with RA agent authentication.
caRouterCert One Time Pin Router Certificate Enrollment Enrolls router certificates using an automatically-generated, one-time PIN that the router can use to retrieve its certificate.
caServerCert Manual Server Certificate Enrollment Enrolls server certificates.
caSignedLogCert Manual Log Signing Certificate Enrollment Enrolls audit log signing certificates.
caSimpleCMCUserCert Simple CMC Enrollment Enrolls user certificates by using the CMC certificate request with CMC Signature authentication.
caSSLClientSelfRenewal Self-renew user SSL client certificates Renews SSL client certificates using certificate-based authentication. The certificate is issued as soon as the request is authenticated and authorized by presenting the original certificate.

NOTE

Renewal profiles can only be used in conjunction with the profile that issued the original certificate. There are two settings that are beneficial:
  • It is important the original enrollment profile name does not change.
  • The Renew Grace Period Constraint should be set in the original enrollment profile. This defines the amount of time before and after the certificate's expiration date when the user is allowed to renew the certificate. There are only a few examples of these in the default profiles, and they are mostly not enabled by default.
caTempTokenDeviceKeyEnrollment Temporary Device Certificate Enrollment Enrolls temporary keys to be used by servers or other network devices on a token; used by the TPS for smart card enrollment operations. These are temporary keys, valid for about a week, and intended to replace a temporarily lost token.
caTempTokenUserEncryptionKeyEnrollment Temporary Token User Encryption Certificate Enrollment Enrolls an encryption key on a token; used by the TPS for smart card enrollment operations. These are temporary keys, valid for about a week, and intended to replace a temporarily lost token.
caTempTokenUserSigningKeyEnrollment Temporary Token User Signing Certificate Enrollment Enrolls a signing key on a token; used by the TPS for smart card enrollment operations. These are temporary keys, valid for about a week, and intended to replace a temporarily lost token.
caTokenDeviceKeyEnrollment Token Device Key Enrollment Enrolls keys to be used by servers or other network devices on a token; used by the TPS for smart card enrollment operations.
caTokenMSLoginEnrollment Token User MS Login Certificate Enrollment Enrolls key to be used by a person for logging into a Windows domain or PC; used by the TPS for smart card enrollment operations.
caTokenUserEncryptionKeyEnrollment Token User Encryption Certificate Enrollment Enrolls an encryption key on a token; used by the TPS for smart card enrollment operations.
caTokenUserEncryptionKeyRenewal smart card token encryption cert renewal profile Renews an encryption key that was enrolled on a token using the caTokenUserEncryptionKeyEnrollment profile; used by a TPS subsystem.
caTokenUserSigningKeyEnrollment Token User Signing Certificate Enrollment Enrolls a signing key on a token; used by the TPS for smart card enrollment operations.
caTokenUserSigningKeyRenewal smart card token signing cert renewal profile Renews a signing that was enrolled on a token using the caTokenUserSigningKeyEnrollment profile; used by a TPS subsystem.
caTPSCert Manual TPS Server Certificate Enrollment Enrolls TPS server certificates.
caTransportCert Manual Data Recovery Manager Transport Certificate Enrollment Enrolls Data Recovery Manager transport certificates.
caUserCert Manual User Dual-Use Certificate Enrollment Enrolls user certificates.
caUUIDdevicecert Manual device Dual-Use Certificate Enrollment to contain UUID in SAN Enrolls certificates for devices which must contain a unique user ID number (UUID) as a component in the certificate's subject alternate name extension.
DomainController Domain Controller Enrolls certificates to be used by a Windows domain controller.

2.3. Configuring Custom Enrollment Profiles to Use with an RA

The profiles used to submit certificate requests through the RA are created and configured in the CA, as described in Section 2.2, “Setting up Certificate Profiles”. However, the way to process those requests and the specific profiles to use for the requests (both for existing and custom profiles) must be configured in the RA by calling on the RA's request queue plug-ins.

2.3.1. Default RA Profiles

There are already four types of certificates that are processed in the RA: SCEP (router), server, user, and RA agent.

Table 2.3. Profiles for the RA

Profile ID Profile Name Description
caDualRAuserCert RA Agent-Authenticated User Certificate Enrollment Enrolls user certificates with RA agent authentication.
caRAagentCert RA Agent-Authenticated Agent User Certificate Enrollment Enrolls RA agent user certificates with RA agent authentication.
caRACert Manual Registration Manager Signing Certificate Enrollment Enrolls Registration Manager certificates.
caRARouterCert RA Agent-Authenticated Router Certificate Enrollment Enrolls router certificates after agent approval (as opposed to automatic enrollment).
caRAserverCert RA Agent-Authenticated Server Certificate Enrollment Enrolls server certificates with RA agent authentication.
caRouterCert One Time Pin Router Certificate Enrollment Enrolls router certificates using an automatically-generated, one-time PIN that the router can use to retrieve its certificate.

2.3.2. Creating RA Enrollment Forms

Each certificate type configured for the RA has a subdirectory in /var/lib/pki-ra/docroot/ee/ which contains index files and enrollment and processing forms. Each rendered page has two files, a .cgi script file and .vm HTML template file.
It is easiest to simply copy the docroot directory for one of the existing profiles and adapt it to the new profile.
To configure new enrollment forms for the RA:
  1. Open the end-entities docroot directory.
    cd /var/lib/pki-ra/docroot/ee/
  2. Copy an existing directory to make a new profile directory. For example:
    cp -r user/ example/
  3. Edit the main index file for the end-entities directory to add the new example profile to the list of available profiles:
    vim index.vm
    
    ... snip ...
     <font size="+1" face="PrimaSans BT, Verdana, Arial, Helvetica, sans-serif">
     RA EE Services
     </font><br>
     <p>
     <center>
     <table border="0" cellspacing="0" cellpadding="0">
     <tr valign="TOP">     
     <td>     
     <font size=4 face="PrimaSans BT, Verdana, sans-serif">     
     <li><a href="/ee/example/index.cgi">Example Profile</a></li>      
     </font>     
     </td>     
     </tr>     
     <tr valign="TOP">
     <td>
     <font size=4 face="PrimaSans BT, Verdana, sans-serif">
     <li><a href="/ee/scep/index.cgi">SCEP Enrollment</a></li>
     </font>
     </td>
     </tr>
    ... snip ...
    
  4. Open the new profile directory.
    cd example/
  5. The user profile directory has three main sets of files:
    • index.cgi and index.vm are all used to generate the index page
    • renew.cgi, renew.vm, renewal.cgi, and renewal.vm are all used to process renewal requests
    • user.cgi, user.vm, submit.cgi, and submit.vm are all used to create and submit new certificate requests
    The index.cgi file is cited in the main end-entities index file.
  6. Optionally, rename the files. index.cgi and index.vm should stay the same.
    mv user.cgi example.cgi
    mv user.vm example.vm
    mv renew.cgi example-renew.cgi
    mv renew.vm example-renew.vm
    mv renewal.cgi example-renewal.cgi
    mv renewal.vm example-renewal.mv
    mv submit.cgi example-submit.cgi
    mv submit.vm example-submit.vm
  7. Update the descriptions and names in the index.vm file. Update the docroot paths to the example/ directory and, if the related certificate and renewal forms were renamed and are being used for the new profile, then change referenced .cgi the file names.
    <font size="+1" face="PrimaSans BT, Verdana, Arial, Helvetica, sans-serif">
    <a href="/ee/index.cgi">RA Services</a> : <a href="/ee/example/index.cgi">Example RA Profile</a><br />
    </font><br>
    <p>
    This is an example profile.
    <p>
    <center>
    <table borer="0" cellspacing="0" cellpadding="0">
    <tr valign="TOP">
    <td>
    <font size=4 face="PrimaSans BT, Verdana, sans-serif">
    <li><a href="example.cgi">New Example Cert</a></li>
    </font>
    </td>
    </tr>
    <tr valign="TOP">
    <td>
    <font size=4 face="PrimaSans BT, Verdana, sans-serif">
    <li><a href="example-renew.cgi">Renewing an Example Cert</a></li>
    </font>
    </td>
    </tr>
    </table>
    </center>
  8. Edit every .cgi and .vm so that the specified directories all point to the new example/ directory. For example:
    vim example.cgi
    
    ...
    my $result = $parser->execute_file_with_context("ee/example/example.vm", 
    ...
    
    vim example.vm
    
    ...
    example.vm:<a href="/ee/example/index.cgi">Example Certificate</a><br />
    ...

2.3.3. Configuring the Request Queues

For the new profile to be used in the RA, the last step is to create the request queue policy in the CS.cfg file for the RA instance.

2.3.3.1. Overview of Request Queue Plug-ins

Both the existing plug-ins and additional libraries can be used to create custom profiles or custom behaviors for the RA.

Table 2.4. RA Request Queue Plug-ins and Libraries

Plug-in or Library Location Description
PKI::Request::Plug-in::AutoAssign (plug-in) /var/lib/pki-ra/lib/perl/PKI/Request/Plug-in Automatically assigns a request to a group of agents.
PKI::Request::Plug-in::CreatePin (plug-in) /var/lib/pki-ra/lib/perl/PKI/Request/Plug-in Creates a one-time PIN for SCEP enrollment.
PKI::Request::Plug-in::EmailNotification (plug-in) /var/lib/pki-ra/lib/perl/PKI/Request/Plug-in Sends email notifications.
PKI::Request::Plug-in::RequestToCA (plug-in) /var/lib/pki-ra/lib/perl/PKI/Request/Plug-in Sends an enrollment request to the CA.
PKI::Base::CertStore (library) /var/lib/pki-ra/lib/perl/PKI/Base/CertStore Accesses the certificate store in the RA.
PKI::Base::PinStore (library) /var/lib/pki-ra/lib/perl/PKI/Base/PinStore Accesses the one-time PIN store.
PKI::Base::UserStore (library) /var/lib/pki-ra/lib/perl/PKI/Base/UserStore Accesses the user and group database.
PKI::Conn::CA (library) /var/lib/pki-ra/lib/perl/PKI/Conn/CA Accesses the CA for enrollment.
PKI::Request::Queue (library) /var/lib/pki-ra/lib/perl/PKI/Request/Queue Accesses the request queue in the RA.

2.3.3.2. Creating the Profile Entry

The response of the RA to each request is configured in the /var/lib/pki-ra/conf/CS.cfg file. There are three ways that a request can be handled — created, approved, and rejected — so each profile entry has to define the behaviors of the RA for those three scenarios. Much like a profile policy set, each operation is defined with a different group of parameters:
  • request.profile_name.approve_request, which specifies the plug-in to call when a request is approved.
  • request.profile_name.reject_request, which sets the plug-in to call when a request is rejected.
  • request.profile_name.create_request, which sets the plug-in to call when a request is created.
The profile_name in the parameter is the name of the directory in the /var/lib/pki-ra/docroot/ee directory for the new profile. For the default enrollment forms, these are scep, agent, server, and user.
The request submission configuration must specify the plug-in to call, the name of the profile to use to submit the request, the CA server to submit it to, and the format of the request. If there are multiple RA groups, then it can also automatically assign the request to a specific group for approval.

Example 2.2. Server Certificate Enrollment

 ... when a server certificate request is approved ...
 request.server.approve_request.0.ca=ca1
 request.server.approve_request.0.plugin=PKI::Request::Plugin::RequestToCA    
 request.server.approve_request.0.profileId=caRAserverCert
 request.server.approve_request.0.reqType=pkcs10
 request.server.approve_request.num_plugins=1

 ... when a server certificate request is submitted ...
 request.server.create_request.0.assignTo=agents
 request.server.create_request.0.plugin=PKI::Request::Plugin::AutoAssign  
 request.server.create_request.1.mailTo=dlackey@redhat.com
 request.server.create_request.1.plugin=PKI::Request::Plugin::EmailNotification    
 request.server.create_request.1.templateDir=/usr/share/pki/ra/conf
 request.server.create_request.1.templateFile=mail_create_request.vm
 request.server.create_request.num_plugins=2

 ... when the request is rejected ...
 request.server.reject_request.num_plugins=0

To create the entry:
  1. Stop the RA.
    service pki-ra stop
  2. Open the CS.cfg file.
    vim /var/lib/pki-ra/conf/CS.cfg
  3. Add the profile configuration entries for the new profile.
    request.example.approve_request.0.ca=ca1
    request.example.approve_request.0.plugin=PKI::Request::Plugin::RequestToCA
    request.example.approve_request.0.profileId=exampleProfile
    request.example.approve_request.0.reqType=crmf
    request.example.approve_request.1.mailTo=$created_by
    request.example.approve_request.1.plugin=PKI::Request::Plugin::EmailNotification
    request.example.approve_request.1.templateDir=/usr/share/pki/ra/conf
    request.example.approve_request.1.templateFile=mail_approve_request.vm
    request.example.approve_request.num_plugins=2
    request.example.create_request.0.assignTo=agents
    request.example.create_request.0.plugin=PKI::Request::Plugin::AutoAssign
    request.example.create_request.1.mailTo=admin@example.com
    request.example.create_request.1.plugin=PKI::Request::Plugin::EmailNotification
    request.example.create_request.1.templateDir=/usr/share/pki/ra/conf
    request.example.create_request.1.templateFile=mail_create_request.vm
    request.example.create_request.num_plugins=2
    request.example.reject_request.num_plugins=0
    For enrollments that require a one-time PIN (such as SCEP and agent certificates, by default), it is possible to specify whether to generate the PIN from the requester's name ($created_by), the site ID ($site_id), or the user ID ($uid). For example:
    request.example.approve_request.0.pinFormat=$uid
    Likewise, the email address to which to send the notification can be configured to a single administrator address or to the requester's address ($created_by). For example:
    request.example.approve_request.1.mailTo=$created_by
  4. Restart the RA.
    service pki-ra start

2.4. Managing Smart Card CA Profiles

The TPS does not generate or approve certificate requests; it sends any requests approved through the Enterprise Security Client to the configured CA to issue the certificate. This means that the CA actually contains the profiles to use for tokens and smart cards. The profiles to use can be automatically assigned, based on the card type, as described in Section 5.4, “Setting Token Types for Specified Smart Cards”.
The profile configuration files are in the /var/lib/subsystem_name/profiles/ca/ directory with the other CA profiles. The default profiles are listed in Table 2.5, “Default Token Certificate Profiles”.

Table 2.5. Default Token Certificate Profiles

Profile Name Configuration File Description
Regular Enrollment Profiles
Token Device Key Enrollment caTokenDeviceKeyEnrollment.cfg For enrolling tokens used for devices or servers.
Token User Encryption Certificate Enrollment caTokenUserEncryptionKeyEnrollment.cfg For enrolling encryption certificates on the token for a user.
Token User Signing Certificate Enrollment caTokenUserSigningKeyEnrollment.cfg For enrolling signing certificates on the token for a user.
Token User MS Login Certificate Enrollment caTokenMSLoginEnrollment.cfg For enrolling user certificates to use for single sign-on to a Windows domain or PC.
Temporary Token Profiles
Temporary Device Certificate Enrollment caTempTokenDeviceKeyEnrollment.cfg For enrolling certificates for a device on a temporary token.
Temporary Token User Encryption Certificate Enrollment caTempTokenUserEncryptionKeyEnrollment.cfg For enrolling an encryption certificate on a temporary token for a user.
Temporary Token User Signing Certificate Enrollment caTempTokenUserSigningKeyEnrollment.cfg For enrolling a signing certificates on a temporary token for a user.
Renewal Profiles[a]
Token User Encryption Certificate Enrollment (Renewal) caTokenUserEncryptionKeyRenewal.cfg For renewing encryption certificates on the token for a user, if renewal is allowed.
Token User Signing Certificate Enrollment (Renewal) caTokenUserSigningKeyRenewal.cfg For renewing signing certificates on the token for a user, if renewal is allowed.
[a] Renewal profiles can only be used in conjunction with the profile that issued the original certificate. There are two settings that are beneficial:
  • It is important the original enrollment profile name does not change.
  • The Renew Grace Period Constraint should be set in the original enrollment profile. This defines the amount of time before and after the certificate's expiration date when the user is allowed to renew the certificate. There are only a few examples of these in the default profiles, and they are mostly not enabled by default.

2.4.1. Editing Enrollment Profiles for the TPS

Administrators have the ability to customize the default smart card enrollment profiles, used with the TPS. For instance, a profile could be edited to include the user's email address in the Subject Alternative Name extension. The email address for the user is retrieved from the authentication directory. To configure the CA for LDAP access, change the following parameters in the profile files, with the appropriate directory information:
policyset.set1.p1.default.params.dnpattern=UID=$request.uid$, O=Token Key User
policyset.set1.p1.default.params.ldap.enable=true
policyset.set1.p1.default.params.ldap.basedn=ou=people,dc=host,dc=example,dc=com
policyset.set1.p1.default.params.ldapStringAttributes=uid,mail
policyset.set1.p1.default.params.ldap.ldapconn.host=localhost.example.com
policyset.set1.p1.default.params.ldap.ldapconn.port=389
These CA profiles come with LDAP lookup disabled by default. The ldapStringAttributes parameter tells the CA which LDAP attributes to retrieve from the company directory. For example, if the directory contains uid as an LDAP attribute name, and this will be used in the subject name of the certificate, then uid must be listed in the ldapStringAttributes parameter, and request.uid listed as one of the components in the dnpattern.
Editing certificate profiles is covered in Section 2.2, “Setting up Certificate Profiles”.

2.4.2. Creating Custom TPS Profiles

Certificate profiles are created as normal in the CA, but they also have to be configured in the TPS for it to be available for token enrollments.

TIP

New profiles are added with new released of Red Hat Certificate System. If an instance is migrated to Certificate System 8.0, then the new profiles need to be added to the migrated instance as if they are custom profiles.
  1. Create a new token profile for the issuing CA. Setting up profiles is covered in Section 2.2, “Setting up Certificate Profiles”.
  2. Copy the profile into the CA's profiles directory, /var/lib/subsystem_name/profiles/ca.
  3. Edit the CA CS.cfg file, and add the new profile references and the profile name to the CA's list of profiles. For example:
    vim /etc/subsystem_name/CS.cfg
    
    profile.list=caUserCert,...,caManualRenewal,tpsExampleEnrollProfile  
    ...
    profile.caTokenMSLoginEnrollment.class_id=caUserCertEnrollImpl
    profile.caTokenMSLoginEnrollment.config=/var/lib/subsystem_name/profiles/ca/tpsExampleEnrollProfile.cfg
  4. Edit the TPS CS.cfg file, and add a line to point to the new CA enrollment profile. For example:
    vim /etc/pki-tps/CS.cfg
    
    op.enroll.userKey.keyGen.signing.ca.profileId=tpsExampleEnrollProfile
  5. Restart the CA and TPS after editing the smart card profiles. For example:
    service pki-ca restart
    service pki-tps restart

2.4.3. Using the Windows Smart Card Logon Profile

The TPS uses a profile to generate certificates to use for single sign-on to a Windows domain or PC; this is the Token User MS Login Certificate Enrollment profile (caTokenMSLoginEnrollment.cfg).
However, there are some special considerations that administrators must account for when configuring Windows smart card login.
  • Issue a certificate to the domain controller, if it is not already configured for SSL.
  • Configure the smart card login per user, rather than as a global policy, to prevent locking out the domain administrator.
  • Enable CRL publishing to the Active Directory server because the domain controller checks the CRL at every login.

2.5. Setting the Signing Algorithms for Certificates

The CA's signing certificate can sign the certificates it issues with any public key algorithm supported by the CA. For example, an ECC signing certificate can sign both ECC and RSA certificate requests as long as both ECC and RSA algorithms are supported by the CA. An RSA signing certificate can can sign a PKCS #10 request with EC keys, but may not be able to sign CRMF certificate requests with EC keys if the ECC module is not available for the CA to verify the CRMF proof of possession (POP).

NOTE

Although Certificate System supports ECC, it does not support it natively. A PKCS#11 module which supports ECC must be loaded before the CA is configured in order for the CA to have an ECC signing certificate or to be able to verify the CRMF POP for certificate requests using EC keys.
Loading ECC modules is covered in the Certificate System Installation Guide.
ECC and RSA are public key encryption and signing algorithms. Both public key algorithms support different cipher suites, algorithms used to encrypt and decrypt data. Part of the function of the CA signing certificate is to issue and sign certificates using one of its supported cipher suites.
Each profile can define which cipher suite the CA should use to sign certificates processed through that profile. If no signing algorithm is set, then the profile uses whatever the default signing algorithm is.

2.5.1. Setting the CA's Default Signing Algorithm

  1. Open the CA console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, expand the Certificate Manager tree.
  3. In the General Settings tab, set the algorithm to use in the Algorithm drop-down menu.

2.5.2. Setting the Signing Algorithm Default in a Profile

Each profile has a Signing Algorithm Default extension defined. The default has two settings: a default algorithm and a list of allowed algorithms, if the certificate request specifies a different algorithm. If no signing algorithms are specified, then the profile uses whatever is set as the default for the CA.
In the profile's .cfg file, the algorithm is set with two parameters:
policyset.serverCertSet.8.default.class_id=signingAlgDefaultImpl
policyset.serverCertSet.8.default.name=Signing Alg
policyset.serverCertSet.8.default.params.signingAlg=SHA1withRSA
policyset.serverCertSet.8.default.params.signingAlgsAllowed=SHA1withRSA,SHA256withRSA,SHA512withRSA,MD5withRSA,MD2withRSA,SHA1withDSA,SHA1withEC
To configure the Signing Algorithm Default through the console:

NOTE

Before a profile can be edited, it must first be disabled by an agent.
  1. Open the CA console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, expand the Certificate Manager tree.
  3. Click the Certificate Profiles item.
  4. Click the Policies tab.
  5. Select the Signing Alg policy, and click the Edit button.
  6. To set the default signing algorithm, set the value in the Defaults tab. If this is set to -, then the profile uses the CA's default.
  7. To set a list of allowed signing algorithms which can be accepted in a certificate request, open the Constraints tab, and set the list of algorithms in the Value field for signingAlgsAllowed.
    The possible values for the constraint are listed in Section B.2.9, “Signing Algorithm Constraint”.

2.6. Managing CA-Related Profiles

Certificate profiles and extensions must be used to set rules on how subordinate CAs can issue certificates. There are two parts to this:
  • Managing the CA signing certificate
  • Defining issuance rules

2.6.1. Setting Restrictions on CA Certificates

When a subordinate CA is created, the root CA can impose limits or restrictions on the subordinate CA. For example, the root CA can dictate the maximum depth of valid certification paths (the number of subordinate CAs allowed to be chained below the new CA) by setting the pathLenConstraint field of the Basic Constraints extension in the CA signing certificate.
A certificate chain generally consists of an entity certificate, zero or more intermediate CA certificates, and a root CA certificate. The root CA certificate is either self-signed or signed by an external trusted CA. Once issued, the root CA certificate is loaded into a certificate database as a trusted CA.
An exchange of certificates takes place when performing an SSL handshake, when sending an S/MIME message, or when sending a signed object. As part of the handshake, the sender is expected to send the subject certificate and any intermediate CA certificates needed to link the subject certificate to the trusted root. For certificate chaining to work properly the certificates should have the following properties:
  • CA certificates must have the Basic Constraints extension.
  • CA certificates must have the keyCertSign bit set in the Key Usage extension.
  • When the CAs generate new keys, they must add the Authority Key Identifier extension to all subject certificates. This extensions helps distinguish the certificates from the older CA certificates. The CA certificates must contain the Subject Key Identifier extension.
For more information on certificates and their extensions, see Internet X.509 Public Key Infrastructure - Certificate and Certificate Revocation List (CRL) Profile (RFC 3280), available at RFC 3280.
These extensions can be configured through the certificate profile enrollment pages. By default, the CA contains the required and reasonable configuration settings, but it is possible to customize these settings.

NOTE

This procedure describes editing the CA certificate profile used by a CA to issue CA certificates to its subordinate CAs.
The profile that is used when a CA instance is first configured is /var/lib/subsystem_name/profiles/ca/caCert.profile. This profile cannot be edited in pkiconsole (since it is only available before the instance is configured). It is possible to edit the policies for this profile in the template file before the CA is configured using a text editor.
To modify the default in the CA signing certificate profile used by a CA:
  1. If the profile is currently enabled, it must be disabled before it can be edited. Open the agent services page, select Manage Certificate Profiles from the left navigation menu, select the profile, and click Disable profile.
  2. Open the CA Console.
    pkiconsole https://server.example.com:9445/ca
  3. In the left navigation tree of the Configuration tab, select Certificate Manager, then Certificate Profiles.
  4. Select caCACert, or the appropriate CA signing certificate profile, from the right window, and click Edit/View.
  5. In the Policies tab of the Certificate Profile Rule Editor, select and edit the Key Usage or Extended Key Usage Extension Default if it exists or add it to the profile.
  6. Select the Key Usage or Extended Key Usage Extension Constraint, as appropriate, for the default.
  7. Set the default values for the CA certificates. For more information, see Section B.1.8, “Key Usage Extension Default” and Section B.1.5, “Extended Key Usage Extension Default”.
  8. Set the constraint values for the CA certificates. There are no constraints to be set for a Key Usage extension; for an Extended Key Usage extension, set the appropriate OID constraints for the CA. For more information, see Section B.1.5, “Extended Key Usage Extension Default”.
  9. When the changes have been made to the profile, log into the agent services page again, and re-enable the certificate profile.
For more information on modifying certificate profiles, see Section 2.2, “Setting up Certificate Profiles” and the Certificate System Agent's Guide.

2.6.2. Changing the Restrictions for CAs on Issuing Certificates

The restrictions on the certificates issued are set by default after the subsystem is configured. These include:
  • Whether certificates can be issued with validity periods longer than the CA signing certificate. The default is to disallow this.
  • The signing algorithm used to sign certificates.
  • The serial number range the CA is able to use to issue certificates.
Subordinate CAs have constraints for the validity periods, types of certificates, and the types of extensions which they can issue. It is possible for a subordinate CA to issue certificates that violate these constraints, but a client authenticating a certificate that violates those constraints will not accept that certificate. Check the constraints set on the CA signing certificate before changing the issuing rules for a subordinate CA.
To change the certificate issuance rules, do the following:
  1. Open the Certificate System Console.
    pkiconsole https://server.example.com:9445/ca
  2. Select the Certificate Manager item in the left navigation tree of the Configuration tab.
    The General Settings Tab

    Figure 2.1. The General Settings Tab


  3. The General Setting tab of the Certificate Manager tab contains the following fields:
    • Override validity nesting requirement. This checkbox sets whether the Certificate Manager can issue certificates with validity periods longer than the CA signing certificate validity period.
      If this checkbox is not selected and the CA receives a request with validity period longer than the CA signing certificate's validity period, it automatically truncates the validity period to end on the day the CA signing certificate expires.
    • Certificate Serial Number. These fields display the serial number range for certificates issued by the Certificate Manager. The server assigns the serial number in the Next serial number field to the next certificate it issues and the number in the Ending serial number to the last certificate it issues.
      The serial number range allows multiple CAs to be deployed and balances the number of certificates each CA issues. The combination of an issuer name and a serial number uniquely identifies a certificate.

      NOTE

      The serial number ranges with cloned CAs are fluid. All cloned CAs share a common configuration entry which defines the next available range. When one CA starts running low on available numbers, it checks this configuration entry and claims the next range. The entry is automatically updated, so that the next CA gets a new range.
      For example, a master CA instance contains an entry which usually begins the range at 1:
      	
       dbs.beginReplicaNumber=1
       dbs.beginRequestNumber=1
       dbs.beginSerialNumber=1
       dbs.enableSerialManagement=true
       dbs.endReplicaNumber=95
       dbs.endRequestNumber=9980000
       dbs.endSerialNumber=ffe0000
       dbs.ldap=internaldb
       dbs.newSchemaEntryAdded=true
       dbs.replicaCloneTransferNumber=5
      A clone CA begins its range where the master CA range ends:
       
       dbs.beginReplicaNumber=97
       dbs.beginRequestNumber=9980001
       dbs.beginSerialNumber=ffe0001
       dbs.enableSerialManagement=true
       dbs.endReplicaNumber=100
       dbs.endRequestNumber=9990000
       dbs.endSerialNumber=fff0000
       dbs.ldap=internaldb
       dbs.newSchemaEntryAdded=true
       dbs.replicaCloneTransferNumber=5
      The serial number ranges have hex values.
      Serial number management can be enabled for CAs which are not cloned, if the parameters are set in the CS.cfg file. However, by default, serial number management is disabled unless a system is cloned, when it is automatically enabled.
      The serial number range cannot be updated manually through the console. The serial number ranges are read-only fields. If cloning or serial number management is not enabled, then the serial number range can be updated by editing the values in the CS.cfg file.
    • Default Signing Algorithm. Specifies the signing algorithm the Certificate Manager uses to sign certificates. The options are MD2withRSA, MD5withRSA, SHA1withRSA, SHA256withRSA, and SHA512withRSA, if the CA's signing key type is RSA.
      The signing algorithm specified in the certificate profile configuration overrides the algorithm set here.
  4. Click Save.

2.7. Managing Subject Names and Subject Alternative Names

The subject name of a certificate is a distinguished name (DN) that contains identifying information about the entity to which the certificate is issued. This subject name is built from standard LDAP directory components, such as email addresses, common names, and organizational units. These components are defined in X.500. In addition to — or even in place of — the subject name, the certificate can have a subject alternative name, which is a kind of extension set for the certificate that includes additional information that is not defined in X.500.
The naming components for both subject names and subject alternative names can be customized.

IMPORTANT

If the subject name is empty, then the Subject Alternative Name extension must be present and marked critical.

2.7.1. Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name

Information from an LDAP directory or that was submitted by the requester can be inserted into the subject alternative name of the certificate by using matching variables in the Subject Alt Name Extension Default configuration. This default sets the type (format) of information and then the matching pattern (variable) to use to retrieve the information. For example:
policyset.userCertSet.8.default.class_id=subjectAltNameExtDefaultImpl
policyset.userCertSet.8.default.name=Subject Alt Name Constraint
policyset.userCertSet.8.default.params.subjAltNameExtCritical=false
policyset.userCertSet.8.default.params.subjAltExtType_0=RFC822Name
policyset.userCertSet.8.default.params.subjAltExtPattern_0=$request.requestor_email$
policyset.userCertSet.8.default.params.subjAltExtGNEnable_0=true
This inserts the requester's email as the first CN component in the subject alt name. To use additional components, increment the Type_, Pattern_, and Enable_ values numerically, such as Type_1.
Configuring the subject alt name is detailed in Section B.1.17, “Subject Alternative Name Extension Default”, as well.
To insert LDAP components into the subject alt name of the certificate:
  1. Inserting LDAP attribute values requires enabling the user directory authentication plug-in, UidPwdDirAuth.
    1. Open the CA Console.
      pkiconsole https://server.example.com:9445/ca
    2. Select Authentication in the left navigation tree.
    3. In the Authentication Instance tab, click Add, and add an instance of the UidPwdDirAuth authentication plug-in.
    4. Set the information for the LDAP directory.
    5. Set the LDAP attributes to populate.
    6. Save the new plug-in instance.
    For information on configuring the LDAP authentication modules, see Section 9.2.1, “Setting up Directory-Based Authentication”.
  2. When the new authentication plug-in is added, the corresponding parameters are added to the CA's CS.cfg file. For example, this instance of the UidPwdDirAuth plug-in is set to populate the mail attribute:
     ...
     auths.instance.UserDirEnrollment.dnpattern=
     auths.instance.UserDirEnrollment.ldapByteAttributes=
     auths.instance.UserDirEnrollment.ldapStringAttributes=mail      
     auths.instance.UserDirEnrollment.pluginName=UidPwdDirAuth
     auths.instance.UserDirEnrollment.ldap.basedn=dc=example,dc=com
     auths.instance.UserDirEnrollment.ldap.maxConns=
     auths.instance.UserDirEnrollment.ldap.minConns=
     auths.instance.UserDirEnrollment.ldap.ldapconn.host=localhost
     auths.instance.UserDirEnrollment.ldap.ldapconn.port=389
     auths.instance.UserDirEnrollment.ldap.ldapconn.secureConn=false...
    The ldapStringAttributes parameter instructs the authentication plug-in to read the value of the mail attribute from the user's LDAP entry and put that value in the certificate request. When the value is in the request, the certificate profile policy can be set to insert that value for an extension value.
  3. To enable the CA to insert the LDAP attribute value in the certificate extension, edit the profile's configuration file, and insert a policy set parameter for an extension. For example, to insert the mail attribute value in the Subject Alternative Name extension in the caDirUser profile, do the following:
    cd /var/lib/subsystem_name/profiles/ca
    
    vi caDirUser.cfg
    
    policyset.setID.8.default.params.subjAltExtPattern_0=$request.auth_token.mail$
  4. Restart the CA.
    service pki-ca restart
For this example, certificates submitted through the caDirUser profile enrollment form will have the Subject Alternative Name extension added with the value of the requester's mail LDAP attribute. For example:
Identifier: Subject Alternative Name - 2.5.29.17
    Critical: no 
    Value: 
    RFC822Name: jsmith@example.com
There are many attributes which can be automatically inserted into certificates by being set as a token ($X$) in any of the Pattern_ parameters in the policy set. The common tokens are listed in Table 2.6, “Variables Used to Populate Certificates”, and the default profiles contain examples for how these tokens are used.

Table 2.6. Variables Used to Populate Certificates

Policy Set Token Description
$request.auth_token.cn$ The LDAP common name (cn) attribute of the user who requested the certificate.
$request.auth_token.mail$ The value of the LDAP email (mail) attribute of the user who requested the certificate.
$request.auth_token.tokenCertSubject$ The certificate subject name.
$request.auth_token.uid$ The LDAP user ID (uid) attribute of the user who requested the certificate.
$request.auth_token.user$
$request.auth_token.userDN$ The user DN of the user who requested the certificate.
$request.auth_token.userid$ The value of the user ID attribute for the user who requested the certificate.
$request.uid$ The value of the user ID attribute for the user who requested the certificate.
$request.profileRemoteAddr$ The IP address of the user making the request. This can be an IPv4 or an IPv6 address, depending on the client. An IPv4 address must be in the format n.n.n.n or n.n.n.n,m.m.m.m. For example, 128.21.39.40 or 128.21.39.40,255.255.255.00. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0, and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.
$request.profileRemoteHost$ The hostname or IP address of the user's machine. The hostname can be the fully-qualified domain name and the protocol, such as http://server.example.com. An IPv4 address must be in the format n.n.n.n or n.n.n.n,m.m.m.m. For example, 128.21.39.40 or 128.21.39.40,255.255.255.00. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0, and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.
$request.requestor_email$ The email address of the person who submitted the request.
$request.requestowner$ The person who submitted the request.
$request.subject$ The subject name DN of the entity to which the certificate is issued. For example, uid=jsmith, e=jsmith@example.com.
$request.tokencuid$ The card unique ID (CUID) of the smart card token used for requesting the enrollment.
$request.upn$ The Microsoft UPN. This has the format (UTF8String)1.3.6.1.4.1.311.20.2.3,$request.upn$.
$server.source$ Instructs the server to generate a version 4 UUID (random number) component in the subject name. This always has the format (IA5String)1.2.3.4,$server.source$.

2.7.2. Changing DN Attributes in CA-Issued Certificates

In certificates issued by the Certificate System, DNs identify the entity that owns the certificate. In all cases, if the Certificate System is connected with a Directory Server, the format of the DNs in the certificates should match the format of the DNs in the directory. It is not necessary that the names match exactly; certificate mapping allows the subject DN in a certificate to be different from the one in the directory.
In the Certificate System, the DN is based on the components, or attributes, defined in the X.509 standard. Table 2.7, “Allowed Characters for Value Types” lists the attributes supported by default. The set of attributes is extensible.

Table 2.7. Allowed Characters for Value Types

Attribute Value Type Object Identifier
cn DirectoryString 2.5.4.3
ou DirectoryString 2.5.4.11
o DirectoryString 2.5.4.10
c PrintableString , two-character 2.5.4.6
l DirectoryString 2.5.4.7
st DirectoryString 2.5.4.8
street DirectoryString 2.5.4.9
title DirectoryString 2.5.4.12
uid DirectoryString 0.9.2342.19200300.100.1.1
mail IA5String 1.2.840.113549.1.9.1
dc IA5String 0.9.2342.19200300.100.1.2.25
serialnumber PrintableString 2.5.4.5
unstructuredname IA5String 1.2.840.113549.1.9.2
unstructuredaddress PrintableString 1.2.840.113549.1.9.8

By default, the Certificate System supports the attributes identified in Table 2.7, “Allowed Characters for Value Types”. This list of supported attributes can be extended by creating or adding new attributes. The syntax for adding additional X.500Name attributes, or components, is as follows:
X500Name.NEW_ATTRNAME.oid=n.n.n.n
X500Name.NEW_ATTRNAME.class=string_to_DER_value_converter_class
The value converter class converts a string to an ASN.1 value; this class must implement the netscape.security.x509.AVAValueConverter interface. The string-to-value converter class can be one of the following:
  • netscape.security.x509.PrintableConverter converts a string to a PrintableString value. The string must have only printable characters.
  • netscape.security.x509.IA5StringConverter converts a string to an IA5String value. The string must have only IA5String characters.
  • netscape.security.x509.DirStrConverter converts a string to a DirectoryString. The string is expected to be in DirectoryString format according to RFC 2253.
  • netscape.security.x509.GenericValueConverter converts a string character by character in the following order, from the smallest characterset to the largest:
    • Printable
    • IA5String
    • BMPString
    • Universal String
An attribute entry looks like the following:
X500Name.MY_ATTR.oid=1.2.3.4.5.6
X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter

2.7.2.1. Adding New or Custom Attributes

To add a new or proprietary attribute to the Certificate System schema, do the following:
  1. Stop the Certificate Manager.
    service pki-ca stop
  2. Open the /var/lib/pki-ca/conf directory.
  3. Open the configuration file, CS.cfg.
  4. Add the new attributes to the configuration file.
    For example, to add three proprietary attributes, MYATTR1 that is a DirectoryString, MYATTR2 that is an IA5String, and MYATTR3 that is a PrintableString, add the following lines at the end of the configuration file:
    X500Name.attr.MYATTR1.oid=1.2.3.4.5.6
    X500Name.attr.MYATTR1.class=netscape.security.x509.DirStrConverter
    X500Name.attr.MYATTR2.oid=11.22.33.44.55.66
    X500Name.attr.MYATTR2.class=netscape.security.x509.IA5StringConverter
    X500Name.attr.MYATTR3.oid=111.222.333.444.555.666
    X500Name.attr.MYATTR3.class=netscape.security.x509.PrintableConverter
    
  5. Save the changes, and close the file.
  6. Restart the Certificate Manager.
    service pki-ca start
  7. Reload the enrollment page and verify the changes; the new attributes should show up in the form.
  8. To verify that the new attributes are in effect, request a certificate using the manual enrollment form.
    Enter values for the new attributes so that it can be verified that they appear in the certificate subject names. For example, enter the following values for the new attributes and look for them in the subject name:
    MYATTR1: a_value
    MYATTR2: a.Value
    MYATTR3: aValue
    cn: John Doe
    o: Example Corporation
    
  9. Open the agent services page, and approve the request.
  10. When the certificate is issued, check the subject name. The certificate should show the new attribute values in the subject name.

2.7.2.2. Changing the DER-Encoding Order

It is possible to change the DER-encoding order of a DirectoryString, so that the string is configurable since different clients support different encodings.
The syntax for changing the DER-encoding order of a DirectoryString is as follows:
X500Name.dirStringEncodingOrder=encoding_list_separated_by_commas
The possible encoding values are as follows:
  • Printable
  • IA5String
  • UniversalString
  • BMPString
  • UTF8String
For example, the DER-encoding ordered can be listed as follows:
X500Name.dirEncodingOrder=Printable,BMPString
To change the DirectoryString encoding, do the following:
  1. Stop the Certificate Manager.
    service pki-ca stop
  2. Open the /var/lib/pki-ca/conf/ directory.
  3. Open the CS.cfg configuration file.
  4. Add the encoding order to the configuration file.
    For example, to specify two encoding values, PrintableString and UniversalString, and the encoding order is PrintableString first and UniversalString next, add the following line at the end of the configuration file:
    X500Name.directoryStringEncodingOrder=PrintableString, UniversalString
    
  5. Save the changes, and close the file.
  6. Start the Certificate Manager.
    service pki-ca start
  7. To verify that the encoding orders are in effect, enroll for a certificate using the manual enrollment form. Use John_Doe for the cn.
  8. Open the agent services page, and approve the request.
  9. When the certificate is issued, use the dumpasn1 tool to examine the encoding of the certificate. The dumpasn1 tool can be downloaded at http://fedoraproject.org/extras/4/i386/repodata/repoview/dumpasn1-0-20050404-1.fc4.html.
    The cn component of the subject name should be encoded as a UniversalString.
  10. Create and submit a new request using John Smith for the cn.
    The cn component of the subject name should be encoded as a PrintableString.

2.7.3. Customizing the Subject DN in a Certificate Request Issued by an RA

By default, the DN is taken from the input provided by the user on the User Enrollment page, specifically "UID" and "Your Email." For example, "UID=yourUID, E=youremail@example.com". You can customize the DN by editing the user.vm file for the RA.

IMPORTANT

Firefox and Internet Explorer use different certificate formats. Therefore, the modifications required are slightly different, depending on the browser the end users will be using.

2.7.3.1. Customizing the Subject DN in a Certificate Request for Firefox

Firefox uses CRMF format for certificate requests.
  1. Edit the user.vm file. By default, this is located in the /var/lib/pki-ra/docroot/ee/user/ directory.
  2. Locate the validate function and form the preferred DN in the var dn= statement. For example:
    var dn = "uid="+x+".e="+e;
    x is the UID and e is the email.

    WARNING

    The Subject DN must match the pattern specified in the Subject Name Constraint definition of the enrollment profile. The default user enrollment profile is specified by /var/lib/pki-ca/profiles/ca/caDualRAuserCert.cfg.
    For example:
    policyset.userCertSet.1.constraint.name=Subject Name Constraint
    policyset.userCertSet.1.constraint.params.pattern=UID=.*
    policyset.userCertSet.1.constraint.params.accept=true
    Using this definition, certificates are only issued if the subject name matches the pattern "UID=.*". Otherwise, the certificate request is rejected.
  3. Add any custom fields to the enrollment form, so that the enrollment form requests all of the information required to form the custom DN. The request form only requests the UID, site ID, and email. The enrollment form is defined at the end of the user.vm file. For example:
    <tr>
    <td>District:</td>
    <td><input type=text name=district value=""></td>
    </tr>
    
  4. Save the user.vm file.
  5. Restart the RA.
    service pki-ra restart

2.7.3.2. Customizing the Subject DN in a Certificate Request for Internet Explorer

Internet Explorer uses PKCS#10 format for certificate requests.
  1. Edit the user.vm file to add the new subject DN format and the updated enrollment form as described in Section 2.7.3.1, “Customizing the Subject DN in a Certificate Request for Firefox”.
  2. To configure the certificate request to have the appropriate PKCS#10 format for Internet Explorer, edit the Sub Send_OnClick function in the Visual Basic blob in user.vm. Form the preferred DN in the szName statement. For example, to add the organization (O=) element to the subject DN:
     ' Contruct the X500 distinguished name
       szName = "0.9.2342.19200300.100.1.1=" & TheForm.uid.Value & ",E=" &
    TheForm.email.Value & ",CN=" & TheForm.cn.Value & ",O=" & TheForm.org.Value"
  3. Save the user.vm file.
  4. Restart the RA.
    service pki-ra restart

Chapter 3. Setting up Key Archival and Recovery

This chapter explains how to use the Data Recovery Manager (DRM) to archive private keys and to recover these archived keys to restore encrypted data.

NOTE

Server-side key generation is an option provided for smart card enrollments performed through the TPS subsystem. This chapter deals with archiving keys through client-side key generation, not the server-side key generation and archivals initiated through the TPS.
Archiving private keys offers protection for users, and for information, if that key is ever lost. Information is encrypted by the public key when it is stored. The corresponding private key must be available to decrypt the information. If the private key is lost, the data cannot be retrieved. A private key can be lost because of a hardware failure or because the key's owner forgets the password or loses the hardware token in which the key is stored. Similarly, encrypted data cannot be retrieved if the owner of the key is unavailable to supply it.
When the DRM is configured, joins a security domain, and is issued a subsystem certificate by a Certificate System CA, it is configured to archive and recover private encryption keys. However, if the DRM certificates are issued by an external CA rather than one of the CAs within the security domain, then the key archival and recovery process must be set up manually.

3.1. About Key Archival and Recovery

Key archival requires only two things: a client (meaning a browser) which can generate dual keys and a certificate profile which is configured to support key archival.

NOTE

For user dual key pairs, only keys that are used exclusively for encrypting data should be archived; signing keys should never be archived. Having two copies of a signing key would defeat the certainty with which the key identifies its owner; a second archived copy could be used to impersonate the digital identity of the original key owner.
With single keys, the same key is used for encryption and signing, so single keys should not be archived, for the same reason that signing keys should not be.
The DRM automatically archives private encryption keys if archiving is configured.
If an end entity loses a private encryption key or is unavailable to use the private key, the key must be recovered before any data that was encrypted with the corresponding public key can be read. Recovery is possible if the private key was archived when the key was generated.
The DRM stores private encryption keys in a secure key repository in its internal database; each key is encrypted and stored as a key record and is given a unique key identifier. When a Certificate Manager receives a certificate request that contains the key archival option, it automatically forwards the request to the DRM to archive the encryption key. The private key is encrypted by the transport key, and the DRM receives the encrypted copy and stores the key in its key repository.
The archived copy of the key remains wrapped with the DRM's storage key. It can be decrypted, or unwrapped, only by using the corresponding private key pair of the storage certificate. A combination of one or more key recovery (or DRM) agents' certificates authorizes the DRM to complete the key recovery to retrieve its private storage key and use it to decrypt/recover an archived private key. The DRM indexes stored keys by key number, owner name, and a hash of the public key, allowing for highly efficient searching.
Figure 3.1, “How the Key Archival Process Works” illustrates how the key archival process occurs when an end entity requests a certificate.
How the Key Archival Process Works

Figure 3.1. How the Key Archival Process Works


Both subsystems subject the request to configured certificate profile constraints at appropriate stages. If the request fails to meet any of the profile constraints, the subsystem rejects the request.
The DRM supports agent-initiated key recovery, when designated recovery agents use the key recovery form on the DRM agent services page to process and approve key recovery requests. With the approval of a specified number of agents, an organization can recover keys when the key's owner is unavailable or when keys have been lost.
In key recovery authorization, one of the key recovery agents informs all required recovery agents about an impending key recovery. All recovery agents access the DRM key recovery page. One of the agents initiates the key recovery process. The DRM returns a notification to the agent includes a recovery authorization reference number identifying the particular key recovery request that the agent is required to authorize. Each agent uses the reference number and authorizes key recovery separately.

3.2. Setting up Key Archival

NOTE

Key archival is only possible using clients which support dual key pairs.
Key archival requires two things:
  • Having a trusted relationship between a CA and a DRM.
  • Having the enrollment form enabled for key archival, meaning it has key archival configured and the DRM transport certificate stored in the form.
Both of these configuration steps are done automatically when the DRM is configured because it is configured to have a trusted relationship with a CA. It is also possible to created that trusted relationship with Certificate Managers outside its security domain by manually configuring the trust relationships and profile enrollment forms.
  1. If necessary, create a trusted manager to establish a relationship between the Certificate Manager and the DRM.
    For the CA to be able to request key archival of the DRM, the two subsystems must be configured to recognize, trust, and communicate with each other. Verify that the Certificate Manager has been set up as a privileged user, with an appropriate SSL client authentication certificate, in the internal database of the DRM. By default, the Certificate Manager uses its subsystem certificate for SSL client authentication to the DRM.
    Follow the instructions in Section 14.3.2.5, “Setting up a Trusted Manager”, and set up the CA as a trusted manager to the DRM.
  2. Copy the base-64 encoded transport certificate for the DRM.
    The transport certificate is stored in the DRM's certificate database, which can be retrieved using the certutil utility. If the transport certificate is signed by a Certificate Manager, then a copy of the certificate is available through the Certificate Manager end-entities page in the Retrieval tab.
  3. Add the transport certificate to the CA's CS.cfg file.
    ca.connector.KRA.enable=true
    ca.connector.KRA.host=server.example.com
    ca.connector.KRA.local=false
    ca.connector.KRA.nickName=subsystemCert cert-pki-ca
    ca.connector.KRA.port=10444
    ca.connector.KRA.timeout=30
    ca.connector.KRA.transportCert=MIIDbDCCAlSgAwIBAgIBDDANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9Eb21haW4gc28gbmFtZWQxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0wNjExMTQxODI2NDdaFw0wODEwMTQxNzQwNThaMD4xGDAWBgNVBAoTD0RvbWFpbiBzbyBuYW1lZDEiMCAGA1UEAxMZRFJNIFRyYW5zcG9ydCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKnMGB3WkznueouwZjrWLFZBLpKt6TimNKV9iz5s0zrGUlpdt81/BTsU5A2sRUwNfoZSMs/d5KLuXOHPyGtmC6yVvaY719hr9EGYuv0Sw6jb3WnEKHpjbUO/vhFwTufJHWKXFN3V4pMbHTkqW/x5fu/3QyyUre/5IhG0fcEmfvYxIyvZUJx+aQBW437ATD99Kuh+I+FuYdW+SqYHznHY8BqOdJwJ1JiJMNceXYAuAdk+9t70RztfAhBmkK0OOP0vH5BZ7RCwE3Y/6ycUdSyPZGGc76a0HrKOz+lwVFulFStiuZIaG1pv0NNivzcj0hEYq6AfJ3hgxcC1h87LmCxgRWUCAwEAAaN5MHcwHwYDVR0jBBgwFoAURShCYtSg+Oh4rrgmLFB/Fg7X3qcwRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUFBzABhihodHRwOi8vY2x5ZGUucmR1LnJlZGhhdC5jb206OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIE8DANBgkqhkiG9w0BAQUFAAOCAQEAFYz5ibujdIXgnJCbHSPWdKG0T+FmR67YqiOtoNlGyIgJ42fi5lsDPfCbIAe3YFqmF3wU472h8LDLGyBjy9RJxBj+aCizwHkuoH26KmPGntIayqWDH/UGsIL0mvTSOeLqI3KM0IuH7bxGXjlION83xWbxumW/kVLbT9RCbL4216tqq5jsjfOHNNvUdFhWyYdfEOjpp/UQZOhOM1d8GFiw8N8ClWBGc3mdlADQp6tviodXueluZ7UxJLNx3HXKFYLleewwIFhC82zqeQ1PbxQDL8QLjzca+IUzq6Cd/t7OAgvv3YmpXgNR0/xoWQGdM1/YwHxtcAcVlskXJw5ZR0Y2zA==
    ca.connector.KRA.uri=/kra/agent/kra/connector
  4. Then edit the enrollment form and add or replace the transport certificate value in the keyTransportCert method.
    vim /var/lib/pki-ca/webapps/ca/ee/ca/ProfileSelect.template
    
    var keyTransportCert = MIIDbDCCAlSgAwIBAgIBDDANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9Eb21haW4gc28gbmFtZWQxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0wNjExMTQxODI2NDdaFw0wODEwMTQxNzQwNThaMD4xGDAWBgNVBAoTD0RvbWFpbiBzbyBuYW1lZDEiMCAGA1UEAxMZRFJNIFRyYW5zcG9ydCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKnMGB3WkznueouwZjrWLFZBLpKt6TimNKV9iz5s0zrGUlpdt81/BTsU5A2sRUwNfoZSMs/d5KLuXOHPyGtmC6yVvaY719hr9EGYuv0Sw6jb3WnEKHpjbUO/vhFwTufJHWKXFN3V4pMbHTkqW/x5fu/3QyyUre/5IhG0fcEmfvYxIyvZUJx+aQBW437ATD99Kuh+I+FuYdW+SqYHznHY8BqOdJwJ1JiJMNceXYAuAdk+9t70RztfAhBmkK0OOP0vH5BZ7RCwE3Y/6ycUdSyPZGGc76a0HrKOz+lwVFulFStiuZIaG1pv0NNivzcj0hEYq6AfJ3hgxcC1h87LmCxgRWUCAwEAAaN5MHcwHwYDVR0jBBgwFoAURShCYtSg+Oh4rrgmLFB/Fg7X3qcwRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUFBzABhihodHRwOi8vY2x5ZGUucmR1LnJlZGhhdC5jb206OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIE8DANBgkqhkiG9w0BAQUFAAOCAQEAFYz5ibujdIXgnJCbHSPWdKG0T+FmR67YqiOtoNlGyIgJ42fi5lsDPfCbIAe3YFqmF3wU472h8LDLGyBjy9RJxBj+aCizwHkuoH26KmPGntIayqWDH/UGsIL0mvTSOeLqI3KM0IuH7bxGXjlION83xWbxumW/kVLbT9RCbL4216tqq5jsjfOHNNvUdFhWyYdfEOjpp/UQZOhOM1d8GFiw8N8ClWBGc3mdlADQp6tviodXueluZ7UxJLNx3HXKFYLleewwIFhC82zqeQ1PbxQDL8QLjzca+IUzq6Cd/t7OAgvv3YmpXgNR0/xoWQGdM1/YwHxtcAcVlskXJw5ZR0Y2zA==;

3.3. Setting up Agent-Approved Key Recovery Schemes

Key recovery agents collectively authorize and retrieve private encryption keys and associated certificates in a PKCS #12 package. To authorize key recovery, the required number of recovery agents access the DRM agent services page and use the Authorize Recovery button to enter each authorization separately.
In key recovery authorization, one of the key recovery agents informs all required recovery agents about an impending key recovery. All recovery agents access the DRM key recovery page. One of the agents initiates the key recovery process. The DRM returns a notification to the agent includes a recovery authorization reference number identifying the particular key recovery request that the agent is required to authorize. Each agent uses the reference number and authorizes key recovery separately.
The page that the first agent used to initiate the key recovery request keeps refreshing until all agents required to authorize have performed the authorization. It is important that the first agent does not close this browser session until the authorization is complete. Otherwise, the key recovery request needs to be started again.
When all of the authorizations are entered, the DRM checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process.
The key recovery agent scheme configures the DRM to recognize to which group the key recovery agents belong and specifies how many of these agents are required to authorize a key recovery request before the archived key is restored.
To set up agent-initiated key recovery, edit two parameters in the DRM configuration:
  • Set the number of recovery managers to require to approve a recovery.
  • Set the group to which these users must belong.
These parameters are set in the DRM's CS.cfg configuration file.
  1. Stop the server before editing the configuration file.
    service pki-kra stop
  2. Open the DRM's CS.cfg file.
    vim /var/lib/pki-kra/conf/CS.cfg
  3. Edit the two recovery scheme parameters.
    kra.noOfRequiredRecoveryAgents=3
    kra.recoveryAgentGroup=Data Recovery Manager Agents
  4. Restart the server.
    service pki-kra start
The default key agent scheme requires a single agent from the Data Recovery Manager Agents group to be in charge of authorizing key recovery.
It is also possible to customize the appearance of the key recovery form. Key recovery agents need an appropriate page to initiate the key recovery process. By default, the DRM's agent services page includes the appropriate HTML form to allow key recovery agents to initiate key recovery, authorize key recovery requests, and retrieve the encryption keys. This form is located in the /var/lib/pki-kra/webapps/kra/agent/kra/ directory, called confirmRecover.html.

IMPORTANT

If the key recovery confirmation form is customized, do not to delete any of the information for generating the response. This is vital to the functioning of the form. Restrict any changes to the content in and appearance of the form.

3.4. Testing the Key Archival and Recovery Setup

To test whether a key can be successfully archived:
  1. Enroll for dual certificates using the CA's Manual User Signing & Encryption Certificates Enrollment form.
  2. Submit the request. Log in to the agent services page, and approve the request.
  3. Log into the end-entities page, and check to see if the certificates have been issued. In the list of certificates, there should be two new certificates with consecutive serial numbers.
  4. Import the certificates into the web browser.
  5. Confirm that the key has been archived. In the DRM's agent services page, select Show completed requests. If the key has been archived successfully, there will be information about that key. If the key is not shown, check the logs, and correct the problem. If the key has been successfully archived, close the browser window.
  6. Verify the key. Send a signed and encrypted email. When the email is received, open it, and check the message to see if it is signed and encrypted. There should be a security icon at the top-right corner of the message window that indicates that the message is signed and encrypted.
  7. Delete the certificate. Check the encrypted email again; the mail client should not be able to decrypt the message.
  8. Test whether an archived key can be recovered successfully:
    1. Open the DRM's agent services page, and click the Recover Keys link. Search for the key by the key owner, serial number, or public key. If the key has been archived successfully, the key information will be shown.
    2. Click Recover.
    3. In the form that appears, enter the PKCS #12 password which encrypts the PKCS #12 package and the base-64 encoded certificate that corresponds to the private key to recover; use the CA to get this information. If the archived key was searched for by providing the base-64 encoded certificate, then the certificate does not have to be supplied here.
    4. The next screen returns a key recovery authorization number and a link to verify the status of this key recovery initiation request. This page keeps refreshing until all agents have completed authorizing the recovery request. It is important not to close this browser window.
      Depending on the agent scheme, a specified number of agents must authorize this key recovery. Send this key recovery request authorization number to each of those agents. Once the agents receive this key recovery authorization number, they can authorize this request by going to the DRM agent services page and clicking the Authorize Recovery link.
    5. Once all the agents have authorized the recovery, the next screen returns a link to download a PKCS #12 blob containing the recovered key pair. Follow the link, and save the blob to file.
  9. Restore the key to the browser's database. Import the .p12 file into the browser and mail client.
  10. Open the test email. The message should be shown again.

Chapter 4. Requesting, Enrolling, and Managing Certificates

Certificates are requested and used by end users. Although certificate enrollment and renewal are operations that are not limited to administrators, understanding the enrollment and renewal processes can make it easier for administrators to manage and create appropriate certificate profiles, as described in Section 2.2, “Setting up Certificate Profiles”, and to use fitting authentication methods (described in Chapter 9, Authentication for Enrolling Certificates) for each certificate type.
This chapter discusses requesting, receiving, and renewing certificates for use outside Certificate System. For information on requesting and renewing Certificate System subsystem certificates, see Chapter 16, Managing Subsystem Certificates.

4.1. About Enrolling and Renewing Certificates

Enrollment is the process for requesting and receiving a certificate. The mechanics for the enrollment process are slightly different depending on the type of certificate, the method for generating its key pair, and the method for generating and approving the certificate itself. Whatever the specific method, certificate enrollment, at a high level, has the same basic steps:
  1. A user generates a certificate request.
    There are several methods of generating a certificate request, and it depends on the type of certificate which method is best. The certutil command can be used to generate a certificate request for any certificate type, and then this request is submitted to the CA's end entities forms; this is most appropriate for server or device certificates. Some certificate profiles accept inputs that generate both the request and (when approved) the certificate; this is the easiest method for user certificates. Lastly, the Java-based subsystems (CA, DRM, OCSP, and TKS) can generate certificate request for their subsystem certificates through their consoles.
  2. The certificate request is submitted to the CA using its relevant end-entity web forms.
  3. The request is verified by authenticating the entity which requested it and by confirming that it meets the certificate profile rules which was used to submit it.
  4. The request is approved.
  5. The user retrieves the new certificate.
When the certificate reaches the end of its validity period, then it can be renewed through the end user services pages. The renewal forms use the serial number or the certificate itself to identify the certificate entry in the CA databases. The renewal process then pulls up the original key, certificate request, and profile, and regenerates the certificate.

4.2. Configuring Internet Explorer to Enroll Certificates

Because of the security settings in Microsoft Windows Vista, requesting and enrolling certificates through the end entities pages using Internet Explorer 7 and 8 requires extra browser configuration. The browser has to be configured to trust the CA before it can access the CA's secure end entities pages.

NOTE

This configuration is not necessary to use Internet Explorer 7 and 8 on Microsoft Windows 2000, 2003, or XP.
  1. Open Internet Explorer.
  2. Import the CA certificate chain.
    1. Open the unsecure end services page for the CA.
      http://server.example.com:9180/ca/ee/ca
    2. Click the Retrieval tab.
    3. Click Import CA Certificate Chain in the left menu, and then select Download the CA certificate chain in binary form.
    4. When prompted, save the CA certificate chain file.
    5. In the Internet Explorer menu, click Tools, and select Internet Options.
    6. Open the Content tab, and click the Certificates button.
    7. Click the Import button. In the import window, browse for and select the imported certificate chain.
      The import process prompts for which certificate store to use for the CA certificate chain. Select Automatically select the certificate store based on the type of certificate.
    8. Once the certificate chain is imported, open the Trusted Root Certificate Authorities tab to verify that the certificate chain was successfully imported.
  3. After the certificate chain is imported, Internet Explorer can access the secure end services pages. Open the secure site.
    https://server.example.com:9443/ca/ee/ca
  4. There is probably a security exception when opening the end services pages. Add the CA services site to Internet Explorer's Trusted Sites list.
    1. In the Internet Explorer menu, click Tools, and select Internet Options.
    2. Open the Security tab, and click Sites to add the CA site to the trusted list.
    3. Set the Security level for this zone slider for the CA services page to Medium; if this security setting is too restrictive in the future, then try resetting it to Medium-low.
  5. Close the browser.
To verify that Internet Explorer can be used for enrollments, try enrolling a user certificate, as described in Section 4.3.1, “Requesting and Receiving a User or Agent Certificate through the End-Entities Page”.

4.3. Requesting and Receiving Certificates

The first step for getting a certificate is generating the request, which is then submitted to the issuing CA. Some Certificate System profiles allow users to request a certificate right through the web services pages, and the profile generates and submits the request in a single step. For other profiles, the request must be generated separately.
Virtually all certificate requests are processed through the end entities services for the CA, which provide the web-based profile forms, and the issued certificates are then retrieved from these pages. This section details the most common certificate enrollment processes.

4.3.1. Requesting and Receiving a User or Agent Certificate through the End-Entities Page

End entities can use the HTML enrollment forms on the Certificate Management end-entities page to create user certificates for email and SSL authentication. Other enrollment forms are available for adding certificates to tokens and signing files. For more information about the end-entities enrollment forms, see the Certificate System Agent's Guide.
The following profiles are used to create user certificates:
  • Manual User Dual-Use Certificate Enrollment
  • Manual User Signing and Encryption Certificates Enrollment
  • Directory-Authenticated User Dual-Use Certificate Enrollment (if directory authentication has been configured)

NOTE

It is important that the agent or user generate and submit the client request from the computer that will be used later to access the subsystem because part of the request process generates a private key on the local machine. If location independence is required, the user can also use a hardware token, such as a smart card, to store the key pair and the certificate.
  1. Open the Certificate Manager's end-entities page.
    https://server.example.com:9444/ca/ee/ca
  2. Select the user certificate enrollment form from the list of certificate profiles.
  3. Fill in the user information.

    NOTE

    The CA certificate request forms support all UTF-8 characters for the common name, organizational unit, and requester name fields. The common name and organization unit fields are included in the subject name of the certificate.
    This support does not include supporting internationalized domain names.
  4. Click Submit.
  5. The key pairs for the user certificate are generated, and the certificate request is sent to the agent queue. Alternatively, if automatic enrollment is configured, the certificate is approved (or rejected) by the server, and the new certificate is displayed in the web browser window.
  6. Once the certificate is approved and generated, the CA sends a notification that you can retrieve the certificate.
    1. Open the Certificate Manager end-entities page.
      https://server.example.com:9444/ca/ee/ca
    2. Click the Retrieval tab.
    3. Fill in the request ID number that was created when the certificate request was submitted, and click Submit.
    4. The next page shows the status of the certificate request. If the status is complete, then there is a link to the certificate. Click the Issued certificate link.
    5. The new certificate information is shown in pretty-print format, in base-64 encoded format, and in PKCS #7 format.
      There are two actions that can be taken through this page:
      • To install this certificate on a server or other application, scroll down to the Installing This Certificate in a Server section, which contains the base-64 encoded certificate.
      • If this is a client certificate that will be installed directly in the web browser, scroll down to the Importing This Certificate section, and click the Import your certificate or Import S/MIME certificate button.
    6. Copy the base-64 encoded certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker lines, to a text file. Save the text file, and use it to store a copy of the certificate in a subsystem's internal database. See Section 14.3.2.1, “Creating Users”.

4.3.2. Requesting Certificates Using certutil

NOTE

ECC certificates cannot be requested using the end user pages, but ECC certificate requests can be submitted through those pages. Therefore, if a user wants to request and ECC certificate and the CA is ECC-enabled, then the request can be generated using certutil.
  1. Open the certificate database directory of the instance for which the certificate is being requested.
    cd /var/lib/subsystem_name/alias
  2. Run the certutil command, defining the key settings, subject name, validity period, and extensions.
    certutil -R -k rsa -g 2048 -s "CN=example cert server.example.com,e=admin@example.com,O=Example Domain" -o request.cert -v 12 -d . -1 -7 -8
    To request a ECC certificate, use -k ec -g 256 to set the ECC key type and length.
  3. Open the certificate request file to make sure it looks correct.
    cat request.cert
    
    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIICbTCCAVUCAQAwKDEQMA4GA1UEChMHRXhhbXBsZTEUMBIGA1UEAxMLZXhhbXBs
    ZSBuZXcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDcH3CcFbSWFYCV
    WrR1pJf8OaLLvTJB45A+grnNqCAQHnsOKO7XLuO+oLt+r1oEtM7o5eXlwZT1BZT5
    bodglwJgo/GXxElqX49EnPdwyNLiK8bMKRkKnPiIi9jkaGbiTnQLrKMO8/sGKTB+
    DGu1VIsj9a/4tt2Kt5wwhtEMIfeNZ4Alk9UCWpC8r/0I3eNzyyk4pJ9qWDzYEpV3
    TVFco/1FWo+yangv7ThSnOJprILIOpcir0vm5zPSlON6JHyJq9O94wSqnIYs/xqC
    iR4SCEx2I3y0Gaym+C78zxJfGFyALFr8LISQLKWJBZhPrUgDwv44x9KSKIkRM9wa
    l6l4eLl5AgMBAAGgADANBgkqhkiG9w0BAQUFAAOCAQEAo3+dEKvtKJlFadlNC7fH
    Ob/aiO2JYfjRFg4qZEXjAAvtl4OiJ0bqdimP5JYv5DLUpdqVZbXFPE5/2OmOCJOi
    kpBKdyBabOTPfoXQe2Nvzw5RoEwT4/vFtRm1bGTHUKQlugfdj26PnMlOWoMn9rCN
    dtEE5eDVeuyWzhj+Ik35AyVhvCXzBQRo3XjFS8Pb/VdhRL/s57eY+pwMaGIyOWgd
    dlf2nmU9e7LL6MrkkZmJeIm8YdDPwMUkK7uzPu3429CERgtkN1UnuIfniKg8rlt2
    gEm12Q6lfGYoZK8Yuaor4pSiQrMHi3xXDQqkjA/hz853wkSWpQAAtjqIzSljdLMY
    Ng==
    -----END NEW CERTIFICATE REQUEST-----
  4. Submit the certificate request to the CA.
    1. Copy the certificate request, including the marker lines -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- to a text file or into the clipboard.
    2. Open the end-entity services page of the Certificate Manager.
      https://server.example.com:9444/ca/ee/ca
    3. In Certificate Profiles of the Enrollment tab, click on the appropriate form to submit the request. The default profiles are listed in Section 2.2.6, “List of Certificate Profiles”.
    4. In the certificate enrollment form, enter the required information.
      The standard requirements are as follows:
      • Certificate Request Type. This is either PKCS#10 or CRMF. Certificate requests created through the subsystem administrative console are PKCS #10; those created through the certutil tool and other utilities are usually PKCS #10.
      • Certificate Request. Paste the base-64 encoded blob, including the -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- marker lines.
      • Requester Name. This is the common name of the person requesting the certificate.
      • Requester Email. This is the email address of the requester. The agent or CA system will use this address to contact the requester when the certificate is issued. For example, jdoe@someCompany.com.
      • Requester Phone. This is the contact phone number of the requester.
    The submitted request is queued for agent approval. An agent needs to process and approve the certificate request, which the CA signs then and delivers back to the email address specified in the request. If the requester has agent access, the requester can log in as an agent and approve the request.
  5. Retrieve the certificate.
    1. Open the Certificate Manager end-entities page.
      https://server.example.com:9444/ca/ee/ca
    2. Click the Retrieval tab.
    3. Fill in the request ID number that was created when the certificate request was submitted, and click Submit.
    4. The next page shows the status of the certificate request. If the status is complete, then there is a link to the certificate. Click the Issued certificate link.
    5. The new certificate information is shown in pretty-print format, in base-64 encoded format, and in PKCS #7 format.
      There are two actions that can be taken through this page:
      • To install this certificate on a server or other application, scroll down to the Installing This Certificate in a Server section, which contains the base-64 encoded certificate.
      • If this is a client certificate that will be installed directly in the web browser, scroll down to the Importing This Certificate section, and click the Import your certificate or Import S/MIME certificate button.
    6. Copy the base-64 encoded certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- marker lines, to a text file. Save the text file, and use it to store a copy of the certificate in a subsystem's internal database. See Section 14.3.2.1, “Creating Users”.
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.

Table 4.1. Options for Requesting Certificates with certutil

Option Description
-R Flag to generate a certificate request.
-k The key type to use; the only native option is rsa. If the CA is ECC-enabled (described in the Installation Guide), then this can also be ec.
-g The key size. The recommended size for RSA keys is 2048 and for ECC, 256.
-s The subject name of the certificate.

NOTE

Certificate System supports all UTF-8 characters for the common name and organizational unit elements included in the subject name of the certificate.
-o The output file to which to save the certificate request.
-v The validity period, in months.
-d Certificate database directory; this is the directory for the subsystem instance.
numbers 1-8 These set the available certificate extensions. Only eight can be specified through the certutil tool:
  • Key Usage: 1
  • Basic Constraints: 2
  • Certificate Authority Key ID: 3
  • CRL Distribution Point: 4
  • Netscape Certificate Type: 5
  • Extended Key Usage: 6
  • Email Subject Alternative Name: 7
  • DNS Subject Alternative Name: 8
-a Outputs the certificate request to an ASCII file instead of binary.

4.4. Enrolling a Certificate on a Cisco Router

Simple Certificate Enrollment Protocol (SCEP), designed by Cisco, is a way for a router to communicate a certificate issuing authority (like a CA or RA) to enroll certificates for the router.
Normally, a router installer enters the RA's URL and a challenge password (also called a one-time PIN) into the router and issues a command to initiate the enrollment. The router then communicates with the RA over SCEP to generate and request the certificate and then to retrieve it. The router can also check the status of a pending request using SCEP.

NOTE

SCEP defines two ways for submitting a certificate request, either to an RA or to a CA. In Certificate System, the RA does not have a signing certificate, so SCEP certificates are always issued and signed with the CA signing certificate, even if they are submitted through the RA.

4.4.1. Enabling SCEP Enrollments

For security reasons, SCEP enrollments are disabled by default in the CA. To allow routers to be enrolled, SCEP enrollments must be manually enabled for the CA.
  1. Stop the CA server, so that you can edit the configuration files.
    service pki-ca stop
  2. Open the CA's CS.cfg file.
    vim /var/lib/pki-ca/conf/CS.cfg
  3. Set the ca.scep.enable to true. If the parameter is not present, then add a line with the parameter.
    ca.scep.enable=true
  4. Restart the CA server.
    service pki-ca start

4.4.2. Configuring Security Settings for SCEP

Several different parameters allow administrators to set specific security requirements for SCEP connections, like using a different certificate for authentication for enrollment than regular certificate enrollments or setting allowed encryption algorithms to prevent downgrading the connection strength. These parameters are listed in Table 4.2, “Configuration Parameters for SCEP Security”.

Table 4.2. Configuration Parameters for SCEP Security

Parameter Description
ca.scep.encryptionAlgorithm Sets the default or preferred encryption algorithm.
ca.scep.allowedEncryptionAlgorithms Sets a comma-separated list of allowed encryption algorithms.
ca.scep.hashAlgorithm Sets the default or preferred hash algorithm.
ca.scep.allowedHashAlgorithms Sets a comma-separated list of allowed hash algorithms.
ca.scep.nickname Gives the nickname of the certificate to use for SCEP communication. The default is to use the CA's key pair and certificate unless this parameter is set.
ca.scep.nonceSizeLimit Sets the maximum nonce size, in bytes, allowed for SCEP requests. The default is 16 bytes.

To set security settings for connections for SCEP enrollments:
  1. Stop the CA server, so that you can edit the configuration files.
    service pki-ca stop
  2. Open the CA's CS.cfg file.
    vim /var/lib/pki-ca/conf/CS.cfg
  3. Set the desired security parameters, as listed in Table 4.2, “Configuration Parameters for SCEP Security”. If the parameter is not already present, then add it to the CS.cfg file.
    ca.scep.encryptionAlgorithm=DES3 
    ca.scep.allowedEncryptionAlgorithms=DES3 
    ca.scep.hashAlgorithm=SHA1 
    ca.scep.allowedHashAlgorithms=SHA1,SHA256,SHA512 
    ca.scep.nickname=Server-Cert
    ca.scep.nonceSizeLimit=25
  4. Restart the CA server.
    service pki-ca start

4.4.3. Configuring a Router for SCEP Enrollment

NOTE

Not all versions of router IOS have the relevant crypto features. Make sure that the firmware image has the Certification Authority Interoperability feature. Certificate System SCEP support was tested on a Cisco 2611 router running IOS C2600 Software (C2600-JK9S-M), version 12.2(40), RELEASE SOFTWARE (fc1).
Before enrolling SCEP certificates on the router, make sure that the router is appropriately configured:
  • The router must be configured with an IP address, DNS server, and routing information.
  • The router's date/time must be correct.
  • The router's hostname and dnsname must be configured.
See the router documentation for instructions on configuring the router hardware.

4.4.4. Generating the SCEP Certificate for a Router

  1. In the RA services page, click the SCEP Enrollment link.
  2. Click the Pin Creation link.
  3. Fill in the information for the certificate request.
  4. Click the Submit button.
  5. Wait for the request to be generated, then retrieve the PIN.
  6. Add the PIN and the router's ID to the flatfile.txt file so that the router can authenticate directly against the CA. For example:
    vim /var/lib/pki-ca/conf/flatfile.txt
    
    UID:172.16.24.238 
    PWD:Uojs93wkfd0IS
    Be sure to insert an empty line after the PWD line.

    NOTE

    This step is only necessary if the SCEP request is going to be posted directly to the CA. If it is posted to the RA, then the RA agent will authorize the request and this authentication step can be skipped.
    The router's IP address can be an IPv4 address or an IPv6 address.
    Using flat file authentication is described in Section 9.2.4, “Configuring Flat File Authentication”.
  7. Log into the router's console. For this example, the router's name is scep:
    scep>
  8. Enable privileged commands.
    scep> enable
  9. Enter configuration mode.
    scep# conf t
  10. Import the CA certificate for every CA in the certificate chain, starting with the root. For example, this imports two CA certificates in the chain into the router:
    scep(config)# crypto ca trusted-root1 
    scep(ca-root)# root CEP http://server.example.com:12888/ee/scep/pkiclient.cgi 
    scep(ca-root)# crl optional 
    scep(ca-root)# exit 
    scep(config)# cry ca authenticate 1 
    scep(config)# crypto ca trusted-root0 
    scep(ca-root)# root CEP http://server.example.com:12888/ee/scep/pkiclient.cgi 
    scep(ca-root)# crl optional 
    scep(ca-root)# exit 
    scep(config)# cry ca authenticate 0
  11. Set up a CA identity, and enter the URL to access the SCEP enrollment profile. For example, for the CA:
    scep(config)# crypto ca identity CA 
    scep(ca-identity)# enrollment url http://server.example.com:9180/ca/cgi-bin 
    scep(ca-identity)# crl optional
    It is also possible to send the request to the RA.
  12. Get the CA's certificate.
    scep(config)# crypto ca authenticate CA 
    Certificate has the following attributes: 
    Fingerprint: 145E3825 31998BA7 F001EA9A B4001F57 
    % Do you accept this certificate? [yes/no]: yes
  13. Generate RSA key pair.
    scep(config)# crypto key generate rsa 
    The name for the keys will be: scep.server.example.com 
    Choose the size of the key modulus in the range of 360 to 2048 for your 
    General Purpose Keys. Choosing a key modulus greater than 512 may take 
    a few minutes. 
    	
    How many bits in the modulus [512]: 
    Generating RSA keys ... 
    [OK]
  14. Lastly, generate the certificate on the router.
    scep(config)# crypto ca enroll CA 
    % 
    % Start certificate enrollment .. 
    % Create a challenge password. You will need to verbally provide this 
    password to the CA Administrator in order to revoke your certificate. 
    For security reasons your password will not be saved in the configuration. 
    Please make a note of it. 
    	
    Password: secret
    Re-enter password: secret
    	
    % The subject name in the certificate will be: scep.server.example.com 
    % Include the router serial number in the subject name? [yes/no]: yes 
    % The serial number in the certificate will be: 57DE391C 
    % Include an IP address in the subject name? [yes/no]: yes 
    % Interface: Ethernet0/0 
    % Request certificate from CA? [yes/no]: yes 
    % Certificate request sent to Certificate Authority 
    % The certificate request fingerprint will be displayed. 
    % The 'show crypto ca certificate' command will also show the fingerprint. 
    	
    % Fingerprint:D89DB555 E64CC2F7 123725B4 3DBDF263 
    	
    Jan 12 13:41:17.348: %CRYPTO-6-CERTRET: Certificate received from Certificate
  15. Close configuration mode.
     scep(config)# exit
  16. To make sure that the router was properly enrolled, list all of the certificates stored on the router.
    scep# show crypto ca certificates 
    Certificate 
     Status: Available 
     Certificate Serial Number: 0C 
     Key Usage: General Purpose 
     Issuer: 
    	CN = Certificate Authority 
    	 O = Sfbay Red hat Domain 20070111d12 
     Subject Name Contains: 
    	Name: scep.server.example.com 
    	IP Address: 10.14.1.94 
    	Serial Number: 57DE391C 
     Validity Date: 
    	start date: 21:42:40 UTC Jan 12 2007 
    	end date: 21:49:50 UTC Dec 31 2008 
     Associated Identity: CA 
    	
    CA Certificate 
     Status: Available 
     Certificate Serial Number: 01 
     Key Usage: Signature 
     Issuer: 
    	CN = Certificate Authority 
    	 O = Sfbay Red hat Domain 20070111d12 
     Subject: 
    	CN = Certificate Authority 
    	 O = Sfbay Red hat Domain 20070111d12 
     Validity Date: 
    	start date: 21:49:50 UTC Jan 11 2007 
    	end date: 21:49:50 UTC Dec 31 2008 
     Associated Identity: CA

4.4.5. Working with Subordinate CAs

Before the router can authenticate to a CA, every CA certificate in the CA's certificate chain must be imported into the router, starting with the root. For example, this imports two CA certificates in the chain into the router:
scep(config)# crypto ca trusted-root1 
scep(ca-root)# root CEP http://server.example.com:12888/ee/scep/pkiclient.cgi 
scep(ca-root)# crl optional 
scep(ca-root)# exit 
scep(config)# cry ca authenticate 1 
scep(config)# crypto ca trusted-root0 
scep(ca-root)# root CEP http://server.example.com:12888/ee/scep/pkiclient.cgi 
scep(ca-root)# crl optional 
scep(ca-root)# exit 
scep(config)# cry ca authenticate 0
If the CA certificates do not have the CRL distribution point extension set, turn off the CRL requirement by setting it to optional:
scep(ca-root)# crl optional
After that, set up the CA identity as described in Section 4.4.4, “Generating the SCEP Certificate for a Router”. For example, for enrolling through the RA:
scep(config)# crypto ca identity CA 
scep(ca-identity)# enrollment url http://server.example.com:12888/ee/scep/pkiclient.cgi 
scep(ca-identity)# crl optional

4.4.6. Re-enrolling a Router

Before a router can be re-enrolled with new certificates, the existing configuration has to be removed.
  1. Remove (zeroize) the existing keys.
    scep(config)# crypto key zeroize rsa 
    % Keys to be removed are named scep.server.example.com. 
    Do you really want to remove these keys? [yes/no]: yes
  2. Remove the CA identity.
    scep(config)# no crypto ca identity CA 
    % Removing an identity will destroy all certificates received from 
    the related Certificate Authority. 
    	
    Are you sure you want to do this? [yes/no]: yes 
    % Be sure to ask the CA administrator to revoke your certificates. 
    	
    No enrollment sessions are currently active.

4.4.7. Enabling Debugging

The router provides additional debugging during SCEP operations by enabling the debug statements.
 scep# debug crypto pki callbacks 
 Crypto PKI callbacks debugging is on 
	
 scep# debug crypto pki messages 
 Crypto PKI Msg debugging is on 
	
 scep# debug crypto pki transactions 
 Crypto PKI Trans debugging is on 
	
 scep#debug crypto verbose 
 verbose debug output debugging is on

4.5. Performing Bulk Issuance

There can be instances when an administrator needs to submit and generate a large number of certificates simultaneously, such as provisioning a new lot of HSMs or servers. A combination of tools supplied with Certificate System can be used to post a file containing certificate requests to the CA. This example procedure uses PKCS10Client to generate the requests and sslget to send the requests to the CA.
  1. Since this process is scripted, multiple variables need to be set to identify the CA (host, port) and the items used for authentication (the agent certificate and certificate database and password). For example, set these variables for the session by exporting them in the terminal:
    export d=/var/tmp/cert8.db
    export p=password
    export f=/var/tmp/server.csr.txt
    export nick="CA agent cert"
    export cahost=1.2.3.4
    export caport=9444

    NOTE

    The local system must have a valid security database and with an agent's certificate in it. To set up the databases:
    1. Export or download the agent user certificate and keys from the browser and save to a file, such as agent.p12.
    2. If necessary, create new security databases.
      certutil -N -d .
    3. Use pk12util to import the certificates.
      # pk12util -i /tmp/agent.p12 -d /var/tmp/cert8.db -W p12filepassword
      If the procedure is successful, the command prints the following:
      pk12util: PKCS12 IMPORT SUCCESSFUL
  2. Two additional variables must be set that identify the CA profile to use to process the requests and that send a post statement to supply the information for the profile form.
    export post="cert_request_type=pkcs10&xmlOutput=true&profileId=caAgentServerCert&cert_request="
    export url="/ca/ee/ca/profileSubmitSSLClient"

    NOTE

    This example submits the certificate requests to the caAgentServerCert profile (identified in the profileId element of the post statement. Any certificate profile can be used, including custom profiles.
  3. Generate the certificate requests using (for this example) PKCS10Client:
    time for i in {1..10}; do /usr/bin/PKCS10Client -d ${d} -p ${p} -o ${f}.${i} -s "cn=testms${i}.example.com"; cat ${f}.${i} >> ${f}; done
    
    perl -pi -e 's/\r\n//;s/\+/%2B/g;s/\//%2F/g' ${f}
    
    wc -l ${f}
  4. Submit the bulk certificate request file created in step 3 to the CA profile interface using sslget. For example:
    cat ${f} | while read thisreq; do /usr/bin/sslget -n "${nick}" -p ${p} -d ${d} -e ${post}${thisreq} -v -r ${url} ${cahost}:${caport}; done

4.6. Configuring and Using the Auto Enrollment Proxy

Red Hat Certificate System's Auto Enrollment Proxy for Windows allows users and computers in a Microsoft Windows domain to enroll for certificates automatically, and have them automatically issued from Red Hat Certificate System.
Certificate System's auto enrollment proxy is designed to integrate seamlessly with an existing Windows infrastructure and to minimize the amount of administration for requesting, issuing, and managing certificates on a Windows domain:
  • Users and computers registered in a Windows domain can automatically discover the location of the proxy on their network.
  • Computers in a domain can automatically generate a certificate request and submit it to a Certificate System CA through the proxy.
  • Certificate requests are authenticated, and therefore can be approved, through the Kerberos authentication mechanism built into Windows.
When the Certificate System CA issues a certificate, the new certificate is then automatically installed into the requesting application.
The Certificate System auto enrollment proxy can issue certificates for domain controllers, web servers, computers, and users by default, and can have custom profiles mapped to other certificate profiles recognized by the Windows domain.

4.6.1. About Auto Enrollment

Windows servers for Server 2000, XP, 2003, and Vista all have a feature for automatic certificate enrollment which allows Windows systems within a domain to contact a domain controller, find available certificate services, and request and receive those services based on their domain credentials.
That is a technical way of saying that whenever a new identity joins a domain — a server, a user, or an administrator — then simply being in the domain allows the entity to be automatically given a certificate because the process of requesting, authenticating, and installing the certificate is automatically handled by the domain.
Certificate System's auto enrollment proxy plugs a Certificate System CA into the Windows domain, so that the Certificate System CA is part of the domain's PKI and can be used for issuing certificates used in and by the domain.

4.6.1.1. Looking at How the Auto Enrollment Proxy Works on Windows

Auto enrollment within a Windows domain simplifies creating and managing secure connections within the domain and establishing a PKI for servers and users on the systems. Users can be issued a certificate when they first log into the domain or servers can be issued certificates when they are first set up.
Most of the time, the certificates issued within the domain are issued by a certificate service on the domain controller. However, administrators may want to use a third-party CA, such as a Certificate Manager, to issue certificates. For that, Microsoft allows an enrollment proxy which essentially imitates a Windows certificate service on the domain.
Microsoft certificate services use a special request interface (ICertRequestD) to manage requests within the domain.
ICertRequestD is a DCOM object. Windows uses components to manage APIs as if they are objects. The intent of the component object model, or COM, is to enable processes to communicate with each other and to generate objects dynamically. Each object is identified in the system registry, and each component exposes itself through some kind of interface. It is possible for COM interfaces to be shared over a network connection, rather than being on the same machine; these networked objects are called distributed component object model, or DCOM, objects.
Every DCOM and COM interface is defined in the registry with a interface identifier (IID) and globally unique identifier (GUID). For example, the IID for the COM object which handles certificate enrollment (ICertEnroll) is 43F8F288-7A20-11D0-8F06-00C04FC295E1, so its registry entry is as follows:
HKEY_CLASSES_ROOT\Interface\43F8F288-7A20-11D0-8F06-00C04FC295E1
For Microsoft's auto enrollment process, an application (like a web server, a domain server, or the management console) calls a control like ICertEnroll, and then the enroll object manages the entire issuance process, from creating keys to generating and submitting the certificate request.
In a Windows domain, servers and applications poll Active Directory to get the list of available certificate services. When the Auto Enrollment Proxy, is configured, its information is added to Active Directory as one of the available certificate services. Then, when an enrollee (like a server) first asks the domain controller for available services, Certificate System is included. The enrollee process then sends certificate request, through the DCOM objects, to the proxy, which then forwards the request to the Certificate System CA.
Using DCOM Objects for Enrollment

Figure 4.1. Using DCOM Objects for Enrollment


The Auto Enrollment Proxy is another Windows service running within the domain, and it has registry entries which match the DCOM ID for the ICertRequestD object. The RPC service (RPCSS) on the machine will perform necessary authorization checks to verify that the enrollee can access the proxy.
Any type of user of the domain can access the process: a person running the Microsoft Management Console, a user running certreq, or a server or web service which initiates an automatic enrollment. Regardless of the method of accessing the proxy, Microsoft's enrollment object will run through a series of checks to authorize the request:
  • That the requested certificate profile is supported. The PKCS#10 request contains an extension which identifies the type of certificate being requested; the template can be mapped to a Certificate System profile.
  • That the Certificate Authority is trusted.
  • That the requester has permission to access the proxy.
If the process meets those requirements, the Windows server generates a PKCS#10 certificate request and submits it to the proxy. The proxy parses the request, pulls out required information and may derive or add other required information, and re-formats the request to meet the requirements for the Red Hat Certificate System CA. The proxy then sends the reformatted request to the Certificate Manager, which automatically issues the certificate (since the request was authenticated in the Windows domain) and sends it to the proxy. The proxy then presents the certificate to the enrolling application.
The Auto Enrollment Process

Figure 4.2. The Auto Enrollment Process


At several points in the process, the DCOM objects pull information about the proxy service from the registry settings or from the entry in Active Directory:
  1. The server runs an LDAP search on the root DSE to find the configuration naming context.
  2. Then, it runs an LDAP search under the CN=Enrollment Services, CN=Public Key Services, CN=Services branch of the configuration naming context, which lists every configured enrollment service, including the Auto Enrollment Proxy.
  3. The enrollment process then locates and uses any enrollment service which matches the required criteria:
    • Has a certificateTemplates attribute which matches the requested certificate type.
      Certificate System 8.0 has two certificate profiles supported by default, for domain controller certificates (caDomainController) and web server certificates (caAgentServerCert).
    • Has a trusted CA that is listed in the CN=Certification Authorities subtree.
    • The last CA in the trust chain must be a self-signed root CA.

4.6.1.2. Planning the Auto Enrollment Configuration

It only requires a single Auto Enrollment Proxy for an entire domain, but it depends on the domain configuration where and what machine the Auto Enrollment Proxy should be installed on. The proxy has to be able to authenticate the requester against information in the domain, so the requester must be in the same forest as the proxy.
Additionally, for security, the proxy should be run on a dedicated machine in a secure environment with access limited to trusted administrators.
The simplest configuration is to install the proxy as the same machine as the domain controller. This limits the field of the proxy to that single domain.
Having the Proxy on the Domain Controller

Figure 4.3. Having the Proxy on the Domain Controller


Because of traffic or security, it may be better to install the proxy on a dedicated machine within the domain, but not a domain controller. Depending on the domain configuration, this can also limit the proxy to entities within the single domain.
Having the Proxy within the Domain

Figure 4.4. Having the Proxy within the Domain


The most complex arrangement has the proxy installed within a single domain but accessible to multiple domains within a Windows forest. For this configuration, see the Windows server and Active Directory documentation to explain how to configure the domain properly.
Using a Single Proxy within a Forest

Figure 4.5. Using a Single Proxy within a Forest


4.6.2. Installing and Setting up the Auto Enrollment Proxy

The Auto Enrollment Proxy must be installed and configured on a Windows server within a Windows domain. The latest releases of the Certificate System Auto Enrollment Proxy are available at http://directory.fedoraproject.org/wiki/Windows_Certificate_Auto_Enrollment.

4.6.2.1. Requirements for the Windows Environment

The Windows environment must be configured and running before you can install the Auto Enrollment Proxy.
  • Active Directory must be installed, and if there are multiple domains in the forest, then they must be able to cross-trust each other.
  • Audit logging should be enabled for the group policy.
  • DNS must be properly configured; the DNS settings can be verified using dcdiag.
  • All Windows servers should access the same NTP server so that their dates and times are in sync.
  • The Microsoft Management Console must be configured, as described in Section 4.6.2.2, “Configuring the Microsoft Management Console to Use with the Auto Enrollment Proxy”.

4.6.2.2. Configuring the Microsoft Management Console to Use with the Auto Enrollment Proxy

The Microsoft Management Console must have the appropriate snap-ins added for the Auto Enrollment Proxy to function.
  1. Open the Microsoft Management Console. The easiest way to do this is to open the Start menu, select Run, and type in mmc.
  2. To add the required snap-ins, open the File, and select Add/Remove Snap-ins.
  3. Select the profile to which to add the snap-ins. (It may be beneficial to have a separate profile for the proxy.) Then click Add.
  4. Select and go through the configuration each required snap-in.
    • Services
    • Certificate Templates
    • Certificates (with the My user account option, to create a snap-in for Certificates -Current User)
    • Certificates (with the Computer account option, to create a snap-in for Certificates [Local Computer)
    • Active Directory users and computers
    • Active Directory domains and trusts
    • DNS
    • Component Services
  5. Save the Microsoft Management Console configuration to the desktop; this ensures that it is easy to access.
  6. Verify that the console is properly configured by re-opening it and double-clicking Certificate Templates folder.

4.6.2.3. Setting up the Auto Enrollment Proxy

  1. Open the Microsoft Management Console. If a profile was saved to the desktop, then launch it from there; otherwise, open the Start menu, select Run, and type in mmc.
  2. Set up the CA's agent certificate. The proxy authenticates to the CA as an agent so that it can immediately approve any certificate requests submitted by the proxy. To do this, the proxy must have the agent certificate.
    1. Retrieve the CA agent certificate from the CA's end entities pages, and save it to a PKCS#12 file. Copy the PKCS#12 to the Windows machine.
    2. In the Microsoft Management Console, open the Certificates - Current User snap-in.
    3. Right-click on Personal, select All tasks, then select Import, to import the saved agent certificate.
  3. Add the CA certificate into the domain group policy. The CA must be trusted in order to issue certificates, meaning the CA certificate has to be loaded.
    1. Use IE and connect to the CA's agent page. No errors/warning should be displayed. If they appear, make sure they don't appear the next time.
    2. Retrieve the CA certificate chain, in binary form, from the CA's end entities pages. Save the certificate chain to the desktop with a name like cacert.cer.
    3. In the Microsoft Management Console, open the Active Directory Users and Computers snap-in.
    4. Right-click Domain in the left menu, and select Properties.
    5. Open the Group Policy tab, then select the Default Domain policy, and press Edit.
    6. In the edit window, open a series of menus: in Computer Configuration, then Windows Settings and Security Settings, and finally open Public Key Policies and Trusted Root Certification Authorities.
    7. Right-click on the right panel, Select 'Import...'. Open the 'cacert.cer' file you saved earlier. Right-click on Personal, select All tasks, then select Import, to import the saved CA certificate chain file.
  4. Install the Auto Enrollment Proxy packages.
    1. Double-click the .exe, and go through the installer.
  5. Configure the Auto Enrollment Proxy by importing the CA certificate, setting the CAs to use, and setting the Auto Enrollment Proxy settings.
    1. Open the Start menu, and select Red Hat Auto Enrollment Proxy.
    2. Open the CA Certificate tab.
      Click Load from File, and import that CA certificate chain from the file. Then click Set to apply the certificate.
    3. Next, click the Active Directory tab.
      Click the Populate AD button to create the Active Directory entry for the proxy service.
    4. Add the connection information for each Certificate Manager which will be used by the proxy. Click Add to add each CA.
      The CA connection requires the following information:
      • The fully-qualified domain name of the Certificate Manager
      • The port number of the Certificate Manager
      • The Certificate System version number of the Certificate Manager
      • The certificate to use to authenticate to the Certificate Manager
    5. In the Logging tab, set any log levels to use for the service.
    6. When all of the configuration settings have been made, click Apply to save the settings.
  6. The last configuration area is setting up the DCOM service.
    1. In the Microsoft Management Console, select the DCOM - Components snap-in.
    2. Select or expand the Computers folder, then My Computer, and DCOM Config.
    3. Right-click Red Hat Auto Enrollment Proxy, and select Properties
    4. In the Security tab, click the Customize radio button under Launch and Activation Permissions, and click the Edit button. Make sure that the administrator and that Everyone is selected.
      Then, click the Customize radio button under Access Permissions, and click the Edit button. Make sure that the administrator and that Everyone is selected.

      NOTE

      The user that launches the proxy and the computer account for the proxy host must be members of the Distributed COM Built-in Principals Group.
    5. In the Identity tab, select the This user radio button. It is better to browser for the user, even if you know the username for the administrator, because the domain name may have to be prepended in order for the user to log into the domain.
    6. Save the changes to the DCOM snap-in.
  7. In Administrative Tools, open Services, and manually start the Auto Enrollment Proxy service. This should then be listed in the Task Manager as rhcsproxy.exe.

4.6.2.4. Troubleshooting and Diagnostic Tips

Microsoft supplies several tools that are beneficial for diagnosing and troubleshooting problems with auto enrollment or the Auto Enrollment Proxy. A list of Windows Server 2003 Support tools is at http://support.microsoft.com/kb/892777, which includes LDP (an LDAP browser) and DCDIAG (used for diagnosing domain controller, and DNS problems). Two monitoring tools, filemon and regmon, are available at http://www.microsoft.com/technet/sysinternals/ProcessesAndThreads/Regmon.ms and are extremely useful for monitoring and troubleshooting registry and file issues, which can help with analyzing the auto enrollment process.
Kerberos Authentication
Auto enrollment uses Microsoft's Kerberos mechanisms to authenticate users, servers, and requests. Make sure that Kerberos, not NTLM, is being used to authenticate entities (this is visible in the Event Viewer security logs). The kerbtray.exe tool can be used to purge Kerberos tickets if NTLM is being used instead of Kerberos.
dcdiag and Replication
If dcdiag shows that there are replication problems, create new replication agreements.
The certificate request failed...
One common error message when generating a certificate using the Microsoft Management Console is The certificate request failed because of one of the following conditions...
If this error occurs when the Microsoft Management Console request wizard is first opened, then it means that the console could not connect to the enrollment service, and there are a couple of different possible reasons:
  • The hostname in enrollment services is incorrect. Use LDP to view the enrollment service in Active Directory for the proxy, and verify the dNSHostName attribute. This value is automatically populated when the proxy is first configured.
  • The proxy host is unreachable. Try to ping the above hostname to make sure DNS resolves the hostname to an IP address correctly, and that the host is online.
  • The proxy service is not running. The proxy is a registered service. It is stopped by default, but Windows should automatically start the service when a certificate request is entered. Check Task Manager to see if the rhcsproxy.exe process is running or check the Services page to restart the service.
  • If the proxy is installed on another machine or another domain, then the DCOM or domain configuration may not be allowing the host to contact the proxy service.
If the request failed error occurs after going through the request wizard, then the console was able to connect to the proxy and generate a request, but the proxy did not return a certificate. Check the Event Viewer application log on the system that is running the proxy to see what errors were recorded.

4.6.3. Managing Auto Enrollment Proxy Settings

The Auto Enrollment proxy is configured in a central Active Directory entry and in the Windows registry of the host where it is installed. These configuration entries can be viewed and, to some extent, edited to redefine the proxy service.

4.6.3.1. Auto Enrollment Proxy Registry Settings

The Auto Enrollment Proxy stores its configuration settings in the Windows registry, underneath the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Red Hat\RHCSProxy\Config
This entry defines the basic behaviors of the proxy service.

Table 4.3. Auto Enrollment Proxy Registry Settings

Name Description Example
RequestType The type of certificate request to send to the CA. The only supported value is PKCS10. PKCS10
LogOptions An decimal integer representing a bitmask of all the selected log options. 503
AuthenticationCertificate A hash of the chosen certificate to use for SSL client authentication to the CA.
CACertificate A binary value, for the DER encoded binary CA certificate.
RetryInterval The number of seconds to wait before trying to use a CA which was previously failing.

4.6.3.2. Listing and Adding CAs in the Windows Domain

All of the CAs configured for enrollment services for a domain are listed in Active directory in the CN=Enrollment Services,CN=Public Key Services subtree. This subtree can be queried to show what Certificate Managers are configured for the proxy and what certificate templates and other settings they have available. For example:
dsquery * "CN=Example RHCS CA,CN=Enrollment Services,CN=Public Key Services,CN=Services,CN=Configuration,DC=server,DC=example,DC=com" -scope base -attr *
The actual configuration for the Certificate Manager is defined in the registry entries for the proxy service. All proxy CAs are listed in the registry under the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Red Hat\RHCSProxy\Config\CertificateAuthorities
Each configured CA is then a subkey under the main entry.
[HKEY_LOCAL_MACHINE\SOFTWARE\Red Hat\RHCSProxy\Config\CertificateAuthorities\1] "hostname"="ca.example.com" "port"="9444" "catype"="3"
New CAs can be added by directly editing the registry entry and adding a new CA or by opening the proxy configuration console and adding a new entry there.

4.6.3.3. Mapping Certificate System Enrollment Profiles to Windows Profiles

The proxy maintains a list of available certificate profiles, by default allowing domain controller certificates (caDomainController) and web server certificates (caAgentServerCert). These profiles are mapped to corresponding Windows certificate templates, maintained in the registry under the following key:
HKEY_LOCAL_MACHINE\SOFTWARE\Red Hat\RHCSProxy\Config\ProfileMap
To add additional certificate profiles to the proxy service, add a subkey under the ProfileMap folder which maps a Windows template to the Certificate System profile. The Windows template is identified in the key name; the corresponding Certificate System profile is set in a CAProfileName parameter. For example:
[HKEY_LOCAL_MACHINE\SOFTWARE\Red Hat\RHCSProxy\Config\ProfileMap\WebServer] "CAProfileName"="caServerCert"

NOTE

Profile maps can only be done by editing the registry keys; they cannot be set in the Auto Enrollment Proxy configuration console.

4.6.4. Manually Requesting Domain Certificates

The auto enrollment proxy, naturally, automatically enrolls servers, hardware, and even users as soon as the entity is added to the Windows domain. However, once the auto enrollment proxy for Red Hat Certificate System is configured, it is also possible to request and receive certificates manually on a Windows domain through a Certificate System CA.
Certificates can be requested using the Microsoft Management Console (MMC) or using the Windows certreq tool.

4.6.4.1. Requesting Certificates through MMC

  1. Open MMC
  2. Open Certificates (Local Computer) -> Persona
  3. Right click the right panel, and select Request New Certificate. This opens a certificate request wizard.
  4. The available types of certificates that can be requested are listed. Select the type of certificate to request.
  5. Fill in the information to use to configure the certificate, such as a name or description.
  6. Click Finish to submit the certificate request to the auto enrollment proxy.

4.6.4.2. Requesting Certificates Using certreq

  1. Create an .inf file to use to supply values for the certificate request. This file defines the settings to use for the certificate request, such as the certificate profile for the Windows domain, the key settings, and any extensions. For example:
    [Version]
     Signature="$Windows NT$"
    [NewRequest]
     Subject = "CN=domain.example.com"
     KeySpec = 1
     KeyLength = 1024
     Exportable = TRUE
     MachineKeySet = TRUE
     SMIME = False
     PrivateKeyArchive = FALSE
     UserProtected = FALSE
     UseExistingKeySet = FALSE
     ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
     ProviderType = 12
     RequestType = PKCS10
     KeyUsage = 0xa0
    [EnhancedKeyUsageExtension]
     OID=1.3.6.1.5.5.7.3.1
    [RequestAttributes]
     CertificateTemplate = DomainController
    More information on using certreq and the format of the request file is available at http://technet.microsoft.com/en-us/library/cc736326(WS.10).aspx.
  2. On the Windows machine, run the certreq command to generate the request, specifying the request .inf file and an output file for the certificate request. For example:
    certreq -new request.inf dc-cert-request.req
  3. Submit the certificate request to the CA, and set the name of the final output certificate file.
    certreq -submit dc-cert-request.req dc-cert.cer
  4. Install the new certificate in the server's database.
    certreq -accept dc-cert.cer
  5. To verify that the certificate is available by checking the certificate list in the management console.

TIP

It is also possible to request and submit a certificate in a single pass. For example:
certreq -f -v -config "domain.example.com\Certificate Authority - SUBCA - server.example.com" -submit dc-cert-request.req dc-cert.cer

4.7. Renewing Certificates

Renewing a certificate regenerates the certificate using the same public key as the original certificate. Renewing a certificate can be preferable to simply generating new keys and installing new certificates; for example, if a new CA signing certificate is created, all of the certificates which that CA issued and signed must be reissued. If the CA signing certificate is renewed, than all of the issued certificates are still valid. A renewed certificate is identical to the original, only with an updated validity period and expiration date.
This section discusses renewing user certificates and creating renewal profiles. For information on renewing Certificate System subsystem certificates, see Chapter 16, Managing Subsystem Certificates.

4.7.1. About Renewal

A renewed certificate is identical to the original certificate, which makes renewing certificates a much simpler and cleaner option for handling the expiration of many kinds of certificates, especially CA signing certificates.

4.7.1.1. The Renewal Process

There are two methods of renewing a certificate. Regenerating the certificate takes its original key and its original profile and request, and recreates a new certificate with a new validity period and expiration date using the identical key. Re-keying a certificate resubmits the initial certificate request to the original profile, but generates a new key pair.
By default, Certificate System supports regenerating user certificates. In this kind of renewal, the CA re-creates the existing user certificate based on its previous configuration, like its public key and defaults, constraints, and other settings.
When the user submits a renewal request, they provide some kind of information to identify which certificate to renew. This can be the serial number or the certificate itself.
Renewal Flow

Figure 4.6. Renewal Flow


The server identifies the certificate and then maps the renewal request to the initial certificate request entry in the CA database. If more than one certificate matches the renewal request, then the most recent certificate entry is used. (The renewal request must be submitted to the same CA which issued the original certificate. This is the only way to map the serial number to the appropriate certificate.)
The certificate entry contains, along with the original certificate, the original profile used to submit the request, its public key, and its extensions. Since the defaults, constraints, and other settings must be the same in the new certificate as in the old, it is important that the renewal process access the original enrollment profile, with the original information.

Example 4.1. Certificate Request Entry

 dn: cn=54,ou=certificateRepository, ou=ca, dc=server.example.com-pki-ca
objectClass: top
objectClass: certificateRecord
serialno: 0254
metaInfo: inLdapPublishDir:true
metaInfo: profileId:caUserCert
metaInfo: requestId:58
notBefore: 20090624082117Z
notAfter: 20091221072117Z
duration: 1115552000000
subjectName: UID=jsmith,E=jsmith@example.com,CN=John Smith,OU=engineering,OU=content,OU=services,OU=people,C=US
publicKeyData:: MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAOhd4g9Fluurl3mtUzEKmilsGolBKr/sEvGpPZecPpcFxfkxwfvfjl6ycEUcxXJXEhdSQ+ZPdCUwakSBhn15Uz8CAwEAAQ==
extension: 1.3.6.1.5.5.7.1.1
extension: 2.5.29.37
extension: 2.5.29.35
extension: 2.5.29.17
extension: 2.5.29.15
userCertificate;binary:: MIIDXzCCAkegAwIBAgIBNjANBgkqhkiG9w0BAQUFADBAMR4wHAYD
 VQQKExVSZWRidWRjb21wdXRlciBEb21haW4xHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0
 eTAeFw0wOTA2MjQxMzIxMTdaFw0wOTEyMjExMzIxMTdaMIGrMQswCQYDVQQGEwJVUzEPMA0GA1UE
 CxMGcGVvcGxlMREwDwYDVQQLEwhzZXJ2aWNlczEQMA4GA1UECxMHY29udGVudDEUMBIGA1UECxML
 ZW5naW5lZXJpbmcxFDASBgNVBAMTC0Rlb24gTGFja2V5MSEwHwYJKoZIhvcNAQkBFhJkbGFja2V5
 QHJlZGhhdC5jb20xFzAVBgoJkiaJk/IsZAEBEwdkbGFja2V5MFwwDQYJKoZIhvcNAQEBBQADSwAw
 SAJBAOhd4g9Fluurl3mtUzEKmilsGolBKr/sEvGpPZecPpcFxfkxwfvfjl6ycEUcxXJXEhdSQ+ZP
 dCUwakSBhn15Uz8CAwEAAaOBvzCBvDAfBgNVHSMEGDAWgBS7F3+uS3y2ZNesUZLcB/ZTwo9LIjBL
 BggrBgEFBQcBAQQ/MD0wOwYIKwYBBQUHMAGGL2h0dHA6Ly93aWxidXIucmVkYnVkY29tcHV0ZXIu
 bG9jYWw6OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYI
 KwYBBQUHAwQwHQYDVR0RBBYwFIESZGxhY2tleUByZWRoYXQuY29tMA0GCSqGSIb3DQEBBQUAA4IB
 AQB1Jig+3mucNrvhl009ZWshzKSZN7d1rGP+SsYCNTk9KzEhU/lCkQnOLbrAMDE7gBKLkDvpm+4y
 ud5qzHC6+tCR+L0H6JCm1Gufv5VE4yIN+dLPcO4Wr8ZCIgt2Rr3aR3FqE0tqUXh2RDmq+EvfxBza
 FOTQpwz2EW1ppIXjKNZpi9+3enjMg0rc/CsT+c1rKeXJzo5mD6n+VmET8ZilvSgyq6jt9KgqeVfM
 Cfl+ypQ2u9EW6a0sYflw+vPOkcXqRUnKfKjn1lq8CALrGDG71pAlHzXQNMB0YWlKKywhdMfbHPN8
 FdFHC6Ro5Ny01DDRBF+y3Iqc3flLFJt1Ya3c8hEc
version: 2
algorithmId: 1.2.840.113549.1.1.1
signingAlgorithmId: 1.2.840.113549.1.1.5
dateOfCreate: 20090624082244Z
dateOfModify: 20090624082244Z
certStatus: VALID
autoRenew: ENABLED
issuedBy: admin
cn: 54

The original certificate request entry also contains the original validity period of the certificate and the grace period for renewing the certificate, the time before and after the expiration date when renewal is allowed. If a certificate is outside of that period, either way, the renewal request is automatically rejected.
While renewal reissues an expired certificate, it does not reissue a revoked certificate. Only an otherwise valid certificate can be renewed.
The server then retrieves the public key from the entry, along with the original certificate request. Using the key and the original certificate request, the CA issues a new certificate, with a new validity period.

NOTE

The renewal process only renews one certificate at a time.
User certificates are frequently issued in pairs, such as encryption and signing certificates, and the initial enrollment issues both certificates at the same time. However, the renewal process takes a single serial number or certificate as its input, so it can only renew one certificate in one step.
To renew both certificates in a certificate pair, each one has to be renewed individually.

4.7.1.2. Renewal Types in Certificate System

As with any certificate request, a renewal request has to be approved before the CA will issue the new certificate. Certificate System has three renewal types, depending on the authorization method used to verify the requester, and any of the three types can be used to renew any kind of certificate:
  • Agent-based renewal, where the agent manually approves the request
  • Directory-based renewal, where the requester authenticates to an LDAP directory
  • Certificate-based renewal, where the certificate stored in the browser's database is used to authenticate the requester

TIP

4.7.2. Creating Custom Renewal Profiles

Certificate renewal regenerates a certificate using its original public key, certificate extensions and constraints, and subject name. A renewed certificate is identical to the original, except that it has a new expiration date.
When a certificate is renewed, it has to be renewed using a renewal profile that corresponds to the initial enrollment profile. Certificate System supports renewals both for tokens and for regular certificates, both through the RA and the CA.
The default configuration profiles cover user certificates and other types of subsystem certificates, as well as token renewals, but it may be necessary or convenient to create a special renewal profile for a custom enrollment form.

4.7.2.1. Default Renewal Profiles

Certificate System contains three default renewal profiles for renewing user certificates.

Table 4.4. Renewal Profiles

Renewal Profile Type
caDirUserRenewal.cfg Directory-based
caManualRenewal.cfg Agent-based
caSSLClientSelfRenewal.cfg Certificate-based

4.7.2.2. Creating an Enrollment Profile

A custom profile is configured the same as described in Section 2.2, “Setting up Certificate Profiles”. There are two settings that must be present in the profile, however, to allow renewal for the certificate: a setting on whether renewal is allowed and a setting on the time period when renewal is allowed.
The renewal parameter sets whether renewal is allowed. This must be true:
renewal=true
The renewal grace period is set through the Renewal Grace Period Constraint (in Section B.2.8, “Renewal Grace Period Constraint”). This constraint has two parameters, setting the time period before and after the expiration date that renewal can be allowed.
policyset.userCertSet.list=1,10,2,3,4,5,6,7,8,9
...
policyset.userCertSet.10.constraint.class_id=renewGracePeriodConstraintImpl
policyset.userCertSet.10.constraint.name=Renewal Grace Period Constraint
policyset.userCertSet.10.constraint.params.renewal.graceBefore=30
policyset.userCertSet.10.constraint.params.renewal.graceAfter=30
policyset.userCertSet.10.default.class_id=noDefaultImpl
policyset.userCertSet.10.default.name=No Default
These two configuration settings have to be set in the original enrollment profile, not the renewal profile. The rules for the renewal grace period are part of the original certificate and are carried over and applied for any subsequent renewals.

4.7.2.3. Creating the Renewal Profile

A renewal profile is much simpler than a standard enrollment profile because it does not need to define any defaults, extensions, or constraints; all of that information is already contained in the original certificate.
What a renewal profile does define is whether renewal is allowed, the input to use to locate the original certificate, and the output of the regenerated certificate.
The renewal option, as with the original profile, is set to either true or false.
renewal=true
The original profile must allow renewal, but the renewal profile can set the renewal is not allowed, which means that a certificate can only be renewed once.
The input depends on the way that the certificate renewal request is authorized. For agent-approved and directory-based authorization, the identity of the requester is verified independently, and then the specified certificate is pulled up using its serial number:
input.i1.class_id=serialNumRenewInputImpl
For agent-based authentication, no authorization method is required; the request will be manually reviewed and approved by a CA agent. In this case, the auth.instance_id parameter is empty.

Example 4.2. Agent-Based Renewal Profile

 desc=This certificate profile is for renewing certificates to be approved manually by agents.
 visible=true
 enable=true
 enableBy=admin
 renewal=true    
 auth.instance_id=    
 name=Renew certificate to be manually approved by agents
 input.list=i1
 input.i1.class_id=serialNumRenewInputImpl    
 outputlist=o1
 output.o1.class_id=certOutputImpl

For directory-based authentication, the requester must log into an LDAP directory and authenticate against that database, so the auth.instance_id parameter must be set to use directory authentication.

Example 4.3. Directory-Based Renewal Profile

 desc=This certificate profile is for renewing a certificate by serial number by using directory based authentication.
 visible=true
 enable=true
 enableBy=admin
 renewal=true    
 auth.instance_id=UserDirEnrollment    
 authz.acl=user_origreq="auth_token.uid"
 name=Directory-Authenticated User Certificate Self-Renew profile
 input.list=i1
 input.i1.class_id=serialNumRenewInputImpl    
 output.list=o1
 output.o1.class_id=certOutputImpl

NOTE

Directory-based renewal works even if the UidPwdDir plug-in has optional fields set to configure things such as the connection or the DN pattern. This is described in Section 9.2.1, “Setting up Directory-Based Authentication”.
However, for certificate-based renewal, the certificate is presented directly by the browser being used to open the renewal forms, and that certificate is checked in the client database. The certificate is used both to verify the identity of the requester and to get the certificate information for renewal. For certificate-based renewal, it is not necessary to specify a serial number input; instead, set the authentication module to use certificate-based authentication.
auth.instance_id=SSLclientCertAuth

Example 4.4. Certificate-Based Renewal Profile

 desc=This certificate profile is for renewing SSL client certificates.
 visible=true
 enable=true
 enableBy=admin
 renewal=true    
 auth.instance_id=SSLclientCertAuth   
 name=Self-renew user SSL client certificates
 output.list=o1
 output.o1.class_id=certOutputImpl

4.7.3. Renewing Certificates

Almost any certificate issued by Certificate System can be renewed (assuming the original issuing profile allows it). Renewing certificates rather then requesting new certificates can be one way of smoothly transitioning between subsystem certificates as they expire, and is especially useful for CA signing certificates.
Certificate System subsystem and user certificates, as well as end user certificates, can be renewed by resubmitting the original certificate request using the original keys. The renewal process can be done by accessing the end user forms or by generating a new certificate request using the old keys with the certutil command.

4.7.3.1. Renewing Certificates through the End User Pages

There are two methods for renewing certificates in the end users forms. Agent-approved and directory-based renewal require submitting the serial number for the certificate, and the CA draws the information from its current certificate directory entry. Certificate-based renewal uses the certificate in the browser database to regenerate the new certificate, which makes it common for user certificate renewals.

NOTE

Encryption and signing certificates are created in a single step. However, the renewal process only renews one certificate at a time.
To renew both certificates in a certificate pair, each one has to be renewed individually.
4.7.3.1.1. Agent-Approved or Directory-Based Renewals
Sometimes, a certificate renewal request has to be manually approved, either by a CA agent or by your providing login information for the user directory.
  1. Open the end-entities services page for the CA which issued the certificate (or its clone).
    https://server.example.com:9444/ca/ee/ca
  2. Click the name of the renewal form to use.
  3. Enter the serial number of the certificate to renew. This can be in decimal or hexadecimal form.
  4. Click the renew button.
  5. The request is submitted. For directory-based renewals, the renewed certificate is automatically returned. Otherwise, the renewal request will be approved by an agent.
4.7.3.1.2. Certificate-Based Renewal
Some user certificates are stored directory in your browser, so some renewal forms will simply check your browser certificate database for a certificate to renew. If a certificate can be renewed, then the CA automatically approved and reissued it.
  1. Open the end-entities services page for the CA which issued the certificate (or its clone).
    https://server.example.com:9444/ca/ee/ca
  2. Click the name of the renewal form to use.
  3. There is no input field, so click the Renew button.
  4. When prompted, select the certificate to renew.
  5. The request is submitted and the renewed certificate is automatically returned.

4.7.3.2. Renewing Certificates Using certutil

certutil can be used to generate a certificate request using an existing key pair in the certificate database. The new certificate request can then be submitted through the regular profile pages for the CA to issue a renewed certificate.

NOTE

Encryption and signing certificates are created in a single step. However, the renewal process only renews one certificate at a time.
To renew both certificates in a certificate pair, each one has to be renewed individually.
  1. Get the password for the token database.
    cat /var/lib/pki-ca/conf/password.conf
    
    internal=263163888660
  2. Open the certificate database directory of the instance that's certificate is being renewed.
    cd /var/lib/pki-ca/alias
  3. List the key and nickname for the certificate being renewed. In order to renew a certificate, the key pairs used to generate and the subject name given to the new certificate must be the same as the one in the old certificate.
    # certutil -K -d .
    
    certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services"
    Enter Password or Pin for "NSS Certificate DB":
    < 0> rsa      69481646e38a6154dc105960aa24ccf61309d37d   caSigningCert cert-pki-ca
  4. Copy the alias directory as a backup, then delete the original certificate from the certificate database. For example:
    certutil -D -n "ServerCert cert-example"  -d .
  5. Run the certutil command with the options set to the values in the existing certificate.
    certutil -d . -R -k "NSS Certificate DB:cert-pki-ca" -s "cn=CA Authority,o=Example Domain" -a -o example.req2.txt
    The difference between generating a new certificate and key pair and renewing the certificate is the value of the -k option. To generate an entirely new request and key pair, then -k sets the key type and is used with -g, which sets the bit length. For a renewal request, the -k option uses the certificate nickname to access the existing key pair stored in the security database.
    The options used to generate the renewal request are listed in Table 4.1, “Options for Requesting Certificates with certutil”, and more information about certutil is available at http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.
  6. Submit the certificate request and then retrieve it and install it, as described in Section 4.3.2, “Requesting Certificates Using certutil”.

Chapter 5. Using and Configuring the Token Management System: TPS, TKS, and Enterprise Security Client

This chapter gives an overview of using hardware security modules, also called HSMs or tokens, to generate and store Certificate System instance certificates and keys. This chapter includes installation and usage considerations for supported HSMs, describes different tasks for managing tokens, and contains other information for using hardware tokens with Certificate System.

5.1. Configuring TPS Smart Card Operations

The way that the TPS is configured affects how smart card operations are handled, both coming in from the Enterprise Security Client and going between the CA and TPS, depending on the nature of the operation.
There are four operations that are performed through the TPS:
  • Formatting the smart card
  • Enrolling the smart card (requesting and installing certificates on the card) and renewing certificates on the card
  • Changing the password (PIN) on the smart card
  • Upgrading the applet version on the smart card
Each of these operations is configured in the TPS instance's CS.cfg file, similar to a CA enrollment profile.

5.1.1. Configuring Format Operations

When the TPS is contacted by a smart card for a format operation, there are several different operations the TPS can perform, depending on the status of the smart card.
  • Whether an empty token should be rejected or have the required applet (card format) uploaded, so it is made usable.
  • Whether a smart card with an outdated applet should be upgraded and, if so, which version of applet to upload.
  • Whether a smart card with outdated keys should be updated with new symmetric keys. Keys can become outdated if the TKS had a master key changeover.
  • Whether to revoke the certificates associated with the token.
For example, to configure the TPS to reject a smart card without an applet, to update a smart card with new symmetric keys, and to revoke certificates associated with the smart card, the following parameters are set:
op.format.tokenKey.update.applet.emptyToken.enable=true
op.format.tokenKey.update.symmetricKeys.enable=true
op.format.tokenKey.revokeCert=true
The different format operations can be configured to happen automatically by setting the appropriate parameters in the CS.cfg file. The TPS can also be configured with other options, such as requiring LDAP authentication and setting which subsystem instances will process the formatting operations. The parameters are listed in Table 5.1, “Format Operation Parameters”.

Table 5.1. Format Operation Parameters

Parameter Description
op.format.tokenType.update.applet.emptyToken.enable Specifies whether TPS should upload an applet to the token when it does not have one. The valid values are true|false.
op.format.tokenType.update.applet.requiredVersion The version of the applet to use. It should be the file name of the applet without the .ijc extension.
op.format.tokenType.update.applet.directory The local (to the TPS) filesystem directory where the applets are located
op.format.tokenType.update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true|false. When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion.
op.format.tokenType.update.symmetricKeys.requiredVersion The required key version.
op.format.tokenType.revokeCert Specifies if TPS should revoke the certificates associated with the token during this format operation. The default is true. The valid values are true|false.
op.format.tokenType.ca.conn The CA connection to use.
op.format.tokenType.loginRequest.enable Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true|false.
op.format.tokenType.tks.conn The TKS connection to use.
op.format.tokenType.auth.id The LDAP authentication instance to use. The default value is ldap1.
op.format.tokenType.auth.enable Specifies whether to authenticate the user information. The valid values are true|false.
op.format.tokenType.issuerinfo.enable Specifies whether the Phone Home information for the Enterprise Security Client is set. The valid values are true|false.
op.format.tokenType.issuerinfo.value Sets the Phone Home URL; this is the URL for the TPS which the Enterprise Security Client will contact for token operations; this value is set on the token when it is formatted. For example, https://tps.example.com:7888/cgi-bin/home/index.cgi.

5.1.2. Configuring TPS Enrollment Operations

Enrollment covers nearly every step of managing certificates on the token, from issuing them to recovering them if they are lost to revoking them.
Most enrollment parameters occur in pairs, one for signing certificates and one for encryption certificates. The processes for both can be slightly different, as in the case of recovery, even for the same certificate pair. For example:
op.enroll.userKey.keyGen.encryption.ca.profileId=caTokenUserEncryptionKeyEnrollment
op.enroll.userKey.keyGen.signing.ca.profileId=caTokenUserSigningKeyEnrollment
Each token type, such as soKey for security officers or userKey for regular users, has its own op.enroll profile definition.
Each enrollment profile definition has two parts for managing keys: how to generate new keys for the enrollment type and how to recover lost keys for the enrollment type. The profile also defines the CA to connection to, the CA profile to use, the LDAP instance to authenticate to, and whether to perform key archival. For example:
... LDAP authentication connection ...
 op.enroll.soKey.auth.enable=true
 op.enroll.soKey.auth.id=ldap2

... card issuer information ...
 op.enroll.soKey.cardmgr_instance=A0000000030000
 op.enroll.soKey.issuerinfo.enable=true
 op.enroll.soKey.issuerinfo.value=http://server.example.coml:7888/cgi-bin/so/index.cgi

... CA connection and profile ...
 op.enroll.soKey.keyGen.encryption.ca.conn=ca1
 op.enroll.soKey.keyGen.encryption.ca.profileId=caTokenUserEncryptionKeyEnrollment
 op.enroll.soKey.keyGen.encryption.certAttrId=c2
 op.enroll.soKey.keyGen.encryption.certId=C2

... key generation information ...
 op.enroll.soKey.keyGen.encryption.cuid_label=$cuid$
 op.enroll.soKey.keyGen.encryption.keySize=1024
 op.enroll.soKey.keyGen.encryption.keyUsage=0
 op.enroll.soKey.keyGen.encryption.keyUser=0
 op.enroll.soKey.keyGen.encryption.label=encryption key for $userid$
 op.enroll.soKey.keyGen.encryption.overwrite=true

... recovering lost tokens ...
 op.enroll.soKey.keyGen.encryption.recovery.destroyed.revokeCert=false
 op.enroll.soKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0
 op.enroll.soKey.keyGen.encryption.recovery.destroyed.scheme=RecoverLast
 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true
 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1
 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.scheme=GenerateNewKey
 op.enroll.soKey.keyGen.encryption.recovery.onHold.revokeCert=true
 op.enroll.soKey.keyGen.encryption.recovery.onHold.revokeCert.reason=6
 op.enroll.soKey.keyGen.encryption.recovery.onHold.scheme=GenerateNewKey
 op.enroll.soKey.keyGen.encryption.revokeCert=true

... key archival information ...
 op.enroll.soKey.keyGen.encryption.serverKeygen.archive=true
 op.enroll.soKey.keyGen.encryption.serverKeygen.drm.conn=drm1
 op.enroll.soKey.keyGen.encryption.serverKeygen.enable=true

NOTE

There are a number of other parameters which are used by the TPS and are included in the configuration which are never to be altered from the default. For creating new enrollment operation profiles, simply copy these parameters from an existing profile. The list of verboten parameters is in Table 5.3, “Important Enrollment Parameters That Should Never Be Edited”.

Table 5.2. Enrollment Operation Parameters

Parameter Description
op.enroll.tokenType.temporaryToken.tokenType The tokenType to use for temporary tokens. tokenType typically refers to the profile defining how many certificates should be generated, how keys should be recovered, and what format should be used.
op.enroll.tokenType.keyGen.recovery.destroyed.keyType.num Specifies number of keyTypes. The default value is 2.
op.enroll.tokenType.keyGen.recovery.destroyed.keyType.value.# Specifies keyType. The valid values are signing|encryption.
op.enroll.tokenType.keyGen.signing.recovery.destroyed.scheme Specifies the signing certificate recovery scheme for destroyed tokens. The default value is GenerateNewKey. The other possible value is RecoverLast.
op.enroll.tokenType.keyGen.signing.recovery.destroyed.revokeCert Sets whether signing certificates should be revoked. The valid values are true|false. The default value is true.
op.enroll.tokenType.keyGen.signing.recovery.destroyed.revokeCert.reason
Sets what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.scheme Specifies the encryption certificate recovery scheme for destroyed tokens. The default value is RecoverLast. The other possible value is GenerateNewKey.
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.revokeCert Specifies if the encryption certificate should be revoked. The valid values are true|false. The default value is true.
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.revokeCert.reason  
op.enroll.tokenType.keyGen.encryption.recovery.destroyed.revokeCert.reason
Specifies what the encryption certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.recovery.keyCompromise.keyType.num The number of key types for recovery for the tokens whose keys are compromised.
op.enroll.tokenType.keyGen.recovery.keyCompromise.keyType.value.# Specifies keyType. The default values are signing|encryption.
op.enroll.tokenType.keyGen.signing.recovery.keyCompromise.scheme Specifies the signing certificate recovery scheme for tokens whose keys are compromised. The default value is GenerateNewKey. The other possible value is RecoverLast.
op.enroll.tokenType.keyGen.signing.recovery.keyCompromise.revokeCert Specifies if the signing certificate should be revoked if the original token's key has been comprised. The valid values are true|false.
op.enroll.tokenType.keyGen.signing.recovery.keyCompromise.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.encryption.recovery.keyCompromise.scheme Specifies encryption certificate recovery scheme for tokens whose key is compromised. The valid values include GenerateNewKey and RecoverLast.
op.enroll.tokenType.keyGen.encryption.recovery.keyCompromise.revokeCert Specifies if the encryption certificate should be revoked if the token's key has been comprised. The valid values are true|false.
op.enroll.tokenType.keyGen.encryption.recovery.keyCompromise.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.recovery.onHold.keyType.num The number of key types for the tokens to put on hold for temporary loss reasons. The valid values are integers. The default is 2.
op.enroll.tokenType.keyGen.recovery.onHold.keyType.value.# Specifies keyType. The default values are signing|encryption.
op.enroll.tokenType.keyGen.signing.recovery.onHold.scheme The recovery scheme for signing certificates for tokens that are to be put on hold. The valid values are GenerateNewKey and RecoverLast.
op.enroll.tokenType.keyGen.signing.recovery.onHold.revokeCert Specifies if the signing certificate should be revoked if the token's key has been comprised. The valid values are true|false.
op.enroll.tokenType.keyGen.signing.recovery.onHold.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.encryption.recovery.onHold.scheme The recovery scheme for encryption certificates for tokens that are to be put on hold. The valid values are GenerateNewKey and RecoverLast.
op.enroll.tokenType.keyGen.encryption.recovery.onHold.revokeCert Specifies if the encryption certificate should be revoked if the token's key has been comprised. The valid values are true|false.
op.enroll.tokenType.keyGen.encryption.recovery.onHold.revokeCert.reason
Specifies what the signing certificate revocation reason should be. The default value is 0. The valid values are as follows:
  • 0 - Unspecified.
  • 1 - Key compromised.
  • 2 - CA key compromised.
  • 3 - Affiliation changed.
  • 4 - Certificate superseded.
  • 5 - Cessation of operation.
  • 6 - Certificate is on hold.
op.enroll.tokenType.keyGen.tokenName The name of the token to use. The TPS can substitute some special strings. For example, if using cuid, the tokenName is substituted with the CUID of the token; if using uid, the tokenName is substituted with the UID of the authenticating user.
op.enroll.tokenType.keyGen.keyType.num The number of keys/certificates to be generated for the profile. The values are integers. The default is 2.
op.enroll.tokenType.keyGen.keyType.value.# Specifies keyType. The default values are signing|encryption.
op.enroll.tokenType.keyGen.signing.keySize Specifies the key size to use for key generation. The recommended setting is 2048.
op.enroll.tokenType.keyGen.signing.label The token label for the signing certificate. The valid values are $pretty_cuid$, $cuid$, $msn$, $userid$, and $profileId$. These variables are replaced by the user-supplied information when the certificate is generated.
op.enroll.tokenType.keyGen.signing.cuid_label The CUID to show in the certificate.
op.enroll.tokenType.keyGen.signing.overwrite Specifies if the TPS should overwrite the existing signing certificate. The valid values are true|false.
op.enroll.tokenType.keyGen.signing.ca.profileId The CA profile that should be used for creating the signing certificate. The default is caTokenUserSigningKeyEnrollment.
op.enroll.tokenType.keyGen.signing.ca.conn The CA connection to use. The default value is ca1.
op.enroll.tokenType.keyGen.encryption.keySize The key size for the encryption key. The recommended setting is 2048.
op.enroll.tokenType.keyGen.encryption.label The token label for the encryption certificate. The valid values are $pretty_cuid$, $cuid$, $msn$, $userid$, and $profileId$. These variables are replaced by the user-supplied information when the certificate is generated.
op.enroll.tokenType.keyGen.encryption.cuid_label The CUID to show in the certificate.
op.enroll.tokenType.keyGen.encryption.overwrite Specifies if the encryption certificate on the token should be overwritten. The valid values are true|false.
op.enroll.tokenType.keyGen.encryption.ca.profileId The CA profile to use for enrolling encryption certificates. The default value is caTokenUserEncryptionKeyEnrollment.
op.enroll.tokenType.keyGen.encryption.ca.conn The CA connection to use to generate encryption certs. The default value is ca1.
op.enroll.tokenType.update.applet.emptyToken.enable Specifies whether TPS should upload an applet to the token when it does not have one. The valid values are true|false.
op.enroll.tokenType.update.applet.enable Specifies if applet upgrade is turned on. The valid values are true|false.
op.enroll.tokenType.update.applet.requiredVersion The version of the applet to use. It should be the file name of the applet without the .ijc extension.
op.enroll.tokenType.update.applet.directory The local filesystem directory where the applets are located.
op.enroll.tokenType.update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true|false. When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion.
op.enroll.tokenType.update.symmetricKeys.requiredVersion The required key version.
op.enroll.tokenType.loginRequest.enable Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true|false.
op.enroll.tokenType.pinReset.enable Specifies if the token's PIN should be reset. The default value is true. The valid values are true|false.
op.enroll.tokenType.pinReset.pin.minLen The minimum number of characters for the PIN.
op.enroll.tokenType.pinReset.pin.maxRetries The maximum number of times PIN authentication can be attempted on the token before the key is locked. This value is set on the token when the token is formatted.
op.enroll.tokenType.pinReset.pin.maxLen The maximum number of characters for the PIN.
op.enroll.tokenType.tks.conn The TKS connection to use.
op.enroll.tokenType.auth.id The LDAP authentication instance to use. The default value is ldap1.
op.enroll.tokenType.auth.enable Specifies whether to authenticate the user information. The valid values are true|false.

There are some parameters in the CS.cfg file that are set to configure signing and encryption enrollment operations which should never be altered.

Table 5.3. Important Enrollment Parameters That Should Never Be Edited

op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.encrypt
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.sign
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.signRecover
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.decrypt
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.derive
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.unwrap
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.wrap
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.verifyRecover
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.verify
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.sensitive
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.private
op.enroll.tokenType.keyGen.signing|encryption.public.keyCapabilities.token
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.encrypt
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.sign
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.signRecover
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.decrypt
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.derive
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.unwrap
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.wrap
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.verifyRecover
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.verify
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.sensitive
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.private
op.enroll.tokenType.keyGen.signing|encryption.private.keyCapabilities.token

5.1.3. Configuring TPS Renewal Operations

Renewal operations regenerate the certificates on a token, using existing key pairs to recreate the certificates. This means that the renewal profile mirrors the enrollment configuration that relates directly to generating the certificate. Other aspects of the enrollment operations — such as recovering a lost token — are still managed through the enrollment configuration.
As with enrollment parameters, the renewal parameters occur in pairs, one for signing certificates and one for encryption certificates.
Each token type, such as soKey for security officers or userKey for regular users, has its own op.renewal profile definition.

Table 5.4. Renewal Operation Parameters

Parameter Description
op.renewal.tokenType.keyType.num The number of keys/certificates that are generated for the profile. The values are integers. The default is 2.
op.renewal.tokenType.keyType.value.# Specifies the key type. The default values are signing|encryption.
op.renewal.tokenType.signing.enable Sets whether the signing certificate renewal profile is enabled.
op.renewal.tokenType.signing.certAttrId Identifies which key on the token is used for the signing certificate.
op.renewal.tokenType.signing.certId Identifies which key on the token is used for the signing certificate.
op.renewal.tokenType.signing.ca.profileId The CA profile that should be used for renewing the signing certificate. The default is caTokenUserSigningKeyRenewal.
op.renewal.tokenType.signing.ca.conn The CA connection to use. The default value is ca1.
op.renewal.tokenType.encryption.enable Sets whether the encryption certificate renewal profile is enabled.
op.renewal.tokenType.encryption.certAttrId Identifies which key on the token is used for the encryption certificate.
op.renewal.tokenType.encryption.certId Identifies which key on the token is used for the encryption certificate.
op.renewal.tokenType.encryption.ca.profileId The CA profile to use for renewing encryption certificates. The default value is caTokenUserEncryptionKeyRenewal.
op.renewal.tokenType.encryption.ca.conn The CA connection to use to generate encryption certs. The default value is ca1.

5.1.4. Configuring the PIN Reset Operation

The PIN is the password which protects the certificates and keys on the smart card. The TPS can place two restrictions on the PIN: the maximum length and the minimum length. For example, to require PINs to be between 6 and 12 characters, the following parameters are set:
op.pinReset.userKey.pinReset.pin.maxLen=12
op.pinReset.userKey.pinReset.pin.minLen=6
Like the formatting operation, the TPS can be configured to upload or update the applet version on the smart card, update the symmetric key, and required LDAP authentication, as well as setting which subsystem instances will process the operation. The CS.cfg file parameters for resetting the PIN are listed in Table 5.5, “PIN Reset Operation Parameters”.

Table 5.5. PIN Reset Operation Parameters

Parameter Description
op.pinReset.tokenType.update.applet.emptyToken.enable Specifies whether TPS should upload an applet to the token when it does not have one. The valid values are true|false.
op.pinReset.tokenType.update.applet.enable Specifies if applet upgrade is turned on. The valid values are true|false.
op.pinReset.tokenType.update.applet.requiredVersion The required key version.
op.pinReset.tokenType.update.applet.directory The local filesystem directory where the applets are located.
op.pinReset.tokenType.update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true|false. When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion.
op.pinReset.tokenType.update.symmetricKeys.requiredVersion The required key version.
op.pinReset.tokenType.loginRequest.enable Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true|false.
op.pinReset.tokenType.pinReset.pin.minLen The minimum number of characters for the PIN.
op.pinReset.tokenType.pinReset.pin.maxRetries The maximum number of times PIN authentication can be attempted on the token before the key is locked. This value is set on the token when the PIN is set or reset.
op.pinReset.tokenType.pinReset.pin.maxLen The maximum number of characters for the PIN.
op.pinReset.tokenType.tks.conn The TKS connection to use.
op.pinReset.tokenType.auth.id The LDAP authentication instance to use. The default value is ldap1.
op.pinReset.tokenType.auth.enable Specifies whether to authenticate the user information. The valid values are true|false.

5.1.5. Configuring the Applet Update Operation

The TPS communicates with an applet on the smart card. The smart cards can be manufactured with both a card manager applet and a vendor applet or with only the card manager applet. If the cards only have the card manager applet, the TPS can install the Certificate System applet onto the smart card. Similarly, an old applet can be replaced with a new applet. Any keys or certificates created or managed with the old applet are destroyed.

NOTE

The only supported card manager applet is the CoolKey applet which ships with Red Hat Enterprise Linux 5.3.
To upgrade the applet in the TPS, put the new applet in the applet directory, and set the update.applet.enable parameter in the CS.cfg file to true. For example, to update the applet when enrolling a smart card of the type userKey, the parameters would be the following:
op.enroll.userKey.update.applet.enable=true
op.enroll.userKey.update.applet.emptyToken.enable=false
op.enroll.userKey.update.applet.requiredVersion=1.3.44724DDE
op.enroll.userKey.update.applet.directory=/usr/share/pki/tps/applets
op.enroll.userKey.update.applet.encryption=true
If a smart card only has the card manager, then the card manager capability must be enabled by editing the following parameter:
op.operation.key_type.update.applet.emptyToken.enable=true

NOTE

If the filename set in the update.applet.requiredVersion parameter contains any alphabetic characters, then all of these alphabetic characters must always be uppercase letters; this applies to the actual name of the file, as well as the update.applet.requiredVersion parameter.
The TPS queries the applet version on the smart card before trying to execute any operations.
If the update feature is enabled and the applet version from the client is different from the one specified by the update.applet.requiredVersion parameter, the TPS updates the applet automatically.

NOTE

The TPS audit log shows whether the applet update worked successfully.
The parameters to enable upgrading the applets are set in the TPS operation configurations. The parameters for upgrading the applet during a formatting operation are in Table 5.1, “Format Operation Parameters”; the parameters for upgrading the applet when resetting the PIN are listed in Table 5.5, “PIN Reset Operation Parameters”; and the parameters for upgrading the applet during an enrollment operation are in Table 5.2, “Enrollment Operation Parameters”.

5.2. Allowing Token Renewal

There are two default policies to allow encryption and signing certificates to be renewed on a token. Whether a token can be renewed depends on whether the user policy for the token allows it to be renewed.
Setting the token policy is a TPS agent task and is described in the Agent's Guide.
  1. Log into the TPS services page as an agent.
    https://server.example.com:7889/tus/
  2. In the Agent Operations tab, search for or list the tokens, and click the token's ID number in the results page.
  3. Click the Edit button at the bottom of the screen.
  4. In the Policy field, set RENEW=YES.
  5. Save the changes.

5.3. Changing the Token Policy

A token policy sets rules on what the user can do after the token is enrolled, such as whether the user can reset the password or reuse the token.
There are three supported token policies:
  • RE_ENROLL, which allows a user to re-enroll certificates with the same token
  • PIN_RESET, which allows the token user to initiate a PIN reset operation
  • RENEW, which allows a user to regenerate their existing certificates using the original keys and an extended validity period
The token policy settings are configured through the TPS agent services page, as described in the Agent's Guide. The way to edit the token policy for a specific token is to select it from the list of tokens in the Agent Operations tab.
Editing the Token Policy

Figure 5.1. Editing the Token Policy


The supported token policies accept values of either YES or NO. To set two policies, separate them with a semi-colon. For example:
RE_ENROLL=NO;PIN_RESET=YES

RENEW=NO;PIN_RESET=NO
If both RE_ENROLL and RENEW are set to YES, then the renewal setting takes precedence, the token certificates are renewed when they expire.
The default values for all three parameters can be set in the TPS's CS.cfg file in the tokendb.defaultPolicy parameter. For example:
tokendb.defaultPolicy=RE_ENROLL=YES

NOTE

If the PIN_RESET policy is not set, then user-initiated PIN resets are allowed by default. If the policy is present and is changed from NO to YES, then a PIN reset can be initiated by the user once; after the PIN is reset, the policy value automatically changes back to NO.

5.4. Setting Token Types for Specified Smart Cards

The TPS can be configured to use specific token profiles to format a new smart card, based on some attribute of the smart card, such as its answer-to-reset (ATR) message or a range of serial numbers for the smart cards.
This is useful to manage multiple types of smart card profiles in a single deployment to determine and assign the smart card profile automatically based on physical distribution of those cards, rather than some software process change.
There are three steps to configuring type-specific formatting operations:
  1. Configure the type-specific TPS profile, as in Section 5.1, “Configuring TPS Smart Card Operations”.
  2. Configure the type-specific authentication profile, as in Section 5.8.3, “Configuring or Disabling LDAP Authentication”.
  3. Configure the mapping filter and target, as in Section 5.4.2, “Mapping Token Types to Smart Card Operation Profiles”.

5.4.1. Default Token Types

There are several default token types already configured for smart card operations, as listed in Table 5.6, “Default Token Types”. There are several profiles available for security officers, regular users, and devices.

Table 5.6. Default Token Types

Token Type Description
cleanToken For operations for any blank token, without any other applied token types.
soKey For operations for generating keys for security officer stations.
soCleanSOToken For operations for blank tokens for security officer stations.
soKeyTemporary For operations for temporary security officer tokens.
soCleanUserToken For operations for blank user tokens for security officers.
soUserKey For operations for security officer user tokens.
tokenKey For operations for generating keys for uses with servers or devices.
userKey For operations for regular user tokens.
userKeyTemporary For operations for temporary user tokens.

5.4.2. Mapping Token Types to Smart Card Operation Profiles

Each type of operation contains a parameter mapping.#. containing mapping IDs.

NOTE

If the mapping.#. parameter contains more than one mapping ID, then each mapping ID is processed in sequential order until a target is determined or an error is returned. If the mapping.#. parameter is missing, then the code returns an error.
Each mapping ID references a series of parameters called filters. Each filter may contain a specific value for the request to be tested against. Empty or missing filters act as a wildcard and allow the request to contain any value and are thus inherently true. If the request passes all filters, the specified target token profile is used.
The filter is then mapped to a target profile or token type. Any token which initiates a format operation which matches that filter is automatically formatted according to the specific token type format profile.
For example:
... this maps CUIDs 1 through 100 to exampleKey ...
op.format.mapping.0.filter.appletMajorVersion=
op.format.mapping.0.filter.appletMinorVersion=
op.format.mapping.0.filter.tokenATR=
op.format.mapping.0.filter.tokenCUID.end=1
op.format.mapping.0.filter.tokenCUID.start=100
op.format.mapping.0.filter.tokenType=exampleKey
op.format.mapping.0.target.tokenType=exampleKey

... this matches every token ...
op.format.mapping.6.filter.appletMajorVersion=
op.format.mapping.6.filter.appletMinorVersion=
op.format.mapping.6.filter.tokenATR=
op.format.mapping.6.filter.tokenCUID.end=
op.format.mapping.6.filter.tokenCUID.start=
op.format.mapping.6.target.tokenType=tokenKey

op.format.mapping.order=0,1,2,3,4,5,6
Blank attributes match every token.

NOTE

The token type is configured in the token itself by the manufacturer or as part of the applet.
The configuration file parameters used to set up mapping and filters are in Table 5.7, “Mapping and Filters”.

Table 5.7. Mapping and Filters

Parameter Description
op.operation[a].mapping.order The order of the mappings. The format is n,n,n. For example, 0,1,2. These mapping IDs must be defined in op.Operation.mapping.# parameters, where # is one of the mapping IDs specified in the order.
op.operation.mapping.#[b].filter.tokenType The filter based on the tokenType sent by the Enterprise Security Client. This is the expected tokenType that TPS will receive from the Enterprise Security Client. For example, userKey. The target tokenType will be matched if the tokenType sent by the Enterprise Security Client also matches.
op.operation.mapping.#.filter.tokenATR The filter based on the ATR sent by the Enterprise Security Client. This is the expected ATR that the TPS will receive from the Enterprise Security Client. For example, 1234. The target tokenType will be matched if the ATR of the token and the ATR mentioned here matches.
op.operation.mapping.#.filter.tokenCUID.start The filter based on the CUID range. The target tokenType will be matched if the CUID falls within the start-end range.
op.operation.mapping.#.filter.tokenCUID.end The filter based on the CUID range. The target tokenType will be matched if the CUID falls within the start-end range.
op.operation.mapping.#.filter.appletMajorVersion The filter based on the applet version. This filter can be empty or an applet major version specified by the client. If both the major and minor versions are both zero, this indicates there is no applet on the token.
op.operation.mapping.#.filter.appletMinorVersion The filter based on the minor applet version. For an applet file named 1.3.423FFAZ.ijc, 3 is the minor version. The target tokenType will be matched if the applet's minor version sent by the Enterprise Security Client matches this parameter.
op.operation.mapping.#.target.tokenType Set this parameter to the tokenType to select for this mapping. For example, userKey.
[a] operation can be enroll, PIN reset, or format.
[b] # is an integer.

5.4.3. Example: Token Mapping with Two Different Token Types

The process for a format operation is as follows:
  1. The user inserts the token. The token is recognized by its CUID in the Enterprise Security Client.
  2. The user selects the token and clicks Format.
  3. The Enterprise Security Client prompts for LDAP authentication.
  4. The format operation completes.
When the token is selected in the Enterprise Security Client, the Enterprise Security Client sends in the applet version, CUID, ATR, and other information about the token to the TPS server. TPS server checks the op.format.mapping.. section in the CS.cfg file and figures out which tokenType to use for the token, either devKey or qaKey. It then uses the appropriate op.format... section to perform LDAP authentication to the appropriate server and to the corresponding TKS for generating session keys.
This is an example, configuring two different sets of tokens distinguished by their CUID ranges. These sets have the following settings:
  • The development team has 100 tokens and the token set CUIDs from 1000-0000-0000-0000 to 1000-0000-0000-0100.
  • The QA team that has 100 tokens and the token set CUIDs from 2000-0000-0000-0000 to 2000-0000-0000-0100.
  • The development team uses the LDAP server ldap-dev, and the QA team uses the LDAP server ldap-qa for authentication.
Configuring the format operation in the TPS involves the following changes to the TPS configuration file, CS.cfg.
##########################################################################
# Create two mappings
##########################################################################
op.format.mapping.0.filter.tokenCUID.start=1000000000000000
op.format.mapping.0.filter.tokenCUID.end=1000000000000100
##########################################################################
op.format.mapping.1.filter.tokenCUID.start=2000000000000000
op.format.mapping.1.filter.tokenCUID.end=20000000000001000
##########################################################################
# Profile for DevKey
##########################################################################
op.format.devKey.update.applet.emptyToken.enable=true
op.format.devKey.update.applet.requiredVersion=1.3.427BDDB8
op.format.devKey.update.applet.directory=/usr/share/pki/tps/applets
op.format.devKey.update.applet.encryption=true
op.format.devKey.update.symmetricKeys.enable=false
op.format.devKey.update.symmetricKeys.requiredVersion=1
op.format.devKey.revokeCert=true
op.format.devKey.ca.conn=ca1
op.format.devKey.loginRequest.enable=true
op.format.devKey.tks.conn=tks1
op.format.devKey.auth.id=ldap-dev
op.format.devKey.auth.enable=true
##########################################################################
# Profile for QAKey
##########################################################################
op.format.qaKey.update.applet.emptyToken.enable=true 
op.format.qaKey.update.applet.requiredVersion=1.3.427BDDB8
op.format.qaKey.update.applet.directory=/usr/share/tps/applets
op.format.qaKey.update.applet.encryption=true
op.format.qaKey.update.symmetricKeys.enable=false
op.format.qaKey.update.symmetricKeys.requiredVersion=1
op.format.qaKey.revokeCert=true 
op.format.qaKey.ca.conn=ca1
op.format.qaKey.loginRequest.enable=true 
op.format.qaKey.tks.conn=tks1
op.format.qaKey.auth.id=ldap-qa 
op.format.qaKey.auth.enable=true
##########################################################################
# LDAP Connection settings for devKey
##########################################################################
auth.instance.0.type=LDAP_Authentication
auth.instance.0.libraryName=/usr/lib/libldapauth.so
auth.instance.0.libraryFactory=GetAuthentication
auth.instance.0.authId=ldap-dev
auth.instance.0.hostport=ldap-dev.example.com:1111
auth.instance.0.SSLOn=false
auth.instance.0.retries=1
auth.instance.0.retryConnect=3
auth.instance.0.baseDN=o=dev
auth.instance.0.ui.title.en=LDAP Authentication
auth.instance.0.ui.description.en=This authenticates user against the DEV
   LDAP directory.
auth.instance.0.ui.id.UID.name.en=LDAP User ID
auth.instance.0.ui.id.PASSWORD.name.en=LDAP Password
auth.instance.0.ui.id.UID.description.en=DEV LDAP User ID
auth.instance.0.ui.id.PASSWORD.description.en=DEV LDAP Password
##########################################################################
 # LDAP Connection settings for qaKey
##########################################################################
auth.instance.1.type=LDAP_Authentication 
auth.instance.1.libraryName=/usr/lib/libldapauth.so
auth.instance.1.libraryFactory=GetAuthentication 
auth.instance.1.authId=ldap-qa
auth.instance.1.hostport=ldap-qa.example.com:2222
auth.instance.1.SSLOn=false
auth.instance.1.retries=1 
auth.instance.1.retryConnect=3 
auth.instance.1.baseDN=o=qa
auth.instance.1.ui.title.en=LDAP Authentication
auth.instance.1.ui.description.en=This authenticates user against the QA
   LDAP directory.
auth.instance.1.ui.id.UID.name.en=LDAP User ID
auth.instance.1.ui.id.PASSWORD.name.en=LDAP Password
auth.instance.1.ui.id.UID.description.en=QA LDAP User ID
auth.instance.1.ui.id.PASSWORD.description.en=QA LDAP Password
##########################################################################
  • The two format operation profiles are devKey and qaKey.
  • The two mapping order 0 refers to the devKey and 1 refers to the qaKey.
  • The two authentication instances 0 and 1 correspond to ldap-dev and ldap-qa, respectively.

5.5. Setting Token Status Transitions

The status of a token helps control the use of that token if it is somehow lost or inaccessible. Essentially, the token status is a way for agents to suspend or terminate tokens, similar to certificates being revoked. The status is stored as a numeric value in the token configuration; the six statuses are listed in Table 5.8, “Token Statuses”.
Agents can change the status of the token. This is a transition, moving from one status to another. The status of the token impacts whether a key should be recovered from the DRM or reissued, whether new tokens will be blocked because there are already active existing tokens, and whether to issue or revoke temporary tokens. Administrators need to be able to control how statuses can be applied. For example, a token which is temporarily lost needs to be moved back to an active state once it is found. However, a token which is marked permanently lost or damaged (meaning it should be revoked) should never be allowed to be moved back into an active state.
This administrative control over status transitions is configured in the tokendb.allowedTransitions parameter in the CS.cfg file. The allowed transitions are set in number pairs, the first showing the original status and the second showing the status it is allowed to move to. For example, this setting allows a token with a status of temporarily lost (3) to move to a status of found (4):
tokendb.allowedTransitions=3:4
Multiple status transitions are entered as a comma-separated list. The default value essentially allows all logical transitions and prohibits permanently lost or damaged tokens from being marked as found.
tokendb.allowedTransitions=0:1,0:2,0:3,0:4,0:5,0:6,3:4,3:5,3:6,4:1,4:2,4:3,4:6

NOTE

If the tokendb.allowedTransitions parameter is missing or not set, then all transitions are allowed. If the parameter is set, then only transitions were are explicitly set are allowed.

IMPORTANT

If no transitions are given from a particular token state (for instance, a transition is given to go to permanently lost, but there is no transition from permantently lost to another state), then the token status cannot be edited. The token will permanently remain in that final state and the Edit Token area in the TPS agent's page will be grayed out.
  1. Stop the TPS subsystem.
    service pki-tps stop
  2. Open the TPS's configuration directory.
    cd /etc/pki-tps
  3. Open the CS.cfg file.
    vim CS.cfg
  4. Add or edit the tokendb.allowedTransitions parameter at the end of the file. The available token statuses are listed in Table 5.8, “Token Statuses”.
    tokendb.allowedTransitions=0:1,0:2,0:3,0:4,0:5,0:6,3:4,3:5,3:6,4:1,4:2,4:3,4:6
  5. Restart the TPS subsystem.
    service pki-tps start

Table 5.8. Token Statuses

Status Meaning Numeric Value
The token is uninitialized. The token has not been enrolled. 0
The token is physically damaged. The TPS revokes the user certificates and marks the token lost. 1
The token has been permanently lost. The TPS revokes the user certificates and marks the token lost. 2
The token is temporarily lost or unavailable. The TPS puts the user certificates on hold and marks the token inactive. 3
The lost token has been found. The TPS takes the certificates off hold and marks the token active. 4
The lost token cannot be found (permanently lost). The TPS revokes both the temporary and the original certificates and marks the token lost. 5
This token has been terminated. The TPS terminates the token. Terminating a token terminates the certificates and keys on the token and breaks the association between the token and the user in the token database. The physical token can still be formatted and reused afterward, but this change of status will mark a record of the termination event. 6

5.6. Automating Encryption Key Recovery

The Certificate System allows for a semi-automated recovery if a user loses, destroys, or misplaces a token. The TPS automatically recovers the appropriate encryption keys and certificates for a permanently or temporarily lost token, depending on the circumstances of the token loss. To prevent misuse of the recovery feature, the TPS requires that a user must have a single active token.
When a user loses a token, the user must first get a replacement token. If a new enrollment is attempted with this new token, the TPS blocks the enrollment since the user already has an active token.
The token status in the database must be changed to lost. This action is performed through the TPS agent services page. The TPS agent, after affirmatively identifying the user, can search for the user's ID in the Search tokens link. The TPS agent select the active token and update the status, with the appropriate reason to recover the key.

Table 5.9. Lost Token Statuses

Agent Status Option Configuration Parameter Default Recovery Scheme
This token has been physically damaged. reason=0 RecoverLast
This token has been permanently lost. reason=1 GenerateNewKey
This token has been temporarily lost. reason=6 GenerateNewKey

There are two different schemes for recovery. GenerateNewKey creates a new key and certificate. This is used for signing keys. RecoverLast recovers the last encryption key and associated certificate.

5.6.1. Configuring Enrollment for Replacement Tokens

The user can enroll for a replacement token. It is preferred that signing keys be generated on the smart card and not archived so that if the smart card is lost, new signing keys and certificates must be regenerated on the token, and temporary certificates created.
There is a different policy set for all three lost states, and each policy sets independently the rules for generating keys. Each policy set is part of the enrollment configuration.
op.enroll.userKey.keyGen.recovery.lost_type
For damaged tokens, the lost_type is destroyed.. For permanently lost tokens, it is keyCompromised. For temporarily lost tokens, it is onHold.
The policy describing which keys should be regenerated and which keys should be recovered is defined in the following TPS CS.cfg parameters. For example:
op.enroll.userKey.keyGen.recovery.destroyed.keyType.num=2
op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.0=signing
op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.1=encryption

op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert=true
op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert.reason=0
op.enroll.userKey.keyGen.signing.recovery.destroyed.scheme=GenerateNewKey

op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert=false
op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0
op.enroll.userKey.keyGen.encryption.recovery.destroyed.scheme=RecoverLast
Set revokeCert=true to revoke certificates if a token's certificates are replaced after being lost.
... for the signing key ... 
 op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert=true
 op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert.reason=0

 op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert=true
 op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert.reason=1

 op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert=true
 op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert.reason=6

 op.enroll.userKey.keyGen.signing.revokeCert=true      

 ... for the encryption key ...
 op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert=false
 op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0
 
 op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true
 op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1

 op.enroll.userKey.keyGen.encryption.recovery.onHold.revokeCert=true
 op.enroll.userKey.keyGen.encryption.recovery.onHold.revokeCert.reason=6

 op.enroll.userKey.keyGen.encryption.revokeCert=true

5.6.2. Configuring Key Generation for Temporary Tokens

If the smart card loss is temporary, the user can be enrolled for a temporary replacement. The profile for the replacement smart card is defined in the userKeyTemporary parameter in the TPS CS.cfg file. The certificate used through this profile is valid for seven days by default.
... snip ...
op.enroll.userKeyTemporary.keyGen.encryption.ca.conn=ca1
op.enroll.userKeyTemporary.keyGen.encryption.ca.profileId=caTempTokenUserEncryptionKeyEnrollment         
op.enroll.userKeyTemporary.keyGen.encryption.certAttrId=c2
op.enroll.userKeyTemporary.keyGen.encryption.certId=C2
op.enroll.userKeyTemporary.keyGen.encryption.cuid_label=$cuid$
op.enroll.userKeyTemporary.keyGen.encryption.keySize=1024
op.enroll.userKeyTemporary.keyGen.encryption.keyUsage=0
op.enroll.userKeyTemporary.keyGen.encryption.keyUser=0
op.enroll.userKeyTemporary.keyGen.encryption.label=encryption key for $userid$
op.enroll.userKeyTemporary.keyGen.encryption.overwrite=true
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.decrypt=true
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.derive=false
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.encrypt=false
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.private=true
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.sensitive=true
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.sign=false
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.signRecover=false
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.token=true
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.unwrap=true
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.verify=false
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.verifyRecover=false
op.enroll.userKeyTemporary.keyGen.encryption.private.keyCapabilities.wrap=false
op.enroll.userKeyTemporary.keyGen.encryption.privateKeyAttrId=k4
op.enroll.userKeyTemporary.keyGen.encryption.privateKeyNumber=4
... snip ...

5.7. Managing Shared Keys

The Token Key Service (TKS) derives keys for the TPS to use. TKS keys process key material sent from the user, the token CUID, an agreed on algorithm, and a public key to recombine a key that exists on the token (that is why the keys are derived rather than generated). These derived keys both encrypt sessions between the TPS and the Enterprise Security Client and generate keys for the token enrollment.
Part of the way that the TKS derives these keys is by using a common master key that is known to the TKS and existent on each of the smart cards or tokens. New master keys can be generated, stored in the TKS, and transported to the smart cards or additional HSM key stores to be used for token management operations using the tkstool command.
Managing master keys is described in this section.

5.7.1. Generating Master Keys

Generate a master key is used as part of the algorithm to derive other keys on tokens and smart cards. New master keys can be generated on the TKS using the tkstool utility.
  1. Get the PIN to use to access the TKS's security databases. The internal PIN is the one used for the security databases.
    cat /var/lib/pki-tks/conf/password.conf
    
    internal=649713464822
    internaldb=secret12
    replicationdb=-752230707
  2. Open the TKS instance alias/ directory.
    cd /var/lib/pki-tks/alias
  3. Generate the new master key. For example:
    tkstool -M -n new_master1 -d /var/lib/pki-tks/alias -h token_name
    
    Enter Password or Pin for "NSS Certificate DB":
    
    Generating and storing the master key on the specified token . . .
    
    Naming the master key "new_master" . . .
    
    Computing and displaying KCV of the master key on the specified token . . .
    
        new_master key KCV:  CA5E 1764
    
    
    Successfully generated, stored, and named the master key
    including computing and displaying its KCV!
  4. Verify that the keys have been added properly to the database.
    tkstool -L -d . 
    
    
     slot:  NSS User Private Key and Certificate Services
    token:  NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
            <0> new_master
Using the tkstool is explained in more detail in the Certificate System Command-Line Tools Guide.

5.7.2. Generating and Transporting Wrapped Master Keys

If a master key is going to be used on an external token or in multiple locations, then that key must be wrapped so that it can be safely transported to the hardware tokens. The tkstool utility can be used to generate both new master and transport keys. The transport key is used to send the master key securely to the facility where the tokens are generated.

NOTE

Tokens that are generated with a particular master key can only be used with that master key.
  1. Get the PIN to use to access the TKS's security databases. The internal PIN is the one used for the security databases.
    cat /var/lib/pki-tks/conf/password.conf
    
    internal=649713464822
    internaldb=secret12
    replicationdb=-752230707
  2. Open the TKS instance alias/ directory.
    cd /var/lib/pki-tks/alias
  3. Create a transport key called transport.
    tkstool -T -d . -n transport

    NOTE

    The tkstool utility prints out the key shares and KCV values for each of the three session keys that are generated. Save them to file since these are all necessary to regenerate the transport key in the new databases in step 7 or to regenerate the key if it is lost.
    When prompted, fill in the database password, then type in some noise to seed the random number generator.
    Enter Password or Pin for "NSS Certificate DB":
    sh: tput: command not found
    
    A random seed must be generated that will be used in the
    creation of your key.  One of the easiest ways to create a
    random seed is to use the timing of keystrokes on a keyboard.
    
    To begin, type keys on the keyboard until this progress meter
    is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!
    
    
    Continue typing until the progress meter is full:
    
    |************************************************************|
    
    Finished.
    
    
    Type the word "proceed" and press enter
    The next prompts generate a series of session keys. For example:
    The next screen generates the first session key share . . .
    
    
    Type the word "proceed" and press enter to continue (or ^C to break):  proceed
    sh: tput: command not found
    
    Generating the first session key share . . .
    
    
        first session key share:      8979 975D 6867 FB07
                                      5107 08B6 E625 01FD
    
    
        first session key share KCV:  0420 54F0
    
    
    (1) Write down and save the value for this first session key share.
    
    (2) Write down and save the KCV value for this first session key share.
    
    
    Type the word "proceed" and press enter to continue (or ^C to break):  proceed
    
    .... snip ....
    
    Generating first symmetric key . . .
    
    Generating second symmetric key . . .
    
    Generating third symmetric key . . .
    
    Extracting transport key from operational token . . .
    
        transport key KCV:  444F D5C2
    
    
    Storing transport key on final specified token . . .
    
    Naming transport key "transport" . . .
    
    Successfully generated, stored, and named the transport key!
  4. Use the transport key to generate and wrap a master key and store it in a file called file.
    tkstool -W -d . -n new_master -t transport -o file 
    
    Enter Password or Pin for "NSS Certificate DB":
    Retrieving the transport key (for wrapping) from the specified token . . .
    Generating and storing the master key on the specified token . . .
    Naming the master key "new_master" . . .
    Successfully generated, stored, and named the master key!
    Using the transport key to wrap and store the master key . . .
    Writing the wrapped data (and resident master key KCV) into the
     file called "file" . . .
    
           wrapped data:   47C0 06DB 7D3F D9ED
                           FE91 7E6F A7E5 91B9
           master key KCV: CED9 4A7B
           (computed KCV of the master key residing inside the wrapped data)
  5. Copy the wrapped master key over to the appropriate locations or facility.
  6. If necessary, generate new security databases on the HSM or at the facility.
    tkstool -N -d directory
  7. Run the tkstool command with the -I option to produce an identical transport key in the new database that was originally generated in the original database. Regenerating the transport key requires that you input the session key share and KCV for each of the three session keys generated in step 3.
    # tkstool -I -d directory -n verify_transport
    Enter Password or Pin for "NSS Certificate DB":
    
    Use the next screen to input the first session key share . . .
    
    
    Type the word "proceed" and press enter to continue (or ^C to break):  proceed
    sh: tput: command not found
    
    Enter the first session key share . . .
    
    
    Type in the first session key share (or ^C to break):
    
    [8979]  [975D]  [6867]  [FB07]  [5107]  [08B6]  [E625]  [01FD]
    
    Type in the corresponding KCV for the first session key share (or ^C to break):
    
    [0420]  [54F/]
    
     ... [snip] ...
  8. Use the transport key to unwrap the master key stored in the file.
    tkstool -U -d directory -n new_master -t verify_transport -i file
    
    Enter Password or Pin for "NSS Certificate DB":
    Retrieving the transport key from the specified token (for
     unwrapping) . . .
    Reading in the wrapped data (and resident master key KCV) from
     the file called "file" . . .
    
         wrapped data:   47C0 06DB 7D3F D9ED
                         FE91 7E6F A7E5 91B9
         master key KCV: CED9 4A7B
         (pre-computed KCV of the master key residing inside the wrapped data)
    
    Using the transport key to temporarily unwrap the master key to
    recompute its KCV value to check against its pre-computed KCV value . . .
         master key KCV: CED9 4A7B
         (computed KCV of the master key residing inside the wrapped data)
         master key KCV: CED9 4A7B
         (pre-computed KCV of the master key residing inside the wrapped data)
    
    Using the transport key to unwrap and store the master key on the
     specified token . . .
    Naming the master key "new_master" . . .
    Successfully unwrapped, stored, and named the master key!
  9. Verify that the keys have been added properly to the database.
    tkstool -L -d . 
    
    
     slot:  NSS User Private Key and Certificate Services
    token:  NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
            <0> transport
            <1> new_master
Using the tkstool is explained in more detail in the Certificate System Command-Line Tools Guide.

5.7.3. Using HSM for Generating Keys

By default the TKS is configured to use the internal software token to generate and store its master keys, but some deployments may require using a hardware security module (HSM) instead of the software token.
To generate keys on HSMs:
  1. Install and configure the TKS subsystem.
  2. Get the PIN to use to access the TKS's security databases. The internal PIN is the one used for the security databases.
    cat /var/lib/pki-tks/conf/password.conf
    
    internal=649713464822
    internaldb=secret12
    replicationdb=-752230707
  3. Generate the TKS master key on the HSM using the tkstool. (By default during installation, the TKS master key is generated on the software token.) For example:
    tkstool -M -n new_master -d /var/lib/pki-tks/alias -h nethsm
    This generates a master key named new_master on the nethsm token for the pki-tks instance.
    For more information on using the tkstool, see the Certificate System Command-Line Tools Guide.
  4. Verify that the keys for the HSM have been added properly to the TKS database.
    tkstool -L -d . -h nethsm
    
    
     slot:  NSS User Private Key and Certificate Services
    token:  NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
            <0> new_master
  5. Update the TKS instance's CS.cfg to contain the following values:
     # useSoftToken tells whether to use software token or no. by default it's true, 
     # even if it's not settks.useSoftToken=false
     # mk_mappings maps key version to key name on token name
     # in this example, #02 is the version number, nethsm is the token name,
     # and new_master is the key name
     tks.mk_mappings.#02#01=nethsm:new_master
    It is not necessary to change the defaultSlot value; it can remain the default value for the software database:
    tks.defaultSlot=Internal Key Storage Token
  6. Restart the TKS instance.
    service pki-tks restart
  7. Update the CS.cfg for every Token Processing System (TPS) which uses the edited TKS instance. Set the requiredVersion parameter and enable key upgrade in all profiles with the parameters update.symmetricKeys.enable and update.symmetricKeys.requiredVersion in the parameter name. For example:
     # note that the "requiredVersion" needs to map with the version number
     # specified in the mk_mappings parameter of TKS's CS.cfg
     op.enroll.userKey.update.symmetricKeys.enable=true
     op.enroll.userKey.update.symmetricKeys.requiredVersion=2
  8. Restart the TPS instance.
    service pki-tps restart

5.7.4. Updating Master Key Versions and Associating the Master Key with Its Version

The master keys stored in the TKS are accessed by the TPS to perform token operations. Some default keys are built into the TKS, but these can be replaced by generating new masters keys. The new master keys should be mapped to the TKS keyset configuration in the TKS CS.cfg file.
The default master key on a token is the first version, set by the smart card manufacturer. This has the value #01 in its key mapping in the TKS CS.cfg file:
tks.mk_mappings.#01#01=tokenname:masterKeyId
Master keys have a numeric identifier such as 01. The TKS maps these IDs to PKCS #11 object nicknames specified in the masterKeyId part of the mapping. Therefore, the first number is updated as the master key version is updated; the second number stays consistent.

NOTE

Smart cards from the Axalto Web Store come with a default developer key set where all keys are set to 404142434445464748494a4b4c4d4e4f. The TKS has this key built in, and it is referred to with the master key set #01. The TKS uses key set #01 by default.

NOTE

Always stop a subsystem instance before editing the configuration file.
  1. Stop the TKS.
    service pki-tks stop
  2. Generate a new master key, as described in Section 5.7.1, “Generating Master Keys”.
  3. To map to the new version of the key, add a mapping parameter, tks.mk_mappings, to the TKS's CS.cfg file. This associates the new master key with the PKCS #11 object. For example, for a key named new_master on a nethsm token:
    tks.mk_mappings.#02#01=nethsm:new_master
    To reference the security database, set the tokenname to internal. The masterKeyId is the name given to the master key when it was generated.
    All numeric key identifiers in mapping configurations must be suffixed with #01. #02 represents the latest master key version.
  4. Each TKS configured in the TPS CS.cfg has a defined keyset that is associated with it:
    conn.tks1.keySet=defKeySet
    The new master key must be associated with the TKS keyset definition so that it can be used by the TPS. This keyset also requires a mapping parameter for the new master key version in the TPS CS.cfg file.
     tks.defKeySet._000=##
     tks.defKeySet._001=## Axalto default key set:
     tks.defKeySet._002=##
     tks.defKeySet._003=## tks.defKeySet.mk_mappings.#02#01=<tokenname>:<nickname>
     tks.defKeySet._004=##
     tks.defKeySet.auth_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
     tks.defKeySet.kek_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
     tks.defKeySet.mac_key=#40#41#42#43#44#45#46#47#48#49#4a#4b#4c#4d#4e#4f
     tks.defKeySet.mk_mappings.#02#01=nethsm:new_master

5.7.5. Configuring Symmetric Key Changeover

When global platform-compliant smart cards are made, the manufacturer burns a set of symmetric keys onto the token. The smart card user shares a master symmetric key with the manufacturer. The smart card TKS is configured to use these symmetric keys. However, during enrollment, it is desirable to replace these symmetric keys with a set that is not shared by the manufacturer to restrict the set of entities that can manipulate the token.

NOTE

Changing the symmetric keys can render the smart cards unusable if the master key is lost. Use key changeover in controlled conditions, and be aware of the implications of erasing a TKS instance. This section contains information on returning the keys to the factory state.
The TKS and TPS are configured for key changeover by enabling the appropriate parameters in the CS.cfg file for both the enroll and format operations.
  1. Stop the TKS instance. For example:
    service pki-tks stop
  2. Get the PIN to use to access the TKS's security databases. The internal PIN is the one used for the security databases.
    cat /var/lib/pki-tks/conf/password.conf
    
    internal=649713464822
    internaldb=secret12
    replicationdb=-752230707
  3. On the TKS instance, generate new keys to use for token-client communications. For example:
    tkstool -M -n new_master -d /var/lib/pki-tks/alias

    NOTE

    If this is being generated on an HSM or other external token, then use the -h option with the command to give the token name.
    Generating a new master key on the TKS is described in more detail in Section 5.7.1, “Generating Master Keys”.
  4. Open the TKS's configuration file.
    vi /etc/pki-tks/CS.cfg
  5. Map the new master key's identifier, 02, to its PKCS #11 object nickname in the TKS's CS.cfg file by adding the tks.mk_mappings.#02#01 and tks.defKeySet.mk_mappings.#02#01 parameters.
    tks.mk_mappings.#02#01=token_name:nickname     
    tks.defKeySet.mk_mappings.#02#01=token_name:nickname
    Mapping master keys in the TKS configuration is described in more detail in Section 5.7.4, “Updating Master Key Versions and Associating the Master Key with Its Version”.
  6. Start the TKS instance.
    service pki-tks start
  7. Stop the TPS instance to edit its configuration.
    service pki-tps stop
  8. Edit the TPS's configuration file.
    vi /etc/pki-tps/CS.cfg
  9. Change the symmetricKeys.enable and requiredVersion parameters to use the newly-generated master keys on the TKS. For example:
    op.operation_type.update.symmetricKeys.enable=true
    op.operation_type.profile_name.update.symmetricKeys.requiredVersion=2
    • For the enroll operation, the lines begin with op.enroll. For example, for the userKey profile:
      op.enroll.userKey.update.symmetricKeys.enable=true
      op.enroll.userKey.update.symmetricKeys.requiredVersion=2
    • For the format operation, the lines begin with op.format. For example, for the userKey profile:
      op.format.tokenKey.update.symmetricKeys.enable=true
      op.format.tokenKey.update.symmetricKeys.requiredVersion=2
    requiredVersion is the numeric key set identifier required for the operation to proceed. If the smart card does not have the key set specified by the requiredVersion parameter, key changeover will occur, and the operation process continues.
The TPS audit log shows whether the key changeover worked successfully.

TIP

While testing this feature for an Axalto Web Store smart card, change the smart card back to the original static 4041.. key set. To do this, change the requiredVersion parameter back to 1 and set a new format. Do this before removing a TKS instance, or else the smart card cannot be managed.

5.8. Configuring the TPS

There are several parameters relating to smart card certificate enrollment — such as enabling SSL — which are not configured when the TPS is first set up. The TPS is fully operational without any further customization, but setting these extra parameters allows more flexibility to using the TPS with the Enterprise Security Client.

5.8.1. Enabling SSL for TPS-Enterprise Security Client Connections

By default, the TPS communicates with the Enterprise Security Client over standard HTTP, but it is configured to listen over two different secure (SSL) ports, for regular and security officer users of the Enterprise Security Client to connect over SSL. The Enterprise Security Client can be configured to connect over these SSL ports.

5.8.1.1. Default TPS SSL Configuration

Each secure authentication port is configured in a <VirtualHost> entry in the /var/lib/pki-tps/confnss.conf file with the SSL configuration. There are two ports configured:
 Listen 7889    
 Listen 7890
Port 7889 is used for client (certificate-based) authentication to the Enterprise Security Client, so it is mainly used for security officer mode. Port 7890 is used for normal SSL connections, so it is mainly used by regular user mode for the Enterprise Security Client.

NOTE

The nss.conf directives are described in more detail in the Configuration Directives section of the mod_nss documentation.
The SSL configuration for port 7889 defines the allowed SSL/TLS protocols, cipher suites, and certificates used by the connection. The most important configuration attribute for the TPS-Enterprise Security Client connection is NSSVerifyClient, which is set to require. This means that client authentication is required to connect to that port.

Example 5.1. Excerpt SSL Configuration for Port 7889

<VirtualHost _default_:7889>

#   Enable/Disable SSL for this virtual host.
NSSEngine on

#   List the ciphers that the client is permitted to negotiate.
NSSCipherSuite -des,-desede3,-rc2,-rc2export,-rc4,-rc4export,+rsa_3des_sha,-rsa_des_56_sha,+rsa_des_sha,-rsa_null_md5,-rsa_null_sha,-rsa_rc2_40_md5,+rsa_rc4_128_md5,-rsa_rc4_128_sha,-rsa_rc4_40_md5,-rsa_rc4_56_sha,-fortezza,-fortezza_rc4_128_sha,-fortezza_null,-fips_des_sha,+fips_3des_sha,-rsa_aes_128_sha,-rsa_aes_256_sha,+ecdhe_ecdsa_aes_256_sha

NSSProtocol SSLv3,TLSv1

#   SSL Certificate Nickname:
NSSNickname "Server-Cert cert-pki-tps"

#   Server Certificate Database:
NSSCertificateDatabase  /var/lib/pki-tps/alias

#   Client Authentication (Type):
NSSVerifyClient require   

</VirtualHost>

The SSL configuration for port 7890 is the same as that for port 7889, with one exception: the NSSVerifyClient directive is set to none. This means that client authentication is not required to connect to that port.

Example 5.2. Excerpt SSL Configuration for Port 7890

<VirtualHost _default_:7890>

#   SSL Engine Switch:
NSSEngine on

#   SSL Cipher Suite:
NSSCipherSuite -des,-desede3,-rc2,-rc2export,-rc4,-rc4export,+rsa_3des_sha,-rsa_des_56_sha,+rsa_des_sha,-rsa_null_md5,-rsa_null_sha,-rsa_rc2_40_md5,+rsa_rc4_128_md5,-rsa_rc4_128_sha,-rsa_rc4_40_md5,-rsa_rc4_56_sha,-fortezza,-fortezza_rc4_128_sha,-fortezza_null,-fips_des_sha,+fips_3des_sha,-rsa_aes_128_sha,-rsa_aes_256_sha,+ecdhe_ecdsa_aes_256_sha

NSSProtocol SSLv3,TLSv1

#   SSL Certificate Nickname:
NSSNickname "Server-Cert cert-pki-tps"

#   Server Certificate Database:
NSSCertificateDatabase  /var/lib/pki-tps/alias

#   Client Authentication (Type):
NSSVerifyClient none  

</VirtualHost>

5.8.1.2. Configuring the Enterprise Security Client to Use SSL

While the TPS listens by default over secure ports, the Enterprise Security Client uses standard ports. The Enterprise Security Client configuration must be updated to use the secure ports.
First, the Enterprise Security Client has to have the CA certificate for the CA which issued the TPS's certificates in order to trust the TPS connection.
  1. Open the CA's end user pages in a web browser.
    https://server.example.com:9444/ca/ee/ca
  2. Click the Retrieval tab at the top.
  3. In the left menu, click the Import CA Certificate Chain link.
  4. Choose the radio button to download the chain as a file, and remember the location and name of the downloaded file.
  5. Open the Enterprise Security Client. For example:
    /usr/lib/esc-1.0.1/esc
  6. Click the View Certificates button.
  7. Click the Authorities tab.
  8. Click Import, and navigate to the CA certificate chain file.
  9. When prompted, confirm that you want to trust the CA.
The Enterprise Security Client needs to be configured to communicate with the TPS over SSL; this is done by setting the Phone Home URL, which is the default URL the Enterprise Security Client uses to connect to the TPS.
Resetting the Enterprise Security Client's Phone Home URL is described in more detail in Managing Smart Cards with the Enterprise Security Client.
  1. Open the Enterprise Security Client. For example:
    /usr/lib/esc-1.0.1/esc
  2. Insert a new, blank token into the machine.
    Blank tokens are unformatted, so they do not have an existing Phone Home URL, and the URL must be set manually. Formatted tokens (and tokens can be formatted by the manufacturer or by your IT department) already have the URL set, and thus do not prompt to set the Phone Home URL.
  3. Fill in the new TPS URL with the SSL port information. For example:
    https://server.example.com:7890/cgi-bin/home/index.cgi

5.8.2. Configuring the Channels between the TPS and Tokens

The TPS communicates with a token through the user interface, the Enterprise Security Client. This channel can be configured for four attributes:
  • Its size
  • Encryption
  • The encryption key version and type

Example 5.3. Default TPS-Token Channel Configuration

channel.blocksize=248
channel.defKeyIndex=0
channel.defKeyVersion=0
channel.encryption=true

The defKeyIndex and defKeyVersion parameters should remain the default value, as in Example 5.3, “Default TPS-Token Channel Configuration”.
The channel.encryption configuration parameter sets whether to use an encrypted channel between the TPS and tokens managed by the Enterprise Security Client.
channel.encryptionchannel.encryption=true
For security, the channel.encryptionchannel.encryption parameter should always be set to true, the default.

5.8.3. Configuring or Disabling LDAP Authentication

The TPS, by default, requires a user to authenticate to an LDAP directory when a smart card operation request is received. There are three parameters for this which can be set for each separate token operation:
op.operation.key_type.auth.enable=true|false
op.operation.key_type.auth.id=ldap_db_config_entry   
op.operation.key_type.loginRequest.enable=true|false
Setting these parameters determines whether LDAP authentication is required, which the LDAP directory to use for the authentication (by referencing its entry in the TPS CS.cfg file), and whether to send the login request to the smart card client program.

NOTE

The user must have an existing LDAP user entry in the LDAP server instance specified in the TPS's CS.cfg file in order to complete the operation.
To configure LDAP authentication:
  1. Stop the TPS subsystem.
    service pki-tps stop
  2. Open the TPS's configuration directory.
    cd /etc/pki-tps
  3. Edit the CS.cfg file.
    vim CS.cfg
  4. Set the authentication parameters.
    op.operation_type.token_type.loginRequest.enable=false|true
    op.operation_type.token_type.auth.id=ldap_db_config_entry  
    op.operation_type.token_type.auth.enable=false|true
    The operation_type is the token operation for which LDAP authentication is being disabled, such as enroll, format, or pinreset. Disabling authentication for one operation type does not disable it for any other operation types.
    The token_type is the token profile. There are default profiles for regular users, security officers, and the users enrolled by security officers. There can also be custom token types for other kinds of users or certificates.
    For example:
    op.enroll.userKey.loginRequest.enable=true
    op.enroll.userKey.auth.id=ldap1
    op.enroll.userKey.pinReset.enable=true
  5. Restart the TPS subsystem.
    service pki-tps start
Like configuring multiple subsystem instances, there can be multiple LDAP directories configured. Additional LDAP parameters, such as the base DN under which to search for entries and the Directory Server hostname and port, are listed in Table 5.10, “LDAP Authentication”.

Table 5.10. LDAP Authentication

Parameter Description
auth.instance.#.attributes
The LDAP attributes of the user entry to be retrieved, if attributes are present, such as auth.instance.0.attributes=mail,cn,uid.
Once retrieved, these attributes can be used in other parameter entries as $auth.attr name$. For example, op.enroll.userKey.keyGen.tokenName=$userid$ [$auth.cn$].
auth.instance.#.type The authentication type to use. This must be LDAP_Authentication.
auth.instance.#.libraryName The library to use for LDAP authentication. Provide the full path to the library. The filename must be libldapauth.so.
auth.instance.#.libraryFactory The function name to use for LDAP authentication. This must be GetAuthentication.
auth.instance.#.authId Specifies this authentication instance ID to use to define operations. For example, ldap1.
auth.instance.#.hostport The LDAP hostname and port number. The format is ldap-hostname:ldap-port.
auth.instance.#.SSLOn Sets whether SSL should be turned on. The valid values are true|false.
auth.instance.#.retries The number of times authentication is tried after failure. The valid values are integers. For example, 1.
auth.instance.#.retryConnect The number of times the TPS tries to reconnect to the LDAP server after a connection attempt fails. The valid values are integers. For example, 3.
auth.instance.#.baseDN The base DN from which to start the LDAP search. For example, o=example.com.
auth.instance.#.ui.title.en The title of the LDAP authentication plug-in. For example, LDAP Authentication.
auth.instance.#.ui.description.en The description of the LDAP authentication activity. For example, This authenticates the user against the LDAP dev directory.
auth.instance.#.ui.id.UID.name.en The UID parameter name. For example, LDAP User ID.
auth.instance.#.ui.id.PASSWORD.name.en The password parameter name. For example, LDAP Password.
auth.instance.#.ui.id.UID.description.en The description of the UID parameter.
auth.instance.#.ui.id.PASSWORD.description.en The description of the password parameter.

5.8.4. Configuring the Token Database

The TPS uses an LDAP database called the token database or tokenDB to keep specific information for each registered token. It also associates tokens with certificates and users.
The token database is viewed or edited through the Administrator tab of the TPS HTML services page. The agent/admin services page is used to add tokens, check token status, edit token information, and view token information, like certificates and past operations.
The parameters used to configure the token database in the TPS are listed in Table 5.11, “Token Database Preferences”.

Table 5.11. Token Database Preferences

Parameter Description
tokendb.auditLog The full path to the audit log file. For example, /var/log/subsystem_name/tokendb-audit.log.
tokendb.hostport The token database (LDAP) hostname and port number. The format is hostname:port.
tokendb.bindDN The bind DN to bind to the token database. The default value is cn=directory manager.
tokendb.bindPassPath The path to a local password file which contains the subsystem passwords. The default file is /etc/pki-tps/password.conf.
tokendb.templateDir The directory where the templates for the TPS agent page are located.
tokendb.userBaseDN The LDAP suffix where the user entries are.
tokendb.baseDN The LDAP suffix where the token entries should be added and modified by the TPS. The default value is ou=Tokens,baseDN.
tokendb.activityBaseDN The LDAP suffix where the token-based activities should be recorded by the TPS. The default value is ou=Activities,baseDN.
tokendb.certBaseDN The LDAP suffix where the certificate entries should be added by the TPS. The default value is ou=certificates,baseDN.
Change these templates only to change the appearance of the TPS agent page
  • tokendb.indexTemplate
  • tokendb.indexAdminTemplate
  • tokendb.newTemplate
  • tokendb.showTemplate
  • tokendb.showCertTemplate
  • tokendb.errorTemplate
  • tokendb.searchTemplate
  • tokendb.searchResultTemplate
  • tokendb.searchCertificateResultTemplate
  • tokendb.editTemplate
  • tokendb.editResultTemplate
  • tokendb.addResultTemplate
  • tokendb.deleteTemplate
  • tokendb.deleteResultTemplate
  • tokendb.searchActivityTemplate
  • tokendb.searchActivityResultTemplate
  • tokendb.showAdminTemplate
  • tokendb.doTokenTemplate
  • tokendb.doTokenConfirmTemplate
  • tokendb.revokeTemplate
  • tokendb.editAdminTemplate
  • tokendb.editAdminResultTemplate
  • tokendb.searchAdminTemplate
  • tokendb.searchAdminResultTemplate
tokendb.defaultPolicy The default policy to use. The valid values are PIN_RESET=YES|NO; and RE_ENROLL=YES|NO;.

5.8.5. Configuring Server-Side Key Generation and Archival of Encryption Keys

NOTE

There is the option when the TPS instance is configured to set up a DRM to perform server-side key generation and key archival and recovery. If this was enabled when the TPS instance as configured, then it is not necessary to configure it manually in the CS.cfg. If, however, the DRM information has changed or the DRM was not configured during the installation process, then the procedure described in this section can be used to set up the DRM.
The global platform environment prevents removing private keys from the smart card. For encryption keys, it is often necessary to back up the key material for later recovery, which means the keys should be generated outside the smart card and then imported. The keys are generated in the DRM subsystem, where the keys can also be archived. The TPS, TKS, and DRM must all be configured to support server-side generation and archival for encryption keys.
To configure server-side key generation for tokens enrolled through the token management system:
  1. Configure the DRM to perform server-side key generation for the appropriate kinds of tokens.
  2. Add the TPS to the DRM as a key recovery agent.
  3. Import the DRM transport key into the TKS.
  4. Configure the TPS to generate and archive keys.

5.8.5.1. Step 1: Configuring the DRM to Perform Server-Side Key Generation for Tokens

The Data Recovery Manager (DRM) has different configuration settings to enable server-side key generation for different types of hardware security modules (HSM). If the DRM is not configured to perform key generation for the specific HSM type, the enrollment process on the TPS could fail.
  1. Open the DRM's configuration directory.
    cd /etc/pki-kra
  2. Edit the CS.cfg file.
    vim CS.cfg
  3. Add the appropriate parameters for token key generation.
    For nCipher netHSM 2000 tokens, use:
    kra.keygen.temporaryPairs = true
    For LunaSA2 tokens, use:
    kra.keygen.temporary == true
    kra.keygen.sensitive == true
    kra.keygen.extractable == true
If none of these parameters are set, the default value is kra.keygen.temporaryPairs = true, which allows netHSM tokens to be enrolled with server-side key generation and archival.

5.8.5.2. Step 2: Adding the TPS as a DRM Recovery Agent

  1. Open the DRM Console
  2. In the Configuration tab, select Users and Groups.
  3. In the Users tab, click Add, and create the new user; give this user a name such as TPS Recovery Agent. Add this user to the Data Recovery Manager Agents group.
  4. Select the TPS user, click Certificates, and import the TPS server certificate.

5.8.5.3. Step 3: Importing the DRM Transport Key into the TKS

Several different keys are used to encrypt the communications between the TKS, TPS, DRM, and token, and all of these certificates and keys are secured, at some point, by the DRM's transport key.
The DRM creates a transport certificate which works with the TKS to provide a secure way to deliver the generated keys to the token. The server transport key must be imported into the TKS certificate database in order to establish secure communication between the DRM and TKS through the TPS.
Additionally, the TKS can derive a key encryption key (KEK) which is only known by the token and the TKS and never leaves either the TKS or the token without proper encryption. This key has to be secured.
The TKS also generates a session key for the DRM to use to transport the server-generated private key securely back to the token.
The server transport key delivers the session key in two different forms to the TPS:
  • The session key wrapped with server transport key which the DRM uses to wrap the generated private key for token
  • The session key wrapped with token's KEK which the token uses to unwrap the private key generated on DRM
The TPS then forwards the session key to the DRM, wrapped with the KEK and the server transport key, along with the server-side key generation request.
To import the DRM transport key into the TKS certificate database:
  1. Retrieve the DRM transport certificate from the issuing CA, and save it to file.
  2. Import the transport certificate into the TKS security databases in the /var/lib/subsystem_name/alias directory. In the TKS Console, click Subsystem Keys and Certificates in the left navigation panel. In the Local Certificates tab, click Add, and paste in the certificate information.
    Alternatively, use the certutil to import the certificate.
    certutil -d . -P cert-db-prefix -A -n DRM Transport -t ,, -a -i certfilename
  3. Stop the TKS.
    service pki-tks stop
  4. Edit the CS.cfg file by adding the DRM transport certificate information to the following parameter:
    tks.drm_transport_cert_nickname=DRM Transport
  5. Restart the TKS.
    service pki-tks start

5.8.5.4. Step 4: Configuring the TPS to Generate and Archive Keys

  1. Stop the TPS.
    service instance_ID stop
  2. Edit the following parameters in the TPS CS.cfg file to use the appropriate DRM connection information:
     conn.drm.totalConns=1
     conn.drm1.hostport=DRM_HOST:DRM_SSLPORT  
     conn.drm1.clientNickname=Server-Cert
     conn.drm1.servlet.GenerateKeyPair=/kra/GenerateKeyPair
     conn.drm1.servlet.TokenKeyRecovery=/kra/TokenKeyRecovery
     conn.drm1.retryConnect=3
     conn.drm1.SSLOn=true
     conn.drm1.keepAlive=false
  3. Also edit the smart card profiles in the TPS CS.cfg file.
    The TPS CS.cfg file has a section defining each type of smart card profile to maintain. In the default configuration, the userKey is defined under the op.enroll.userKey subsection. The keyGen subsection of the userKey profile defines each type of key/certificate pair allowed for that type of smart card. In the default configuration, one of the key/certificate pairs is encryption. Set the following parameters to enable server-side key generation and to archive keys:
    op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true
    op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=drm1
    op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true
    op.enroll.userKey.keyGen.encryption.serverKeygen.encryptPrivKey=true
  4. Restart the TPS subsystem.
    service instance_ID start

5.8.6. Configuring IPv6 Support

By default, the TPS listens over both its IPv4 and IPv6 address. This is configured in the nss.conf file in the Listen directive:
Listen 7889

Listen 7890
To restrict the TPS its IPv4 address, then edit Listen line to specify an IPv4-style address:
 Listen 0.0.0.0:7889

5.9. Scaling the TPS and Its Support Subsystems

When the TPS is configured, it is configured to work with a specific instance of a CA, TKS, and, optionally, DRM subsystems. It is possible after the configuration process to edit the TPS CS.cfg file to provide backup CA, TKS, and DRM subsystems so that there is failover support in case the primary subsystem is unavailable. There are two good reasons for failover:
  • To provide fail-over support. The TPS can be configured to communicate with multiple instances of CA, TKS, or DRM subsystems, so if one instance is unavailable, the TPS can still process user operations initiated through the Enterprise Security Client. The instances in these cases all have the same policies in effect. This is described in Section 5.9.1, “Configuring Failover Support”.
  • To perform different operations under different policies. The TPS can route its jobs to different subsystem instances when there are different types of tokens or operations. For example, enrollment requests for temporary tokens can be sent to one CA with one set of policies while enrollments for regular tokens are sent to a different CA. This is described in Section 5.9.2, “Configuring Multiple Support Subsystem Instances for Different Functions”.
The support subsystem (CA, TKS, and DRM) can handle requests from several TPS subsystems, so there does not have to be a one-to-one ratio, where there is one CA for every TPS.
Scaling the TPS and Its Dependent Subsystems

Figure 5.2. Scaling the TPS and Its Dependent Subsystems


For multiple TPSs to use the same CA, TKS, or DRM, simply configure each TPS to use the same support subsystem or add the subsystems to the conn.subsystem# parameter for the TPS.
Likewise, a single TPS can handle requests from multiple Enterprise Security Clients, simply by configuring the Phone Home URLs in the Enterprise Security Clients' esc-prefs.js files to point to the same TPS. (This is described more in the Managing Smart Cards with the Enterprise Security Client guide.)
The token management system as a whole, then, has very flexible scalability. Additionally subsystems and clients can be added to improve performance without affecting the configuration of other subsystem instances.

5.9.1. Configuring Failover Support

The subsystem instance to which the TPS connects is set in the conn.subsystem#.hostport parameter of the CS.cfg configuration file. For example, the CA instance is set in the following parameter:
conn.ca1.hostport=aCA.example.com:9443
To configure failover support, list multiple instances in the conn.subsystem#.hostport parameter, separated by spaces. For example:
conn.ca1.hostport=aCA.example.com:9443 bCA.example.com:9443 cCA.example.com:9443
For failover support to be properly configured, all of the subsystem instances must have the same policies and configuration; this means all of the subsystems must be clones. For example, if the TPS is configured to communicate with three CAs, the three CAs must be clones of each other. This means that the values of the other configuration parameters are the same between the instances.
The CA configuration parameters are listed in Table 5.12, “CA Connection Settings”. The TKS configuration parameters are listed in Table 5.13, “TKS Connection Settings”. The DRM configuration parameters are listed in Table 5.14, “DRM Connection Settings”.

Table 5.12. CA Connection Settings

Parameter Description
conn.ca#.hostport The Certificate Authority hostname and port number. The format is hostname:port. This should be the CA's end-entity SSL port.
conn.ca#.clientNickname The client certificate nickname. This certificate is used by the TPS when connecting to the CA. This client certificate should be trusted by the CA, and the client should be a configured CA agent.
conn.ca#.servlet.enrollment The servlet that performs profile-based certificate enrollment. The value must be /ca/ee/ca/profileSubmitSSLClient.
conn.ca#.servlet.renewal The servlet that performs profile-based certificate renewal. The value must be /ca/ee/ca/profileSubmitSSLClient.
conn.ca1.servlet.revoke The servlet that performs certificate revocation; for example, /ca/subsystem/ca/doRevoke.
conn.ca1.servlet.unrevoke The servlet that unrevokes a certificate; for example, /ca/subsystem/ca/doUnrevoke.
conn.ca#.retryConnect The number of times the TPS tries to reconnect to the CA if the connection fails. The valid values are integers. For example, 3.
conn.ca#.timeout The number of seconds before the TPS times out after failing to connect to the CA. For example, 30.
conn.ca#.SSLOn Sets if SSL needs to be turned on to connect to the CA. This value must be true.
conn.ca#.keepAlive Sets whether to keep the connection to the CA alive or terminate it after every operation. The valid values are true|false.

Table 5.13. TKS Connection Settings

Parameter Description
conn.tks#.hostport The TKS subsystem hostname and port number. The format is hostname:port. This should be the TKS's agent port.
conn.tks#.clientNickname The client certificate nickname to use. This certificate is used by the TPS when connecting to the TKS. This client certificate should be trusted by the TKS, and the client should be a configured TKS agent.
conn.tks#.retryConnect The number of times the TPS tries to reconnect to the TKS after a connection attempt fails. The valid values are integers. For example, 3.
conn.tks#.SSLOn Sets whether SSL needs to be turned on for the connection to the TKS. This value must be true.
conn.tks#.keepAlive Sets whether to keep the connection to the TKS alive or terminate it after every operation. The valid values are true|false.
conn.tks#.serverKeygen Sets where key generation happens. When set to true, key generation happens on the server. When set to false, key generation happens on the smart card.
conn.tks1.servlet.computeSessionKey The servlet to compute session key for the secure channel; for example, /tks/agent/tks/computeSessionKey.
conn.tks1.servlet.createKeySetData The servlet to create key set data; for example, /tks/agent/tks/createKeySetData. This servlet is used for key upgrade.
conn.tks1.servlet.encryptData The servlet which encrypts data with token's KEK key; for example, /tks/agent/tks/encryptData.

Table 5.14. DRM Connection Settings

Parameter Description
conn.drm#.hostport The DRM subsystem hostname and port number. The format is hostname:port This should be the DRM agent port.
conn.drm#.clientNickname The client certificate nickname to use. This certificate is used by TPS when connecting to the DRM. This client certificate should be trusted by the DRM, and the client should be a configured DRM agent.
conn.drm#.retryConnect The number of times the TPS tries to reconnect to the DRM after a connection attempt fails. The valid values are integers. For example, 3.
conn.drm#.SSLOn Sets whether SSL needs to be turned on for the connection to the DRM. This value must be true.
conn.drm#.keepAlive Sets whether to keep the connection to the DRM alive or terminate it after every operation. The valid values are true|false.
conn.drm1.servlet.GenerateKeyPair The servlet for handling server-side key pair generation; for example, /kra/agent/kra/GenerateKeyPair.
conn.drm1.servlet.TokenKeyRecovery The servlet for handling smart card key recovery; for example, /kra/agent/kra/TokenKeyRecovery.

5.9.2. Configuring Multiple Support Subsystem Instances for Different Functions

Along with configuring multiple instances for failover support, the TPS can be configured to use multiple instances of a subsystem to perform different functions for different TPS profiles. For instance, the TPS can be configured to use CA1 to enroll temporary tokens (type userKeyTemporary) and CA2 to enroll regular tokens (type userKey).
  1. Open the TPS CS.cfg file.
  2. Create additional instance entries.
    Each subsystem configured for the TPS has its own set of parameters, beginning with conn.subsystem#. To configure multiple instances of a subsystem, create a new set of connection parameters, and increment the #. For example:
    conn.ca1.clientNickname=subsystemCert cert-pki-tps
    conn.ca1.hostport=aCA.example.com:9443
    conn.ca1.keepAlive=true
    conn.ca1.retryConnect=3
    conn.ca1.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient
    conn.ca1.servlet.revoke=/ca/subsystem/ca/doRevoke
    conn.ca1.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke
    conn.ca1.timeout=100
    
    conn.ca2.clientNickname=subsystemCert cert-pki-tps
    conn.ca2.hostport=bCA.example.com:9543
    conn.ca2.keepAlive=true
    conn.ca2.retryConnect=3
    conn.ca2.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient
    conn.ca2.servlet.revoke=/ca/subsystem/ca/doRevoke
    conn.ca2.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke
    conn.ca2.timeout=100
  3. Set up the operation parameters to use the different instances to perform the different TPS functions.
    The parameters for the different operations set the type of operation, the type of token profile, the subsystem type, and other parameters specific to the operation and the subsystem type.
    For example, the TKS subsystem connection to use for regular enrollment operations would be as follows:
    op.enroll.userKey.tks.conn=tks1
    The CA configuration parameters to enroll and format that kind of token are as follows:
    op.enroll.userKey.keyGen.encryption.ca.conn=ca1
    op.enroll.userKey.keyGen.signing.ca.conn=ca2
    op.enroll.userKeyTemporary.keyGen.auth.ca.conn=ca2
    op.format.tokenKey.ca.conn=ca1
    The CA parameters not only specify the type of token (userKey) but also the type of certificate (encryption). It would be possible in this case to use different CAs for signing and encryption certificate enrollments.
    The DRM parameters also specify the types of keys being generated and archived:
    op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=drm1
    op.enroll.tokenKey.keyGen.encryption.serverKeygen.drm.conn=drm2
    The format operation parameters are listed in Table 5.1, “Format Operation Parameters”; the reset operation parameters are listed in Table 5.5, “PIN Reset Operation Parameters”; and the enroll operation parameters are listed in Table 5.2, “Enrollment Operation Parameters”.
  4. Set the mapping parameters for the different tokenType operations. The mapping parameters help the TPS distinguish between the different types of tokens, assign the correct tokenType to the token, and direct their requests to appropriate operation handling parameters. For example:
    op.enroll.mapping.0.filter.appletMajorVersion=1
    op.enroll.mapping.0.filter.appletMinorVersion=5
    op.enroll.mapping.0.filter.tokenATR=
    op.enroll.mapping.0.filter.tokenCUID.end=1000
    op.enroll.mapping.0.filter.tokenCUID.start=4000
    op.enroll.mapping.0.filter.tokenType=userKey
    op.enroll.mapping.0.target.tokenType=userKey
    The mapping and filter parameters are listed in Table 5.7, “Mapping and Filters”.

5.10. Potential Token Operation Errors

Errors that are returned by smart cards are listed in Section 15.7, “Smart Card Error Codes”. These errors are specifically related to the function or behavior of the smart cards themselves, not necessarily the TPS or token management system in Certificate System.
When managing the TPS itself, it is important to know that token operations can cause a large number of unindexed searches to be returned in the instance's internal Directory Server logs. (An unindexed search shows up in Red Hat Directory Server access logs as notes=U.) Unindexed searches are resource-intensive and can affect performance for the Directory Server. However, many of the unindexed searches returned for Certificate System token operations are improperly labeled index searches when they are really indexed VLV searches. The remainder of the unindexed searches still had very low etimes for the searches and should not significantly affect Certificate System performance.

Chapter 6. Revoking Certificates and Issuing CRLs

The Certificate System provides methods for revoking certificates and for producing lists of revoked certificates, called certificate revocation lists (CRLs). This chapter describes the methods for revoking a certificate, describes CMC revocation, and provides details about CRLs and setting up CRLs.

6.1. About Revoking Certificates

Certificates can be revoked by an end user (the original owner of the certificate) or by a Certificate Manager agent. End users can revoke certificates by using the revocation form provided in the end-entities page. Agents can revoke end-entity certificates by using the appropriate form in the agent services interface. Certificate-based (SSL client authentication) is required in both cases.
An end user can revoke only certificates that contain the same subject name as the certificate presented for authentication. After successful authentication, the server lists the certificates belonging to the end user. The end user can then select the certificate to be revoked or can revoke all certificates in the list. The end user can also specify additional details, such as the date of revocation and revocation reason for each certificate or for the list as a whole.
Agents can revoke certificates based on a range of serial numbers or based on subject name components. When the revocation request is submitted, agents receive a list of certificates from which they can pick the ones to be revoked. For instructions on how agents revoke end-entity certificates, see the Certificate System Agent's Guide.
When it receives the CRL, the Certificate Manager marks the corresponding certificate records in its internal database as revoked, and, if configured to do so, removes the revoked certificates from the publishing directory and updates the CRL in the publishing directory.
Server and client applications that use public-key certificates as ID tokens need access to information about the validity of a certificate. Because one of the factors that determines the validity of a certificate is its revocation status, these applications need to know whether the certificate being validated has been revoked. The CA has a responsibility to do the following:
  • Revoke the certificate if any of the certificate information becomes false.
  • Make the revoked certificate status available to parties or applications that need to verify its validity status.
Whenever a certificate is revoked, the Certificate Manager automatically updates the status of the certificate in its internal database, it marks the copy of the certificate in its internal database as revoked and removes the revoked certificate from the publishing directory, if the Certificate Manager is configured to remove the certificate from the database.
One of the standard methods for conveying the revocation status of certificates is by publishing a list of revoked certificates, known a certificate revocation list (CRL). A CRL is a publicly available list of certificates that have been revoked.
The Certificate Manager can be configured to generate CRLs. These CRLs can be created to conform to X.509 standards by enabling extension-specific modules in the CRL configuration. The server supports standard CRL extensions through its CRL issuing points framework; see Section 6.3.3, “Setting CRL Extensions” for more information on setting up CRL extensions for issuing points. The Certificate Manager can generate the CRL every time a certificate is revoked and at periodic intervals. If publishing is set up, the CRLs can be published to a file, an LDAP directory, or an OCSP responder.
A CRL is issued and digitally signed by the CA that issued the certificates listed in the CRL. The CA may use a single key pair to sign both the certificates and CRLs it issues or two separate key pairs, one for signing certificates and another one for signing CRLs.
By default, the Certificate Manager uses a single key pair for signing the certificates it issues and CRLs it generates. To create another key pair for the Certificate Manager and use it exclusively for signing CRLs, see Section 6.3.4, “Setting a CA to Use a Different Certificate to Sign CRLs”.
CRLs are generated when issuing points are defined and configured and any CRL extensions are enabled.
When CRLs are enabled, the server collects revocation information as certificates are revoked. The server attempts to match the revoked certificate against all issuing points that are set up. A given certificate can match none of the issuing points, one of the issuing points, several of the issuing points, or all of the issuing points. When a certificate that has been revoked matches an issuing point, the server stores the information about the certificate in the cache for that issuing point.
The cache is copied to the internal directory at the intervals set for copying the cache. When the interval for creating a CRL is reached, a CRL is created from the cache. If a delta CRL has been set up for this issuing point, a delta CRL is also created at this time. The full CRL contains all revoked certificate information since the Certificate Manager began collecting this information. The delta CRL contains all revoked certificate information since the last update of the full CRL.
The full CRL and the delta CRL have the same number, allowing clients to determine a match between them. This numbering is how the delta CRL references the full CRL from which it gathers information. For example, if the full CRL is the first CRL, it may be known as CRL 1. The corresponding delta CRL would be called delta CRL 1. Therefore, delta CRL 1 refers back to CRL 1 as its full CRL.

NOTE

When changes are made to the extensions for an issuing point, no delta CRL is created with the next full CRL for that issuing point. A delta CRL is created with the second full CRL that is created, and then all subsequent full CRLs.
The internal database stores only the latest CRL and delta CRL. As each new CRL is created, the old one is overwritten.
When CRLs are published, each update to the CRL and delta CRL is published to the locations specified in the publishing set up. The method of publishing determines how many CRLs are stored. For file publishing, each CRL that is published to a file using the number for the CRL, so no file is overwritten. For LDAP publishing, each CRL that is published replaces the old CRL in the attribute containing the CRL in the directory entry.
By default, CRLs do not contain information about revoked expired certificates. The server can include revoked expired certificates by enabling that option for the issuing point. If expired certificates are included, information about revoked certificates is not removed from the CRL when the certificate expires. If expired certificates are not included, information about revoked certificates is removed from the CRL when the certificate expires.

6.1.1. User-Initiated Revocation

When an end user submits a certificate revocation request, the first step in the revocation process is for the Certificate Manager to identify and authenticate the end user to verify that the user is attempting to revoke his own certificate, not a certificate belonging to someone else.
In SSL client authentication, the server expects the end user to present a certificate that has the same subject name as the one to be revoked and uses that for authentication purposes. The server verifies the authenticity of a revocation request by mapping the subject name in the certificate presented for client authentication to certificates in its internal database. The server revokes the certificate only if the certificate maps successfully to one or more valid or expired certificates in its internal database.
After successful authentication, if the server detects only one valid or expired certificate matching the subject name of the one presented for client authentication, it revokes the certificate. If the server detects more than one valid or expired certificate with a matching subject name, it lists all those certificates. The user can then either select the certificate to be revoked or revoke all certificates in the list.

6.1.2. Reasons for Revoking a Certificate

A Certificate Manager can revoke any certificate it has issued. There are generally accepted reason codes for revoking a certificate that are often included in the CRL, such as the following:
  • 0. Unspecified; no particular reason is given.
  • 1. The private key associated with the certificate was compromised.
  • 2. The private key associated with the CA that issued the certificate was compromised.
  • 3. The owner of the certificate is no longer affiliated with the issuer of the certificate and either no longer has rights to the access gained with the certificate or no longer needs it.
  • 4. Another certificate replaces this one.
  • 5. The CA that issued the certificate has ceased to operate.
  • 6. The certificate is on hold pending further action. It is treated as revoked but may be taken off hold in the future so that the certificate is active and valid again.
A certificate can be revoked by administrators, agents, and end entities. Agents and administrators with agent privileges can revoke certificates using the forms in the agent services page. End users can revoke certificates using the forms in the Revocation tab of the end-entity interface. End users can revoke only their own certificates, whereas agents and administrators can revoke any certificates issued by the server. End users are also required to authenticate to the server in order to revoke a certificate.
Whenever a certificate is revoked, the Certificate Manager updates the status of the certificate in its internal database. The server uses the entries in the internal database to track of all revoked certificates, and, when configured, it makes the CRLs public by publishing it to a central repository to notify other users that the certificates in the list are no longer valid.

6.1.3. CRL Issuing Points

Because CRLs can grow very large, there are several methods to minimize the overhead of retrieving and delivering large CRLs. One of these methods partitions the entire certificate space and associates a separate CRL with every partition. This partition is called a CRL issuing point, the location where a subset of all the revoked certificates is maintained. Partitioning can be based on whether the revoked certificate is a CA certificate or end-entity certificate. Each issuing point is identified by its name.
By default, the Certificate Manager generates and publishes a single CRL, the master CRL. An issuing point can be defined for user certificates, for CA signing certificates, or for all revoked certificate information, including expired certificates.
Once the issuing points have been defined, they can be included in certificates so that an application that needs to check the revocation status of a certificate can access the CRL issuing points specified in the certificate instead of the master or main CRL. Since the CRL maintained at the issuing point is smaller than the master CRL, checking the revocation status is much faster.
CRL distribution points can be associated with certificates by setting the CRLDistributionPoint extension.

6.1.4. Delta CRLs

Delta CRLs can be issued for any defined issuing point. A delta CRL contains information about any certificates revoked since the last update to the full CRL. Delta CRLs for an issuing point are created by enabling the DeltaCRLIndicator extension.

6.1.5. Publishing CRLs

The Certificate Manager can publish the CRL to a file, an LDAP-compliant directory, or to an OCSP responder. Where and how frequently CRLs are published are configured in the Certificate Manager, as described in Chapter 8, Publishing Certificates and CRLs.
Because CRLs can be very large, publishing CRLs can take a very long time, and it is possible for the process to be interrupted. Special publishers can be configured to publish CRLs to a file over HTTP1.1, and, if the process is interrupted, the CA subsystem's web server can resume publishing at the point it was interrupted, instead of having to begin again. This is described in Section 8.3, “Publishing CRLs over HTTP”.

6.1.6. Certificate Revocation Pages

The end-entities page of the Certificate Manager includes default HTML forms for SSL client authenticated revocation. The forms are accessible from the Revocation tab. The form for SSL client authenticated-revocation is shown by clicking the User Certificate link.
To change the form appearance to suit an organization's requirements, edit the UserRevocation.html, the form that allows SSL client authenticated revocation of client or personal certificates. The file is the in /var/lib/subsystem_name/webapps/subsystem_name/ee/subsystem_type directory.

6.2. CMC Revocation

CMC revocation allows users to set up a revocation client, sign the revocation request with an agent certificate, and then send the signed request to the Certificate Manager. When this method is used, the Certificate Manager automatically issues certificates when a valid certificate request signed with the agent's certificate is received and automatically revokes a certificate when a valid revocation request signed with the agent's certificate is received.

6.2.1. Setting up CMC Revocation

To use CMC to revoke certificates, do the following:
  • Set up an instance of the CMCAuth Authentication plug-in module. An instance is enabled and configured by default.
  • Use the agent certificate to sign revocation requests.

6.2.1.1. About the revoker Utility

The CMC revocation utility, revoker, is used to sign a revocation request with an agent's certificate. This utility has the following syntax:
revoker -d /instance/alias/ -n cert_nickname -i issuerName -s serialName
 -m reason -c comment
-d is the directory where the cert8.db, key3.db, and secmod.db databases containing the agent certificate are located. -n is the nickname of the agent's certificate. -i is the issuer name of the certificate being revoked. -s is the serial number of the certificate being revoked in decimal value. -m is the reason the certificate is being revoked, which can be any of the following:
  • 0 — unspecified
  • 1 — the key was compromised
  • 2 — the CA key was compromised
  • 3 — the employee's affiliation changed
  • 4 — the certificate has been superseded
  • 5 — cessation of operation
  • 6 — the certificate is on hold
-c adds comments about the request.

NOTE

Surround values that include spaces in quotation marks.

6.2.2. Testing CMC Revoke

  1. Create a CMC revocation request for an existing certificate.
    revoker -d /instance/alias -n nickname -i issuerName -s serialName -m reason -c comment
    For example, if the directory containing the agent certificate is /var/lib/pki-ca/alias, the nickname of the certificate is AgentCert, and the serial number of the certificate is 22, the command is as shown:
    revoker -d "/var/lib/pki-ca/alias" -n "ManagerAgentCert" -i "cn=agentAuthMgr" -s 22 -m 0 -c "test comment"
  2. Open the end-entities page.
    https://server.example.com:9444/ca/ee/ca
  3. Select the Revocation tab.
  4. Select the CMC Revoke link on the menu.
  5. Paste the output from the revoker into the text area.
  6. Remove -----BEGIN NEW CERTIFICATE REQUEST----- and ----END NEW CERTIFICATE REQUEST----- from the pasted content.
  7. Click Submit.
  8. The returned page should confirm that correct certificate was been revoked.

6.3. Issuing CRLs

  1. The Certificate Manager uses its CA signing key to sign CRLs. To use a separate signing key pair for CRLs, set up a CRL signing key and change the Certificate Manager configuration to use this key to sign CRLs. See Section 6.3.4, “Setting a CA to Use a Different Certificate to Sign CRLs” for more information.
  2. Set up CRL issuing points. An issuing point is already set up and enabled for a master CRL.
    Default CRL Issuing Point

    Figure 6.1. Default CRL Issuing Point


    Additional issuing points for the CRLs can be created. See Section 6.3.1, “Configuring Issuing Points” for details.
    There are four types of CRLs the issuing points can create, depending on the options set when configuring the issuing point to define what the CRL will list:
    • Master CRL contains the list of revoked certificates from the entire CA.
    • ARL is an Authority Revocation List containing only revoked CA certificates.
    • CRL with expired certificates includes revoked certificates that have expired in the CRL.
    • CRL from certificate profiles determines the revoked certificates to include based on the profiles used to create the certificates originally.
  3. Configure the CRLs for each issuing point. See Section 6.3.2, “Configuring CRLs for Each Issuing Point” for details.
  4. Set up the CRL extensions which are configured for the issuing point. See Section 6.3.3, “Setting CRL Extensions” for details.
  5. Set up the delta CRL for an issuing point by enabling extensions for that issuing point, DeltaCRLIndicator or CRLNumber.
  6. Set up the CRLDistributionPoint extension to include information about the issuing point.
  7. Set up publishing CRLs to files, an LDAP directory, or an OCSP responder. See Chapter 8, Publishing Certificates and CRLs for details about setting up publishing.

6.3.1. Configuring Issuing Points

Issuing points define which certificates are included in a new CRL. A master CRL issuing point is created by default for a master CRL containing a list of all revoked certificates for the Certificate Manager.
To create a new issuing point, do the following:
  1. Open the Certificate System Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the left navigation menu. Then select CRL Issuing Points.
  3. To edit an issuing point, select the issuing point, and click Edit. The only parameters which can be edited are the name of the issuing point and whether the issuing point is enabled or disabled.
    To add an issuing point, click Add. The CRL Issuing Point Editor window opens.
    CRL Issuing Point Editor

    Figure 6.2. CRL Issuing Point Editor


    NOTE

    If some fields do not appear large enough to read the content, expand the window by dragging one of the corners.
    Fill in the following fields:
    • Enable. Enables the issuing point if selected; deselect to disable.
    • CRL Issuing Point name. Gives the name for the issuing point; spaces are not allowed.
    • Description. Describes the issuing point.
  4. Click OK.
To view and configure a new issuing point, close the CA Console, then open the Console again. The new issuing point is listed below the CRL Issuing Points entry in the navigation tree.
Configure CRLs for the new issuing point, and set up any CRL extensions that will be used with the CRL. See Section 6.3.2, “Configuring CRLs for Each Issuing Point” for details on configuring an issuing point. See Section 6.3.3, “Setting CRL Extensions” for details on setting up the CRL extensions. All the CRLs created appear on the Update Revocation List page of the agent services pages.

6.3.2. Configuring CRLs for Each Issuing Point

Information, such as the generation interval, the CRL version, CRL extensions, and the signing algorithm, can all be configured for the CRLs for the issuing point. The CRLs must be configured for each issuing point.
  1. Open the CA console.
    pkiconsole https://server.example.com:9445/ca
  2. In the navigation tree, select Certificate Manager, and then select CRL Issuing Points.
  3. Select the issuing point name below the Issuing Points entry.
  4. Configure how and how often the CRLs are updated by supplying information in the Update tab for the issuing point. This tab has two sections, Update Schema and Update Frequency.
    • The Update Schema section has the following options:
      • Enable CRL generation. This checkbox sets whether CRLs are generated for that issuing point.
      • Generate full CRL every # delta(s). This field sets how frequently CRLs are created in relation to the number of changes.
      • Extend next update time in full CRLs. This adds the nextUpdate field to the published CRLs, which indicates the date by which the next CRL will be issued.
    • The Update Frequency section sets the different intervals when the CRLs are generated and published to the directory.
      • Every time a certificate is revoked or released from hold. This sets the Certificate Manager to generate the CRL every time it revokes a certificate. The Certificate Manager attempts to publish the CRL to the configured directory whenever it is generated. Publishing a CRL can be time consuming if the CRL is large. Configuring the Certificate Manager to publish CRLs every time a certificate is revoked may engage the server for a considerable amount of time; during this time, the server will not be able to update the directory with any changes it receives.
        This setting is not recommended for a standard installation. This option should be selected to test revocation immediately, such as testing whether the server publishes the CRL to a flat file.
      • Update the CRL at. This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separate list of times, such as 01:50,04:55,06:55.
      • Update the CRL every. This checkbox enables generating and publishing CRLs at the interval set in the field. For example, to publish CRLs every day, select the checkbox, and enter 1440 in this field.
      • Next update grace period. If the Certificate Manager updates the CRL at a specific frequency, the server can be configured to have a grace period to the next update time to allow time to create the CRL and publish it. For example, if the server is configured to update the CRL every 20 minutes with a grace period of 2 minutes, and if the CRL is updated at 16:00, the CRL is updated again at 16:18.
  5. The Cache tab sets whether caching is enabled and the cache frequency.
    CRL Cache Tab

    Figure 6.3. CRL Cache Tab


    • Enable CRL cache. This checkbox enables the cache, which is used to create delta CRLs. If the cache is disabled, delta CRLs will not be created. For more information about the cache, see Section 6.1, “About Revoking Certificates”.
    • Update cache every. This field sets how frequently the cache is written to the internal database. Set to 0 to have the cache written to the database every time a certificate is revoked.
    • Enable cache recovery. This checkbox allows the cache to be restored.
  6. The Format tab sets the formatting and contents of the CRLs that are created. There are two sections, CRL Format and CRL Contents.
    CRL Format Tab

    Figure 6.4. CRL Format Tab


    • The CRL Format section has two options:
      • Revocation list signing algorithm is a drop down list of allowed ciphers to encrypt the CRL.
      • Allow extensions for CRL v2 is a checkbox which enabled CRL v2 extensions for the issuing point. If this is enabled, set the required CRL extensions described in Section 6.3.3, “Setting CRL Extensions”.

      NOTE

      Extensions must be turned on to create delta CRLs.
    • The CRL Contents section has three checkboxes which set what types of certificates to include in the CRL:
      • Include expired certificates. This includes revoked certificates that have expired. If this is enabled, information about revoked certificates remains in the CRL after the certificate expires. If this is not enabled, information about revoked certificates is removed when the certificate expires.
      • CA certificates only. This includes only CA certificates in the CRL. Selecting this option creates an Authority Revocation List (ARL), which lists only revoked CA certificates.
      • Certificates issued according to profiles. This only includes certificates that were issued according to the listed profiles; to specify multiple profiles, enter a comma-separated list.
  7. Click Save.
  8. Extensions are allowed for this issuing point and can be configured. See Section 6.3.3, “Setting CRL Extensions” for details.

6.3.3. Setting CRL Extensions

NOTE

Extensions only need configured for an issuing point if the Allow extensions for CRLs v2 checkbox is selected for that issuing point.
When the issuing point is created, three extensions are automatically enabled: CRLReason, InvalidityDate, and CRLNumber. Other extensions are available but are disabled by default. These can be enabled and modified. For more information about the available CRL extensions, see Section B.4.2, “Standard X.509 v3 CRL Extensions Reference”.
To configure CRL extensions, do the following:
  1. Open the CA console.
    pkiconsole https://server.example.com:9445/ca
  2. In the navigation tree, select Certificate Manager, and then select CRL Issuing Points.
  3. Select the issuing point name below the Issuing Points entry, and select the CRL Extension entry below the issuing point.
    The right pane shows the CRL Extensions Management tab, which lists configured extensions.
    CRL Extensions

    Figure 6.5. CRL Extensions


  4. To modify a rule, select it, and click Edit/View.
  5. Most extensions have two options, enabling them and setting whether they are critical. Some require more information. Supply all required values. See Section B.4.2, “Standard X.509 v3 CRL Extensions Reference” for complete information about each extension and the parameters for those extensions.
  6. Click OK.
  7. Click Refresh to see the updated status of all the rules.

6.3.4. Setting a CA to Use a Different Certificate to Sign CRLs

A Certificate Manager uses the key pair corresponding to the CA signing certificate for signing certificates and certificate revocation lists (CRLs). To use a different key pair to sign the CRLs that the Certificate Manager generates, then a CRL signing certificate can be created. The Certificate Manager's CRL signing certificate must be signed or issued by itself.
To enable a Certificate Manager to sign CRLs with a different key pair, do the following:
  1. Request and install a CRL signing certificate for the Certificate Manager.
    This can be done through the certificate wizard in System Keys and Certificates in the console. Use the wizard to request a certificate of the "other" type, and specify "crlSigning" as the certificate type.
    Alternatively, use the certutil tool to generate a key pair, request a certificate for the key pair, and install the certificate in the Certificate Manager's certificate database. For more information about the certutil tool, see http://www.mozilla.org/projects/security/pki/nss/tools/.
  2. When the certificate request has been created, submit it through the Certificate Manager end-entities page. The page has a URL in the following format:
    https://hostname:port/ca/ee/ca
    
  3. After the request is submitted, log into the agent services page.
  4. Check the request for required extensions. The CRL signing certificate must contain the Key Usage extension with the crlSigning bit set.
  5. Approve the request.
  6. After the CRL signing certificate is generated, install the certificate in the Certificate Manager's database through System Keys and Certificates in the console.
  7. Stop the Certificate Manager.
  8. Update the Certificate Manager's configuration to recognize the new key pair and certificate.
    1. Open the Certificate Manager instance configuration directory.
      /var/lib/pki-ca/conf
    2. Open the CS.cfg file.
    3. Add the following lines to the configuration file:
      ca.crl_signing.cacertnickname=nickname cert-instance_ID
      ca.crl_signing.defaultSigningAlgorithm=signing_algorithm
      ca.crl_signing.tokenname=token_name
      nickname is the name assigned to the CRL signing certificate; instance_ID is the name of the Certificate Manager instance; signing_algorithm is MD5withRSA, MD2withRSA, or SHA1withRSA, if the key type is RSA; and token_name is the name of the token used for generating the key pair and the certificate. If the internal/software token is used, use Internal Key Storage Token as the value.
      For example, the entries might look like this:
      ca.crl_signing.cacertnickname=crlSigningCert cert-pki-ca
      ca.crl_signing.defaultSigningAlgorithm=MD5withRSA
      ca.crl_signing.tokenname=Internal Key Storage Token
      
    4. Save the changes, and close the file.
  9. Restart the Certificate Manager.
    service pki-ca restart
    Now the Certificate Manager is ready to use the CRL signing certificate to sign the CRLs it generates.

6.4. Setting Full and Delta CRL Schedules

CRLs are published periodically. Setting that period is touched on in the configuration in Section 6.3.2, “Configuring CRLs for Each Issuing Point”.
First, CRLs are issued according to a time-based schedule. CRLs can be issued every single time a certificate is revoked, at a specific time of day, or once every so-many minutes.
However, this time-based publishing schedule applies to every CRL that is generated. There are two kinds of CRLs, however. The full CRL has a record of every single revoked certificate. However, the Certificate System also publishes a delta CRL, which contains only the certificates that have been revoked since the last CRL (delta or full) was published.
By default, full and delta CRLs are generated at the same time, and every time. However, it is possible to space out when full CRLs are published and to publish multiple interim delta CRLs. This is configured in the CRL schema, which sets the scheme for publishing delta and full CRLs.
A full CRL is also called an extended update. By default, every CRL publishing period has an extended update. However, this can be configured so that not every publishing period is an extended update and to set the interval of when the extended updates are published.
If the interval is set to 3, for example, then the first CRL publishing is both a full and delta CRL, then the next two publishing updates are only delta CRLs, and then the fourth interval is both a full and delta CRL again. In other words, every third publishing interval has both a full CRL and a delta CRL.
Interval   1, 2, 3, 4, 5, 6, 7 ...
Full CRL   1        4        7 ...
Delta CRL  1, 2, 3, 4, 5, 6, 7 ...

NOTE

For delta CRLs to be published independent of full CRLs, the CRL cache must be enabled.

6.4.1. Configuring Extended Updated Intervals for CRLs in the Console

  1. Open the console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, expand the Certificate Manager folder and the CRL Issuing Points subfolder.
  3. Select the MasterCRL node.
  4. Deselect the Extend next update time in full CRLs check box, which disables publishing a full CRL every time a CRL is published. Then, set the new full CRL interval in the Generate full CRL every ... deltas field.
  5. Save the changes.

6.4.2. Configuring Extended Updated Intervals for CRLs in CS.cfg

Two parameters need to be configured for setting the full/delta CRL publishing interval in the CS.cfg file, ca.crl.extendedNextUpdate and ca.crl.MasterCRL.updateSchema.
  1. Stop the CA server.
    service pki-ca stop
  2. Open the CA configuration directory.
    cd /var/lib/subsystem_name/conf
  3. Edit the CS.cfg file, and add two lines to set the extended updated interval:
    ca.crl.extendedNextUpdate=false
    ca.crl.MasterCRL.updateSchema=3
    The default interval is 1, meaning a full CRL is published every time a CRL is published. The updateSchema interval can be set to any integer.
  4. Restart the CA server.
    service pki-ca start

6.5. Enabling Automatic Revocation Checking for Agent Certificates

A Certificate Manager can be configured to check the revocation status of an agent's certificate the server receives during SSL client authentication. For information about setting up an OCSP responder, see Chapter 7, Using the Online Certificate Status Protocol Responder.

NOTE

The subsystem CS.cfg configuration file includes a parameter, jss.ocspcheck.enable, which sets whether a Certificate Manager should use an OCSP to verify the revocation status of the certificate it receives as a part of SSL client or server authentication. Changing the value of this parameter to true means the Certificate Manager reads the Authority Information Access extension in the certificate and verifies the revocation status of the certificate from the OCSP responder specified in the extension.
The configuration files of the Certificate Manager include parameters to specify whether the server should do the revocation checking and at what interval. Revocation-status verification works only for agent certificates that have been issued by the Certificate Manager, not by any third-party CAs.
To configure a Certificate Manager to verify the revocation status of its agents' certificates, do the following:
  1. Stop the subsystem instance.
    service pki-ca start
  2. Open the instanceDirectory/conf/ directory.
  3. Open the CS.cfg file.
  4. Edit the following parameters:
    • revocationChecking.bufferSize . Sets the total number of last-checked certificates the server should maintain in its cache. For example, if the buffer size is 2, the server retains the last two certificates checked in its cache. By default, the server caches the last 50 certificates.
    • revocationChecking.subsystem. Gives the name of the Certificate System instance. subsystem indicates whether the subsystem is a Certificate Manager (ca). Do not change the default values.
    • revocationChecking.enabled . Sets revocation checking. true enables checking; false disables checking. By default, the feature is enabled.
    • revocationChecking.unknownStateInterval . Sets how frequently the server checks the revocation status. The default interval is 0 seconds.
    • revocationChecking.validityInterval . Sets how long the cached certificates are considered valid. Be judicious when choosing the interval. For example, if the validity period is 60 seconds, the server discards the certificates in its cache every minute and attempts to retrieve them from their source. The Certificate Manager uses its internal database to retrieve and verify the revocation status of the certificates. The default validity period is 120 seconds (2 minutes).
  5. Start the Certificate System instance.
    service instance_ID start
    

Chapter 7. Using the Online Certificate Status Protocol Responder

This chapter provides an overview of an Online Certificate Status Protocol (OCSP) service and explains how the OCSP service verifies the current status of the certificates issued by the Certificate Manager. The chapter also explains how to configure the Online Certificate Status Managers to publish CRLs.

7.1. Setting up the OCSP Responder

If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the OCSP service. The CA's CRL publishing is set up automatically, and its signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the OCSP service must be manually configured after the Online Certificate Status Manager is configured.

NOTE

Not every CA within the security domain to which the OCSP Manager belongs is automatically trusted by the OCSP Manager when it is configured. Every CA in the certificate chain of the CA configured in the CA panel is trusted automatically by the OCSP Manager. Other CAs within the security domain but not in the certificate chain must be trusted manually.
To set up the Online Certificate Status Manager for a Certificate Manager outside the security domain, do the following:
  1. Configure the CRLs for every CA that will publish to an OCSP responder. See Chapter 6, Revoking Certificates and Issuing CRLs for details.
  2. Enable publishing, set up a publisher, and set publishing rules in every CA that the OCSP service will handle. See Chapter 8, Publishing Certificates and CRLs for details. This is not necessary if the Certificate Managers publish to an LDAP directory and the Online Certificated Status Manager is set up to read from that directory.
  3. The certificate profiles must be configured to include the Authority Information Access extension, pointing to the location at which the Certificate Manager listens for OCSP service requests. See Section 7.3, “Enabling the Certificate Manager's Internal OCSP Service” for more information.
  4. Configure the OCSP Responder.
  5. Restart both subsystems after configuring them.
  6. Verify that the CA is properly connected to the OCSP responder; see Section 7.2.1, “Verify Certificate Manager and Online Certificate Status Manager Connection”.

7.2. Identifying the CA to the OCSP Responder

Before a CA is configured to publish CRLs to the Online Certificate Status Manager, the CA must be identified to the Online Certificate Status Manager by storing the CA signing certificate in the internal database of the Online Certificate Status Manager. The Certificate Manager signs CRLs with the key pair associated with this certificate; the Online Certificate Status Manager verifies the signature against the stored certificate.

NOTE

If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the Online Certificate Status Manager to recognize the CA; the CA signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the CA signing certificate must be manually added to the certificate database after the Online Certificate Status Manager is configured.
It is not necessary to import the certificate chain for a CA which will publish its CRL to the Online Certificate Status Manager. The only time a certificate chain is needed for the OCSP service is if the CA connects to the Online Certificate Status Manager through SSL authentication when it publishes its CRL. Otherwise, the Online Certificate Status Manager does not need to have the complete certificate chain.
However, the Online Certificate Status Manager must have the certificate which signed the CRL, either a CA signing certificate or a separate CRL signing certificate, in its certificate database. The OCSP service verifies the CRL by comparing the certificate which signed the CRL against the certificates in its database, not against a certificate chain. If both a root CA and one of its subordinate CAs publish CRLs to an Online Certificate Status Manager, the Online Certificate Status Manager needs the CA signing certificate of both CAs.
To import the CA or CRL signing certificate which is used to sign the certificates the CA is publishing to the Online Certificate Status Manager, do the following:
  1. Get the Certificate Manager's base-64 CA signing certificate from the end-entities page of the CA.
  2. Open the Online Certificate Status Manager agent page. The URL has the format https://hostname:SSLport/ocsp/agent/ocsp.
  3. In the left frame, click Add Certificate Authority.
  4. In the form, paste the encoded CA signing certificate inside the text area labeled Base 64 encoded certificate (including the header and footer).
  5. To verify that the certificate is added successfully, in the left frame, click List Certificate Authorities.
The resulting form should show information about the new CA. The This Update, Next Update, and Requests Served Since Startup fields should show a value of zero (0).

7.2.1. Verify Certificate Manager and Online Certificate Status Manager Connection

When the Certificate Manager is restarted, it tries to connect to the Online Certificate Status Manager's SSL port. To verify that the Certificate Manager did indeed communicate with the Online Certificate Status Manager, check the This Update and Next Update fields, which should be updated with the appropriate timestamps of the CA's last communication with the Online Certificate Status Manager. The Requests Served Since Startup field should still show a value of zero (0) since no client has tried to query the OCSP service for certificate revocation status.

7.2.2. Configure the Revocation Info Stores

The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL store for verifying the revocation status of certificates. The Online Certificate Status Manager can be configured to use the CRL published to an LDAP directory, instead of the CRL in its internal database.
To configure the Online Certificate Status Manager to use the CRLs in its internal database or an LDAP directory for verifying revocation status of certificate, do the following:
  1. Open the Online Certificate Status Manager Console.
    pkiconsole https://server.example.com:11445/ocsp
  2. In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
    The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
  3. Select the appropriate option:
    • To use the CRLs in its internal database, select defStore, and click Edit/View.
    • To use the CRLs in LDAP directories, click Set Default to enable the ldapStore option, select ldapStore, and click Edit/View.
  4. For defStore, fill in the following values:
    • notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
    • includeNextUpdate. The Online Certificate Status Manager can include the timestamp of the next CRL update time.
    For ldapStore, fill in the following values:
    • numConns. The total number of LDAP directories the OCSP service should check. By default, this is set to 0. Setting this value shows the corresponding number of host, port, baseDN, and refreshInSec fields.
    • host. The fully-qualified DNS hostname of the LDAP directory.
    • port. The non-SSL port of the LDAP directory.
    • baseDN. The DN to start searching for the CRL. For example, O=example.com.
    • refreshInSec. How often the connection is refreshed. The default is 86400 seconds (daily).
    • caCertAttr. Leave the default value, cACertificate;binary, as it is. It is the attribute to which the Certificate Manager publishes its CA signing certificate.
    • crlAttr. Leave the default value, certificateRevocationList;binary, as it is. It is the attribute to which the Certificate Manager publishes CRLs.
    • notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
    • includeNextUpdate. The Online Certificate Status Manager can include the timestamp of the next CRL update time.

7.2.3. Testing the OCSP Service Setup

Test whether the Certificate Manager can service OCSP requests properly by doing the following:
  1. Turn on revocation checking in the browser or client.
  2. Request a certificate from the CA that has been enabled for OCSP services.
  3. Approve the request.
  4. Download the certificate to the browser or client.
  5. Make sure the CA is trusted by the browser or client.
  6. Check the status of Certificate Manager's internal OCSP service.
    Open the CA agent services page, and select the OCSP Services link.
  7. Test the independent Online Certificate Status Manager subsystem.
    Open the Online Certificate Status Manager agent services page, and click the List Certificate Authorities link.
    The page should show information about the Certificate Manager configured to publish CRLs to the Online Certificate Status Manager. The page also summarizes the Online Certificate Status Manager's activity since it was last started.
  8. Revoke the certificate.
  9. Verify the certificate in the browser or client. The server should return that the certificate has been revoked.
  10. Check the Certificate Manager's OCSP-service status again to verify that these things happened:
    • The browser sent an OCSP query to the Certificate Manager.
    • The Certificate Manager sent an OCSP response to the browser.
    • The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
  11. Check the independent OCSP service subsystem again to verify that these things happened:
    • The Certificate Manager published the CRL to the Online Certificate Status Manager.
    • The browser sent an OCSP response to the Online Certificate Status Manager.
    • The Online Certificate Status Manager sent an OCSP response to the browser.
    • The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.

7.3. Enabling the Certificate Manager's Internal OCSP Service

The Certificate Manager has a built-in OCSP service, which can be used by OCSP-compliant clients to query the Certificate Manager directly about the revocation status of the certificate. When the Certificate Manager is installed, an OCSP signing certificate is issued and the OCSP service is turned on by default. This OCSP signing certificate is used to sign all responses to OCSP service requests. Since the internal OCSP service checks the status of certificates stored in the Certificate Manager's internal database, publishing does not have to be configured to use this service.
Clients can query the OCSP service through the non-SSL end-entity port of the Certificate Manager. When queried for the revocation status of a certificate, the Certificate Manager searches its internal database for the certificate, checks its status, and responds to the client. Since the Certificate Manager has real-time status of all certificates it has issued, this method of revocation checking is the most accurate.
Every CA's built-in OCSP service is turned on at installation. However, to use this service, the CA needs to issue certificates with the Authority Information Access extension
  1. Go to the CA's end-entities page. For example:
    https://server.example.com:9444/ca/ee/ca
  2. Find the CA signing certificate.
  3. Look for the Authority Info Access extension in the certificate, and note the Location URIName value, such as https://server.example.com:9444/ca/ocsp.
  4. Update the enrollment profiles to enable the Authority Information Access extension, and set the Location parameter to the Certificate Manager's URI. For information on editing the certificate profiles, see Section 2.2, “Setting up Certificate Profiles”.
  5. Restart the CA instance.
    service instance_ID restart
To disable the Certificate Manager's internal OCSP service, edit the CA's CS.cfg file and change the value of the ca.ocsp parameter to false.
ca.ocsp=false

7.4. Enabling Revocation Checking for the TPS and RA

Both the TPS and RA subsystems use web-based administrative services, which require administrators and agents to authenticate using SSL client certificates. The TPS also uses certificate-based authentication for officers to access the Enterprise Security Client interfaces.
Because administrative functions depend on having a valid certificate, the validity of the certificate should be checked in both subsystems so that suspended or lost tokens or revoked certificates cannot be used to gain access to the administrative functions of the subsystem.
OCSP checking can be enabled in both the TPS and the RA by setting certain parameters in their nss.conf files. Most of the configuration for enabling OCSP validation is already in the file, but it needs to be uncommented and configured.

NOTE

NSS, part of the Apache web server used by the TPS and the RA, provides the mechanism for contacting the OCSP service. However, NSS caches OCSP responses for 60 minutes. If the TPS or RA polls again for the revocation status of a certificate within an hour of its being checked, NSS returns the cached response, even if the revocation status has changed.
If there is a very important or vulnerable certificate revocation, then it may be beneficial to restart the subsystem to clear its NSS cache so an inaccurate status cannot be returned.
  1. Update to the latest version of NSS.
    yum update nss
  2. Open the subsystem's nss.conf file. For example:
    vim /var/lib/pki-tps/conf/nss.conf
  3. Enable OCSP checking, and set the information for the OCSP service to use by uncommenting three lines:
    NSSOCSP on
    NSSOCSPDefaultResponder on
    
    NSSOCSPDefaultURL http://ocsp.example.com:11180/ocsp/ocsp
    The TPS and RA can be configured to work with the CA's internal OCSP service or an external OCSP Manager.
  4. Set the certificate to use for authentication for OCSP validation.
    NSSOCSPDefaultName caCert
    If the CA's internal OCSP service is used, then the certificate to use for authentication is the CA signing certificate, which is the default value (caCert) the NSSOCSPDefaultName parameter.
    To use an external OCSP Manager, set the certificate nickname to the OCSP signing certificate nickname for the OCSP Manager; by default, this is ocspSigningCert
    NSSOCSPDefaultName ocspSigningCert
  5. Add the OCSP certificate used by the OCSP service to the subsystem's cert8.db database.
    If the CA's internal OCSP service is used, then there is no need to import a certificate, because the CA is already trusted by both the TPS and RA.
    To use an OCSP Manager, then the certificate must be imported into the TPS or RA security database:
    1. Retrieve the OCSP signing certificate from the end-entities services pages for the CA. The OCSP signing certificate has a subject name such as CN=OCSP Signing Certificate, O=Example Domain.
      Save the certificate to a file like example.cert.
    2. Import the OCSP signing certificate into the subsystem's security database.
      certutil -A -n "ocspSigningCert cert-pki-ocsp" -t CTu,Cu,Cu -d /var/lib/pki-tps/alias -a -i /tmp/example.cert
      Importing certificates into the security database is described in Section 16.5.1.2, “Installing Certificates Using certutil”.
    3. Import the OCSP signing certificate into the subsystem's security database.
      certutil -A -n "ocspSigningCert cert-pki-ocsp" -t u,u,u -d /var/lib/pki-ca/alias -a -i /tmp/example.cert
      Importing certificates into the security database is described in Section 16.5.1.2, “Installing Certificates Using certutil”.
  6. Configure the OCSP timeout value. The parameter determines how long the TPS waits for a response from the OCSP responder before timing out. The default value (60 seconds) is usually fine, but when there is spotty network performance, it is better to set a higher value to keep the slower transactions from timing out unnecessarily.
    NSSOCSPTimeout 90
    If the timeout is not set, there is a default value of 60 seconds.
  7. Configure how the OCSP cache is handled for the TPS. Not setting any cache parameters simply uses the default settings. The cache parameters can be configured to enable more frequent OCSP checks.
    The TPS uses the OCSP services provided by the NSS security libraries. The idea of the OCSP cache is to keep a record of recent responses from the OCSP server. If not too much time has passed since a particular validation request has been made to the OCSP server, the cache settings give the TPS the option of getting the validity of the certificate from the value in the cache rather than the server. This flexibility reduces the strain on the OCSP server.
    The default values that govern cache behavior are all set to allow a fairly long time between fetches to the OCSP server.
    There are three parameters that control caching behavior:
    • NSSOCSPCacheSize controls the number of certificate validity requests that can be stored in cache. The default is 1000.
    • NSSOCSPMinCacheEntryDuration sets the minimum amount of time (in minutes) that the TPS waits after checking a certificate's status before the certificate status can be re-checked. To increase security, set this time to something small, so that the OCSP responder can be checked as often as possible and catch recently revoked certificates. The default time is one hour.
    • NSSOPCSPMaxCacheEntryDuration sets the maximum amount of time before the TPS checks the OCSP responder about a certificate. OCSP responders have an optional setting to configure it's a good time for the client to query the service. The NSSOPCSPMaxCacheEntryDuration attribute overrides the default settings in the OCSP responder and allows you to define whatever window you want. The default setting for this is one day.
    For example:
    NSSOCSPCacheSize 1000
    NSSOCSPMinCacheEntryDuration 60
    NSSOPCSPMaxCacheEntryDuration 80
  8. Restart the subsystem. For example:
    service pki-tps restart

7.5. Enabling Certificate Revocation Checking for DRM and TKS Users

Like the RA and TPS, the DRM and TKS subsystems do not have OCSP checking enabled, by default, to validate subsystem certificates. This means it is possible for someone to log into the administrative or agent interfaces with a revoked certificate.
OCSP checking can be enabled for the DRM and TKS very easily by editing the server.xml file.
  1. Open the server.xml file for the subsystem. For example:
    vim /var/lib/pki-kra/conf/server.xml
  2. There are two different sections in the file for the agent and administrator interfaces. The OCSP parameters need to be added to both sections to enable and configure OCSP checking. For example:

    Example 7.1. OCSP Settings for the DRM Agent Interface

    <Connector name="Agent" port="10443" maxHttpHeaderSize="8192"
            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
            enableLookups="false" disableUploadTimeout="true"
            acceptCount="100" scheme="https" secure="true"
            clientAuth="true" sslProtocol="SSL"
            sslOptions="ssl2=true,ssl3=true,tls=true"
           
    ssl2Ciphers="-SSL2_RC4_128_WITH_MD5, ..."
           
    ssl3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA, ..."
           
    tls3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA, ..."
            SSLImplementation="org.apache.tomcat.util.net.jss.JSSImplementation"
            enableOCSP="true"   
            ocspResponderURL="http://server.example.com:9180/ca/ocsp"   
            ocspResponderCertNickname="ocspSigningCert cert-pki-ca 102409a"   
            ocspCacheSize="1000"   
            ocspMinCacheEntryDuration="60"   
            ocspMaxCacheEntryDuration="120"   
            ocspTimeout="10"   
            debug="true"
            serverCertNickFile="/var/lib/pki-kra/conf/serverCertNick.conf"
            passwordFile="/var/lib/pki-kra/conf/password.conf"
            passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
            certdbDir="/var/lib/pki-kra/alias"/>

    All of the OCSP checking parameters are listed in Table 7.1, “OCSP Parameters for server.xml”.
  3. If the given OCSP service is not the CA, then the OCSP service's signing certificate must be imported into the subsystem's NSS database. This can be done in the console or using certutil; both options are covered in Section 16.5.1, “Installing Certificates in the Certificate System Database”.
  4. Restart the subsystem. For example:
    service pki-kra restart

Table 7.1. OCSP Parameters for server.xml

Parameter Description
enableOCSP Enables (or disables) OCSP checking for the subsystem.
ocspResponderURL Sets the URL where the OCSP requests are sent.
ocspResponderCertNickname Sets the nickname of the signing certificate for the responder, either the OCSP signing certificate or the CA signing certificate. If this is the OCSP signing certificate, then the certificate must be imported into the subsystem's NSS database and have the appropriate trust settings set. The CA signing certificate will be in the database already, as long as the subsystems are in the same security domain.
ocspCacheSize Sets the maximum number of cache entries.
ocspMinCacheEntryDuration Sets minimum seconds before another fetch attempt can be made. For example, if this is set to 120, then the validity of a certificate cannot be checked again until at least 2 minutes after the lest validity check.
ocspMaxCacheEntryDuration Sets the maximum number of seconds to wait before making the next fetch attempt. This prevents having too large a window between validity checks.
ocspTimeout Sets the timeout period, in seconds, for the OCSP request.

7.6. Submitting OCSP Requests Using the GET Method

OCSP requests which are smaller than 255KB can be submitted to the Online Certificate Status Manager using a GET method, as described in RFC 2560. To submit OCSP requests over GET:
  1. Generate an OCSP request for the certificate that's status is being queried. For example:
    # OCSPClient server.example.com 11180 /var/lib/pki-ca/alias 'caSigningCert cert-pki-ca' 1 /export/output.txt 1
    URI: /ocsp/ee/ocsp
    Data Length: 68
    Data: MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ
    44kgy35o7xW5BMzM8FTvyTwCAQE=
    The Certificate System's OCSPClient tool has the format:
    OCSPClient host port /path/to/CA_cert_database 'CA_signing_cert_nickname' serial_number output_file times
    An OCSP request can also be generated using OpenSSL tools, as described at http://openssl.org/docs/apps/ocsp.html, or through a browser such as Internet Explorer 7.0.
  2. Paste the URL in the address bar of a web browser to return the status information. The browser must be able to handle OCSP requests.
    https://server.example.com:11443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewd
         Dnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
  3. The OCSP Manager responds with the certificate status which the browser can interpret. The possible statuses are GOOD, REVOKED, and UNKNOWN.
Alternatively, run the OCSP from the command line by using a tool such as wget to send the request and checking the OCSP logs for the response. For example:
  1. Generate an OCSP request for the certificate that's status is being queried.
    # OCSPClient server.example.com 11443 /var/lib/pki-ca/alias 'caSigningCert cert-pki-ca' 1 /export/output.txt 1
    URI: /ocsp/ee/ocsp
    Data Length: 68
    Data: MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ
    44kgy35o7xW5BMzM8FTvyTwCAQE=
  2. Connect to the OCSP Manager using wget to send the OCSP request.
    wget https://server.example.com:11443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4J
         pmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE= --no-check-certificate
    --16:34:34-- https://server.example.com:11443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABky
         iCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
       =>`MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE='
    Resolving server.example.com... 192.168.123.224
    Connecting to server.example.com|192.168.123.224|:11443... connected.
    WARNING: Certificate verification error for server.example.com: self signed certificate 
          in certificate chain
    HTTP request sent, awaiting response... 200 OK
    Length: 2,362 (2.3K) [application/ocsp-response]
    
    100%[======================================================================>] 2,362 --.--K/s
    
    16:34:34 (474.43 MB/s) - `MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewd
         Dnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=' saved [2362/2362]
  3. The status for the specified certificate is written to the OCSP's debug log and can be GoodInfo, RevokeInfo, or UnknownInfo.
    [16/Jul/2009:16:48:47][http-11443-Processor24]: Serial Number: 1 
         Status: com.netscape.cmsutil.ocsp.GoodInfo
For certificates issued by a 7.1 CA with the Authority Information Access extension to be sent to the OCSP with the GET method, a redirect needs to be created to forward the requests to the appropriate URL, as described in Section 7.7, “Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier”.

7.7. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier

The location for the OCSP user pages, specified in the URL with the file root /ocsp/ee/ocsp/, is different in Certificate System 8.0 than the location in Certificate System 7.1, which was simply /ocsp/. In order for certificates issued by a 7.1 CA with the Authority Information Access extension to be sent to the OCSP, create a redirect to forward the requests to the appropriate URL.

NOTE

Setting the redirect is only required to manage certificates issued by a 7.1 CA with the Authority Information Access extension. If the certificates are issued by a later version Certificate Manager or do not contain the Authority Information Access extension, then this configuration is not necessary.
  1. Stop the OCSP Responder. For example:
    service pki-ocsp stop
  2. Open the OCSP's end user web applications directory. For example:
    cd /var/lib/pki-ocsp/webapps
  3. Open the ROOT/WEB-INF/ directory in the ROOT folder of the OCSP's web applications directory. For example:
    cd /var/lib/pki-ocsp/webapps/ROOT/WEB-INF/
  4. Create and open the lib/ directory in the ROOT folder of the OCSP's web applications directory. For example:
    mkdir lib
    cd lib/
  5. Create a symlink that links back to the /usr/share/java/pki/cms.jar JAR file. For example:
    ln -s /usr/share/java/pki/cms.jar cms.jar
  6. Move up to the main web application directory. For example:
    cd /var/lib/pki-ocsp/webapps/
  7. Rename the current instance (ocsp) directory. For example:
    mv /var/lib/pki-ocsp/webapps/ocsp /var/lib/pki-ocsp/webapps/ocsp2
  8. Open the WEB-INF/ directory in the original ocsp/ directory. For example:
    cd /var/lib/pki-ocsp/webapps/ocsp/WEB-INF
  9. In original ocsp/WEB-INF/ directory, edit the web.xml file and add lines mapping between the eeocspAddCRL and csadmin-wizard servlets.
       <servlet-mapping>
          <servlet-name>  ocspOCSP  </servlet-name>
          <url-pattern>   /ee/ocsp/*  </url-pattern>
       </servlet-mapping>
  10. Create and install the web.xml file in the ROOT directory. For example:
    <?xml version="1.0" encoding="ISO-8859-1"?>
    <web-app>
    
      <display-name>Welcome to Tomcat</display-name>
      <description>
         Welcome to Tomcat
      </description>
    
      <servlet>
        <servlet-name>ocspProxy</servlet-name>
        <servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class>
        <init-param>
          <param-name>destContext</param-name>
          <param-value>/ocsp2</param-value>
        </init-param>
        <init-param>
          <param-name>destServlet</param-name>
          <param-value>/ee/ocsp</param-value>
        </init-param>
      </servlet>
    
      <servlet>
        <servlet-name>ocspOther</servlet-name>
        <servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class>
        <init-param>
          <param-name>destContext</param-name>
          <param-value>/ocsp2</param-value>
        </init-param>
        <init-param>
          <param-name>srcContext</param-name>
          <param-value>/ocsp</param-value>
        </init-param>
        <init-param>
          <param-name>destServlet</param-name>
          <param-value></param-value>
        </init-param>
        <init-param>
          <param-name>matchURIStrings</param-name>
         
    <param-value>/ocsp/registry,/ocsp/acl,/ocsp/jobsScheduler,/ocsp/ug,/ocsp/server,/ocsp/log,
                /ocsp/auths,/ocsp/start,/ocsp/ocsp,/ocsp/services,/ocsp/agent,/ocsp/ee,
                /ocsp/admin</param-value>
        </init-param>
        <init-param>
          <param-name>destServletOnNoMatch</param-name>
          <param-value>/ee/ocsp</param-value>
        </init-param>
        <init-param>
          <param-name>appendPathInfoOnNoMatch</param-name>
          <param-value>/ocsp</param-value>
        </init-param>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>ocspProxy</servlet-name>
        <url-pattern>/ocsp</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>ocspOther</servlet-name>
        <url-pattern>/ocsp/*</url-pattern>
      </servlet-mapping>
    
    </web-app>
  11. Edit the /var/lib/pki-ocsp/conf/context.xml, changing the following line:
    <Context> 
     to 
    <Context crossContext="true" >
  12. Edit the /var/lib/pki-ocsp/webapps/ocsp2/services.template file and change the following line:
    result.recordSet[i].uri); 
     to 
    result.recordSet[i].uri + "/");
  13. Start the OCSP instance. For example:
    service pki-ocsp start

Part II. Additional Configuration to Manage CA Services

Table of Contents

8. Publishing Certificates and CRLs
8.1. About Publishing
8.1.1. Publishers
8.1.2. Mappers
8.1.3. Rules
8.1.4. Publishing to Files
8.1.5. OCSP Publishing
8.1.6. LDAP Publishing
8.2. Setting up Publishing
8.2.1. Configuring Publishing to a File
8.2.2. Configuring Publishing to an OCSP
8.2.3. Configuring Publishing to an LDAP Directory
8.2.4. Creating Rules
8.2.5. Enabling Publishing
8.3. Publishing CRLs over HTTP
8.3.1. Configuring CRL Publishing to Resume after Interrupted Downloads
8.3.2. Retrieving CRLs Using wget
8.3.3. Retrieving Partial CRLs
8.4. Publishing Cross-Pair Certificates
8.5. Testing Publishing to Files
8.6. Viewing Certificates and CRLs Published to File
8.7. Updating Certificates and CRLs in a Directory
8.7.1. Manually Updating Certificates in the Directory
8.7.2. Manually Updating the CRL in the Directory
8.8. Registering and Deleting Mapper and Publisher Plug-in Modules
9. Authentication for Enrolling Certificates
9.1. Configuring Agent-Approved Enrollment
9.2. Automated Enrollment
9.2.1. Setting up Directory-Based Authentication
9.2.2. Setting up PIN-Based Enrollment
9.2.3. Using Certificate-Based Authentication
9.2.4. Configuring Flat File Authentication
9.3. Setting up CMC Enrollment
9.3.1. Setting up the Server for Multiple Requests in a Full CMC Request
9.3.2. Testing CMCEnroll
9.4. Testing Enrollment
9.5. Managing Authentication Plug-ins
10. Using Automated Notifications
10.1. About Automated Notifications for the CA
10.1.1. Types of Automated Notifications
10.1.2. Determining End-Entity Email Addresses
10.1.3. About RA Notifications
10.2. Setting up Automated Notifications for the CA
10.2.1. Setting up Automated Notifications in the Console
10.2.2. Configuring Specific Notifications by Editing the CS.cfg File
10.2.3. Testing Configuration
10.3. Customizing Notification Messages
10.3.1. Customizing CA Notification Messages
10.3.2. Customizing RA Notification Messages
10.4. Configuring a Mail Server for Certificate System Notifications
10.5. Creating Custom Notifications for the CA
11. Setting Automated Jobs
11.1. About Automated Jobs
11.1.1. Setting up Automated Jobs
11.1.2. Types of Automated Jobs
11.2. Setting up the Job Scheduler
11.3. Setting up Specific Jobs
11.3.1. Configuring Specific Jobs Using the Certificate Manager Console
11.3.2. Configuring Jobs by Editing the Configuration File
11.3.3. Configuration Parameters of certRenewalNotifier
11.3.4. Configuration Parameters of requestInQueueNotifier
11.3.5. Configuration Parameters of publishCerts
11.3.6. Configuration Parameters of unpublishExpiredCerts
11.3.7. Frequency Settings for Automated Jobs
11.4. Registering or Deleting a Job Module

Chapter 8. Publishing Certificates and CRLs

Red Hat Certificate System includes a customizable publishing framework for the Certificate Manager, enabling certificate authorities to publish certificates, certificate revocation lists (CRLs), and other certificate-related objects to any of the supported repositories: an LDAP-compliant directory, a flat file, and an online validation authority. This chapter explains how to configure a Certificate Manager to publish certificates and CRLs to a file, to a directory, and to the Online Certificate Status Manager.
The general process to configure publishing is as follows:
  1. Configure publishing to a file, LDAP directory, or OCSP responder.
    There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or narrower definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.
  2. Set rules to determine what certificates are published to the locations. Any rule which a certificate or CRL matches is activated, so the same certificate can be published to a file and to an LDAP directory by matching a file-based rule and matching a directory-based rule.
    Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. Disable all rules that will not be used.
  3. Configure CRLs. CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
  4. Enable publishing after setting up publishers, mappers, and rules. Once publishing is enabled, the server starts publishing immediately. If the publishers, mappers, and rules are not completely configured, publishing may not work correctly or at all.

8.1. About Publishing

The Certificate System is capable of publishing certificates to a file or an LDAP directory and of publishing CRLs to a file, an LDAP directory, or to an OCSP responder.
For additional flexibility, specific types of certificates or CRLs can be published to a single format or all three. For example, CA certificates can be published only to a directory and not to a file, and user certificates can be published to both a file and a directory.

NOTE

An OCSP responder only provides information about CRLs; certificates are not published to an OCSP responder.
Different publishing locations can be set for certificates files and CRL files, as well as different publishing locations for different types of certificates files or different types of CRL files.
Similarly, different types of certificates and different types of CRLs can be published to different places in a directory. For example, certificates for users from the West Coast division of a company can be published in one branch of the directory, while certificates for users in the East Coast division can be published to another branch in the directory.
When publishing is enabled, every time a certificate or a CRL is issued, updated, or revoked, the publishing system is invoked. The certificate or CRL is evaluated by the rules to see if it matches the type and predicate set in the rule. The type specifies if the object is a CRL, CA certificate, or any other certificate. The predicate sets more criteria for the type of object being evaluated. For example, it can specify user certificates, or it can specify West Coast user certificates. To use predicates, a value needs to be entered in the predicate field of the publishing rule, and a corresponding value (although formatted somewhat differently) needs to be contained in the certificate or certificate request to match. The value in the certificate or certificate request may be derived from information in the certificate, such as the type of certificate, or may be derived from a hidden value that is placed in the request form. If no predicate is set, all certificates of that type are considered to match. For example, all CRLs match the rule if CRL is set as the type.
Every rule that is matched publishes the certificate or CRL according to the method and location specified in that rule. A given certificate or CRL can match no rules, one rule, more than one rule, or all rules. The publishing system attempts to match every certificate and CRL issued against all rules.
When a rule is matched, the certificate or CRL is published according to the method and location specified in the publisher associated with that rule. For example, if a rule matches all certificates issued to users, and the rule has a publisher that publishes to a file in the location /etc/CS/certificates, the certificate is published as a file to that location. If another rule matches all certificates issued to users, and the rule has a publisher that publishes to the LDAP attribute userCertificate;binary attribute, the certificate is published to the directory specified when LDAP publishing was enabled in this attribute in the user's entry.
For rules that specify to publish to a file, a new file is created when either a certificate or a CRL is issued in the stipulated directory.
For rules that specify to publish to an LDAP directory, the certificate or CRL is published to the entry specified in the directory, in the attribute specified. The CA overwrites the values for any published certificate or CRL attribute with any subsequent certificate or CRL. Simply put, any existing certificate or CRL that is already published is replaced by the next certificate or CRL.
For rules that specify to publish to an Online Certificate Status Manager, a CRL is published to this manager. Certificates are not published to an Online Certificate Status Manager.
For LDAP publishing, the location of the user's entry needs to be determined. Mappers are used to determine the entry to which to publish. The mappers can contain an exact DN for the entry, some variable that associates information that can be gotten from the certificate to create the DN, or enough information to search the directory for a unique attribute or set of attributes in the entry to ascertain the correct DN for the entry.
When a certificate is revoked, the server uses the publishing rules to locate and delete the corresponding certificate from the LDAP directory or from the filesystem.
When a certificate expires, the server can remove that certificate from the configured directory. The server does not do this automatically; the server must be configured to run the appropriate job. For details, see Chapter 11, Setting Automated Jobs.
Setting up publishing involves configuring publishers, mappers, and rules.

8.1.1. Publishers

Publishers specify the location to which certificates and CRLs are published. When publishing to a file, publishers specify the filesystem publishing directory. When publishing to an LDAP directory, publishers specify the attribute in the directory that stores the certificate or CRL; a mapper is used to determine the DN of the entry. For every DN, a different formula is set for deriving that DN. The location of the LDAP directory is specified when LDAP publishing is enabled. When publishing a CRL to an OCSP responder, publishers specify the hostname and URI of the Online Certificate Status Manager.

8.1.2. Mappers

Mappers are only used in LDAP publishing. Mappers construct the DN for an entry based on information from the certificate or the certificate request. The server has information from the subject name of the certificate and the certificate request and needs to know how to use this information to create a DN for that entry. The mapper provides a formula for converting the information available either to a DN or to some unique information that can be searched in the directory to obtain a DN for the entry.

8.1.3. Rules

Rules for file, LDAP, and OCSP publishing tell the server whether and how a certificate or CRL is to be published. A rule first defines what is to be published, a certificate or CRL matching certain characteristics, by setting a type and predicate for the rule. A rule then specifies the publishing method and location by being associated with a publisher and, for LDAP publishing, with a mapper.
Rules can be as simple or complex as necessary for the PKI deployment and are flexible enough to accommodate different scenarios.

8.1.4. Publishing to Files

The server can publish certificates and CRLs to flat files, which can then be imported into any repository, such as a relational database. When the server is configured to publish certificates and CRLs to file, the published files are DER-encoded binary blobs, base-64 encoded text blobs, or both.
  • For each certificate the server issues, it creates a file that contains the certificate in either DER-encoded or base-64 encoded format. Each file is named either cert-serial_number.der or cert-serial_number.b64. The serial_number is the serial number of the certificate contained in the file. For example, the filename for a DER-encoded certificate with the serial number 1234 is cert-1234.der.
  • Every time the server generates a CRL, it creates a file that contains the new CRL in either DER-encoded or base-64 encoded format. Each file is named either issuing_point_name-this_update.der or issuing_point_name-this_update.b64, depending on the format. The issuing_point_name identifies the CRL issuing point which published the CRL, and this_update specifies the value derived from the time-dependent update value for the CRL contained in the file. For example, the filename for a DER-encoded CRL with the value This Update: Friday January 28 15:36:00 PST 2009, is MasterCRL-20090128-153600.der.

8.1.5. OCSP Publishing

There are two forms of Certificate System OCSP services, an internal service for the Certificate Manager and the Online Certificate Status Manager. The internal service checks the internal database of the Certificate Manager to report on the status of a certificate. The internal service is not set for publishing; it uses the certificates stored in its internal database to determine the status of a certificate. The Online Certificate Status Manager checks CRLs sent to it by Certificate Manager. A publisher is set for each location a CRL is sent and one rule for each type of CRL sent.
For detailed information on both OCSP services, see Chapter 7, Using the Online Certificate Status Protocol Responder.

8.1.6. LDAP Publishing

In LDAP publishing, the server publishes the certificates, CRLs, and other certificate-related objects to a directory using LDAP or LDAPS. The branch of the directory to which it publishes is called the publishing directory.
  • For each certificate the server issues, it creates a blob that contains the certificate in its DER-encoded format in the specified attribute of the user's entry. The certificate is published as a DER encoded binary blob.
  • Every time the server generates a CRL, it creates a blob that contains the new CRL in its DER-encoded format in the specified attribute of the entry for the CA.
The server can publish certificates and CRLs to an LDAP-compliant directory using the LDAP protocol or LDAP over SSL (LDAPS) protocol, and applications can retrieve the certificates and CRLs over HTTP. Support for retrieving certificates and CRLs over HTTP enables some browsers to import the latest CRL automatically from the directory that receives regular updates from the server. The browser can then use the CRL to check all certificates automatically to ensure that they have not been revoked.
For LDAP publishing to work, the user entry must be present in the LDAP directory.
If the server and publishing directory become out of sync for some reason, privileged users (administrators and agents) can also manually initiate the publishing process. For instructions, see Section 8.7.2, “Manually Updating the CRL in the Directory”.

8.2. Setting up Publishing

The general process to configure publishing involves setting up a publisher to publish the certificates or CRLs to the specific location. There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or finer definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.
  1. Publishing to file simply publishes the CRLs or certificates to text files on a given host. This is covered in Section 8.2.1, “Configuring Publishing to a File”.
  2. Publishing to an OCSP Manager is a way to publish CRLs to a specific location for client verification. This is covered in Section 8.2.2, “Configuring Publishing to an OCSP”.
    For OCSP publishing, CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
  3. LDAP publishing publishes the certificates to specific entries within an LDAP database, so other clients can access the entries. There are three steps for configuring LDAP publishing:
    1. Configure the Directory Server to which certificates will be published. Refer to Section 8.2.3.1, “Configuring the LDAP Directory”.
    2. Configure a publisher for each type of object published: CA certificates, cross-pair certificates, CRLs, and user certificates. The publisher declares in which attribute to store the object. The attributes set by default are the X.500 standard attributes for storing each object type. This attribute can be changed in the publisher, but, generally, LDAP publishers do not need changed. For more information, see Section 8.2.3, “Configuring Publishing to an LDAP Directory”.
    3. Set up mappers to enable an entry's DN to be derived from the certificate's subject name. This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.
      For details about setting up mappers, see Section 8.2.3.3, “Creating Mappers”.
After setting up the publishing locations, then define rules to determine what certificates are published where (Section 8.2.4, “Creating Rules”). Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any rule which it matches is activated. The same certificate can be published to a file and to an LDAP directory by matching a file-based rule and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. There can be different rules for different kinds of certificates or different kinds of CRLs. The rule first determines if the object meets the criteria by matching the type and predicate set in the rule. The destination of matching objects is determined by the publisher and mapper associated with the rule.
After setting up all of the publishers, mappers, and rules, enable publishing (Section 8.2.5, “Enabling Publishing”). As soon as publishing is enabled, the server starts publishing immediately. If the publishers, mappers, and rules are not completely configured, publishing may not work correctly or at all.

8.2.1. Configuring Publishing to a File

Publishers must be created and configured for each publishing location; publishers are not automatically created for publishing to a file. To publish all files to a single location, create one publisher. To publish to different locations, create a publisher for each location. A location can either contain an object type, like user certificates, or a subset of an object type, like West Coast user certificates.
To create publishers for publishing to files:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
    The Publishers Management tab, which lists configured publisher instances, opens on the right.
    Using the Publishers Management Tab to Create Publishers

    Figure 8.1. Using the Publishers Management Tab to Create Publishers


  3. Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
    Select Publisher Plug-in Implementation Window

    Figure 8.2. Select Publisher Plug-in Implementation Window


  4. Select the FileBasedPublisher module, then open the editor window.
    This is the module that enables the Certificate Manager to publish certificates and CRLs to files.
  5. Configure the information for publishing the certificate:
    • The publisher ID, an alphanumeric string with no spaces like PublishCertsToFile
    • The path to the directory in which the Certificate Manager should publish the files. The path can be an absolute path or can be relative to the Certificate System instance directory. For example, /export/CS/certificates.
    • The file type to publish, by selecting the checkboxes for DER-encoded files, base-64 encoded files, or both.
    • The format of the timestamp to use to name the published certificate or CRL files.
    • For CRLs, whether to generate a link in the file to go to the latest CRL. If enabled, the link assumes that the name of the CRL issuing point to use with the extension will be supplied in the crlLinkExt field.
    • For CRLs, whether to compress (zip) CRLs and the compression level to use.
After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 8.2.4, “Creating Rules”.

8.2.2. Configuring Publishing to an OCSP

A publisher must be created and configured for each publishing location; publishers are not automatically created for publishing to the OCSP responder. Create a single publisher to publish everything to s single location, or create a publisher for every location to which CRLs will be published. Each location can contain a different kind of CRL.
To create publishers for publishing CRLs to an OCSP:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
    Publishers Management Tab

    Figure 8.3. Publishers Management Tab


  3. Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
    Select Publisher Plug-in Implementation Window

    Figure 8.4. Select Publisher Plug-in Implementation Window


  4. Select the OCSPPublisher module, then open the editor window. This is the publisher module that enables the Certificate Manager to publish CRLs to the Online Certificate Status Manager.
    Publisher Editor Window

    Figure 8.5. Publisher Editor Window


    The host can be the fully-qualified domain name or an IPv4 or IPv6 address.
  5. Set the publisher ID, an alphanumeric string with no spaces like PublishCertsToOCSP; the fully-qualified domain name, such as ocspResponder.example.com, and port number of the Online Certificate Status Manager; and the default path, /ocsp/ee/ocsp/addCRL.
After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 8.2.4, “Creating Rules”.

8.2.3. Configuring Publishing to an LDAP Directory

Configuring LDAP publishing is similar to other publishing procedures, with additional steps to configure the directory:
  1. Configure the Directory Server to which certificates will be published. Certain attributes have to be added to entries and bind identities and authentication methods have to be configured.
  2. Configure a publisher for each type of object published: CA certificates, cross-pair certificates, CRLs, and user certificates. The publisher declares in which attribute to store the object. The attributes set by default are the X.500 standard attributes for storing each object type. This attribute can be changed in the publisher, but, generally, it's not necessary to change the LDAP publishers.
  3. Set up mappers to enable an entry's DN to be derived from the certificate's subject name. This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.
    For details about setting up mappers, see Section 8.2.3.3, “Creating Mappers”.
  4. Create rules to connect publishers to mappers, as described in Section 8.2.4, “Creating Rules”.

8.2.3.1. Configuring the LDAP Directory

Before certificates and CRLs can be published, the Directory Server must be configured to work with the publishing system.
  1. Set up the entry for the CA. For the Certificate Manager to publish its CA certificate and CRL, the directory must include an entry for the CA.
    The Certificate Manager automatically creates an entry for the CA in the directory. This option is set in both the CA and CRL mapper instances and enabled by default. If the directory restricts the Certificate Manager from creating entries in the directory, turn off this option in those mapper instances, and add an entry for the CA manually in the directory.
    When adding the CA's entry to the directory, select the entry type based on the DN of the CA:
    • If the CA's DN begins with the cn component, create a new person entry for the CA. Selecting a different type of entry may not allow the cn component to be specified.
    • If the CA's DN begins with the ou component, create a new organizationalunit entry for the CA.
    The entry does not have to be in the certificationAuthority object class. The Certificate Manager will convert this entry to the certificationAuthority object class automatically by publishing its CA's signing certificate.
    For more information on creating directory entries, see the Red Hat Directory Server documentation.
  2. Add the correct schema elements to the CA and user directory entries.
    For a Certificate Manager to publish certificates and CRLs to a directory, it must figured with specific attributes and object classes.
    Certificate Type Schema Reason
    End-entity userCertificate;binary (attribute)
    This is the attribute to which the Certificate Manager publishes the certificate.
    This is a multi-valued attribute, and each value is a DER-encoded binary X.509 certificate. The LDAP object class named inetOrgPerson allows this attribute. The strongAuthenticationUser object class allows this attribute and can be combined with any other object class to allow certificates to be published to directory entries with other object classes. The Certificate Manager does not automatically add this object class to the schema table of the corresponding Directory Server.
    If the directory object that it finds does not allow the userCertificate;binary attribute, adding or removing the certificate fails.
    CA caCertificate;binary (attribute)
    This is the attribute to which the Certificate Manager publishes the certificate.
    The Certificate Manager publishes its own CA certificate to its own LDAP directory entry when the server starts. The entry corresponds to the Certificate Manager's issuer name.
    This is a required attribute of the certificationAuthority object class. The Certificate Manager adds this object class to the directory entry for the CA if it can find the CA's directory entry.
    CRL certificateRevocationList;binary (attribute)
    This is the attribute to which the Certificate Manager publishes the CRL.
    The Certificate Manager publishes the CRL to its own LDAP directory entry. The entry corresponds to the Certificate Manager's issuer name.
    This is an attribute of the certificationAuthority object class. The value of the attribute is the DER-encoded binary X.509 CRL. The CA's entry must already contain the certificationAuthority object class for the CRL to be published to the entry.
  3. Set up a bind DN for the Certificate Manager to use to access the Directory Server.
    The Certificate Manager user must have read-write permissions to the directory to publish certificates and CRLs to the directory so that the Certificate Manager can modify the user entries with certificate-related information and the CA entry with CA's certificate and CRL related information.
    The bind DN entry can be either of the following:
    • An existing DN that has write access, such as the Directory Manager.
    • A new user which is granted write access. The entry can be identified by the Certificate Manager's DN, such as cn=testCA, ou=Research Dept, o=Example Corporation, st=California, c=US.

      NOTE

      Carefully consider what privileges are given to this user. This user can be restricted in what it can write to the directory by creating ACLs for the account. For instructions on giving write access to the Certificate Manager's entry, see the Directory Server documentation.
  4. Set the directory authentication method for how the Certificate Manager authenticates to Directory Server. There are three options: basic authentication (simple username and password); SSL without client authentication (simple username and password); and SSL with client authentication (certificate-based).
    See the Red Hat Directory Server documentation for instructions on setting up these methods of communication with the server.

8.2.3.2. Configuring LDAP Publishers

The Certificate Manager creates, configures, and enables a set of publishers that are associated with LDAP publishing. The default publishers (for CA certificates, user certificates, CRLs, and cross-pair certificates) already conform to the X.500 standard attributes for storing certificates and CRLs and do not need to be changed.

Table 8.1. LDAP Publishers

Publisher Description
LdapCaCertPublisher Publishes CA certificates to the LDAP directory.
LdapCrlPublisher Publishes CRLs to the LDAP directory.
LdapDeltaCrlPublisher Publishes Delta CRLs to the LDAP directory.
LdapUserCertPublisher Publishes all types of end-entity certificates to the LDAP directory.
LdapCrossCertPairPublisher Publishes cross-signed certificates to the LDAP directory.

8.2.3.3. Creating Mappers

Mappers are only used with LDAP publishing. Mappers define a relationship between a certificate's subject name and the DN of the directory entry to which the certificate is published. The Certificate Manager needs to derive the DN of the entry from the certificate or the certificate request so it can determine which entry to use. The mapper defines the relationship between the DN for the user entry and the subject name of the certificate or other input information so that the exact DN of the entry can be determined and found in the directory.
When it is configured, the Certificate Manager automatically creates a set of mappers defining the most common relationships. The default mappers are listed in Table 8.2, “Default Mappers”.

Table 8.2. Default Mappers

Mapper Description
LdapUserCertMap Locates the correct attribute of user entries in the directory in order to publish user certificates.
LdapCrlMap Locates the correct attribute of the CA's entry in the directory in order to publish the CRL.
LdapCaCertMap Locates the correct attribute of the CA's entry in the directory in order to publish the CA certificate.

To use the default mappers, configure each of the macros by specifying the DN pattern and whether to create the CA entry in the directory. To use other mappers, create and configure an instance of the mapper. For more information, see Section C.2, “Mapper Plug-in Modules ”.
To modify a mapper:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Mappers.
    The Mappers Management tab, which lists configured mappers, opens on the right.
    Mappers Management Tab

    Figure 8.6. Mappers Management Tab


  3. In the mapper list, select a mapper to modify.
  4. To edit an existing mapper, click Edit/View. The editor window opens.
    Mapper Editor Window

    Figure 8.7. Mapper Editor Window


  5. To create a new mapper instance, click Add. The Select Mapper Plugin Implementation window opens, which lists registered mapper modules. Select a module, and edit it. For complete information about these modules, see Section C.2, “Mapper Plug-in Modules ”.
    Selecting a New Mapper Type

    Figure 8.8. Selecting a New Mapper Type


  6. Edit the mapper instance, and click OK.
    Creating a New Mapper

    Figure 8.9. Creating a New Mapper


    See Section C.2, “Mapper Plug-in Modules ” for detailed information about each mapper.

8.2.3.4. Creating Rules

After configuring the mappers for LDAP publishing, configure the rules for the published certificates and CRLs, as described in Section 8.2.4, “Creating Rules”.

8.2.4. Creating Rules

Rules determine what certificate object is published in what location. Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any rule which it matches is activated. In this way, the same certificate or CRL can be published to a file, to an Online Certificate Status Manager, and to an LDAP directory by matching a file-based rule, an OCSP rule, and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. The rules can be more detailed for different kinds of certificates or different kinds of CRLs.
The rule first determines if the object matches by matching the type and predicate set up in the rule with the object. Where matching objects are published is determined by the publisher and mapper associated with the rule.
Rules are created for each type of certificate the Certificate Manager issues.
Modify publishing rules by doing the following:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Rules.
    The Rules Management tab, which lists configured rules, opens on the right.
    Rules Management Tab

    Figure 8.10. Rules Management Tab


  3. To edit an existing rule, select that rule from the list, and click Edit. This opens the Rule Editor window.
    Using the Rule Editor Window to Edit an Existing Rule

    Figure 8.11. Using the Rule Editor Window to Edit an Existing Rule


  4. To create a rule, click Add. This opens the Select Rule Plug-in Implementation window.
    Select Rule Plugin Implementation Window

    Figure 8.12. Select Rule Plugin Implementation Window


    Select the Rule module. This is the only default module. If any custom modules have been been registered, they are also available.
  5. Edit the rule.
    Rule Editor Window

    Figure 8.13. Rule Editor Window


    • type. This is the type of certificate for which the rule applies. For a CA signing certificate, the value is cacert. For a cross-signed certificate, the value is xcert. For all other types of certificates, the value is certs. For CRLs, specify crl.
    • predicate. This sets the predicate value for the type of certificate or CRL issuing point to which this rule applies. The predicate values for CRL issuing points, delta CRLs, and certificates are listed in Table 8.3, “Predicate Expressions”.
    • enable.
    • mapper. Mappers are not necessary when publishing to a file; they are only needed for LDAP publishing. If this rule is associated with a publisher that publishes to an LDAP directory, select an appropriate mapper here. Leave blank for all other forms of publishing.
    • publisher. Sets the publisher to associate with the rule.
Table 8.3, “Predicate Expressions” lists the predicates that can be used to identify CRL issuing points and delta CRLs and certificate profiles.

Table 8.3. Predicate Expressions

Predicate Type Predicate
CRL Issuing Point
issuingPointId==Issuing_Point_Instance_ID && isDeltaCRl==[true|false]
To publish only the master CRL, set isDeltaCRl==false. To publish only the delta CRL, set isDeltaCRl==true. To publish both, set a rule for the master CRL and another rule for the delta CRL.
Certificate Profile
profileId==profile_name
To publish certificates based on the profile used to issue them, set profileId== to a profile name, such as caServerCert.

8.2.5. Enabling Publishing

Publishing can be enabled for only files, only LDAP, or both. Publishing should be enabled after setting up publishers, rules, and mappers. Once enabled, the server attempts to begin publishing. If publishing was not configured correctly before being enabled, publishing may exhibit undesirable behavior or may fail.

NOTE

Configure CRLs. CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing.
    The right pane shows the details for publishing to an LDAP-compliant directory.
  3. To enable publishing to a file only, select Enable Publishing.
  4. To enable LDAP publishing, select both Enable Publishing and Enable Default LDAP Connection.
    Enabling Publishing

    Figure 8.14. Enabling Publishing


    In the Destination section, set the information for the Directory Server instance.
    • Host name. If the Directory Server is configured for SSL client authenticated communication, the name must match the cn component in the subject DN of the Directory Server's SSL server certificate.
      The hostname can be the fully-qualified domain name or an IPv4 or IPv6 address.
    • Port number.
    • Directory Manager DN. This is the distinguished name (DN) of the directory entry that has Directory Manager privileges. The Certificate Manager uses this DN to access the directory tree and to publish to the directory. The access control set up for this DN determines whether the Certificate Manager can perform publishing. It is possible to create another DN that has limited read-write permissions for only those attributes that the publishing system actually needs to write.
    • Password. This is the password which the CA uses to bind to the LDAP directory to which the certificate or CRL is published. The Certificate Manager saves this password in its password.conf file. For example:
      CA LDAP Publishing:password
      The parameter name which identifies the publishing password (CA LDAP Publishing) is set in the Certificate Manager's CS.cfg file in the ca.publish.ldappublish.ldap.ldapauth.bindPWPrompt parameter, and it can be edited.
    • Client certificate. This sets the certificate the Certificate Manager uses for SSL client authentication to the publishing directory. By default, the Certificate Manager uses its SSL server certificate.
    • LDAP version. Select LDAP version 3.
    • Authentication. The way the Certificate Manager authenticates to the Directory Server. The choices are Basic authentication and SSL client authentication.
      If the Directory Server is configured for basic authentication or for SSL communication without client authentication, select Basic authentication and specify values for the Directory manager DN and password.
      If the Directory Server is configured for SSL communication with client authentication, select SSL client authentication and the Use SSL communication option, and identify the certificate that the Certificate Manager must use for SSL client authentication to the directory.
The server attempts to connect to the Directory Server. If the information is incorrect, the server displays an error message.

8.3. Publishing CRLs over HTTP

Certificate System can publish CRLs to a plain file over HTTP. For example, publishing to an OCSP responder means that the CA sends a text file of its CRL to a specific URL or web-based directory for the OCSP.
Publishing CRLs over HTTP gives some robustness to how the CRLs are published. The publishing process can be interruped and resumed smoothly. It also gives flexibility for retrieving CRLs, since they can be downloaded using tools like wget.

8.3.1. Configuring CRL Publishing to Resume after Interrupted Downloads

CRLs can be very large, so downloading CRLs can take a very long time. If the process is interrupted, then downloading has to begin all over again to publish the entire CRL.
Certificate System can publish CRLs to a plain file and then allow it to be downloaded over HTTP 1.1. Additionally, Certificate System can publish compressed (zipped) CRLs which use byte ranges to track the compressed contents, so that the download progress can be tracked and, if it is interrupted, the download can resume at the point where it dropped off.
Using HTTP 1.1 allows the client to avoid fetching a CRL which has already been retrieved.
To do this, the Certificate Manager publishes the CRL to a file and uses the Certificate Manager's web server to handle the HTTP 1.1 downloads.
Configuring the CA publishing to allow CRL downloads to resume after interruptions requires configuring two things:
  • A CRL file publisher pointing to the Certificate Manager's web server directory
  • Settings in the Certificate Manager web server configuration to allow the published CRL file to be downloaded
To configure CRL publishing over HTTP 1.1:
  1. Create the directory to which to publish the CRL files. For example:
    mkdir /var/lib/pki-ca/webapps/ca/ee/ca/crl
  2. Open the console for the Certificate Manager.
    pkiconsole https://server.example.com:9445/ca
  3. In the left menu, open the Publishing folder, and select the Publishers link.
  4. In the Publishers Management tab, click Add.
  5. Select the FileBasedPublisher plug-in.
  6. Fill in the CRL publishing information.
    Three points are required for publishing CRLs over HTTP 1.1:
    • Select latestCrlLink, which configures the server to send the latest generated CRL or the most recent partial CRL.
    • Set the crlLinkExt to bin, which gives the proper file extension to the compressed published CRL.
    • Select the zipCrls checkbox to compress the CRL and, optionally, set the compression level.
  7. In the left menu, select the Rules link.
  8. Click Add in the Rules Management tab to create a new rule for CRL publishing.
  9. Select Rule and click Next.
  10. In the Rule Editor, configure the new rule.
    • Set the type to crl.
    • Make sure that the enable checkbox is selected.
    • Set the mapper to NoMap.
    • Select the new CRL file publisher from the publisher drop-down menu.
  11. Disable any unused rules.
  12. In the left menu, select the main Publishing folder, and, in the General tab, check the Enable Publishing checkbox.

    NOTE

    Make sure that the Enable Default LDAP Connection option is not selected.
  13. Edit the CA's server.xml file to point to the published CRL location as its docroot by adding a new <Context line. For example:
    vim /var/lib/pki-ca/conf/server.xml
    
    <Server>
          ....
          <!--  <Context docBase="webapps" path="/webapps" reloadable="false"/> -->  this line is commented out by default    
          <Context path="/ca/ee/ca/crl" docBase="/var/lib/pki-ca/webapps/ca/ee/ca/crl" allowLinking="true"/>   this is the new line    
         </Host>
       </Engine>
     </Service>
    </Server>
  14. It can be beneficial to test the setup by interrupting a CRL download and then downloading the partial CRL.
    To emulate interrupting a CRL download, download a CRL and then remove blocks of it using dd:
    wget --no-check-certificate -d https://server.example.com:9444/ca/ee/ca/crl/MasterCRL.bin
    mv MasterCRL.bin MasterCRL.bin.full
    dd if=MasterCRL.bin.full of=MasterCRL.bin count=200 bs=1
    Then attempt to download the partial CRL using wget -c.
    wget --no-check-certificate -c -d https://server.example.com:9444/ca/ee/ca/crl/MasterCRL.bin

8.3.2. Retrieving CRLs Using wget

Because CRLs can be published as a text file over HTTP, they can be manually retrieved from the CA using a tool like wget. wget can be used to retrieve any type of published CRL:
  • Full CRLs. For example:
    wget --no-check-certificate -d https://server.example.com:9444/ca/ee/ca/crl/MasterCRL.bin
  • Delta CRLs. For example:
    wget --no-check-certificate -N -d https://server.example.com:9444/ca/ee/ca/crl/MasterCRL.bin
The relevant parameters for wget are summarized in Table 8.4, “wget Options to Use for Retrieving CRLs”.

Table 8.4. wget Options to Use for Retrieving CRLs

Argument Description
no argument Retrieves the full CRL.
-N Retrieves the CRL that is newer than the local copy (delta CRL).
-c Retrieves a partially-downloaded file.
--no-check-certificate Skips SSL for the connection, so it is not necessary to configure SSL between the host and client.
-d Prints debug information.

8.3.3. Retrieving Partial CRLs

Because CRLs can be so large, the publishing process can take a long time, which opens up the possibilities of the publishing process being interrupted. Section 8.3.1, “Configuring CRL Publishing to Resume after Interrupted Downloads” describes how to configure publishing so that the partial CRL can be resumed after a publishing operation is interrupted.
To retrieve a partial CRL, run the wget command with -c option. This picks upm the CRL download at the place it was terminated.
wget --no-check-certificate -c -d https://server.example.com:9444/ca/ee/ca/crl/MasterCRL.bin
Other relevant parameters for wget are summarized in Table 8.4, “wget Options to Use for Retrieving CRLs”.

TIP

It can be beneficial to test the setup in Section 8.3.1, “Configuring CRL Publishing to Resume after Interrupted Downloads” by interrupting a CRL download and then downloading the partial CRL.
To emulate interrupting a CRL download, download a CRL and then remove blocks of it using dd:
wget --no-check-certificate -d https://server.example.com:9444/ca/ee/ca/crl/MasterCRL.bin
mv MasterCRL.bin MasterCRL.bin.full
dd if=MasterCRL.bin.full of=MasterCRL.bin count=200 bs=1
Then attempt to download the partial CRL using wget -c.

8.4. Publishing Cross-Pair Certificates

The cross-pair certificates can be published as a crossCertificatePair entry to an LDAP directory or to a file; this is enabled by default. If this has been disabled, it can be reenabled through the Certificate Manager Console by doing the following:
  1. Open the CA console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select the Certificate Manager link in the left pane, then the Publishing link.
  3. Click the Rules link under Publishing. This opens the Rules Management pane on the right.
  4. If the rule exists and has been disabled, select the enable checkbox. If the rule has been deleted, then click Add and create a new rule.
    1. Select xcerts from the type drop-down menu.
    2. Make sure the enable checkbox is selected.
    3. Select LdapCaCertMap from the mapper drop-down menu.
    4. Select LdapCrossCertPairPublisher from the publisher drop-down menu.
The mapper and publisher specified in the publishing rule are both listed under Mapper and Publisher under the Publishing link in the left navigation window of the CA Console. The mapper, LdapCaCertMap, by default designates that the crossCertificatePair be stored to the LdapCaSimpleMap LDAP entry. The publisher, LDAPCrossPairPublisher, by default sets the attribute to store the cross-pair certificate in the CA entry to crossCertificatePair;binary.

8.5. Testing Publishing to Files

To verify that the Certificate Manager is publishing certificates and CRLs correctly to file:
  1. Open the CA's end-entities page, and request a certificate.
  2. Approve the request through the agent services page, if required.
  3. Retrieve the certificate from the end-entities page, and download the certificate into the browser.
  4. Check whether the server generated the DER-encoded file containing the certificate.
    Open the directory to which the binary blob of the certificate is supposed to be published. The certificate file should be named cert-serial_number.der.
  5. Convert the DER-encoded certificate to its base 64-encoded format using the Binary to ASCII tool. For more information on this tool, refer to the Certificate System Command-Line Tools Guide.
    BtoA input_file output_file
    input_file sets the path to the file that contains the DER-encoded certificate, and output_file sets the path to the file to write the base-64 encoded certificate.
  6. Open the ASCII file; the base-64 encoded certificate is similar to the one shown:
    -----BEGIN CERTIFICATE-----
    MMIIBtgYJYIZIAYb4QgIFoIIBpzCCAZ8wggGbMIIBRaADAgEAAgEBMA0GCSqGSIb3DQEBBAUAMFcxC
    AJBgNVBAYTAlVTMSwwKgYDVQQKEyNOZXRzY2FwZSBDb21tdW5pY2F0aWhfyyuougjgjjgmkgjkgmjg
    fjfgjjjgfyjfyj9ucyBDb3Jwb3JhdGlvbjpMEaMBgGA1UECxMRSXNzdWluZyhgdfhbfdpffjphotoo
    gdhkBBdXRob3JpdHkwHhcNOTYxMTA4MDkwNzM0WhcNOTgxMTA4MDkwNzMM0WjBXMQswCQYDVQQGEwJ
    VUzEsMCoGA1UEChMjTmV0c2NhcGUgQ29tbXVuaWNhdGlvbnMgQ29ycG9yY2F0aW9ucyBDb3Jwb3Jhd
    GlvbjpMEaMBgGA1UECxMRSXNzdWluZyBBdXRob3JpdHkwHh
    -----END CERTIFICATE-----
  7. Convert the base 64-encoded certificate to a readable form using the Pretty Print Certificate tool. For more information on this tool, refer to the Certificate System Command-Line Tools Guide.
    PrettyPrintCert input_file [output_file]
    input_file sets the path to the ASCII file that contains the base-64 encoded certificate, and output_file, optionally, sets the path to the file to write the certificate. If an output file is not set, the certificate information is written to the standard output.
  8. Compare the output with the certificate issued; check the serial number in the certificate with the one used in the filename.
    If everything matches, the Certificate Manager is configured correctly to publish certificates to file.
  9. Revoke the certificate.
  10. Check whether the server generated the DER-encoded file containing the CRL.
    Open the directory to which the server is to publish the CRL as a binary blob. The CRL file should have a name in the form crl-this_update.der. this_update specifies the value derived from the time-dependent This Update variable of the CRL.
  11. Convert the DER-encoded CRL to its base 64-encoded format using the Binary to ASCII tool.
    BtoA input_file output_file
  12. Convert the base 64-encoded CRL to readable form using the Pretty Print CRL tool.
    PrettyPrintCrl input_file [output_file]
  13. Compare the output.

8.6. Viewing Certificates and CRLs Published to File

Certificates and CRLs can be published to two types of files: base-64 encoded or DER-encoded. The content of these files can be viewed by converting the files to pretty-print format using the dumpasn1 tool or the PrettyPrintCert or PrettyPrintCRL tool.
To view the content in a base-64 encoded file:
  1. Convert the base-64 file to binary. For example:
    AtoB /tmp/example.b64 /tmp/example.bin
  2. Use the PrettyPrintCert or PrettyPrintCRL tool to convert the binary file to pretty-print format. For example:
    PrettyPrintCert example.bin example.cert
    Alternatively, the dumpasn1 can be used to convert a binary certificate or CRL to pretty-print format. The dumpasn1 tool can be downloaded at http://fedoraproject.org/extras/4/i386/repodata/repoview/dumpasn1-0-20050404-1.fc4.html.
To view the content of a DER-encoded file, simply run the dumpasn1, PrettyPrintCert, or PrettyPrintCRL tool with the DER-encoded file. For example:
PrettyPrintCRL example.der example.crl

8.7. Updating Certificates and CRLs in a Directory

The Certificate Manager and the publishing directory can become out of sync if certificates are issued or revoked while the Directory Server is down. Certificates that were issued or revoked need to be published or unpublished manually when the Directory Server comes back up.
To find certificates that are out of sync with the directory ‐ valid certificates that are not in the directory and revoked or expired certificates that are still in the directory ‐ the Certificate Manager keeps a record of whether a certificate in its internal database has been published to the directory. If the Certificate Manager and the publishing directory become out of sync, use the Update Directory option in the Certificate Manager agent services page to synchronize the publishing directory with the internal database.
The following choices are available for synchronizing the directory with the internal database:
  • Search the internal database for certificates that are out of sync and publish or unpublish.
  • Publish certificates that were issued while the Directory Server was down. Similarly, unpublish certificates that were revoked or that expired while Directory Server was down.
  • Publish or unpublish a range of certificates based on serial numbers, from serial number xx to serial number yy.
A Certificate Manager's publishing directory can be manually updated by a Certificate Manager agent only.

8.7.1. Manually Updating Certificates in the Directory

The Update Directory Server form in the Certificate Manager agent services page can be used to update the directory manually with certificate-related information. This form initiates a combination of the following operations:
  • Update the directory with certificates.
  • Remove expired certificates from the directory.
    Removing expired certificates from the publishing directory can be automated by scheduling an automated job. For details, see Chapter 11, Setting Automated Jobs.
  • Remove revoked certificates from the directory.
Manually update the directory with changes by doing the following:
  1. Open the Certificate Manager agent services page.
  2. Select the Update Directory Server link.
  3. Select the appropriate options, and click Update Directory.
    The Certificate Manager starts updating the directory with the certificate information in its internal database. If the changes are substantial, updating the directory can take considerable time. During this period, any changes made through the Certificate Manager, including any certificates issued or any certificates revoked, may not be included in the update. If any certificates are issued or revoked while the directory is updated, update the directory again to reflect those changes.
When the directory update is complete, the Certificate Manager displays a status report. If the process is interrupted, the server logs an error message.
If the Certificate Manager is installed as a root CA, the CA signing certificate may get published using the publishing rule set up for user certificates when using the agent interface to update the directory with valid certificates. This may return an object class violation error or other errors in the mapper. Selecting the appropriate serial number range to exclude the CA signing certificate can avoid this problem. The CA signing certificate is the first certificate a root CA issues.
  • Modify the default publishing rule for user certificates by changing the value of the predicate parameter to profileId!=caCACert.
  • Use the LdapCaCertPublisher publisher plug-in module to add another rule, with the predicate parameter set to profileId=caCACert, for publishing subordinate CA certificates.

8.7.2. Manually Updating the CRL in the Directory

The Certificate Revocation List form in the Certificate Manager agent services page manually updates the directory with CRL-related information.
Manually update the CRL information by doing the following:
  1. Open the Certificate Manager agent services page.
  2. Select Update Revocation List.
  3. Click Update.
The Certificate Manager starts updating the directory with the CRL in its internal database. If the CRL is large, updating the directory takes considerable time. During this period, any changes made to the CRL may not be included in the update.
When the directory is updated, the Certificate Manager displays a status report. If the process is interrupted, the server logs an error message.

8.8. Registering and Deleting Mapper and Publisher Plug-in Modules

New mapper or publisher plug-in modules can be registered in a Certificate Manager's publishing framework. Unwanted mapper or publisher plug-in modules can be deleted. Before deleting a module, delete all the rules that are based on this module.
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing.
  3. To register or delete a mapper module, select Mappers, and then select the Mapper Plugin Registration tab.
  4. To register or delete a publisher module, select Publishers, and then select the Publisher Plug-in Registration tab.
  5. To delete a plug-in, select the plug-in, and click Delete. Confirm the deletion in the popup window that appears.
  6. To register a plug-in, click Register.
  7. Set the plug-in name and plug-in class name. The class name is, the path to the implementing Java class. If this class is part of a package, include the package name. For example, to register a class named customMapper in a package named com.customplugins, the name is com.customplugins.customMapper.

Chapter 9. Authentication for Enrolling Certificates

This chapter covers how to enroll end entity certificates, how to create and manage server certificates, the authentication methods available in the Certificate System to use when enrolling end entity certificates, and how to set up those authentication methods.
Enrollment is the process of issuing certificates to an end entity. The process is creating and submitting the request, authenticating the user requesting it, and then approving the request and issuing the certificate.
The method used to authenticate the end entity determines the entire enrollment process. There are three ways that the Certificate System can authenticate an entity:
  • In agent-approved enrollment, end-entity requests are sent to an agent for approval. The agent approves the certificate request.
  • In automatic enrollment, end-entity requests are authenticated using a plug-in, and then the certificate request is processed; an agent is not involved in the enrollment process.
  • In CMC enrollment, a third party application can create a request that is signed by an agent and then automatically processed.
A Certificate Manager is initially configured for agent-approved enrollment and for CMC authentication. Automated enrollment is enabled by configuring one of the authentication plug-in modules. More than one authentication method can be configured in a single instance of a subsystem.

NOTE

An email can be automatically sent to an end entity when the certificate is issued for any authentication method by configuring automated notifications. See Chapter 10, Using Automated Notifications for more information on notifications.

9.1. Configuring Agent-Approved Enrollment

The Certificate Manager is initially configured for agent-approved enrollment. An end entity makes a request which is sent to the agent queue for an agent's approval. An agent can modify request, change the status of the request, reject the request, or approve the request. Once the request is approved, the signed request is sent to the Certificate Manager for processing. The Certificate Manager processes the request and issues the certificate.
The agent-approved enrollment method is not configurable. If a Certificate Manager is not configured for any other enrollment method, the server automatically sends all certificate-related requests to a queue where they await agent approval. This ensures that all requests that lack authentication credentials are sent to the request queue for agent approval.
To use agent-approved enrollment, leave the authentication method blank in the profile's .cfg file. For example:
auth.instance_id=

9.2. Automated Enrollment

In automated enrollment, an end-entity enrollment request is processed as soon as the user successfully authenticates by the method set in the authentication plug-in module; no agent approval is necessary. The following authentication plug-in modules are provided:
  • Directory-based enrollment. End entities are authenticated against an LDAP directory using their user ID and password or their DN and password. See Section 9.2.1, “Setting up Directory-Based Authentication”.
  • PIN-based enrollment. End entities are authenticated against an LDAP directory using their user ID, password, and a PIN set in their directory entry. See Section 9.2.2, “Setting up PIN-Based Enrollment”.
  • Certificate-based authentication. Entities of some kind — both end users and other entities, like servers or tokens — are authenticated to the CA using a certificate issued by the CA which proves their identity. This is most commonly used for renewal, where the original certificate is presented to authenticate the renewal process. See Section 9.2.3, “Using Certificate-Based Authentication”.
  • AgentCertAuth. This method automatically approves a certificate request if the entity submitting the request is authenticated as a subsystem agent. A user authenticates as an agent by presenting an agent certificate. If the presented certificate is recognized by the subsystem as an agent certificate, then the CA automatically processes the certificate request.
    This form of automatic authentication can be associated with the certificate profile for enrolling for server certificates.
    This plug-in is enabled by default and has no parameters.
  • Flat file-based enrollment. Used exclusively for router (SCEP) enrollments, a text file is used which contains a list of IP addresses, hostnames, or other identifier and a password, which is usually a random PIN. A router authenticates to the CA using its ID and PIN, and then the CA compares the presented credentials to the list of identities in the text file. See Section 9.2.4, “Configuring Flat File Authentication”.
  • raCertAuth. This is similar to agent-approved authentication because, in fact, the RA agent has already approved the certificate request. The RA then submits the approved certificate request to the CA; the RA essentially is authenticated as a CA agent, so the request submitted by the RA subsystem is automatically approved.

9.2.1. Setting up Directory-Based Authentication

The UidPwdDirAuth and the UdnPwdDirAuth plug-in modules implement directory-based authentication. End users enroll for a certificate by providing their user IDs or DN and password to authenticate to an LDAP directory.
  1. Create an instance of either the UidPwdDirAuth or UdnPwdDirAuth authentication plug-in module and configure the instance.
    1. Open the CA Console.
      pkiconsole https://server.example.com:9445/ca
    2. In the Configuration tab, select Authentication in the navigation tree.
      The right pane shows the Authentication Instance tab, which lists the currently configured authentication instances.

      NOTE

      The UidPwdDirAuth plug-in is enabled by default.
    3. Click Add.
      The Select Authentication Plug-in Implementation window appears.
    4. Select UidPwdDirAuth for user ID and password authentication, or select UdnPwdDirAuth for DN and password authentication.
    5. Fill in the following fields in the Authentication Instance Editor window:
      • Authentication Instance ID. Accept the default instance name, or enter a new name.
      • dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.
      • ldapStringAttributes. Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes are copied from the authentication directory into the authentication token and used by the certificate profile to generate the subject name. Entering values for this parameter is optional.
      • ldapByteAttributes. Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules, such as adding additional information to users' certificates.
        Entering values for this parameter is optional.
      • ldap.ldapconn.host. Specifies the fully-qualified DNS hostname of the authentication directory.
      • ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests; if the ldap.ldapconn.secureConn. checkbox is selected, this should be the SSL port number.
      • ldap.ldapconn.secureConn. Specifies the type, SSL or non-SSL, of the port on which the authentication directory listens to requests from the Certificate System. Select if this is an SSL port.
      • ldap.ldapconn.version. Specifies the LDAP protocol version, either 2 or 3. The default is 3, since all Directory Servers later than version 3.x are LDAPv3.
      • ldap.basedn. Specifies the base DN for searching the authentication directory. The server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.
      • ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory. The permissible values are 1 to 3.
      • ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory. The permissible values are 3 to 10.
    6. Click OK. The authentication instance is set up and enabled.
  2. Set the certificate profiles to use to enroll users by setting policies for specific certificates. Customize the enrollment forms by configuring the inputs in the certificate profiles, and include inputs for the information needed by the plug-in to authenticate the user. If the default inputs do not contain all of the information that needs to be collected, submit a request created with a third-party tool.

9.2.2. Setting up PIN-Based Enrollment

PIN-based authentication involves setting up PINs for each user in the LDAP directory, distributing those PINs to the users, and then having the users provide the PIN along with their user ID and password when filling out a certificate request. Users are then authenticated both against an LDAP directory using their user ID and password and against the PIN in their LDAP entry. When the user successfully authenticates, the request is automatically processed, and a new certificate is issued.
The Certificate System provides a tool, setpin, that adds the necessary schema for PINs to the Directory Server and generates the PINs for each user.
The PIN tool performs the following functions:
  • Adds the necessary schema for PINs to the LDAP directory.
  • Adds a PIN manager user who has read-write permissions to the PINs that are set up.
  • Sets up ACIs to allow for PIN removal once the PIN has been used, giving read-write permissions for PINs to the PIN manager, and preventing users from creating or changing PINs.
  • Creates PINs in each user entry.

NOTE

This tool is documented in the Certificate System Command-Line Tools Guide.
  1. Use the PIN tool to add schema needed for PINs, add PINs to the user entries, and then distribute the PINs to users.
    1. Open the /usr/lib/pki/native-tools directory.
    2. Open the setpin.conf file in a text editor.
    3. Follow the instructions outlined in the file and make the appropriate changes.
      Usually, the parameters which need updated are the Directory Server's host name, Directory Manager's bind password, and PIN manager's password.
    4. Run the setpin command with its optfile option pointing to the setpin.conf file.
      setpin optfile=/usr/lib/pki/native-tools/setpin.conf
      The tool modifies the schema with a new attribute (by default, pin) and a new object class (by default, pinPerson), creates a pinmanager user, and sets the ACI to allow only the pinmanager user to modify the pin attribute.
    5. To generate PINs for specific user entries or to provide user-defined PINs, add these PINs using an input file. For information on constructing an input file, see the PIN generator chapter in the Certificate System Command-Line Tools Guide.
    6. Run the setpin command to create hashed PINs in the directory.
      Run the tool first without the write option to generate a list of PINs without actually changing the directory.
      For example:
      setpin host=yourhost port=9446 length=11 input=infile output=outfile write "binddn=cn=pinmanager,o=example.com" bindpw="password" basedn=o=example.com "filter=(uid=u*)"
    7. Use the output file for delivering PINs to users after completing setting up the required authentication method.
      After confirming that the PIN-based enrollment works, deliver the PINs to users so they can use them during enrollment. To protect the privacy of PINs, use a secure, out-of-band delivery method.
  2. Set the policies for specific certificates in the certificate profiles to enroll users. See Chapter 2, Making Rules for Issuing Certificates for information about certificate profile policies.
  3. Create and configure an instance of the UidPwdPinDirAuth authentication plug-in.
    1. Open the CA Console.
      pkiconsole https://server.example.com:9445/ca
    2. In the Configuration tab, select Authentication in the navigation tree.
      The right pane shows the Authentication Instance tab, which lists the currently configured authentication instances.
    3. Click Add.
      The Select Authentication Plug-in Implementation window appears.
    4. Select the UidPwdPinDirAuth plug-in module.
    5. Fill in the following fields in the Authentication Instance Editor window:
      • Authentication Instance ID. Accept the default instance name or enter a new name.
      • removePin. Sets whether to remove PINs from the authentication directory after end users successfully authenticate. Removing PINs from the directory restricts users from enrolling more than once, and thus prevents them from getting more than one certificate.
      • pinAttr. Specifies the authentication directory attribute for PINs. The PIN Generator utility sets the attribute to the value of the objectclass parameter in the setpin.conf file; the default value for this parameter is pin.
      • dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.
      • ldapStringAttributes. Specifies the list of LDAP string attributes that should be considered authentic for the end entity. Entering values for this parameter is optional.
      • ldapByteAttributes. Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules, such as adding additional information to users' certificates.
        Entering values for this parameter is optional.
      • ldap.ldapconn.host. Specifies the fully-qualified DNS host name of the authentication directory.
      • ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests from the Certificate System.
      • ldap.ldapconn.secureConn. Specifies the type, SSL or non-SSL, of the port on which the authentication directory listens to requests. Select if this is an SSL port.
      • ldap.ldapconn.version. Specifies the LDAP protocol version, either 2 or 3. By default, this is 3, since all Directory Server versions later than 3.x are LDAPv3.
      • ldap.ldapAuthentication.bindDN. Specifies the user entry as whom to bind when removing PINs from the authentication directory. Specify this parameter only if the removePin checkbox is selected. It is recommended that a separate user entry that has permission to modify only the PIN attribute in the directory be created and used. For example, do not use the Directory Manager's entry because it has privileges to modify the entire directory content.
      • password. Gives the password associated with the DN specified by the ldap.ldapauthbindDN parameter. When saving changes, the server stores the password in the single sign-on password cache and uses it for subsequent start ups. This parameter needs set only if the removePin checkbox is selected.
      • ldap.ldapAuthentication.clientCertNickname. Specifies the nickname of the certificate to use for SSL client authentication to the authentication directory to remove PINs. Make sure that the certificate is valid and has been signed by a CA that is trusted in the authentication directory's certificate database and that the authentication directory's certmap.conf file has been configured to map the certificate correctly to a DN in the directory. This is needed for PIN removal only.
      • ldap.ldapAuthentication.authtype. Specifies the authentication type, basic authentication or SSL client authentication, required in order to remove PINs from the authentication directory.
        • BasicAuth specifies basic authentication. With this option, enter the correct values for ldap.ldapAuthentication.bindDN and password parameters; the server uses the DN from the ldap.ldapAuthentication.bindDN attribute to bind to the directory.
        • SslClientAuth specifies SSL client authentication. With this option, set the value of the ldap.ldapconn.secureConn parameter to true and the value of the ldap.ldapAuthentication.clientCertNickname parameter to the nickname of the certificate to use for SSL client authentication.
      • ldap.basedn. Specifies the base DN for searching the authentication directory; the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.
      • ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory. The permissible values are 1 to 3.
      • ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory. The permissible values are 3 to 10.
    6. Click OK.
  4. Customize the enrollment forms by configuring the inputs in the certificate profiles. Include the information that will be needed by the plug-in to authenticate the user. If the default inputs do not contain all of the information that needs to be collected, submit a request created with a third-party tool.

9.2.3. Using Certificate-Based Authentication

Certificate-based authentication is when a certificate is presented that verifies the identity of the requester and automatically validates and authenticates the request being submitted. This is most commonly used for renewal processes, when the original certificate is presented by the user, server, and application and that certificate is used to authenticate the request, as illustrated in Example 4.4, “Certificate-Based Renewal Profile”.
There are other circumstances when it may be useful to use certificate-based authentication for initially requesting a certificate. For example, tokens may be bulk-loaded with generic certificates which are then used to authenticate the users when they enroll for their user certificates or, alternatively, users can be issued signing certificates which they then use to authenticate their requests for encryption certificates.
The certificate-based authentication module, SSLclientCertAuth, is enabled by default, and this authentication method can be referenced in any custom certificate profile.

9.2.4. Configuring Flat File Authentication

A router certificate is enrolled and authenticated using a randomly-generated PIN. This PIN is recognized already by the RA, so submitting a router request to the RA is automatically approved.
It is also possible for a router to submit a certificate request directly to the CA. In that case, the CA uses the flatFileAuth authentication module to process a text file which contains the router's authentication credentials.

9.2.4.1. Configuring the flatFileAuth Module

Flat file authentication is already configured for SCEP enrollments, but the location of the flat file and its authentication parameters can be edited.
  1. Open the CA Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Authentication in the navigation tree.
  3. Select the flatFileAuth authentication module.
  4. Click Edit/View.
  5. To change the file location and name, reset the fileName field.
    To change the authentication name parameter, reset the keyAttributes value to another value submitted in the SCEP enrollment form, like CN. It is also possible to use multiple name parameters by separating them by commas, like UID,CN. To change the password parameter name, reset the authAttributes field.
  6. Save the edits.

9.2.4.2. Editing flatfile.txt

The same flatfile.txt file is used to authenticate every SCEP enrollment. This file must be manually updated every time a new PIN is issued to a router, assuming that the router contacts the CA directly.
By default, this file is in /var/lib/pki-ca/conf/ and specifies two parameters per authentication entry, the UID of the site (usually its IP address, either IPv4 or IPv6) and the random PIN generated by the RA.
UID:192.168.123.123
PIN:HU89dj
Each entry must be followed by a blank line. For example:
UID:192.168.123.123
PIN:HU89dj

UID:12.255.80.13
PIN:fiowIO89

UID:0.100.0.100
PIN:GRIOjisf
If the authentication entries are not separated by an empty line, then when the router attempts to authenticate to the CA, it will fail. For example:
... flatfile.txt entry ...
UID:192.168.123.123
PIN:HU89dj
UID:12.255.80.13
PIN:fiowIO89

... error log entry ...
[13/Jun/2009:13:03:09][http-9180-Processor24]: FlatFileAuth: authenticating user: finding user from key: 192.168.123.123
[13/Jun/2009:13:03:09][http-9180-Processor24]: FlatFileAuth: User not found in password file.

9.3. Setting up CMC Enrollment

CMC enrollment sets up an enrollment client, signs the certificate request with an agent certificate, and then sends the signed request to the Certificate Manager. When this method is set up, the Certificate Manager automatically issues certificates when a valid request signed with the agent certificate is received.
The CMCAuth authentication plug-in also activates CMC revocation. CMC revocation sets up a revocation client, signs the request with the agent certificate, and then sends the signed request to the Certificate Manager. When this method is set up, the Certificate Manager automatically revokes certificates when a valid request signed with the agent certificate is received.
To set up CMC enrollment:
  1. Set up the certificate profile to use to enroll users by setting policies for specific certificates in the certificate profile. See Chapter 2, Making Rules for Issuing Certificates for information about profile policies.
  2. If necessary, set up the CMCAuth authentication plug-in. An instance of this plug-in module is created and enabled by default. It has no configuration parameters. When the instance is enabled, CMC enrollment and CMC revocation are both enabled for the server.
    1. Open the CA Console.
      pkiconsole https://server.example.com:9445/ca
    2. In the Configuration tab, select Authentication in the navigation tree.
      The right pane shows the Authentication Instance tab listing currently configured authentication instances.
    3. Click Add.
      The Select Authentication Plug-in Implementation window appears.
    4. Select the CMCAuth plug-in module.
    5. In the Authentication Instance ID field, type a unique name for this instance that will identify it if the default name is not to be used.
      There are no configuration options for this plug-in; it simply enables this functionality.
    6. Click OK. The authentication instance is now set up and enabled.
  3. Use the CMCEnroll utility to sign certificate requests with the agent certificate.
    This utility has the following syntax:
    CMCEnroll -d /certificate/directory -h password
       -n cert_nickname -r certrequest.file -p certDB_passwd [-c]
    

    Table 9.1. CMCEnroll Usage Options

    Parameter Description
    d
    The location of the directory containing the cert8.db, key3.db, and secmod.db files associated with the agent certificate.
    h Password to the database specified in the d option.
    n The common name of the certificate.
    r The filename of the certificate request.
    p The password to the browser certificate database.
    c Optional. Includes a comment about the request.

    NOTE

    Surround values that include spaces in quotation marks.

9.3.1. Setting up the Server for Multiple Requests in a Full CMC Request

CMC supports multiple CRMF or PKCS #10 requests in a single full CMC request. If the numRequests parameter in the .cfg file is larger than 1, modify the server's certificate profile by doing the following:
  1. By default, the servlet processing a full CMC request uses the caFullCMCUserCert profile. This profile only handles a single request.
  2. To use the new profile instead of the default, modify the web.xml file in the /var/lib/pki-ca/webapps/WEB-INF/ directory. Locate the servlet which processes the full CMC request; by default, this is /ca/profileSubmitCMCFull. Change the value for the profileID parameter to the name of the new profiles.

    NOTE

    To modify the profile for the end-user services, edit the profiles in the /var/lib/pki-ca/webapps directory. If the services are not separated, edit the profiles in the /var/lib/pki-ca/webapps (agent services) directory.
    For information on creating a new profile, see Chapter 2, Making Rules for Issuing Certificates.
  3. Restart the server.
    service pki-ca restart

9.3.2. Testing CMCEnroll

  1. Enable CMCEnroll.
  2. Create a certificate request using the certutil tool.
  3. Copy the PKCS #10 ASCII output to a text file.
  4. Run the CMCEnroll utility.
    For example, if the input file called request34.txt, the agent certificate is stored in the directory /var/lib/pki-ca/alias, the certificate common name of the agent certificate is CertificateManagerAgentsCert, and the password for the certificate database is secret, the command is as follows:
    CMCEnroll -d "/var/lib/pki-ca/alias" -n "CertificateManagerAgentsCert" -r /export/requests/request34.txt -p secret
    The output of this command is stored in a file with the same filename with .out appended to the filename.
  5. Submit the signed certificate through the end-entities page.
    1. Open the end-entities page.
      https://server.example.com:9444/ca/ee/ca
    2. Select the CMC enrollment form from the list of certificate profiles.
    3. Paste the content of the output file into the Certificate Request text area of this form.
    4. Remove -----BEGIN NEW CERTIFICATE REQUEST----- and ----END NEW CERTIFICATE REQUEST----- from the pasted content.
    5. Fill in the contact information, and submit the form.
  6. The certificate is immediately processed and returned.
  7. Use the agent page to search for the new certificate.

9.4. Testing Enrollment

For information on testing enrollment through the profiles, see Chapter 2, Making Rules for Issuing Certificates. To test whether end users can successfully enroll for a certificate using the authentication method set:
  1. Open the end-entities page.
    https://server.example.com:9444/ca/ee/ca
  2. In the Enrollment tab, open the customized enrollment form.
  3. Fill in the values, and submit the request.
  4. Enter the password to the key database when prompted.
  5. When the correct password is entered, the client generates the key pair.
    Do not interrupt the key-generation process. Upon completion of the key generation, the request is submitted to the server to issue the certificate. The server subjects the request to the certificate profile and issues the certificate only if the request meets all the requirements.
    When the certificate is issued, install the certificate in the browser.
  6. Verify that the certificate is installed in the browser's certificate database.
  7. If directory- or PIN-based authentication was configured with PIN removal, re-enroll for another certificate using the same PIN. The request should be rejected.

9.5. Managing Authentication Plug-ins

Custom authentication plug-in modules can be registered through the CA Console. Authentication plug-in modules can also be deleted through the CA Console. Before deleting a module, delete instances that are based on that module.
  1. Log into the console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, click Authentication in the navigation tree
  3. In the right pane, click the Authentication Plug-in Registration tab.
    The tab lists modules that are already registered.
  4. To delete a registered module, select that module, and click Delete.
  5. To register a plug-in, click Register.
    The Register Authentication Plug-in Implementation window appears.
  6. Specify which module to register by filling in the two fields:
    • Plugin name. The name for the module.
    • Class name. The full name of the class for this module. This is the path to the implementing Java™ class. If this class is part of a package, include the package name. For example, to register a class named customAuth in a package named com.customplugins, the class name is com.customplugins.customAuth.
  7. Click OK.

Chapter 10. Using Automated Notifications

The Certificate System can be configured to send automatic email notifications to end users when certificates are issued or revoked or to an agent when a new request has arrived in the agent request queue. This chapter describes automated notifications and details how to enable, configure, and customize the notification email messages that are sent.

NOTE

Because of the types of notifications that can be sent, only Certificate Managers have the ability to be configured for notifications; this option is not available on the other subsystems.

10.1. About Automated Notifications for the CA

Automated notifications are email messages sent when a specified event occurs. The system uses listeners that monitor the system to determine when a particular event has occurred; when the event happens, then the system is triggered to send an email to the configured recipient. Each type of notification uses a template, either in plain text or HTML, to construct the notification message. The template contains text and tokens that are expanded to fill in the correct information for a particular event. The messages can be customized by changing the text and tokens contained in the templates. The HTML templates can also be customized for different appearances and formatting.

10.1.1. Types of Automated Notifications

There are three types of automated notifications:
  • Certificate Issued.
    A notification message is automatically sent to users who have been issued certificates. A rejection message is sent to a user if the user's certificate request is rejected.
  • Certificate Revocation.
    A notification message is automatically sent to users when the user certificate is revoked.
  • Request in Queue.
    A notification message is automatically sent to one or more agents when a request enters the agent request queue, using the email addresses set for the agent. This notification type sends an email every time a message enters the queue. For more information about the request in queue job, see Section 11.1.2.2, “requestInQueueNotifier”.
    There is also a job that sends a notification to agents about the status of the queue, which includes a summary of the queue status at certain intervals.

10.1.2. Determining End-Entity Email Addresses

The notification system determines the email address of an end entity by checking first the certificate request or revocation request, then the subject name of the certificate, and last the Subject Alternative Name extension of the certificate, if the certificate contains this extension. If an email address cannot be found, the notification is sent to the email address specified in the Sender's Email Address field of the Notification panel.

10.1.3. About RA Notifications

The notifications covered in this chapter are for operations that occur on the CA. The RA subsystem, however, also provides a method to send notifications to agents (or users) for certificate operations. These RA notifications are configured, by default, as part of the RA profile. There are two types of events that can trigger a notification:
  • A new request is submitted or created (sent to agents)
  • A request is accepted (sent to users)
The RA can send notifications to an agent whenever a request is submitted, if it is configured in the RA profile. These RA notifications are sent to members of the specified RA group, such as the default agents group.
request.user.create_request.1.assignTo=agents
request.user.create_request.1.plugin=PKI::Request::Plugin::AutoAssign
request.user.create_request.1.mailTo=
request.user.create_request.1.plugin=PKI::Request::Plugin::EmailNotification
Other RA notifications alert the requester to indicate whether the request was approved or rejected.
request.user.approve_request.1.mailTo=$created_by
request.user.approve_request.1.plugin=PKI::Request::Plugin::EmailNotification
Configuring notifications as part of RA enrollment profiles is covered in Section 2.3.3, “Configuring the Request Queues”.

10.2. Setting up Automated Notifications for the CA

10.2.1. Setting up Automated Notifications in the Console

  1. Open the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. Open the Configuration tab.
  3. Open the Certificate Manager heading in the navigation tree on the left. Then select Notification.
    The Notification tabs appear in the right side of the window.
  4. Notifications can be sent for three kinds of events: newly-issued certificates, revoked certificates, and new certificate requests. To send a notification for any event, select the tab, check the Enable checkbox, and specify information in the following fields:
    • Sender's E-mail Address. Type the sender's full email address of the user who is notified of any delivery problems.
    • Recipient's E-mail Address. These are the email addresses of the agents who will check the queue. To list more than one recipient, separate the email addresses with commas. For new requests in queue only.
    • Subject. Type the subject title for the notification.
    • Content template path. Type the path, including the filename, to the directory that contains the template to use to construct the message content.
  5. Click Save.

    NOTE

  6. Customize the notification message templates. See Section 10.3, “Customizing Notification Messages” for more information.
  7. Test the configuration. See Section 10.2.3, “Testing Configuration”.

10.2.2. Configuring Specific Notifications by Editing the CS.cfg File

  1. Stop the CA subsystem.
    service pki-ca stop
  2. Open the CS.cfg file for that instance. This file is in the instance's conf/ directory.
  3. Edit all of the configuration parameters for the notification type being enabled.
    For certificate issuing notifications, there are four parameters:
    ca.notification.certIssued.emailSubject
    ca.notification.certIssued.emailTemplate
    ca.notification.certIssued.enabled
    ca.notification.certIssued.senderEmail
    
    For certificate revocation notifications, there are four parameters:
    ca.notification.certRevoked.emailSubject
    ca.notification.certRevoked.emailTemplate
    ca.notification.certRevoked.enabled
    ca.notification.certRevoked.senderEmail
    
    For certificate request notifications, there are five parameters:
    ca.notification.requestInQ.emailSubject
    ca.notification.requestInQ.emailTemplate
    ca.notification.requestInQ.enabled
    ca.notification.requestInQ.recipientEmail
    ca.notification.requestInQ.senderEmail
    
    The parameters for the notification messages are explained in Section 10.2, “Setting up Automated Notifications for the CA”.
  4. Save the file.
  5. Restart the CA instance.
    service pki-ca start
  6. If a job has been created to send automated messages, check that the mail server is correctly configured. See Section 10.4, “Configuring a Mail Server for Certificate System Notifications”.
  7. The messages that are sent automatically can be customized; see Section 10.3, “Customizing Notification Messages” for more information.

10.2.3. Testing Configuration

To test whether the subsystem sends email notifications as configured, do the following:
  1. Change the email address in the notification configuration for the request in queue notification to an accessible agent or administrator email address.
  2. Open the end-entities page, and request a certificate using the agent-approved enrollment form.
    When the request gets queued for agent approval, a request-in-queue email notification should be sent. Check the message to see if it contains the configured information.
  3. Log into the agent interface, and approve the request.
    When the server issues a certificate, the user receive a certificate-issued email notification to the address listed in the request. Check the message to see if it has the correct information.
  4. Log into the agent interface, and revoke the certificate.
    The user email account should contain an email message reading that the certificate has been revoked. Check the message to see if it has the correct information.

10.3. Customizing Notification Messages

The email notifications are constructed using a template for each type of message. This allows messages to be informative, easily reproducible, and easily customizeable. Both the CA and the RA use templates for their notification messages. The CA uses a template pair, for HTML and plain text messages. The RA uses .vb files.

10.3.1. Customizing CA Notification Messages

Each type of CA notification message has an HTML template and a plain text template associated with it. Messages are constructed from text, tokens, and, for the HTML templates, HTML markup. Tokens are variables, identified by a dollar sign ($), in the message that are replaced by the current value when the message is constructed. See Table 10.3, “Notification Variables” for a list of available tokens.
The contents of any message type can be modified by changing the text and tokens in the message template. The appearance of the HTML messages can be changed by modifying the HTML commands in the HTML message template.
The default text version of the certificate-issuance-notification message is as follows:
Your certificate request has been processed successfully.
SubjectDN= $SubjectDN
IssuerDN= $IssuerDN
notAfter= $NotAfter
notBefore= $NotBefore
Serial Number= 0x$HexSerialNumber
To get your certificate, please follow this URL:
https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&
 serialNumber=$SerialNumber
Please contact your admin if there is any problem.
And, of course, this is just a \$SAMPLE\$ email notification form.
This template can be customized as desired, by rearranging, adding, or removing tokens and text, as shown:
THE EXAMPLE COMPANY CERTIFICATE ISSUANCE CENTER 
Your certificate has been issued!
You can pick up your new certificate at the following website:
https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&
 serialNumber=$SerialNumber
This certificate has been issued with the following information:
Serial Number= 0x$HexSerialNumber
Name of Certificate Holder = $SubjectDN
Name of Issuer = $IssuerDN
Certificate Expiration Date = $NotAfter
Certificate Validity Date = $NotBefore
Contact IT by calling X1234, or going to the IT website http://IT
 if you have any problems.
Notification message templates are located in the /var/lib/pki-ca/emails directory.
The name and location of these messages can be changed; make the appropriate changes when configuring the notification. All template names can be changed except for the certificate rejected templates; these names must remain the same. The templates associated with certificate issuance and certificate rejection must be located in the same directory and must use the same extension.
Table 10.1, “Notification Templates” lists the default template files provided for creating notification messages. Table 10.2, “Job Notification Email Templates” lists the default template files provided for creating job summary messages.

Table 10.1. Notification Templates

Filename Description
certIssued_CA Template for plain text notification emails to end entities when certificates are issued.
certIssued_CA.html Template for HTML-based notification emails to end entities when certificates are issued.
certRequestRejected.html Template for HTML-based notification emails to end entities when certificate requests are rejected.
certRequestRevoked_CA Template for plain text notification emails to end entities when a certificate is revoked.
certRequestRevoked_CA.html Template for HTML-based notification emails to end entities when a certificate is revoked.
reqInQueue_CA Template for plain text notification emails to agents when a request enters the queue.
reqInQueue_CA.html Template for HTML-based notification emails to agents when a request enters the queue.

Table 10.2. Job Notification Email Templates

Filename Description
rnJob1.txt Template for formulating the message content sent to end entities to inform them that their certificates are about to expire and that the certificates should be renewed or replaced before they expire.
rnJob1Summary.txt
Template for constructing the summary report to be sent to agents and administrators. Uses the rnJob1Item.txt template to format items in the message.
rnJob1Item.txt Template for formatting the items included in the summary report.
riq1Item.html Template for formatting the items included in the summary table, which is constructed using the riq1Summary.html template.
riq1Summary.html
Template for formulating the report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager.
publishCerts
Template for the report or table that summarizes the certificates to be published to the directory. Uses the publishCertsItem.html template to format the items in the table.
publishCertsItem.html
Template for formatting the items included in the summary table.
ExpiredUnpublishJob
Template for the report or table that summarizes removal of expired certificates from the directory. Uses the ExpiredUnpublishJobItem template to format the items in the table.
ExpiredUnpublishJobItem
Template for formatting the items included in the summary table.

Table 10.3, “Notification Variables” lists and defines the variables that can be used in the notification message templates.

Table 10.3. Notification Variables

Token Description
$CertType
Specifies the type of certificate; these can be any of the following:
  • SSL client (client)
  • SSL server (server)
  • CA signing certificate (ca)
  • other (other).
$ExecutionTime Gives the time the job was run.
$HexSerialNumber Gives the serial number of the certificate that was issued in hexadecimal format.
$HttpHost Gives the fully qualified host name of the Certificate Manager to which end entities should connect to retrieve their certificates.
$HttpPort Gives the Certificate Manager's end-entities (non-SSL) port number.
$InstanceID
Gives the ID of the subsystem that sent the notification.
$IssuerDN Gives the DN of the CA that issued the certificate.
$NotAfter Gives the end date of the validity period.
$NotBefore Gives the beginning date of the validity period.
$RecipientEmail Gives the email address of the recipient.
$RequestId Gives the request ID.
$RequestorEmail Gives the email address of the requester.
$RequestType Gives the type of request that was made.
$RevocationDate Gives the date the certificate was revoked.
$SenderEmail Gives the email address of the sender; this is the same as the one specified in the Sender's E-mail Address field in the notification configuration.
$SerialNumber Gives the serial number of the certificate that has been issued; the serial number is displayed as a hexadecimal value in the resulting message.
$Status Gives the request status.
$SubjectDN Gives the DN of the certificate subject.
$SummaryItemList Lists the items in the summary notification. Each item corresponds to a certificate the job detects for renewal or removal from the publishing directory.
$SummaryTotalFailure Gives the total number of items in the summary report that failed.
$SummaryTotalNum Gives the total number of certificate requests that are pending in the queue or the total number of certificates to be renewed or removed from the directory in the summary report.
$SummaryTotalSuccess Shows how many of the total number of items in the summary report succeeded.

10.3.2. Customizing RA Notification Messages

As with CA notification messages, the body of the RA notification templates is comprised of text and variable tokens (prefaced by a dollar sign, $). (These RA tokens are listed in Table 10.4, “RA Notification Message Tokens”.)
Unlike CA notification messages, which have both HTML and plain notification templates, the RA notifications are only configured in plain text.
There are two email notification templates for RA events:
  • mail_create_request.vm, which is sent to agents when a request is created
  • mail_approve_request.vm, which is sent to the requester when a request is approved
The contents of any message can be modified by changing the text and tokens in the message template.

Example 10.1. Default Approved Request Notification for an RA

Reply-to: $mail_to
Subject: Request #$request_id approved
To: $mail_to
Content-type: text/plain\n\n
Request #$request_id has been approved
for
Subject DN: $subject_dn

Import certificate at:
https://$machineName:$nonClientAuthSecurePort/ee/request/getcert.cgi?id=$request_id

The text can be revised or additional tokens added to provide additional information about the event.

Example 10.2. Custom Approved Request Notification for an RA

Reply-to: $mail_to
Subject: Your certificate request, ID #$request_id, has been approved
To: $mail_to
Content-type: text/plain\n\n

Certificate request #$request_id, with the subject name $subject_dn for $uid, has been approved. This 
certificate can be imported by clicking the following link:
https://$machineName:$nonClientAuthSecurePort/ee/request/getcert.cgi?id=$request_id

The available notification message tokens are listed in Table 10.4, “RA Notification Message Tokens”.

Table 10.4. RA Notification Message Tokens

Token Description
created_by The email given by the requester when the request was submitted.
machineName The hostname of the server for the RA instance.
mail_to The value of the request.profile_name.approve_request.1.mailTo. Notification emails are sent to this address.
nonClientAuthSecurePort The secure end-entities port number for the RA, which uses SSL but does not require client-based authentication.
request_id The request ID number for the submitted certificate request. This is used to identify and access both the initial request and the issued certificate (if the request is approved).
site_id The IP address of a site or network, usually for a router. This is usually used for generated PINs.
subject_dn The subject name or subject DN of the issued certificate.
uid The UID of the requester for the certificate. This is usually used for generated PINs, such as with requesting agent certificates.

10.4. Configuring a Mail Server for Certificate System Notifications

The notifications and jobs features use the mail server configured in the Certificate System CA instances to send notification messages. Set up a mail server by doing the following:
  1. Open the CA subsystem administrative console. For example:
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, highlight the instance name at the top, and select the SMTP tab.
  3. Supply the server name and port number of the mail server.
    The server name is the fully qualified DNS hostname of the machine on which the mail server is installed, such as mail.example.com. By default, the hostname of the mail server is localhost instead of the actual hostname.
    The default port number on which the SMTP mail server listens is 25.
  4. Click Save.

10.5. Creating Custom Notifications for the CA

It can be possible to create custom notification functions to handle other PKI operations, such as token enrollments, by editing existing email notifications plug-ins for the Certificate System CA. Before attempting to create or use custom notification plug-ins, contact Red Hat support services.

Chapter 11. Setting Automated Jobs

The Certificate System provides a customizable Job Scheduler that supports various mechanisms for scheduling cron jobs. This chapter explains how to configure Certificate System to use specific job plug-in modules for accomplishing jobs.

11.1. About Automated Jobs

The Certificate Manager Console includes a Job Scheduler option that can execute specific jobs at specified times. The Job Scheduler is similar to a traditional Unix cron daemon; it takes registered cron jobs and executes them at a pre-configured date and time. If configured, the scheduler checks at specified intervals for jobs waiting to be executed; if the specified execution time has arrived, the scheduler initiates the job automatically.
Jobs are implemented as Java™ classes, which are then registered with Certificate System as plug-in modules. One implementation of a job module can be used to configure multiple instances of the job. Each instance must have a unique name (an alphanumeric string with no spaces) and can contain different input parameter values to apply to different jobs.

11.1.1. Setting up Automated Jobs

The automated jobs feature is set up by doing the following:

11.1.2. Types of Automated Jobs

The types of automated jobs are certRenewalNotifier, requestInQueueNotifier, publishCerts, and unpublishExpiredCerts.

11.1.2.1. certRenewalNotifier

The certRenewalNotifier job checks for certificates that are about to expire in the internal database. When it finds one, it automatically emails the certificate's owner and continues sending email reminders for a configured period of time or until the certificate is replaced. The job collects a summary of all renewal notifications and mails the summary to the configured agents or administrators.
The job determines the email address to send the notification using an email resolver. By default, the email address is found in the certificate itself or in the certificate's associated enrollment request.

11.1.2.2. requestInQueueNotifier

The requestInQueueNotifier module checks the status of the request queue at pre-configured time intervals. If any deferred enrollment requests are waiting in the queue, the job constructs an email message summarizing its findings and sends it to the specified agents.

11.1.2.3. publishCerts

The publishCerts module checks for any new certificates that have been added to the publishing directory that have not yet been published. When these new certificates are added, they are automatically published to an LDAP directory or file by the publishCerts job.

NOTE

Most of the time, publishers immediately publish any certificates that are created matching their rules to the appropriate publishing directory.
If a certificate is successfully published when it is created, then the publishCerts job will not re-publish the certificate. Therefore, the new certificate will not be listed in the job summary report, since the summary only lists certificates published by the publishCerts job.

11.1.2.4. unpublishExpiredCerts

Expired certificates are not automatically removed from the publishing directory. If a Certificate Manager is configured to publish certificates to an LDAP directory, over time the directory will contain expired certificates.
The unpublishExpiredCerts job checks for certificates that have expired and are still marked as published in the internal database at the configured time interval. The job connects to the publishing directory and deletes those certificates; it then marks those certificates as unpublished in the internal database. The job collects a summary of expired certificates that it deleted and mails the summary to the agents or administrators specified by the configuration.

NOTE

This job automates removing expired certificates from the directory. Expired certificates can also be removed manually; for more information on this, see Section 8.7, “Updating Certificates and CRLs in a Directory”.

11.2. Setting up the Job Scheduler

The Certificate Manager can execute a job only if the Job Scheduler is enabled. The job settings, such as enabling the job schedule, setting the frequency, and enabling the job modules, can be done through the Certificate System CA Console or through editing the CS.cfg file.
To turn the Job Scheduler on:
  1. Open the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab navigation tree, click Job Scheduler.
    This opens the General Settings tab, which shows whether the Job Scheduler is currently enabled.
  3. Click the Enable Jobs Schedule checkbox to enable or disable the Job Scheduler.
    Disabling the Job Scheduler turns off all the jobs.
  4. Set the frequency which the scheduler checks for jobs in the Check Frequency field.
    The frequency is how often the Job Scheduler daemon thread wakes up and calls the configured jobs that meet the cron specification. By default, it is set to one minute.

    NOTE

    The window for entering this information may be too small to see the input. Drag the corners of the Certificate Manager Console to enlarge the entire window.
  5. Click Save.

11.3. Setting up Specific Jobs

Automated jobs can be configured through the Certificate Manager Console or by editing the configuration file directory. It is recommended that these changes be made through the Certificate Manager Console.

11.3.1. Configuring Specific Jobs Using the Certificate Manager Console

To enable and configure an automated job using the Certificate Manager Console:
  1. Open the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. Confirm that the Jobs Scheduler is enabled. See Section 11.2, “Setting up the Job Scheduler” for more information.
  3. In the Configuration tab, select Job Scheduler from the navigation tree. Then select Jobs to open the Job Instance tab.
    Select the job instance from the list, and click Edit/View.
    The Job Instance Editor opens, showing the current job configuration.
    Job Configuration

    Figure 11.1. Job Configuration


  4. Select enabled to turn on the job.
  5. Set the configuration settings by specifying them in the fields for this dialog.
  6. Click OK.
  7. Click Refresh to view any changes in the main window.
  8. If the job is configured to send automatic messages, check that a mail server is set up correctly. See Section 10.4, “Configuring a Mail Server for Certificate System Notifications”.
  9. Customize the email message text and appearance.

11.3.2. Configuring Jobs by Editing the Configuration File

  1. Ensure that the Jobs Scheduler is enabled and configured; see Section 11.2, “Setting up the Job Scheduler”.
  2. Stop the CA subsystem instance.
    service pki-ca stop
  3. Open the CS.cfg file for that server instance in a text editor.
  4. Edit all of the configuration parameters for the job module being configured.
  5. Save the file.
  6. Restart the server instance.
    service pki-ca start
  7. If the job will send automated messages, check that the mail server is set up correctly. See Section 10.4, “Configuring a Mail Server for Certificate System Notifications”.
  8. Customize the automatic job messages.

11.3.3. Configuration Parameters of certRenewalNotifier

Table 11.1, “certRenewalNotifier Parameters” gives details for each of these parameters that can be configured for the certRenewalNotifier job, either in the CS.cfg file or in the Certificate Manager Console.

Table 11.1. certRenewalNotifier Parameters

Parameter Description
enabled Specifies whether the job is enabled or disabled. The value true enables the job; false disables it.
cron
Sets the schedule when this job should be run. This sets the time at which the Job Scheduler daemon thread checks the certificates for sending renewal notifications. These settings must follow the conventions in Section 11.3.7, “Frequency Settings for Automated Jobs”. For example:
03**1-5
The job in the example is run Monday through Friday at 3:00 pm.
notifyTriggerOffset Sets how long (in days) before the certificate expiration date the first notification will be sent.
notifyEndOffset Sets how long (in days) after the certificate expires that notifications will continue to be sent if the certificate is not replaced.
senderEmail Sets the sender of the notification messages, who will be notified of any delivery problems.
emailSubject Sets the text of the subject line of the notification message.
emailTemplate Sets the path, including the filename, to the directory that contains the template to use to create the message content.
summary.enabled Sets whether a summary report of renewal notifications should be compiled and sent. The value true enables sending the summary; false disables it. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
summary.recipientEmail Specifies the recipients of the summary message. These can be agents who need to know the status of user certificates or other users. Set more than one recipient by separating each email address with a comma.
summary.senderEmail Specifies the email address of the sender of the summary message.
summary.emailSubject Gives the subject line of the summary message.
summary.itemTemplate Gives the path, including the filename, to the directory that contains the template to use to create the content and format of each item to be collected for the summary report.
summary.emailTemplate Gives the path, including the filename, to the directory that contains the template to use to create the summary report email notification.

11.3.4. Configuration Parameters of requestInQueueNotifier

Table 11.2, “requestInQueueNotifier Parameters” gives details for each of these parameters that can be configured for the requestInQueueNotifier job, either in the CS.cfg file or in the Certificate Manager Console.

Table 11.2. requestInQueueNotifier Parameters

Parameter Description
enabled Sets whether the job is enabled (true) or disabled (false).
cron
Sets the time schedule for when the job should run. This is the time at which the Job Scheduler daemon thread checks the queue for pending requests. This setting must follow the conventions in Section 11.3.7, “Frequency Settings for Automated Jobs”. For example:
00**0
subsystemid Specifies the subsystem which is running the job. The only possible value is ca, for the Certificate Manager.
summary.enabled Specifies whether a summary of the job accomplished should be compiled and sent. The value true enables the summary reports; false disables them. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
summary.emailSubject Sets the subject line of the summary message.
summary.emailTemplate Specifies the path, including the filename, to the directory containing the template to use to create the summary report.
summary.senderEmail Specifies the sender of the notification message, who will be notified of any delivery problems.
summary.recipientEmail Specifies the recipients of the summary message. These can be agents who need to process pending requests or other users. More than one recipient can be listed by separating each email address with a comma.

11.3.5. Configuration Parameters of publishCerts

Table 11.3, “publishCerts Parameters” gives details for each of these parameters that can be configured for the publishCerts job, either in the CS.cfg file or in the Certificate Manager Console.

Table 11.3. publishCerts Parameters

Parameter Description
enabled Sets whether the job is enabled. The value true is enabled; false is disabled.
cron
Sets the time schedule for when the job runs. This is the time the Job Scheduler daemon thread checks the certificates to removing expired certificates from the publishing directory. This setting must follow the conventions in Section 11.3.7, “Frequency Settings for Automated Jobs”. For example:
00**6
summary.enabled Specifies whether a summary of the certificates removed by the job should be compiled and sent. The value true enables the summaries; false disables them. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
summary.emailSubject Gives the subject line of the summary message.
summary.emailTemplate Specifies the path, including the filename, to the directory containing the template to use to create the summary report.
summary.itemTemplate Specifies the path, including the filename, to the directory containing the template to use to create the content and format of each item collected for the summary report.
summary.senderEmail Specifies the sender of the summary message, who will be notified of any delivery problems.
summary.recipientEmail Specifies the recipients of the summary message. These can be agents who need to know the status of user certificates or other users. More than one recipient can be set by separating each email address with a comma.

11.3.6. Configuration Parameters of unpublishExpiredCerts

Table 11.4, “unpublishExpiredCerts Parameters” gives details for each of these parameters that can be configured for the unpublishedExpiresCerts job, either in the CS.cfg file or in the Certificate Manager Console.

Table 11.4. unpublishExpiredCerts Parameters

Parameter Description
enabled Sets whether the job is enabled. The value true is enabled; false is disabled.
cron
Sets the time schedule for when the job runs. This is the time the Job Scheduler daemon thread checks the certificates to removing expired certificates from the publishing directory. This setting must follow the conventions in Section 11.3.7, “Frequency Settings for Automated Jobs”. For example:
00**6
summary.enabled Specifies whether a summary of the certificates removed by the job should be compiled and sent. The value true enables the summaries; false disables them. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
summary.emailSubject Gives the subject line of the summary message.
summary.emailTemplate Specifies the path, including the filename, to the directory containing the template to use to create the summary report.
summary.itemTemplate Specifies the path, including the filename, to the directory containing the template to use to create the content and format of each item collected for the summary report.
summary.senderEmail Specifies the sender of the summary message, who will be notified of any delivery problems.
summary.recipientEmail Specifies the recipients of the summary message. These can be agents who need to know the status of user certificates or other users. More than one recipient can be set by separating each email address with a comma.

11.3.7. Frequency Settings for Automated Jobs

The Job Scheduler uses a variation of the Unix crontab entry format to specify dates and times for checking the job queue and executing jobs. As shown in Table 11.5, “Time Values for Scheduling Jobs” and Figure 11.1, “Job Configuration”, the time entry format consists of five fields. (The sixth field specified for the Unix crontab is not used by the Job Scheduler.) Values are separated by spaces or tabs.
Each field can contain either a single integer or a pair of integers separated by a hyphen (-) to indicate an inclusive range. To specify all legal values, a field can contain an asterisk rather than an integer. Day fields can contain a comma-separated list of values. The syntax of this expression is
Minute Hour Day_of_month Month_of_year Day_of_week

Table 11.5. Time Values for Scheduling Jobs

Field Value
Minute 0-59
Hour 0-23
Day of month 1-31
Month of year 1-12
Day of week 0-6 (where 0=Sunday)

For example, the following time entry specifies every hour at 15 minutes (1:15, 2:15, 3:15, and so on):
15 * * * *
The following example sets a job to run at noon on April 12:
0 12 12 4 *
The day-of-month and day-of-week options can contain a comma-separated list of values to specify more than one day. If both day fields are specified, the specification is inclusive; that is, the day of the month is not required to fall on the day of the week to be valid. For example, the following entry specifies a job execution time of midnight on the first and fifteenth of every month and on every Monday:
0 0 1,15 * 1
To specify one day type without the other, use an asterisk in the other day field. For example, the following entry runs the job at 3:15 a.m. every weekday morning:
15 3 * * 1-5

11.4. Registering or Deleting a Job Module

Custom job plug-ins can be registered through the Certificate Manager Console. Registering a new module involves specifying the name of the module and the full name of the Java™ class that implements the module.
To register a new job module:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Job Scheduler in the left navigation tree. Select Jobs.
    The Job Instance tab opens, which lists any currently configured jobs. Select the Job Plugin Registration tab.
  3. Click Register to add the new module.
  4. In the Register Job Scheduler Plugin Implementation window, supply the following information:
    • Plugin name. Type a name for the plug-in module.
    • Class name. Type the full name of the class for this module; this is the path to the implementing Java™ class. If this class is part of a package, include the package name. For example, to register a class named customJob that is in a package named com.customplugins, type com.customplugins.customJob.
  5. Click OK.

NOTE

It is also possible to delete job modules, but this is not recommended.
If it is necessary to delete a module, open the Job Plugin Registration tab as when registering a new module, select the module to delete, and click Delete. When prompted, confirm the deletion.

Part III. Managing the Subsystem Instances

Table of Contents

12. Editing Configuration in the CS.cfg File
12.1. Default File and Directory Locations for Certificate System Subsystems
12.1.1. Default CA Instance Information
12.1.2. Default RA Instance Information
12.1.3. Default DRM Instance Information
12.1.4. Default OCSP Instance Information
12.1.5. Default TKS Instance Information
12.1.6. Default TPS Instance Information
12.1.7. Shared Certificate System Subsystem File Locations
12.2. CS.cfg Files
12.2.1. Locating the CS.cfg File
12.2.2. Overview of the CS.cfg Configuration File
12.2.3. Editing the Configuration File
12.3. System Passwords
12.3.1. Configuring the password.conf
12.3.2. Protecting the password.conf File
12.3.3. Requiring System Password Prompts
12.3.4. Changing System Passwords
12.3.5. Password-Quality Checker
12.4. Configuration Files for Web Services
13. Basic Subsystem Management
13.1. Starting and Stopping Subsystem Instances
13.1.1. Starting and Stopping a Subsystem Server Instance
13.1.2. Restarting a Subsystem after a Machine Restart
13.1.3. Checking the Subsystem Instance Status
13.1.4. Managing Subsystem Processes with chkconfig
13.2. Opening Subsystem Consoles and Services
13.2.1. Finding the Subsystem Web Services Pages
13.2.2. Starting the Certificate System Administrative Console
13.3. Customizing Web Services Pages
13.3.1. Customizing CA End-Entities Pages
13.3.2. Customizing RA End-Entities Pages
13.3.3. Setting Limits on Searches through the CA End-Entities Pages
13.4. Configuring Ports
13.4.1. Changing a Port Number
13.4.2. Using a Single SSL Port
13.4.3. Updating Existing CAs to Use End-Entity Client Authentication Ports (Avoiding TLS-Related Man-in-the-Middle Attacks)
13.5. Configuring the LDAP Database
13.5.1. Changing the Internal Database Configuration
13.5.2. Enabling SSL Client Authentication with the Internal Database
13.5.3. Restricting Access to the Internal Database
13.6. Searching the SQLite Database
13.7. Viewing Security Domain Configuration
13.8. Managing the SELinux Policies for Subsystems
13.8.1. About SELinux
13.8.2. Viewing SELinux Policies for Subsystems
13.9. Backing up and Restoring Certificate System
13.10. Self-Tests
13.10.1. Self-Test Logging
13.10.2. Configuring Self-Tests
13.10.3. Modifying Self-Test Configuration
14. Managing Certificate System Users and Groups
14.1. About Authorization
14.2. Default Groups
14.2.1. Administrators
14.2.2. Auditors
14.2.3. Agents
14.2.4. Enterprise Groups
14.3. Managing Users and Groups for a CA, OCSP, DRM, or TKS
14.3.1. Managing Groups
14.3.2. Managing Users
14.4. Creating and Managing Users and Groups for an RA
14.4.1. Managing RA Groups
14.4.2. Managing RA Users
14.5. Creating and Managing Users for a TPS
14.5.1. Searching for Users
14.5.2. Adding Users
14.5.3. Setting Profiles for Users
14.5.4. Changing Roles for Users
14.5.5. Renewing TPS Agent and Administrator Certificates
14.5.6. Deleting Users
14.6. Configuring Access Control for Users for the CA, OCSP, DRM, and TKS
14.6.1. About Access Control
14.6.2. Editing ACLs
15. Configuring Subsystem Logs
15.1. An Overview of Log Settings
15.1.1. Services That Are Logged
15.1.2. Log Levels (Message Categories)
15.1.3. Buffered and Unbuffered Logging
15.1.4. Log File Rotation
15.2. Certificate System Logs
15.2.1. System Log
15.2.2. Transactions Log
15.2.3. Debug Logs
15.2.4. Error Log
15.2.5. Installation Logs
15.2.6. Apache and Tomcat Error and Access Logs
15.2.7. Self-Tests Log
15.3. Configuring Logs Using the UI
15.3.1. Configuring Logs in the Console (for the CA, OCSP, DRM, and TKS)
15.3.2. Configuring TPS Audit Logs in the Admin Services Page
15.4. Configuring Logs in the CS.cfg File
15.4.1. Configuring Logs in the CS.cfg File for the CA, OCSP, DRM, and TKS
15.4.2. Configuring RA Logging
15.4.3. Configuring TPS Logging
15.5. Managing Signed Audit Logs
15.5.1. Configuring a Signed Audit Log for a CA, OCSP, DRM, or TKS
15.5.2. Configuring TPS Signed Audit Logging
15.5.3. Handling Audit Logging Failures
15.5.4. Signing Log Files
15.6. Viewing Logs
15.7. Smart Card Error Codes
15.8. Managing Log Modules
15.8.1. Registering a Log Module
15.8.2. Deleting a Log Module
16. Managing Subsystem Certificates
16.1. Required Subsystem Certificates
16.1.1. Certificate Manager Certificates
16.1.2. RA Certificates
16.1.3. Online Certificate Status Manager Certificates
16.1.4. Data Recovery Manager Certificates
16.1.5. TKS Certificates
16.1.6. TPS Certificates
16.1.7. Using an HSM to Store Subsystem Certificates
16.2. Requesting a Subsystem, Server, or Signing Certificate through the Console
16.3. Renewing Subsystem Certificates
16.4. Using Cross-Pair Certificates
16.4.1. Installing Cross-Pair Certificates
16.4.2. Searching for Cross-Pair Certificates
16.5. Managing the Certificate Database
16.5.1. Installing Certificates in the Certificate System Database
16.5.2. Viewing Database Content
16.5.3. Deleting Certificates from the Database
16.6. Changing the Trust Settings of a CA Certificate
16.6.1. Changing Trust Settings through the Console
16.6.2. Changing Trust Settings Using certutil
16.7. Managing Tokens Used by the Subsystems
16.7.1. Detecting Tokens
16.7.2. Viewing Tokens
16.7.3. Changing a Token's Password

Chapter 12. Editing Configuration in the CS.cfg File

The primary configuration file for every subsystem is its CS.cfg file. This chapter covers basic information about and rules for editing the CS.cfg file This chapter also describes some other useful configuration files used by the subsystems, such as password and web services files.

12.1. Default File and Directory Locations for Certificate System Subsystems

Certificate System servers consist of subsystems (which are types of servers) and instances.
Server subsystems are servers for a specific type of PKI function and are installed by the Certificate System RPMs. This general subsystem information is contained in non-relocatable, RPM-defined shared libraries, Java archive files, binaries, and templates. These are stored in a fixed location.

NOTE

There is an environment variable, DONT_RUN_PKICREATE, which stops the pkicreate script from running automatically after the subsystems are installed. This allows the default instances to be installed in user-defined installation directories, instead of the default locations in /var/lib. To use custom directory locations, install the subsystems through the ISO image with this environment variable set to block the pkicreate script.
Server instances are somewhat relocatable and have user-specific default and customized forms and data. Subsystem instances can be stored anywhere on a system.
When the Certificate System is first installed, one instance for each subsystem type is also installed. The default information such as the port numbers, instance name, and configuration file location for each subsystem (after being installed and going through the setup process) is listed in the following sections.

12.1.1. Default CA Instance Information

The default CA configuration is listed in Table 12.1, “Default CA Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every CA instance.

Table 12.1. Default CA Instance Information

Setting Value
Standard Port[a] 9180
Agents Port[a] 9443
Secure End Users Port[a] 9444
End-Entities Client Authentication Port[a] 9446
Admin Port[a] 9445
Tomcat Port[a] 9701
Instance Name pki-ca
Main Directory /var/lib/pki-ca
Configuration Directory /etc/pki-ca
Configuration File