Page 1
Red Hat Certificate
System 8.0
Admin Guide
Publication date: July 22, 2009, updated on March 25, 2010
Page 2
Admin Guide
Red Hat Certificate System 8.0 Admin Guide
Copyright © 2009 Red Hat, Inc.
Copyright © 2009 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available
at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this
document or an adaptation of it, you must provide the URL for the original version.
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.
All other trademarks are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park, NC 27709 USA
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.
Page 3
iii
About This Guide xv
1. Recommended Concepts ............................................................................................... xv
2. What Is in This Guide .................................................................................................... xv
3. Supported Platforms, Hardware, and Programs .............................................................. xvi
3.1. Supported Platforms ........................................................................................... xvi
3.2. Supported Web Browsers ................................................................................... xvi
3.3. Supported Smart Cards ..................................................................................... xvii
3.4. Supported HSM ................................................................................................ xvii
3.5. Supported Charactersets ................................................................................... xvii
4. Examples and Formatting ............................................................................................ xviii
4.1. Formatting for Examples and Commands ........................................................... xviii
4.2. Tool Locations .................................................................................................. xviii
4.3. Guide Formatting .............................................................................................. xviii
5. Additional Reading ........................................................................................................ xix
6. Giving Feedback ........................................................................................................... xx
7. Document History ......................................................................................................... xxi
1. Overview of Red Hat Certificate System Subsystems 1
1.1. How Certificates Are Used ............................................................................................ 1
1.1.1. Uses for Certificates .......................................................................................... 1
1.1.2. Types of Certificates .......................................................................................... 3
1.2. A Review of Certificate System Subsystems .................................................................. 5
1.2.1. Certificate Manager ........................................................................................... 6
1.2.2. Registration Authority ......................................................................................... 7
1.2.3. Data Recovery Manager .................................................................................... 7
1.2.4. Online Certificate Status Manager ...................................................................... 7
1.2.5. Token Processing System .................................................................................. 7
1.2.6. Token Key Service ............................................................................................ 8
1.2.7. Enterprise Security Client ................................................................................... 8
1.3. A Look at Managing Certificates ................................................................................... 8
1.4. A Look at the Token Management System ................................................................... 11
1.5. Red Hat Certificate System Services ........................................................................... 13
1.5.1. Interfaces for Administrators ............................................................................. 13
1.5.2. Agent Interfaces .............................................................................................. 16
1.5.3. End User Pages .............................................................................................. 17
1.5.4. Enterprise Security Client ................................................................................. 18
I. Setting up Certificate Services 21
2. Making Rules for Issuing Certificates 23
2.1. About Certificate Profiles .................................................................................... 23
2.1.1. The Profile .............................................................................................. 23
2.1.2. Certificate Extensions: Defaults and Constraints ........................................ 25
2.1.3. Inputs and Outputs .................................................................................. 26
2.2. Setting up Certificate Profiles .............................................................................. 26
2.2.1. Creating Certificate Profiles through the CA Console .................................. 27
2.2.2. Editing Certificate Profiles in the Console .................................................. 35
2.2.3. Creating and Editing Certificate Profiles through the Command Line ............ 36
2.2.4. Defining Key Defaults in Profiles ............................................................... 39
2.2.5. Configuring Cross-Pair Profiles ................................................................. 39
2.2.6. List of Certificate Profiles ......................................................................... 41
2.3. Configuring Custom Enrollment Profiles to Use with an RA ................................... 48
Page 4
Admin Guide
iv
2.3.1. Default RA Profiles .................................................................................. 48
2.3.2. Creating RA Enrollment Forms ................................................................. 48
2.3.3. Configuring the Request Queues .............................................................. 50
2.4. Managing Smart Card CA Profiles ....................................................................... 53
2.4.1. Editing Enrollment Profiles for the TPS ..................................................... 54
2.4.2. Creating Custom TPS Profiles .................................................................. 54
2.4.3. Using the Windows Smart Card Logon Profile ........................................... 55
2.5. Setting the Signing Algorithms for Certificates ...................................................... 55
2.5.1. Setting the CA's Default Signing Algorithm ................................................ 55
2.5.2. Setting the Signing Algorithm Default in a Profile ....................................... 56
2.6. Managing CA-Related Profiles ............................................................................ 58
2.6.1. Setting Restrictions on CA Certificates ..................................................... 58
2.6.2. Changing the Restrictions for CAs on Issuing Certificates ........................... 59
2.7. Managing Subject Names and Subject Alternative Names ..................................... 61
2.7.1. Inserting LDAP Directory Attribute Values and Other Information into the
Subject Alt Name .............................................................................................. 61
2.7.2. Changing DN Attributes in CA-Issued Certificates ...................................... 64
2.7.3. Customizing the Subject DN in a Certificate Request Issued by an RA ......... 67
3. Setting up Key Archival and Recovery 69
3.1. About Key Archival and Recovery ....................................................................... 69
3.2. Setting up Key Archival ...................................................................................... 70
3.3. Setting up Agent-Approved Key Recovery Schemes ............................................. 72
3.4. Testing the Key Archival and Recovery Setup ...................................................... 73
4. Requesting, Enrolling, and Managing Certificates 75
4.1. About Enrolling and Renewing Certificates ........................................................... 75
4.2. Configuring Internet Explorer to Enroll Certificates ................................................ 75
4.3. Requesting and Receiving Certificates ................................................................. 77
4.3.1. Requesting and Receiving a User or Agent Certificate through the End-
Entities Page .................................................................................................... 77
4.3.2. Requesting Certificates Using certutil ........................................................ 81
4.4. Enrolling a Certificate on a Cisco Router ............................................................. 85
4.4.1. Configuring a Router for SCEP Enrollment ................................................ 86
4.4.2. Generating the SCEP Certificate for a Router ............................................ 86
4.4.3. Working with Subordinate CAs ................................................................. 89
4.4.4. Re-enrolling a Router ............................................................................... 90
4.4.5. Enabling Debugging ................................................................................. 90
4.5. Performing Bulk Issuance ................................................................................... 90
4.5.1. Creating the Bulk Issuance File ................................................................ 91
4.5.2. Running the Bulk Issuance Command ....................................................... 92
4.6. Configuring and Using the Auto Enrollment Proxy ................................................. 93
4.6.1. About Auto Enrollment ............................................................................. 93
4.6.2. Installing and Setting up the Auto Enrollment Proxy ................................... 98
4.6.3. Managing Auto Enrollment Proxy Settings ............................................... 109
4.6.4. Manually Requesting Domain Certificates ................................................ 112
4.7. Renewing Certificates ....................................................................................... 116
4.7.1. About Renewal ...................................................................................... 116
4.7.2. Creating Custom Renewal Profiles .......................................................... 119
4.7.3. Renewing Certificates ............................................................................ 121
5. Using and Configuring the Token Management System: TPS, TKS, and Enterprise
Security Client 127
Page 5
v
5.1. Configuring TPS Smart Card Operations ............................................................ 127
5.1.1. Configuring Format Operations ............................................................... 127
5.1.2. Configuring TPS Enrollment Operations .................................................. 128
5.1.3. Configuring TPS Renewal Operations ..................................................... 133
5.1.4. Configuring the PIN Reset Operation ...................................................... 134
5.1.5. Configuring the Applet Update Operation ................................................. 135
5.2. Allowing Token Renewal ................................................................................... 136
5.3. Changing the Token Policy ................................................................................ 137
5.4. Setting Token Types for Specified Smart Cards .................................................. 139
5.4.1. Default Token Types .............................................................................. 139
5.4.2. Mapping Token Types to Smart Card Operation Profiles ........................... 139
5.4.3. Example: Token Mapping with Two Different Token Types ......................... 141
5.5. Automating Encryption Key Recovery ................................................................ 143
5.5.1. Configuring Enrollment for Replacement Tokens ...................................... 143
5.5.2. Configuring Key Generation for Temporary Tokens ................................... 144
5.6. Managing Shared Keys ..................................................................................... 145
5.6.1. Generating Master Keys ......................................................................... 145
5.6.2. Generating and Transporting Wrapped Master Keys ................................. 146
5.6.3. Using HSM for Generating Keys ............................................................. 149
5.6.4. Updating Master Key Versions and Associating the Master Key with Its
Version ........................................................................................................... 151
5.6.5. Configuring Symmetric Key Changeover ................................................. 152
5.7. Configuring the TPS ......................................................................................... 154
5.7.1. Enabling SSL for TPS-Enterprise Security Client Connections ................... 154
5.7.2. Configuring the Channels between the TPS and Tokens ........................... 156
5.7.3. Configuring or Disabling LDAP Authentication .......................................... 157
5.7.4. Configuring the Token Database ............................................................. 159
5.7.5. Configuring Server-Side Key Generation and Archival of Encryption Keys .. 160
5.7.6. Configuring IPv6 Support ....................................................................... 163
5.8. Scaling the TPS and Its Support Subsystems ..................................................... 163
5.8.1. Configuring Failover Support .................................................................. 164
5.8.2. Configuring Multiple Support Subsystem Instances for Different Functions
........................................................................................................................ 166
5.9. Potential Token Operation Errors ....................................................................... 167
6. Revoking Certificates and Issuing CRLs 169
6.1. About Revoking Certificates .............................................................................. 169
6.1.1. User-Initiated Revocation ........................................................................ 171
6.1.2. Reasons for Revoking a Certificate ......................................................... 171
6.1.3. CRL Issuing Points ................................................................................ 171
6.1.4. Delta CRLs ............................................................................................ 172
6.1.5. Publishing CRLs .................................................................................... 172
6.1.6. Certificate Revocation Pages .................................................................. 172
6.2. CMC Revocation .............................................................................................. 172
6.2.1. Setting up CMC Revocation ................................................................... 173
6.2.2. Testing CMC Revoke ............................................................................. 173
6.3. Issuing CRLs .................................................................................................... 174
6.3.1. Configuring Issuing Points ...................................................................... 175
6.3.2. Configuring CRLs for Each Issuing Point ................................................. 176
6.3.3. Setting CRL Extensions ......................................................................... 180
6.3.4. Setting a CA to Use a Different Certificate to Sign CRLs ........................... 181
6.4. Setting Full and Delta CRL Schedules ............................................................... 182
Page 6
Admin Guide
vi
6.4.1. Configuring Extended Updated Intervals for CRLs in the Console .............. 183
6.4.2. Configuring Extended Updated Intervals for CRLs in CS.cfg ...................... 183
6.5. Enabling Automatic Revocation Checking for Agent Certificates ........................... 184
7. Using the Online Certificate Status Protocol Responder 187
7.1. Setting up the OCSP Responder ....................................................................... 187
7.2. Identifying the CA to the OCSP Responder ........................................................ 188
7.2.1. Verify Certificate Manager and Online Certificate Status Manager
Connection ...................................................................................................... 189
7.2.2. Configure the Revocation Info Stores ...................................................... 189
7.2.3. Testing the OCSP Service Setup ............................................................ 190
7.3. Enabling the Certificate Manager's Internal OCSP Service ................................... 191
7.4. Enabling Revocation Checking for the TPS and RA ............................................ 192
7.5. Enabling Certificate Revocation Checking for DRM and TKS Users ...................... 194
7.6. Submitting OCSP Requests Using the GET Method ............................................ 196
7.7. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier ... 197
II. Additional Configuration to Manage CA Services 201
8. Publishing Certificates and CRLs 203
8.1. About Publishing .............................................................................................. 203
8.1.1. Publishers ............................................................................................. 204
8.1.2. Mappers ................................................................................................ 205
8.1.3. Rules .................................................................................................... 205
8.1.4. Publishing to Files ................................................................................. 205
8.1.5. OCSP Publishing ................................................................................... 205
8.1.6. LDAP Publishing .................................................................................... 206
8.2. Setting up Publishing ........................................................................................ 206
8.2.1. Configuring Publishing to a File .............................................................. 207
8.2.2. Configuring Publishing to an OCSP ......................................................... 210
8.2.3. Configuring Publishing to an LDAP Directory ........................................... 211
8.2.4. Creating Rules ....................................................................................... 217
8.2.5. Enabling Publishing ................................................................................ 221
8.3. Publishing CRLs over HTTP ............................................................................. 222
8.3.1. Configuring CRL Publishing to Resume after Interrupted Downloads .......... 223
8.3.2. Retrieving CRLs Using wget ................................................................... 228
8.3.3. Retrieving Partial CRLs .......................................................................... 228
8.4. Publishing Cross-Pair Certificates ...................................................................... 229
8.5. Testing Publishing to Files ................................................................................. 230
8.6. Viewing Certificates and CRLs Published to File ................................................. 231
8.7. Updating Certificates and CRLs in a Directory .................................................... 231
8.7.1. Manually Updating Certificates in the Directory ........................................ 232
8.7.2. Manually Updating the CRL in the Directory ............................................ 233
8.8. Registering and Deleting Mapper and Publisher Plug-in Modules ......................... 233
9. Authentication for Enrolling Certificates 235
9.1. Configuring Agent-Approved Enrollment ............................................................. 235
9.2. Automated Enrollment ....................................................................................... 236
9.2.1. Setting up Directory-Based Authentication ............................................... 236
9.2.2. Setting up PIN-Based Enrollment ............................................................ 238
9.2.3. Using Certificate-Based Authentication .................................................... 241
9.2.4. Configuring Flat File Authentication ......................................................... 241
Page 7
vii
9.3. Setting up CMC Enrollment ............................................................................... 244
9.3.1. Setting up the Server for Multiple Requests in a Full CMC Request ............ 245
9.3.2. Testing CMCEnroll ................................................................................. 246
9.4. Testing Enrollment ............................................................................................ 246
9.5. Managing Authentication Plug-ins ...................................................................... 247
10. Using Automated Notifications 249
10.1. About Automated Notifications for the CA ......................................................... 249
10.1.1. Types of Automated Notifications .......................................................... 249
10.1.2. Determining End-Entity Email Addresses ............................................... 249
10.1.3. About RA Notifications ......................................................................... 250
10.2. Setting up Automated Notifications for the CA .................................................. 250
10.2.1. Setting up Automated Notifications in the Console .................................. 250
10.2.2. Configuring Specific Notifications by Editing the CS.cfg File .................... 251
10.2.3. Testing Configuration ............................................................................ 252
10.3. Customizing Notification Messages .................................................................. 253
10.3.1. Customizing CA Notification Messages .................................................. 253
10.3.2. Customizing RA Notification Messages .................................................. 255
10.4. Configuring a Mail Server for Certificate System Notifications ............................. 256
10.5. Creating Custom Notifications for the CA ......................................................... 257
11. Setting Automated Jobs 259
11.1. About Automated Jobs .................................................................................... 259
11.1.1. Setting up Automated Jobs ................................................................... 259
11.1.2. Types of Automated Jobs ..................................................................... 259
11.2. Setting up the Job Scheduler ........................................................................... 260
11.3. Setting up Specific Jobs .................................................................................. 261
11.3.1. Configuring Specific Jobs Using the Certificate Manager Console ............ 261
11.3.2. Configuring Jobs by Editing the Configuration File .................................. 264
11.3.3. Configuration Parameters of certRenewalNotifier .................................... 265
11.3.4. Configuration Parameters of requestInQueueNotifier ............................... 265
11.3.5. Configuration Parameters of publishCerts .............................................. 266
11.3.6. Configuration Parameters of unpublishExpiredCerts ................................ 266
11.3.7. Frequency Settings for Automated Jobs ................................................. 267
11.4. Registering or Deleting a Job Module ............................................................... 268
III. Managing the Subsystem Instances 271
12. Editing Configuration in the CS.cfg File 273
12.1. Default File and Directory Locations for Certificate System Subsystems .............. 273
12.1.1. Default CA Instance Information ............................................................ 273
12.1.2. Default RA Instance Information ............................................................ 274
12.1.3. Default DRM Instance Information ......................................................... 275
12.1.4. Default OCSP Instance Information ....................................................... 275
12.1.5. Default TKS Instance Information .......................................................... 276
12.1.6. Default TPS Instance Information .......................................................... 277
12.1.7. Shared Certificate System Subsystem File Locations .............................. 278
12.2. CS.cfg Files .................................................................................................... 279
12.2.1. Locating the CS.cfg File ....................................................................... 279
12.2.2. Overview of the CS.cfg Configuration File .............................................. 279
12.2.3. Editing the Configuration File ................................................................ 285
12.3. System Passwords ......................................................................................... 285
Page 8
Admin Guide
viii
12.3.1. Configuring the password.conf .............................................................. 286
12.3.2. Protecting the password.conf File .......................................................... 286
12.3.3. Requiring System Password Prompts .................................................... 287
12.3.4. Changing System Passwords ............................................................... 293
12.3.5. Password-Quality Checker .................................................................... 293
12.4. Configuration Files for Web Services ............................................................... 294
13. Basic Subsystem Management 295
13.1. Starting and Stopping Subsystem Instances ..................................................... 295
13.1.1. Starting and Stopping a Subsystem Server Instance ............................... 295
13.1.2. Restarting a Subsystem after a Machine Restart .................................... 295
13.1.3. Checking the Subsystem Instance Status .............................................. 295
13.1.4. Managing Subsystem Processes with chkconfig ..................................... 296
13.2. Opening Subsystem Consoles and Services ..................................................... 298
13.2.1. Finding the Subsystem Web Services Pages ......................................... 298
13.2.2. Starting the Certificate System Administrative Console ........................... 300
13.3. Customizing Web Services Pages ................................................................... 301
13.3.1. Customizing CA End-Entities Pages ...................................................... 301
13.3.2. Customizing RA End-Entities Pages ...................................................... 303
13.3.3. Setting Limits on Searches through the CA End-Entities Pages ............... 304
13.4. Configuring Ports ............................................................................................ 306
13.4.1. Changing a Port Number ...................................................................... 307
13.4.2. Using a Single SSL Port ....................................................................... 308
13.4.3. Updating Existing CAs to Use End-Entity Client Authentication Ports
(Avoiding TLS-Related Man-in-the-Middle Attacks) ............................................ 309
13.5. Configuring the LDAP Database ...................................................................... 312
13.5.1. Changing the Internal Database Configuration ....................................... 313
13.5.2. Enabling SSL Client Authentication with the Internal Database ................ 314
13.5.3. Restricting Access to the Internal Database ........................................... 317
13.6. Searching the SQLite Database ....................................................................... 318
13.7. Viewing Security Domain Configuration ............................................................ 318
13.8. Managing the SELinux Policies for Subsystems ................................................ 319
13.8.1. About SELinux ..................................................................................... 320
13.8.2. Viewing SELinux Policies for Subsystems .............................................. 320
13.9. Backing up and Restoring Certificate System ................................................... 322
13.10. Self-Tests ..................................................................................................... 324
13.10.1. Self-Test Logging ............................................................................... 324
13.10.2. Configuring Self-Tests ......................................................................... 324
13.10.3. Modifying Self-Test Configuration ........................................................ 325
14. Managing Certificate System Users and Groups 327
14.1. About Authorization ......................................................................................... 327
14.2. Default Groups ............................................................................................... 327
14.2.1. Administrators ...................................................................................... 328
14.2.2. Auditors ............................................................................................... 329
14.2.3. Agents ................................................................................................. 329
14.2.4. Enterprise Groups ................................................................................ 329
14.3. Managing Users and Groups for a CA, OCSP, DRM, or TKS ............................. 330
14.3.1. Managing Groups ................................................................................ 330
14.3.2. Managing Users ................................................................................... 331
14.4. Creating and Managing Users and Groups for an RA ........................................ 336
14.4.1. Managing RA Groups ........................................................................... 337
Page 9
ix
14.4.2. Managing RA Users ............................................................................. 340
14.5. Creating and Managing Users for a TPS .......................................................... 349
14.5.1. Searching for Users ............................................................................. 349
14.5.2. Adding Users ....................................................................................... 350
14.5.3. Setting Profiles for Users ...................................................................... 351
14.5.4. Changing Roles for Users .................................................................... 352
14.5.5. Renewing TPS Agent and Administrator Certificates ............................... 353
14.5.6. Deleting Users ..................................................................................... 353
14.6. Configuring Access Control for Users for the CA, OCSP, DRM, and TKS ............. 354
14.6.1. About Access Control ........................................................................... 354
14.6.2. Editing ACLs ........................................................................................ 356
15. Configuring Subsystem Logs 359
15.1. An Overview of Log Settings ........................................................................... 359
15.1.1. Services That Are Logged .................................................................... 359
15.1.2. Log Levels (Message Categories) ......................................................... 360
15.1.3. Buffered and Unbuffered Logging .......................................................... 361
15.1.4. Log File Rotation ................................................................................. 362
15.2. Certificate System Logs .................................................................................. 362
15.2.1. System Log ......................................................................................... 362
15.2.2. Transactions Log ................................................................................. 363
15.2.3. Debug Logs ......................................................................................... 363
15.2.4. Error Log ............................................................................................. 365
15.2.5. Installation Logs ................................................................................... 366
15.2.6. Apache and Tomcat Error and Access Logs ........................................... 366
15.2.7. Self-Tests Log ...................................................................................... 367
15.3. Configuring Logs Using the UI ......................................................................... 367
15.3.1. Configuring Logs in the Console (for the CA, OCSP, DRM, and TKS) ....... 367
15.3.2. Configuring TPS Audit Logs in the Admin Services Page ........................ 368
15.4. Configuring Logs in the CS.cfg File .................................................................. 370
15.4.1. Configuring Logs in the CS.cfg File for the CA, OCSP, DRM, and TKS ...... 370
15.4.2. Configuring RA Logging ....................................................................... 371
15.4.3. Configuring TPS Logging ...................................................................... 373
15.5. Managing Signed Audit Logs ........................................................................... 376
15.5.1. Configuring a Signed Audit Log for a CA, OCSP, DRM, or TKS ................ 376
15.5.2. Configuring TPS Signed Audit Logging .................................................. 379
15.5.3. Handling Audit Logging Failures ............................................................ 381
15.5.4. Signing Log Files ................................................................................. 382
15.6. Viewing Logs .................................................................................................. 382
15.7. Smart Card Error Codes ................................................................................. 383
15.8. Managing Log Modules ................................................................................... 384
15.8.1. Registering a Log Module ..................................................................... 384
15.8.2. Deleting a Log Module ......................................................................... 385
16. Managing Subsystem Certificates 387
16.1. Required Subsystem Certificates ..................................................................... 387
16.1.1. Certificate Manager Certificates ............................................................ 387
16.1.2. RA Certificates ..................................................................................... 389
16.1.3. Online Certificate Status Manager Certificates ........................................ 389
16.1.4. Data Recovery Manager Certificates ..................................................... 391
16.1.5. TKS Certificates ................................................................................... 392
16.1.6. TPS Certificates ................................................................................... 393
Page 10
Admin Guide
x
16.1.7. Using an HSM to Store Subsystem Certificates ...................................... 393
16.2. Requesting a Subsystem, Server, or Signing Certificate through the Console ....... 394
16.3. Renewing Subsystem Certificates .................................................................... 405
16.4. Using Cross-Pair Certificates ........................................................................... 406
16.4.1. Installing Cross-Pair Certificates ............................................................ 407
16.4.2. Searching for Cross-Pair Certificates ..................................................... 407
16.5. Managing the Certificate Database .................................................................. 407
16.5.1. Installing Certificates in the Certificate System Database ........................ 407
16.5.2. Viewing Database Content .................................................................... 410
16.5.3. Deleting Certificates from the Database ................................................. 412
16.6. Changing the Trust Settings of a CA Certificate ................................................ 413
16.6.1. Changing Trust Settings through the Console ........................................ 413
16.6.2. Changing Trust Settings Using certutil ................................................... 414
16.7. Managing Tokens Used by the Subsystems ...................................................... 414
16.7.1. Detecting Tokens ................................................................................. 415
16.7.2. Viewing Tokens .................................................................................... 415
16.7.3. Changing a Token's Password .............................................................. 415
IV. References 417
A. Certificate Profile Input and Output Reference 419
A.1. Input Reference ............................................................................................... 419
A.1.1. Certificate Request Input ........................................................................ 419
A.1.2. CMC Certificate Request Input ............................................................... 419
A.1.3. Dual Key Generation Input ..................................................................... 419
A.1.4. File-Signing Input .................................................................................. 420
A.1.5. Image Input ........................................................................................... 420
A.1.6. Key Generation Input ............................................................................. 420
A.1.7. nsHKeyCertRequest (Token Key) Input ................................................... 420
A.1.8. nsNKeyCertRequest (Token User Key) Input ........................................... 420
A.1.9. Serial Number Renewal Input ................................................................. 421
A.1.10. Subject DN Input ................................................................................. 421
A.1.11. Subject Name Input ............................................................................. 421
A.1.12. Submitter Information Input .................................................................. 421
A.2. Output Reference ............................................................................................. 421
A.2.1. Certificate Output .................................................................................. 421
A.2.2. PKCS #7 Output ................................................................................... 422
A.2.3. CMMF Output ....................................................................................... 422
B. Defaults, Constraints, and Extensions for Certificates and CRLs 423
B.1. Defaults Reference ........................................................................................... 423
B.1.1. Authority Info Access Extension Default .................................................. 423
B.1.2. Authority Key Identifier Extension Default ................................................ 425
B.1.3. Basic Constraints Extension Default ....................................................... 425
B.1.4. CRL Distribution Points Extension Default ............................................... 426
B.1.5. Extended Key Usage Extension Default .................................................. 429
B.1.6. Freshest CRL Extension Default ............................................................. 430
B.1.7. Issuer Alternative Name Extension Default .............................................. 433
B.1.8. Key Usage Extension Default ................................................................. 434
B.1.9. Name Constraints Extension Default ....................................................... 435
B.1.10. Netscape Certificate Type Extension Default .......................................... 440
B.1.11. Netscape Comment Extension Default .................................................. 440
Page 11
xi
B.1.12. No Default Extension ........................................................................... 440
B.1.13. OCSP No Check Extension Default ...................................................... 440
B.1.14. Policy Constraints Extension Default ..................................................... 441
B.1.15. Policy Mappers Extension Default ......................................................... 442
B.1.16. Signing Algorithm Default ..................................................................... 443
B.1.17. Subject Alternative Name Extension Default .......................................... 443
B.1.18. Subject Directory Attributes Extension Default ....................................... 447
B.1.19. Subject Key Identifier Extension Default ................................................ 448
B.1.20. Subject Name Default .......................................................................... 448
B.1.21. Token Supplied Subject Name Default .................................................. 449
B.1.22. User Supplied Extension Default ........................................................... 449
B.1.23. User Key Default ................................................................................. 450
B.1.24. User Signing Algorithm Default ............................................................. 450
B.1.25. User Subject Name Default .................................................................. 451
B.1.26. User Validity Default ............................................................................ 451
B.1.27. Validity Default ..................................................................................... 451
B.2. Constraints Reference ...................................................................................... 451
B.2.1. Basic Constraints Extension Constraint ................................................... 452
B.2.2. Extended Key Usage Extension Constraint .............................................. 453
B.2.3. Extension Constraint .............................................................................. 453
B.2.4. Key Constraint ...................................................................................... 453
B.2.5. Key Usage Extension Constraint ............................................................ 453
B.2.6. No Constraint ........................................................................................ 455
B.2.7. Netscape Certificate Type Extension Constraint ....................................... 455
B.2.8. Renewal Grace Period Constraint ........................................................... 455
B.2.9. Signing Algorithm Constraint .................................................................. 456
B.2.10. Subject Name Constraint ..................................................................... 456
B.2.11. Unique Subject Name Constraint .......................................................... 457
B.2.12. Validity Constraint ................................................................................ 457
B.3. Standard X.509 v3 Certificate Extension Reference ............................................ 457
B.3.1. authorityInfoAccess ................................................................................ 459
B.3.2. authorityKeyIdentifier ............................................................................. 460
B.3.3. basicConstraints .................................................................................... 461
B.3.4. certificatePoliciesExt .............................................................................. 461
B.3.5. CRLDistributionPoints ............................................................................ 461
B.3.6. extKeyUsage ......................................................................................... 462
B.3.7. issuerAltName Extension ....................................................................... 463
B.3.8. keyUsage .............................................................................................. 463
B.3.9. nameConstraints .................................................................................... 464
B.3.10. OCSPNocheck .................................................................................... 464
B.3.11. policyConstraints .................................................................................. 465
B.3.12. policyMappings .................................................................................... 465
B.3.13. privateKeyUsagePeriod ........................................................................ 466
B.3.14. subjectAltName .................................................................................... 466
B.3.15. subjectDirectoryAttributes ..................................................................... 466
B.3.16. subjectKeyIdentifier .............................................................................. 467
B.4. CRL Extensions ............................................................................................... 467
B.4.1. About CRL Extensions ........................................................................... 467
B.4.2. Standard X.509 v3 CRL Extensions Reference ........................................ 471
B.4.3. Netscape-Defined Certificate Extensions Reference ................................. 480
C. Publishing Module Reference 483
Page 12
Admin Guide
xii
C.1. Publisher Plug-in Modules ................................................................................ 483
C.1.1. FileBasedPublisher ................................................................................ 483
C.1.2. LdapCaCertPublisher ............................................................................. 483
C.1.3. LdapUserCertPublisher .......................................................................... 484
C.1.4. LdapCrlPublisher ................................................................................... 484
C.1.5. LdapDeltaCrlPublisher ........................................................................... 484
C.1.6. LdapCertificatePairPublisher .................................................................. 485
C.1.7. OCSPPublisher ..................................................................................... 485
C.2. Mapper Plug-in Modules ................................................................................. 485
C.2.1. LdapCaSimpleMap ................................................................................ 486
C.2.2. LdapDNExactMap ................................................................................. 487
C.2.3. LdapSimpleMap .................................................................................... 487
C.2.4. LdapSubjAttrMap ................................................................................... 488
C.2.5. LdapDNCompsMap ............................................................................... 488
C.3. Rule Instances ................................................................................................. 491
C.3.1. LdapCaCertRule .................................................................................... 491
C.3.2. LdapXCertRule ...................................................................................... 491
C.3.3. LdapUserCertRule ................................................................................. 492
C.3.4. LdapCRLRule ........................................................................................ 492
D. ACL Reference 493
D.1. About ACL Configuration Files .......................................................................... 493
D.2. Common ACLs ................................................................................................ 494
D.2.1. certServer.acl.configuration .................................................................... 494
D.2.2. certServer.admin.certificate .................................................................... 495
D.2.3. certServer.admin.request.enrollment ....................................................... 495
D.2.4. certServer.auth.configuration .................................................................. 496
D.2.5. certServer.clone.configuration ................................................................. 496
D.2.6. certServer.general.configuration .............................................................. 496
D.2.7. certServer.log.configuration .................................................................... 497
D.2.8. certServer.log.configuration.fileName ...................................................... 497
D.2.9. certServer.log.configuration.signedAudit.expirationTime ............................ 497
D.2.10. certServer.log.content .......................................................................... 498
D.2.11. certServer.log.content.signedAudit ........................................................ 498
D.2.12. certServer.registry.configuration ............................................................ 499
D.2.13. certServer.usrgrp.administration ............................................................ 499
D.3. Certificate Manager-Specific ACLs .................................................................... 499
D.3.1. certServer.admin.ocsp ........................................................................... 499
D.3.2. certServer.ca.certificate .......................................................................... 500
D.3.3. certServer.ca.certificates ........................................................................ 500
D.3.4. certServer.ca.clone ................................................................................ 500
D.3.5. certServer.ca.configuration ..................................................................... 501
D.3.6. certServer.ca.connector ......................................................................... 501
D.3.7. certServer.ca.connectorInfo .................................................................... 501
D.3.8. certServer.ca.crl .................................................................................... 502
D.3.9. certServer.ca.directory ........................................................................... 502
D.3.10. certServer.ca.group .............................................................................. 502
D.3.11. certServer.ca.ocsp ............................................................................... 503
D.3.12. certServer.ca.profile ............................................................................. 503
D.3.13. certServer.ca.profiles ........................................................................... 503
D.3.14. certServer.ca.registerUser .................................................................... 503
D.3.15. certServer.ca.request.enrollment ........................................................... 504
Page 13
xiii
D.3.16. certServer.ca.request.profile ................................................................. 504
D.3.17. certServer.ca.requests ......................................................................... 504
D.3.18. certServer.ca.systemstatus ................................................................... 505
D.3.19. certServer.ee.certchain ......................................................................... 505
D.3.20. certServer.ee.certificate ........................................................................ 505
D.3.21. certServer.ee.certificates ...................................................................... 506
D.3.22. certServer.ee.crl .................................................................................. 506
D.3.23. certServer.ee.profile ............................................................................. 506
D.3.24. certServer.ee.profiles ........................................................................... 506
D.3.25. certServer.ee.request.enrollment ........................................................... 507
D.3.26. certServer.ee.request.ocsp ................................................................... 507
D.3.27. certServer.ee.request.revocation ........................................................... 507
D.3.28. certServer.ee.requestStatus .................................................................. 507
D.3.29. certServer.job.configuration .................................................................. 508
D.3.30. certServer.kra.configuration .................................................................. 508
D.3.31. certServer.ocsp.configuration ................................................................ 508
D.3.32. certServer.policy.configuration ............................................................... 509
D.3.33. certServer.profile.configuration .............................................................. 509
D.3.34. certServer.publisher.configuration .......................................................... 509
D.3.35. certServer.ra.configuration .................................................................... 510
D.3.36. certServer.securitydomain.domainxml ................................................... 510
D.4. Data Recovery Manager-Specific ACLs ............................................................. 511
D.4.1. certServer.job.configuration .................................................................... 511
D.4.2. certServer.kra.certificate.transport ........................................................... 511
D.4.3. certServer.kra.configuration .................................................................... 511
D.4.4. certServer.kra.connector ........................................................................ 512
D.4.5. certServer.kra.GenerateKeyPair .............................................................. 512
D.4.6. certServer.kra.getTransportCert .............................................................. 512
D.4.7. certServer.kra.group .............................................................................. 513
D.4.8. certServer.kra.key .................................................................................. 513
D.4.9. certServer.kra.keys ................................................................................ 513
D.4.10. certServer.kra.registerUser ................................................................... 513
D.4.11. certServer.kra.request .......................................................................... 514
D.4.12. certServer.kra.request.status ................................................................ 514
D.4.13. certServer.kra.requests ........................................................................ 514
D.4.14. certServer.kra.systemstatus .................................................................. 514
D.4.15. certServer.kra.TokenKeyRecovery ......................................................... 515
D.5. Online Certificate Status Manager-Specific ACLs ............................................... 515
D.5.1. certServer.ca.ocsp ................................................................................. 515
D.5.2. certServer.ee.crl .................................................................................... 516
D.5.3. certServer.ee.request.ocsp ..................................................................... 516
D.5.4. certServer.ocsp.ca ................................................................................. 516
D.5.5. certServer.ocsp.cas ............................................................................... 517
D.5.6. certServer.ocsp.certificate ...................................................................... 517
D.5.7. certServer.ocsp.configuration .................................................................. 517
D.5.8. certServer.ocsp.crl ................................................................................. 517
D.5.9. certServer.ocsp.group ............................................................................ 518
D.5.10. certServer.ocsp.info ............................................................................. 518
D.5.11. certServer.ocsp.systemstatus ................................................................ 518
D.6. Token Key Service-Specific ACLs ..................................................................... 518
D.6.1. certServer.tks.encrypteddata .................................................................. 519
Page 14
Admin Guide
xiv
D.6.2. certServer.tks.group ............................................................................... 519
D.6.3. certServer.tks.importTransportCert .......................................................... 519
D.6.4. certServer.tks.keysetdata ....................................................................... 519
D.6.5. certServer.tks.registerUser ..................................................................... 520
D.6.6. certServer.tks.sessionkey ....................................................................... 520
D.6.7. certServer.tks.systemstatus .................................................................... 520
Glossary 521
Index 535
Page 15
xv
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”.
Concept Related Chapters
Overviews of important concepts Chapter 1, Overview of Red Hat Certificate System Subsystems
Issuing certificates Chapter 2, Making Rules for Issuing Certificates
Managing certificates on tokens Chapter 5, Using and Configuring the Token Management System: TPS, TKS,
Page 16
About This Guide
xvi
Concept Related Chapters
Archiving keys Chapter 3, Setting up Key Archival and Recovery
Publishing certificates Chapter 8, Publishing Certificates and CRLs
Revoking certificates Chapter 6, Revoking Certificates and Issuing CRLs
Options for issuing certificates Chapter 7, Using the Online Certificate Status Protocol Responder
Configuring and managing Certificate System subsystems Chapter 12, Editing Configuration in the CS.cfg File
References for Subsystem Components Appendix A, Certificate Profile Input and Output Reference
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
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.
Page 17
Supported Smart Cards
xvii
NOTE
The only browser that is fully-supported for the HTML-based instance configuration wizard
is Mozilla Firefox.
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.x Agent services are not
supported for Mac
Firefox 2.x
Table 2. Supported Web Browsers by Platform
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.
Page 18
About This Guide
xviii
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.
To start the Red Hat Certificate System:
service pki-ca start
Example 1. Example Command
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
Monospace
with a
background
Italicized text Any text which is italicized is a variable, such as
Page 19
Additional Reading
xix
Formatting Style Purpose
Bolded text Most phrases which are in bold are application names, such as
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 Guide1 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 Guide2 covers the installation process for all Certificate System
subsystems.
This manual is intended for Certificate System administrators.
• Certificate System Administrator's Guide3 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 Guide4 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.
Page 20
About This Guide
xx
• Managing Smart Cards with the Enterprise Security Client5 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 Services6 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 Guide7 covers the command-line scripts supplied with Red
Hat Certificate System.
This manual is intended for Certificate System administrators.
• Certificate System Migration Guide8 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 Notes9 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 Bugzilla10. 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.
10
http://bugzilla.redhat.com/bugzilla
Page 21
Document History
xxi
7. Document History
Revision
8.0.16
March 25, 2010 Ella 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
December 16, 2009 Ella 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
November 25, 2009 Ella Deon Lackey
Adding the OCSP configuration section for the TKS and DRM subsystems, per Errata
RHBA-2009:1602.
Revision
8.0.13
November 19, 2009 Ella Deon Lackey
Updating the OCSP configuration section for the TPS and RA subsystems, per updates from Errata
RHBA-2009:1596.
Revision
8.0.12
November 13, 2009 Ella Deon Lackey
Correcting CRL scheduling screenshot, so it matches the text example.
Revision
8.0.11
October 13, 2009 Ella Deon Lackey
Tech edits to the TPS configuration chapter from Jack Magne, per Bugzilla #510610.
Revision
8.0.10
September 30, 2009 Ella Deon Lackey
Tech edits to the TPS configuration chapter, per Bugzilla #510610.
Revision 8.0.9 September 9, 2009 Ella 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 August 28, 2009 Ella Deon Lackey
Tech edits to the publishing and authentication chapters, per Bugzilla #510607 and #510622.
Revision 8.0.7 August 26, 2009 Ella Deon Lackey
Added a section on setting search result limits for the web services pages, as indicated in Bugzilla
#482935.
Revision 8.0.6 August 22, 2009 Ella 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 August 19, 2009 Ella Deon Lackey
Page 22
About This Guide
xxii
Adding back in the book index.
Revision 8.0.4 August 18, 2009 Ella 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 August 12, 2009 Ella 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 August 7, 2009 Ella 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 August 4, 2009 Ella 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 July 22, 2009 Ella Deon Lackey
Initial draft for Certificate System 8.0 Administrator's Guide.
Page 23
Chapter 1.
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
• Section 1.1.1.1, “SSL”
• Section 1.1.1.2, “Signed and Encrypted Email”
• Section 1.1.1.3, “Single Sign-on”
• Section 1.1.1.4, “Object Signing”
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.
Page 24
Chapter 1. Overview of Red Hat Certificate System Subsystems
2
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.
Page 25
Types of Certificates
3
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.
Certificate Type Use Example
Client SSL certificates Used for client authentication
Server SSL certificates Used for server authentication
S/MIME certificates Used for signed and
Page 26
Chapter 1. Overview of Red Hat Certificate System Subsystems
4
Certificate Type Use Example
CA certificates Used to identify CAs. Client
Object-signing certificates Used to identify signers of
Table 1.1. Common Certificates
• Section 1.1.2.1, “CA Signing Certificates”
• Section 1.1.2.2, “Other Signing Certificates”
• Section 1.1.2.3, “SSL Server and Client Certificates”
• Section 1.1.2.4, “User Certificates”
• Section 1.1.2.5, “Dual-Key Pairs”
• Section 1.1.2.6, “Cross-Pair Certificates”
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.
Page 27
A Review of Certificate System Subsystems
5
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:
Page 28
Chapter 1. Overview of Red Hat Certificate System Subsystems
6
• 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.
Page 29
Registration Authority
7
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 loadbalancer 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.
Page 30
Chapter 1. Overview of Red Hat Certificate System Subsystems
8
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.
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.
Page 31
A Look at Managing Certificates
9
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.
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.
Page 32
Chapter 1. Overview of Red Hat Certificate System Subsystems
10
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.
Page 33
A Look at the Token Management System
11
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
Page 34
Chapter 1. Overview of Red Hat Certificate System Subsystems
12
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.
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.
Page 35
Red Hat Certificate System Services
13
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”.
Page 36
Chapter 1. Overview of Red Hat Certificate System Subsystems
14
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 certificatebased 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.
Page 37
Interfaces for Administrators
15
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.
Page 38
Chapter 1. Overview of Red Hat Certificate System Subsystems
16
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.
Page 39
End User Pages
17
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”.
Page 40
Chapter 1. Overview of Red Hat Certificate System Subsystems
18
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.
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:
Page 41
Enterprise Security Client
19
• 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.
Page 42
20
Page 43
Part I. Setting up Certificate Services
Page 44
Page 45
Chapter 2.
23
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
Page 46
Chapter 2. Making Rules for Issuing Certificates
24
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”.
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 CRMFbased 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.
Page 47
Certificate Extensions: Defaults and Constraints
25
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
...
Example 2.1. Example caUserCert Profile
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
Page 48
Chapter 2. Making Rules for Issuing Certificates
26
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
• Section 2.2.1, “Creating Certificate Profiles through the CA Console”
• Section 2.2.2, “Editing Certificate Profiles in the Console”
• Section 2.2.3, “Creating and Editing Certificate Profiles through the Command Line”
• Section 2.2.4, “Defining Key Defaults in Profiles”
• Section 2.2.6, “List of Certificate Profiles”
Page 49
Creating Certificate Profiles through the CA Console
27
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.
Page 50
Chapter 2. Making Rules for Issuing Certificates
28
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
Page 51
Creating Certificate Profiles through the CA Console
29
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.
a. To add a policy, click Add.
b. Choose the default from the Default field, choose the constraints associated with that policy in
the Constraints field, and click OK.
Page 52
Chapter 2. Making Rules for Issuing Certificates
30
c. 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.
d. Configure any parameters in the Defaults and Constraints tabs.
Page 53
Creating Certificate Profiles through the CA Console
31
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.
a. To add an input, click Add.
Page 54
Chapter 2. Making Rules for Issuing Certificates
32
b. Choose the input from the list, and click OK. See Section A.1, “Input Reference” for complete
details of the default inputs.
c. The New Certificate Profile Editor window opens. Set the input ID, and click OK.
Page 55
Creating Certificate Profiles through the CA Console
33
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.
Page 56
Chapter 2. Making Rules for Issuing Certificates
34
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.
a. To add an output, click Add.
b. Choose the output from the list, and click OK.
c. 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.
a. Open the CA's services page.
Page 57
Editing Certificate Profiles in the Console
35
https://server.example.com:9445/ca/services
b. 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.
c. Click the name of the certificate profile to approve.
d. 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
Page 58
Chapter 2. Making Rules for Issuing Certificates
36
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.
• Section 2.2.3.1, “Profile Configuration Parameters”
• Section 2.2.3.2, “Modifying Certificate Extensions through the Command Line”
• Section 2.2.3.3, “Adding Inputs through the Command Line”
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
Page 59
Creating and Editing Certificate Profiles through the Command Line
37
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.
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_idGives 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.nameGives the user-defined name of the constraint. For example, policyset.serverCertSet.1.constraint.name=Subject Name Constraint.
policyset.policyset_id.policy_number.constraint.params.attributeSpecifies 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_idGives 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.nameGives the user-defined name of the default. For example, policyset.serverCertSet.1.default.name=Subject Name Default
policyset.policyset_id.policy_number.default.params.attributeSpecifies 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$.
Table 2.1. Profile Configuration File Parameters
Page 60
Chapter 2. Making Rules for Issuing Certificates
38
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”.
Page 61
Defining Key Defaults in Profiles
39
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
Page 62
Chapter 2. Making Rules for Issuing Certificates
40
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).
Page 63
List of Certificate Profiles
41
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.
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.
Page 64
Chapter 2. Making Rules for Issuing Certificates
42
Profile ID Profile Name Description
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 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
Page 65
List of Certificate Profiles
43
Profile ID Profile Name Description
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.
Page 66
Chapter 2. Making Rules for Issuing Certificates
44
Profile ID Profile Name Description
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 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.
Page 67
List of Certificate Profiles
45
Profile ID Profile Name Description
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 automaticallygenerated, 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 the original
enrollment profile
name does not
change.
• The Renew
Grace Period
Constraint
should be set
in the original
Page 68
Chapter 2. Making Rules for Issuing Certificates
46
Profile ID Profile Name Description
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.
caTempTokenDeviceKeyEnrollmentTemporary 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.
caTempTokenUserEncryptionKeyEnrollmentTemporary 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.
caTempTokenUserSigningKeyEnrollmentTemporary 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
Page 69
List of Certificate Profiles
47
Profile ID Profile Name Description
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.
caTokenUserEncryptionKeyEnrollmentToken User Encryption
Certificate Enrollment
Enrolls an encryption key on
a token; used by the TPS
for smart card enrollment
operations.
caTokenUserEncryptionKeyRenewalsmart 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.
caTokenUserSigningKeyEnrollmentToken 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.
Table 2.2. Certificate Profiles
Page 70
Chapter 2. Making Rules for Issuing Certificates
48
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.
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 automaticallygenerated, one-time PIN that
the router can use to retrieve its
certificate.
Table 2.3. Profiles for the RA
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:
Page 71
Creating RA Enrollment Forms
49
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
Page 72
Chapter 2. Making Rules for Issuing Certificates
50
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.
Page 73
Configuring the Request Queues
51
Plug-in or Library Location Description
PKI::Request::Plugin::AutoAssign (plug-in)
/var/lib/pki-ra/lib/perl/PKI/
Request/Plug-in
Automatically assigns a request
to a group of agents.
PKI::Request::Plugin::CreatePin (plug-in)
/var/lib/pki-ra/lib/perl/PKI/
Request/Plug-in
Creates a one-time PIN for
SCEP enrollment.
PKI::Request::Plugin::EmailNotification (plug-in)
/var/lib/pki-ra/lib/perl/PKI/
Request/Plug-in
Sends email notifications.
PKI::Request::Plugin::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/CAAccesses the CA for
enrollment.
PKI::Request::Queue (library) /var/lib/pki-ra/lib/perl/PKI/
Request/Queue
Accesses the request queue in
the RA.
Table 2.4. RA Request Queue Plug-ins and Libraries
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.
... 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 ...
Page 74
Chapter 2. Making Rules for Issuing Certificates
52
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
Example 2.2. Server Certificate Enrollment
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.
Page 75
Managing Smart Card CA Profiles
53
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”.
Profile Name Configuration File Description
Regular Enrollment Profiles
Token Device Key Enrollment caTokenDeviceKeyEnrollment.cfgFor enrolling tokens used for devices or
Token User Encryption Certificate Enrollment caTokenUserEncryptionKeyEnrollment.cfgFor enrolling encryption certificates on the
Token User Signing Certificate Enrollment caTokenUserSigningKeyEnrollment.cfgFor enrolling signing certificates on the token
Token User MS Login Certificate Enrollment caTokenMSLoginEnrollment.cfg For enrolling user certificates to use for single
Temporary Token Profiles
Temporary Device Certificate Enrollment caTempTokenDeviceKeyEnrollment.cfgFor enrolling certificates for a device on a
Temporary Token User Encryption Certificate Enrollment caTempTokenUserEncryptionKeyEnrollment.cfgFor enrolling an encryption certificate on a
Temporary Token User Signing Certificate Enrollment caTempTokenUserSigningKeyEnrollment.cfgFor enrolling a signing certificates on a
Renewal Profiles
1
Token User Encryption Certificate Enrollment (Renewal) caTokenUserEncryptionKeyRenewal.cfgFor renewing encryption certificates on the
Token User Signing Certificate Enrollment (Renewal) caTokenUserSigningKeyRenewal.cfgFor renewing signing certificates on the token
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 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.
Table 2.5. Default Token Certificate Profiles
Page 76
Chapter 2. Making Rules for Issuing Certificates
54
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
Page 77
Using the Windows Smart Card Logon Profile
55
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.
Page 78
Chapter 2. Making Rules for Issuing Certificates
56
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:
Page 79
Setting the Signing Algorithm Default in a Profile
57
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.
Page 80
Chapter 2. Making Rules for Issuing Certificates
58
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 32801.
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
1
http://www.ietf.org/rfc/rfc3280.txt
Page 81
Changing the Restrictions for CAs on Issuing Certificates
59
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 reenable 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
Page 82
Chapter 2. Making Rules for Issuing Certificates
60
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.
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.
Page 83
Managing Subject Names and Subject Alternative Names
61
Serial number management can be enabled for CAs which are not cloned, if the
parameters are set in the CS.cfg file.
dbs.beginSerialNumber=1
dbs.enableSerialManagement=true
dbs.endReplicaNumber=100
dbs.endRequestNumber=10000000
dbs.endSerialNumber=10000000
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:
Page 84
Chapter 2. Making Rules for Issuing Certificates
62
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.
a. Open the CA Console.
pkiconsole https://server.example.com:9445/ca
b. Select Authentication in the left navigation tree.
c. In the Authentication Instance tab, click Add, and add an instance of the UidPwdDirAuth
authentication plug-in.
d. Set the information for the LDAP directory.
e. Set the LDAP attributes to populate.
f. 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.
Page 85
Inserting LDAP Directory Attribute Values and Other Information into the Subject Alt Name
63
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.
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,
Page 86
Chapter 2. Making Rules for Issuing Certificates
64
Policy Set Token Description
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$.
Table 2.6. Variables Used to Populate Certificates
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.
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
Table 2.7. Allowed Characters for Value Types
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:
Page 87
Changing DN Attributes in CA-Issued Certificates
65
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
Page 88
Chapter 2. Making Rules for Issuing Certificates
66
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:
Page 89
Customizing the Subject DN in a Certificate Request Issued by an RA
67
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.
Page 90
Chapter 2. Making Rules for Issuing Certificates
68
NOTE
There is no graphical interface for performing this customization.
To customize the DN:
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 formulate your preferred DN in the var dn= statement. For
example:
var dn = "uid="+x+".e="+e;
x is the UID and e is the email.
3. Save the file.
Currently, the request form only requests UID, Site ID, and Email information. If the site requires more
information than the form provides for, then you need to modify the enrollment form to allow additional
input. The enrollment form is included at the end of the user.vm file. For example:
<tr>
<td>District:</td>
<td><input type=text name=district value=""></td>
</tr>
After making the appropriate changes to the enrollment form, edit the user.vm file to customize the
Subject DN to utilize the information collected from the user.
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.
Page 91
Chapter 3.
69
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.
Page 92
Chapter 3. Setting up Key Archival and Recovery
70
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.
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.
Page 93
Setting up Key Archival
71
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
Page 94
Chapter 3. Setting up Key Archival and Recovery
72
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
Page 95
Testing the Key Archival and Recovery Setup
73
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:
Page 96
Chapter 3. Setting up Key Archival and Recovery
74
a. 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.
b. Click Recover.
c. In the form that appears, enter the 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.
d. 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.
e. 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.
Page 97
Chapter 4.
75
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.
Page 98
Chapter 4. Requesting, Enrolling, and Managing Certificates
76
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.
a. Open the unsecure end services page for the CA.
http://server.example.com:9180/ca/ee/ca
b. Click the Retrieval tab.
c. Click Import CA Certificate Chain in the left menu, and then select Download the CA
certificate chain in binary form.
d. When prompted, save the CA certificate chain file.
e. In the Internet Explorer menu, click Tools, and select Internet Options.
f. Open the Content tab, and click the Certificates button.
g. 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.
h. 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.
a. In the Internet Explorer menu, click Tools, and select Internet Options.
b. Open the Security tab, and click Sites to add the CA site to the trusted list.
c. 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”.
Page 99
Requesting and Receiving Certificates
77
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.
Page 100
Chapter 4. Requesting, Enrolling, and Managing Certificates
78
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.
Loading...