Red Hat CERTIFICATE SYSTEM 7.3 - COMMAND-LINE Administration Manual
Below you will find brief information for 7.3 Certificate System. This guide covers installing, configuring, and managing Certificate System subsystems, including adding users, requesting/revoking certificates, publishing CRLs, and managing smart cards. Intended for Certificate System administrators.
Advertisement
Advertisement
Red Hat Certificate
System 7.3
Administration Guide
Publication date: May 2007, updated March 25, 2010
Administration Guide
Red Hat Certificate System 7.3 Administration 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 and revoking certificates; publishing CRLs; and managing smart cards. This guide is intended for Certificate System administrators.
About This Guide xvii
1. Recommended Knowledge ........................................................................................... xvii
2. What Is in This Guide .................................................................................................. xvii
3. Examples and Formatting .............................................................................................. xix
3.1. File Locations for Examples and Commands ....................................................... xix
3.2. Using Mozilla LDAP Tools .................................................................................. xix
3.3. Default Port Numbers ......................................................................................... xix
3.4. Guide Formatting ............................................................................................... xix
4. Additional Reading ........................................................................................................ xx
5. Giving Feedback ........................................................................................................... xxi
6. Document History ......................................................................................................... xxi
1. Overview 1
1.1. Features ...................................................................................................................... 1
1.1.1. Subsystems ...................................................................................................... 1
1.1.2. Interfaces .......................................................................................................... 2
1.1.3. Logging ............................................................................................................. 2
1.1.4. Auditing ............................................................................................................. 2
1.1.5. Self-Tests .......................................................................................................... 3
1.1.6. Authorization ..................................................................................................... 3
1.1.7. Security-Enhanced Linux Support ....................................................................... 3
1.1.8. Authentication .................................................................................................... 3
1.1.9. Registration Authority ......................................................................................... 4
1.1.10. SCEP .............................................................................................................. 4
1.1.11. Certificate Issuance .......................................................................................... 4
1.1.12. Certificate Profiles ............................................................................................ 5
1.1.13. CRLs .............................................................................................................. 5
1.1.14. Publishing ....................................................................................................... 5
1.1.15. Notifications ..................................................................................................... 5
1.1.16. Jobs ................................................................................................................ 5
1.1.17. Dual Key Pairs ................................................................................................ 6
1.1.18. HSMs and Crypto Accelerators ......................................................................... 6
1.1.19. Support for Open Standards ............................................................................. 6
1.2. How the Certificate System Works ................................................................................ 7
1.2.1. About the Certificate Manager ............................................................................ 7
1.2.2. How the Certificate Manager Works .................................................................... 9
1.2.3. Data Recovery Manager .................................................................................. 11
1.2.4. Online Certificate Status Manager .................................................................... 11
1.2.5. Token Key Service ........................................................................................... 12
1.2.6. Token Processing System ................................................................................ 12
1.3. Deployment Scenarios ................................................................................................ 12
1.3.1. Single Certificate Manager ............................................................................... 12
1.3.2. Certificate Manager and DRM .......................................................................... 13
1.3.3. Cloned Certificate Manager .............................................................................. 14
1.3.4. Smart Card Enrollment .................................................................................... 15
1.4. System Architecture ................................................................................................... 15
1.4.1. Certificate System Instance .............................................................................. 17
1.4.2. HTTP Engine .................................................................................................. 17
1.4.3. User Interfaces ................................................................................................ 17
1.4.4. JSS and the JNI Layer .................................................................................... 18
1.4.5. NSS ................................................................................................................ 18
1.4.6. PKCS #11 ....................................................................................................... 19 iii
Administration Guide
1.4.7. Management Tools .......................................................................................... 19
1.4.8. JRE ................................................................................................................ 20
1.4.9. Internal Database ............................................................................................ 20
1.4.10. SSL/TLS and Supported Cipher Suites ............................................................ 20
1.5. Support for Open Standards ....................................................................................... 21
1.5.1. Certificate Management Formats and Protocols ................................................. 21
1.5.2. Security and Directory Protocols ....................................................................... 21
2. Installation and Configuration 23
2.1. Deployment Considerations ......................................................................................... 23
2.1.1. Security Domains ............................................................................................ 24
2.1.2. Cloning a Subsystem ....................................................................................... 24
2.1.3. Self-Signed Root CA or Subordinate CA ........................................................... 24
2.2. Prerequisites .............................................................................................................. 25
2.2.1. Supported Platforms ........................................................................................ 25
2.2.2. Required Programs and Dependencies ............................................................. 26
2.2.3. Packages Installed ........................................................................................... 28
2.3. Configuration Preparation ........................................................................................... 32
2.3.1. Required Information ........................................................................................ 32
2.3.2. Default Settings ............................................................................................... 33
2.4. Configuration Setup Wizard ........................................................................................ 34
2.4.1. Security Domain Panel .................................................................................... 34
2.4.2. Subsystem Type Panel .................................................................................... 35
2.4.3. PKI Hierarchy Panel ........................................................................................ 36
2.4.4. CA Information Panel ....................................................................................... 37
2.4.5. TKS Information Panel ..................................................................................... 37
2.4.6. DRM Information Panel .................................................................................... 38
2.4.7. Authentication Directory Panel .......................................................................... 39
2.4.8. Internal Database Panel ................................................................................... 39
2.4.9. Key Store Panel .............................................................................................. 40
2.4.10. Key Pairs Panel ............................................................................................. 41
2.4.11. Subject Names Panel ..................................................................................... 42
2.4.12. Requests and Certificates Panel ..................................................................... 43
2.4.13. Export Keys and Certificates Panel ................................................................. 44
2.4.14. Administrator Panel ........................................................................................ 45
2.5. Installing the Certificate System ................................................................................. 46
2.5.1. Installing from an ISO Image ............................................................................ 46
2.5.2. Installing through up2date ................................................................................ 48
2.6. Configuring the Default Subsystem Instances ............................................................... 48
2.6.1. Configuring a CA ............................................................................................. 48
2.6.2. Configuring a DRM, OCSP, or TKS ................................................................... 50
2.6.3. Configuring a TPS ........................................................................................... 51
2.7. Creating Additional Subsystem Instances ..................................................................... 52
2.7.1. Running pkicreate ............................................................................................ 52
2.7.2. Running pkicreate with Port Separation ............................................................. 53
2.8. Cloning a Subsystem .................................................................................................. 53
2.9. Silent Installation ........................................................................................................ 55
2.10. Updating Certificate System Packages ....................................................................... 56
2.10.1. Updating Certificate System on Red Hat Enterprise Linux ................................. 57
2.10.2. Updating Certificate System on Solaris ............................................................ 57
2.11. Uninstalling Certificate System Subsystems ................................................................ 59
2.11.1. Removing a Subsystem Instance .................................................................... 59 iv
2.11.2. Removing Certificate System Subsystems ....................................................... 59
3. Administrative Basics 61
3.1. Administrative Console ............................................................................................... 61
3.2. Enabling SSL Client Authentication for the Certificate System Console ........................... 62
3.3. System Passwords ..................................................................................................... 64
3.3.1. Protecting the password.conf File ..................................................................... 64
3.3.2. Password-Quality Checker ............................................................................... 66
3.4. Starting, Stopping, and Restarting Certificate System Subsystems ................................. 66
3.4.1. Starting a Server Instance ................................................................................ 66
3.4.2. Stopping a Server Instance .............................................................................. 66
3.4.3. Restarting a Server Instance ............................................................................ 66
3.4.4. Restarting a Subsystem after a Machine Restart ............................................... 67
3.5. Mail Server ................................................................................................................ 67
3.6. Configuration Files ..................................................................................................... 67
3.6.1. Locating the Configuration File ......................................................................... 68
3.6.2. Editing the Configuration File ........................................................................... 68
3.6.3. Guidelines for Editing the Configuration File ...................................................... 68
3.6.4. Duplicating Configuration from One Instance to Another ..................................... 70
3.6.5. Other File Locations ........................................................................................ 70
3.6.6. Default Server Instance Locations .................................................................... 72
3.7. Using Security-Enhanced Linux ................................................................................... 74
3.8. Using Java Servlets .................................................................................................... 75
3.9. Logs .......................................................................................................................... 75
3.9.1. About Logs ...................................................................................................... 76
3.9.2. Services That Are Logged ................................................................................ 79
3.9.3. Log Levels (Message Categories) ..................................................................... 79
3.9.4. Buffered Versus Unbuffered Logging ................................................................. 81
3.9.5. Log File Rotation ............................................................................................. 81
3.9.6. Configuring Logs in the Console ....................................................................... 82
3.9.7. Configuring Logs in the CS.cfg File ................................................................... 83
3.9.8. Configuring TPS Logs ...................................................................................... 84
3.9.9. Monitoring Logs ............................................................................................... 85
3.9.10. Signing Log Files ........................................................................................... 86
3.9.11. Registering a Log Module ............................................................................... 87
3.9.12. Deleting a Log Module ................................................................................... 87
3.9.13. Signed Audit Log ........................................................................................... 87
3.10. Self-Tests ................................................................................................................. 91
3.10.1. Self-Test Logging ........................................................................................... 92
3.10.2. Self-Test Configuration ................................................................................... 92
3.10.3. Modifying Self-Test Configuration .................................................................... 92
3.11. Ports ........................................................................................................................ 93
3.11.1. About Ports ................................................................................................... 93
3.11.2. Changing a Port Number ................................................................................ 96
3.11.3. Configuring Port Separation ............................................................................ 96
3.11.4. Redirecting Subsystem Communications to Secure End-Entities Port ................. 99
3.12. The Internal LDAP Database ................................................................................... 103
3.12.1. Changing the Internal Database Configuration ............................................... 104
3.12.2. Enabling SSL Client Authentication with the Internal Database ........................ 105
3.12.3. Restricting Access to the Internal Database ................................................... 106
3.13. Backing up and Restoring Certificate System ........................................................... 106 v
Administration Guide
4. Certificate Manager 109
4.1. How the Certificate Manager Works ........................................................................... 109
4.1.1. Enrollment ..................................................................................................... 109
4.1.2. Revocation .................................................................................................... 110
4.2. Certificate Manager Certificates ................................................................................. 111
4.2.1. CA Signing Key Pair and Certificate ................................................................ 111
4.2.2. OCSP Signing Key Pair and Certificate ........................................................... 112
4.2.3. SSL Server Key Pair and Certificate ............................................................... 112
4.2.4. Certificate Considerations ............................................................................... 112
4.2.5. Cross-Pair Certificates .................................................................................... 113
4.3. CA Hierarchy ............................................................................................................ 113
4.3.1. Subordination to a Public CA .......................................................................... 114
4.3.2. Subordination to a Certificate System CA ........................................................ 114
4.4. Security Domains ..................................................................................................... 114
4.4.1. The domain.xml File ...................................................................................... 115
4.4.2. Security Domain Roles ................................................................................... 116
4.4.3. Creating a Security Domain ............................................................................ 117
4.4.4. Joining a Security Domain .............................................................................. 118
4.4.5. Additional Security Domain Information ........................................................... 118
4.5. Configuring the Certificate Manager Instance ............................................................. 118
4.6. CA Certificate Reissuance ........................................................................................ 120
4.7. Changing the Rules for Issuing Certificates ................................................................ 120
4.8. Setting Restrictions on CA Certificates through Certificate Extensions .......................... 122
4.9. Creating Certificate Manager Agents and Administrators ............................................. 124
4.10. Checking the Revocation Status of Agent Certificates ............................................... 125
4.11. CRL Signing Key Pair and Certificate ....................................................................... 127
4.12. DNs in the Certificate System .................................................................................. 128
4.12.1. Extending Attribute Support .......................................................................... 129
5. Registration Authority 133
5.1. Introduction .............................................................................................................. 133
5.1.1. What is a Registration Authority? .................................................................... 133
5.1.2. Enrollment Types ........................................................................................... 133
5.1.3. Roles ............................................................................................................ 134
5.1.4. Interfaces ...................................................................................................... 134
5.2. Installation and Configuration .................................................................................... 135
5.2.1. Configuration ................................................................................................. 136
5.2.2. Directory Structure ......................................................................................... 140
5.2.3. Configuration Parameters ............................................................................... 140
5.2.4. RA Request Queue Plugins ............................................................................ 142
5.2.5. Libraries ........................................................................................................ 143
5.3. Working With the Registration Authority ..................................................................... 143
5.3.1. Configuring Additional RA Instances ............................................................... 143
5.3.2. Customizing the Subject DN in the CSR .......................................................... 147
5.3.3. Using the End Users Services Interface .......................................................... 148
5.3.4. Using the Agent Services Interface ................................................................. 153
5.3.5. Using the Administrator Interface .................................................................... 153
5.3.6. Command-line Operations .............................................................................. 155
6. Online Certificate Status Protocol Responder 157
6.1. About OCSP Services .............................................................................................. 157
6.1.1. OCSP Response Signing ............................................................................... 157 vi
6.1.2. OCSP Responses .......................................................................................... 158
6.2. CA OCSP Services .................................................................................................. 158
6.2.1. The Certificate Manager's Internal OCSP Service ............................................ 158
6.2.2. Online Certificate Status Manager ................................................................... 158
6.3. Online Certificate Status Manager Certificates ............................................................ 159
6.3.1. OCSP Signing Key Pair and Certificate ........................................................... 159
6.3.2. SSL Server Key Pair and Certificate ............................................................... 159
6.3.3. Recognizing Online Certificate Status Manager Certificates .............................. 160
6.4. Configuring the Online Certificate Status Manager ...................................................... 160
6.5. Creating Online Certificate Status Manager Agents and Administrators ......................... 161
6.6. Configuring the Certificate Manager's Internal OCSP Service ...................................... 162
6.7. Setting up the OCSP Responder ............................................................................... 163
6.8. Identifying the CA to the OCSP Responder ................................................................ 164
6.8.1. Verify Certificate Manager and Online Certificate Status Manager Connection ..... 165
6.8.2. Configure the Revocation Info Stores .............................................................. 165
6.9. Testing the OCSP Service Setup ............................................................................... 166
6.10. Submitting OCSP Requests Using the GET Method .................................................. 167
6.11. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier ......... 169
7. Data Recovery Manager 173
7.1. PKI Setup for Archiving and Recovering Keys ............................................................ 173
7.2. Data Recovery Manager Certificates .......................................................................... 173
7.2.1. Transport Key Pair and Certificate .................................................................. 174
7.2.2. Storage Key Pair ........................................................................................... 174
7.2.3. SSL Server Certificate .................................................................................... 174
7.3. Forms for Users and Key Recovery Agents ................................................................ 174
7.4. Overview of Archiving Keys ....................................................................................... 175
7.4.1. Reasons to Archive Keys ............................................................................... 175
7.4.2. Where the Keys Are Stored ............................................................................ 175
7.4.3. How Key Archival Works ................................................................................ 175
7.5. Overview of Key Recovery ........................................................................................ 177
7.5.1. Key Recovery Agents and Their Passwords .................................................... 177
7.5.2. Key Recovery Agent Scheme ......................................................................... 178
7.6. Configuring Key Archival and Recovery Process ........................................................ 178
7.6.1. Setting up Key Archival .................................................................................. 178
7.6.2. Setting up Key Recovery ................................................................................ 179
7.6.3. Testing the Key Archival and Recovery Setup .................................................. 180
7.7. Creating Data Recovery Manager Agents and Administrators ...................................... 181
8. Token Processing System 183
8.1. Working with Multiple Instances of a Subsystem ......................................................... 183
8.1.1. Configuring Failover Support .......................................................................... 184
8.1.2. Configuring Multiple Instances for Different Functions ....................................... 184
8.2. Formatting Smart Cards ............................................................................................ 186
8.3. Resetting the Smart Card PIN ................................................................................... 186
8.4. Applet Upgrade ........................................................................................................ 186
8.5. Enrolling Smart Cards through the Enterprise Security Client ....................................... 187
8.5.1. Enabling SSL in the TPS ............................................................................... 188
8.5.2. Configuring Server-Side Key Generation and Archival of Encryption Keys .......... 189
8.5.3. Looking at Smart Card Certificate Enrollment Profiles ....................................... 191
8.5.4. Automating Encryption Key Recovery .............................................................. 192
8.5.5. Configuring Symmetric Key Changeover ......................................................... 194 vii
Administration Guide
8.5.6. Setting Token Types for Specified Smart Cards ............................................... 196
8.6. Configuring LDAP Authentication ............................................................................... 198
8.7. Token Database ....................................................................................................... 199
8.8. Configuring TPS Logging .......................................................................................... 199
8.8.1. Thread Correlation ......................................................................................... 199
8.9. TPS Configuration Parameters .................................................................................. 199
8.9.1. TKS Configuration File Parameters ................................................................. 215
9. Token Key Service 217
9.1. Overview .................................................................................................................. 217
9.2. Using Master Keys ................................................................................................... 217
9.3. Configuring the TKS to Associate the Master Key with Its Version ................................ 219
9.4. Using HSM for Generating Keys ................................................................................ 219
9.5. Creating Token Key Service Agents and Administrators .............................................. 220
10. Enterprise Security Client 223
11. Managing Certificates 225
11.1. Certificate Overview ................................................................................................ 225
11.1.1. Types of Certificates ..................................................................................... 225
11.1.2. Determining Which Certificates to Install ........................................................ 227
11.1.3. Certificate Data Formats ............................................................................... 229
11.1.4. Certificate Setup Wizard ............................................................................... 229
11.2. Requesting and Receiving Certificates ..................................................................... 230
11.2.1. Requesting Certificates ................................................................................. 231
11.2.2. Submitting Certificate Requests ..................................................................... 245
11.2.3. Retrieving Certificates from the End-Entities Page .......................................... 249
11.3. Managing User Certificates .................................................................................... 251
11.3.1. Managing Certificate System User and Agent Certificates ............................... 252
11.3.2. Importing Certificates into Mozilla Firefox ....................................................... 253
11.4. Managing the Certificate Database .......................................................................... 254
11.4.1. Installing Certificates in the Certificate System Database ................................. 254
11.4.2. Viewing Database Content ............................................................................ 258
11.4.3. Deleting Certificates from the Database ......................................................... 260
11.4.4. Changing the Trust Settings of a CA Certificate .............................................. 261
11.5. Configuring the Server Certificate Use Preferences ................................................... 262
12. Managing Tokens 265
12.1. Tokens for Storing Certificate System Keys and Certificates ....................................... 265
12.1.1. Internal Tokens ............................................................................................ 265
12.1.2. External Tokens ........................................................................................... 265
12.1.3. Considerations for External Tokens ............................................................... 265
12.2. Using Hardware Security Modules with Subsystems ................................................. 266
12.2.1. Chrysalis LunaSA HSM ................................................................................ 267
12.2.2. Installing External Tokens and Unsupported HSM .......................................... 267
12.3. Managing Tokens Used by the Subsystems ............................................................. 268
12.3.1. Viewing Tokens ............................................................................................ 268
12.3.2. Changing a Token's Password ...................................................................... 268
12.4. Detecting Tokens .................................................................................................... 268
12.5. Hardware Cryptographic Accelerators ...................................................................... 269
13. Certificate Profiles 271
13.1. About Certificate Profiles ......................................................................................... 271
13.2. How Certificate Profiles Work .................................................................................. 272 viii
13.3. Setting up Certificate Profiles .................................................................................. 273
13.3.1. Modifying Certificate Profiles through the CA Console .................................... 273
13.3.2. Modifying Certificate Profiles through the Command Line ................................ 282
13.3.3. Populating Certificates with Directory Attributes .............................................. 285
13.3.4. Customizing the Enrollment Form ................................................................. 288
13.4. Certificate Profile Reference .................................................................................... 288
13.5. Input Reference ...................................................................................................... 289
13.5.1. Certificate Request Input .............................................................................. 289
13.5.2. CMC Certificate Request Input ...................................................................... 289
13.5.3. Dual Key Generation Input ........................................................................... 289
13.5.4. File-Signing Input ......................................................................................... 289
13.5.5. Image Input ................................................................................................. 290
13.5.6. Key Generation Input ................................................................................... 290
13.5.7. nsHcertificateRequest (Token Key) Input ....................................................... 290
13.5.8. nsNcertificateRequest (Token User Key) Input ............................................... 290
13.5.9. Subject DN Input ......................................................................................... 290
13.5.10. Subject Name Input .................................................................................... 290
13.5.11. Submitter Information Input ......................................................................... 291
13.6. Output Reference ................................................................................................... 291
13.6.1. Certificate Output ......................................................................................... 291
13.6.2. PKCS #7 Output .......................................................................................... 291
13.6.3. CMMF Output .............................................................................................. 291
13.7. Defaults Reference ................................................................................................. 292
13.7.1. Authority Info Access Extension Default ........................................................ 292
13.7.2. Authority Key Identifier Extension Default ...................................................... 293
13.7.3. Basic Constraints Extension Default .............................................................. 294
13.7.4. CRL Distribution Points Extension Default ..................................................... 295
13.7.5. Extended Key Usage Extension Default ........................................................ 297
13.7.6. Freshest CRL Extension Default ................................................................... 298
13.7.7. Issuer Alternative Name Extension Default .................................................... 300
13.7.8. Key Usage Extension Default ....................................................................... 301
13.7.9. Name Constraints Extension Default ............................................................. 302
13.7.10. Netscape Certificate Type Extension Default ................................................ 306
13.7.11. Netscape Comment Extension Default ......................................................... 306
13.7.12. No Default Extension .................................................................................. 306
13.7.13. OCSP No Check Extension Default ............................................................. 306
13.7.14. Policy Constraints Extension Default ........................................................... 307
13.7.15. Policy Mappers Extension Default ............................................................... 308
13.7.16. Signing Algorithm Default ........................................................................... 308
13.7.17. Subject Alternative Name Extension Default ................................................. 309
13.7.18. Subject Directory Attributes Extension Default .............................................. 311
13.7.19. Subject Key Identifier Extension Default ...................................................... 312
13.7.20. Subject Name Default ................................................................................ 312
13.7.21. Token Supplied Subject Name Default ......................................................... 313
13.7.22. User Supplied Extension Default ................................................................. 313
13.7.23. User Supplied Key Default .......................................................................... 314
13.7.24. User Signing Algorithm Default ................................................................... 315
13.7.25. User Supplied Subject Name Default ........................................................... 315
13.7.26. User Supplied Validity Default ..................................................................... 315
13.7.27. Validity Default ........................................................................................... 315
13.8. Constraints Reference ............................................................................................. 316 ix
Administration Guide
13.8.1. Basic Constraints Extension Constraint ......................................................... 316
13.8.2. Extended Key Usage Extension Constraint .................................................... 317
13.8.3. Extension Constraint .................................................................................... 317
13.8.4. Key Constraint ............................................................................................. 317
13.8.5. Key Usage Extension Constraint ................................................................... 317
13.8.6. No Constraint .............................................................................................. 319
13.8.7. Netscape Certificate Type Extension Constraint ............................................. 319
13.8.8. Signing Algorithm Constraint ......................................................................... 319
13.8.9. Subject Name Constraint .............................................................................. 319
13.8.10. Unique Subject Name Constraint ................................................................ 320
13.8.11. Validity Constraint ....................................................................................... 320
14. Revocation and CRLs 321
14.1. Revocation ............................................................................................................. 321
14.1.1. SSL Client Authenticated Revocation ............................................................ 321
14.1.2. Certificate Revocation Forms ........................................................................ 321
14.2. CMC Revocation .................................................................................................... 322
14.2.1. Setting up CMC Revocation ......................................................................... 322
14.2.2. Testing CMC Revoke ................................................................................... 323
14.3. About CRLs ............................................................................................................ 323
14.3.1. Reasons for Revoking a Certificate ............................................................... 324
14.3.2. Publishing CRLs .......................................................................................... 325
14.3.3. CRL Issuing Points ...................................................................................... 325
14.3.4. Delta CRLs .................................................................................................. 325
14.3.5. How CRLs Work .......................................................................................... 325
14.4. Issuing CRLs .......................................................................................................... 326
14.4.1. Configuring Issuing Points ............................................................................ 328
14.4.2. Configuring CRLs for Each Issuing Point ....................................................... 329
14.4.3. Setting CRL Extensions ................................................................................ 333
14.5. Setting Full and Delta CRL Schedules ..................................................................... 334
14.5.1. Configuring Extended Updated Intervals for CRLs in the Console .................... 335
14.5.2. Configuring Extended Updated Intervals for CRLs in CS.cfg ............................ 336
15. Publishing 337
15.1. About Publishing ..................................................................................................... 337
15.1.1. About Publishers .......................................................................................... 337
15.1.2. About Mappers ............................................................................................ 337
15.1.3. About Rules ................................................................................................. 338
15.1.4. Publishing to Files ........................................................................................ 338
15.1.5. LDAP Publishing .......................................................................................... 338
15.1.6. OCSP Publishing ......................................................................................... 339
15.1.7. How Publishing Works ................................................................................. 339
15.2. Setting up Publishing .............................................................................................. 340
15.3. Configuring Publishers ............................................................................................ 341
15.3.1. Configuring Publishers for Publishing to a File ............................................... 341
15.3.2. Configuring Publishers for Publishing to OCSP .............................................. 343
15.3.3. Configuring Publishers for LDAP Publishing ................................................... 345
15.4. Configuring Mappers ............................................................................................... 346
15.5. Rules ..................................................................................................................... 350
15.5.1. Modifying Publishing Rules for Certificates and CRLs ..................................... 351
15.5.2. Predicates Used in Publishing Rules ............................................................. 355
15.6. Enabling Publishing ................................................................................................ 355 x
15.7. Publishing Cross-Pair Certificates ............................................................................ 357
15.8. Testing Publishing to Files ....................................................................................... 357
15.9. Viewing Certificates and CRLs Published to File ....................................................... 359
15.10. Configuring the Directory for LDAP Publishing ........................................................ 359
15.10.1. Schema ..................................................................................................... 360
15.10.2. Entry for the CA ......................................................................................... 360
15.10.3. Bind DN .................................................................................................... 361
15.10.4. Directory Authentication Method .................................................................. 361
15.11. Updating Certificates and CRLs in a Directory ........................................................ 361
15.11.1. Manually Updating Certificates in the Directory ............................................. 362
15.11.2. Manually Updating the CRL in the Directory ................................................. 363
15.12. Registering and Deleting Mapper and Publisher Plug-in Modules ............................. 363
15.13. Module Reference ................................................................................................. 364
15.13.1. Publisher Plug-in Modules .......................................................................... 364
15.13.2. Mapper Plug-in Modules ............................................................................ 367
15.13.3. Configuring Rule Instances ......................................................................... 373
16. Authentication for Enrolling Certificates 377
16.1. Enrollment Overview ............................................................................................... 377
16.1.1. The Authentication Process .......................................................................... 377
16.2. Agent-Approved Enrollment ..................................................................................... 378
16.2.1. Configuring Agent-Approved Enrollment ........................................................ 378
16.3. Automated Enrollment ............................................................................................. 378
16.3.1. Setting up Directory-Based Authentication ..................................................... 379
16.3.2. Setting up PIN-based Enrollment .................................................................. 380
16.4. Setting up CMC Enrollment ..................................................................................... 384
16.4.1. Setting up the Server for Multiple Requests in a Full CMC Request .................. 385
16.4.2. Testing CMCEnroll ....................................................................................... 385
16.5. Certificate-Based Enrollment ................................................................................... 386
16.5.1. Setting up Certificate-Based Enrollment ......................................................... 387
16.6. Testing Enrollment .................................................................................................. 388
16.7. Managing Authentication Plug-ins ............................................................................ 389
17. User and Group Authorization 391
17.1. About Authorization ................................................................................................. 391
17.1.1. How Authorization Works ............................................................................. 391
17.1.2. Default Groups ............................................................................................ 391
17.2. Creating Users ....................................................................................................... 394
17.3. Setting up a Trusted Manager ................................................................................. 395
17.4. Modifying Certificate System User Entries ................................................................ 398
17.4.1. Changing a Certificate System User's Login Information ................................. 398
17.4.2. Changing a Certificate System User's Certificate ............................................ 399
17.4.3. Changing Members in a Group ..................................................................... 399
17.4.4. Deleting a Certificate System User ................................................................ 399
17.5. Creating a New Group ............................................................................................ 400
17.6. Authorization for Certificate System Users ................................................................ 401
17.6.1. Access Control Lists (ACLs) ......................................................................... 401
17.6.2. Access Control Instructions (ACIs) ................................................................ 401
17.6.3. Changing Privileges ..................................................................................... 401
17.6.4. How ACIs Are Formed ................................................................................. 401
17.6.5. Editing ACLs ................................................................................................ 404
17.7. ACL Reference ....................................................................................................... 406 xi
Administration Guide
17.7.1. certServer.acl.configuration ........................................................................... 406
17.7.2. certServer.admin.certificate ........................................................................... 407
17.7.3. certServer.admin.request.enrollment .............................................................. 407
17.7.4. certServer.auth.configuration ......................................................................... 408
17.7.5. certServer.ca.certificate ................................................................................ 408
17.7.6. certServer.ca.certificates ............................................................................... 409
17.7.7. certServer.ca.configuration ............................................................................ 409
17.7.8. certServer.ca.connector ................................................................................ 410
17.7.9. certServer.ca.clone ....................................................................................... 410
17.7.10. certServer.ca.crl ......................................................................................... 411
17.7.11. certServer.ca.directory ................................................................................ 411
17.7.12. certServer.ca.group .................................................................................... 411
17.7.13. certServer.ca.ocsp ...................................................................................... 412
17.7.14. certServer.ca.profiles .................................................................................. 412
17.7.15. certServer.ca.profile .................................................................................... 412
17.7.16. certServer.ca.requests ................................................................................ 413
17.7.17. certServer.ca.request.enrollment ................................................................. 413
17.7.18. certServer.ca.request.profile ........................................................................ 414
17.7.19. certServer.ca.systemstatus .......................................................................... 414
17.7.20. certServer.ee.certificate .............................................................................. 414
17.7.21. certServer.ee.certificates ............................................................................. 415
17.7.22. certServer.ee.certchain ............................................................................... 415
17.7.23. certServer.ee.crl ......................................................................................... 416
17.7.24. certServer.ee.profile .................................................................................... 416
17.7.25. certServer.ee.profiles .................................................................................. 416
17.7.26. certServer.ee.facetofaceenrollment .............................................................. 417
17.7.27. certServer.ee.request.enrollment ................................................................. 417
17.7.28. certServer.ee.request.facetofaceenrollment .................................................. 417
17.7.29. certServer.ee.request.ocsp .......................................................................... 418
17.7.30. certServer.ee.request.revocation ................................................................. 418
17.7.31. certServer.ee.requestStatus ........................................................................ 418
17.7.32. certServer.general.configuration .................................................................. 419
17.7.33. certServer.job.configuration ......................................................................... 419
17.7.34. certServer.kra.certificate.transport ................................................................ 420
17.7.35. certServer.kra.configuration ......................................................................... 420
17.7.36. certServer.kra.connector ............................................................................. 421
17.7.37. certServer.kra.key ....................................................................................... 421
17.7.38. certServer.kra.keys ..................................................................................... 421
17.7.39. certServer.kra.request ................................................................................. 422
17.7.40. certServer.kra.requests ............................................................................... 422
17.7.41. certServer.kra.request.status ....................................................................... 422
17.7.42. certServer.kra.systemstatus ........................................................................ 423
17.7.43. certServer.log.configuration ......................................................................... 423
17.7.44. certServer.log.configuration.SignedAudit.expirationTime ................................ 424
17.7.45. certServer.log.configuration.fileName ........................................................... 424
17.7.46. certServer.log.content.SignedAudit .............................................................. 425
17.7.47. certServer.log.content ................................................................................. 425
17.7.48. certServer.ocsp.ca ...................................................................................... 426
17.7.49. certServer.ocsp.cas .................................................................................... 426
17.7.50. certServer.ocsp.certificate ........................................................................... 426
17.7.51. certServer.ocsp.configuration ...................................................................... 427 xii
17.7.52. certServer.ocsp.crl ...................................................................................... 427
17.7.53. certServer.profile.configuration .................................................................... 427
17.7.54. certServer.publisher.configuration ................................................................ 428
17.7.55. certServer.registry.configuration ................................................................... 429
17.7.56. certServer.usrgrp.administration .................................................................. 429
18. Automated Notifications 431
18.1. About Automated Notifications ................................................................................. 431
18.1.1. Types of Automated Notifications .................................................................. 431
18.1.2. Determining End-Entity Email Addresses ....................................................... 431
18.2. Setting Up Automated Notifications .......................................................................... 432
18.2.1. Configuring Specific Notifications by Editing the Configuration File ................... 433
18.2.2. Testing Configuration .................................................................................... 434
18.3. Customizing Notification Messages .......................................................................... 435
18.3.1. Notification Message Templates .................................................................... 435
18.3.2. Token Definitions .......................................................................................... 437
19. Automated Jobs 439
19.1. About Automated Jobs ............................................................................................ 439
19.1.1. Setting up Automated Jobs ........................................................................... 439
19.1.2. Types of Automated Jobs ............................................................................. 439
19.2. Setting up the Job Scheduler .................................................................................. 440
19.2.1. Enabling and Configuring the Job Scheduler .................................................. 440
19.3. Setting up Specific Jobs .......................................................................................... 441
19.3.1. Configuring Specific Jobs Using the Certificate Manager Console .................... 442
19.3.2. Configuring Jobs by Editing the Configuration File .......................................... 444
19.3.3. Configuration Parameters of requestInQueueNotifier ...................................... 444
19.3.4. Configuration Parameters of publishCerts ...................................................... 445
19.3.5. Configuration Parameters of unpublishExpiredCerts ....................................... 446
19.3.6. Frequency Settings for Automated Jobs ........................................................ 447
19.4. Managing Job Plug-ins ............................................................................................ 448
19.4.1. Registering or Deleting a Job Module ............................................................ 448
20. Configuring the Certificate System for High Availability 451
20.1. High Availability Overview ....................................................................................... 451
20.1.1. Architecture of a Failover System ................................................................. 451
20.1.2. Load Balancing ............................................................................................ 452
20.2. Cloning Preparation ................................................................................................ 452
20.2.1. Diagnostics .................................................................................................. 453
20.3. Testing the Cloned Configuration ............................................................................. 453
20.4. Clone-Master Conversion ........................................................................................ 454
20.4.1. Converting a Master CA into a Cloned CA ..................................................... 455
20.4.2. Converting a Cloned CA into a Master CA ..................................................... 456
20.4.3. Converting a Master OCSP into a Cloned OCSP .......................................... 457
20.4.4. Converting a Cloned OCSP into a Master OCSP .......................................... 457
A. Certificate and CRL Extensions 459
A.1. Introduction to Certificate Extensions ......................................................................... 459
A.1.1. Structure of Certificate Extensions .................................................................. 460
A.1.2. Sample Certificate Extensions ........................................................................ 461
A.2. Note on Object Identifiers ......................................................................................... 462
A.3. Standard X.509 v3 Certificate Extensions .................................................................. 463
A.3.1. authorityInfoAccess ........................................................................................ 464 xiii
Administration Guide
A.3.2. The authorityKeyIdentifier ............................................................................... 464
A.3.3. basicConstraints ............................................................................................ 465
A.3.4. certificatePolicies ........................................................................................... 465
A.3.5. CRLDistributionPoints .................................................................................... 466
A.3.6. extKeyUsage ................................................................................................. 466
A.3.7. issuerAltName Extension ............................................................................... 467
A.3.8. keyUsage ...................................................................................................... 467
A.3.9. nameConstraints ........................................................................................... 469
A.3.10. OCSPNocheck ............................................................................................ 469
A.3.11. policyConstraints .......................................................................................... 469
A.3.12. policyMappings ............................................................................................ 470
A.3.13. privateKeyUsagePeriod ................................................................................ 470
A.3.14. subjectAltName ........................................................................................... 471
A.3.15. subjectDirectoryAttributes ............................................................................. 471
A.3.16. subjectKeyIdentifier ...................................................................................... 471
A.4. Introduction to CRL Extensions ................................................................................. 472
A.4.1. Structure of CRL Extensions .......................................................................... 472
A.4.2. Sample CRL and CRL Entry Extensions ......................................................... 473
A.5. Standard X.509 v3 CRL Extensions .......................................................................... 474
A.5.1. Extensions for CRLs ...................................................................................... 474
A.5.2. CRL Entry Extensions .................................................................................... 480
A.6. Netscape-Defined Certificate Extensions ................................................................... 482
A.6.1. netscape-cert-type ......................................................................................... 482
A.6.2. netscape-comment ........................................................................................ 482
B. Introduction to Public-Key Cryptography 485
B.1. Internet Security Issues ............................................................................................ 485
B.2. Encryption and Decryption ........................................................................................ 486
B.2.1. Symmetric-Key Encryption ............................................................................. 486
B.2.2. Public-Key Encryption .................................................................................... 487
B.2.3. Key Length and Encryption Strength ............................................................... 488
B.3. Digital Signatures ..................................................................................................... 488
B.4. Certificates and Authentication .................................................................................. 489
B.4.1. A Certificate Identifies Someone or Something ................................................ 489
B.4.2. Authentication Confirms an Identity ................................................................. 490
B.4.3. How Certificates Are Used ............................................................................. 493
B.4.4. Single Sign-on ............................................................................................... 495
B.4.5. Contents of a Certificate ................................................................................ 495
B.4.6. How CA Certificates Establish Trust ............................................................... 498
B.5. Managing Certificates ............................................................................................... 503
B.5.1. Issuing Certificates ........................................................................................ 503
B.5.2. Certificates and the LDAP Directory ................................................................ 504
B.5.3. Key Management .......................................................................................... 504
B.5.4. Revoking Certificates ..................................................................................... 505
C. Enrolling a Certificate in a Cisco Router 507
C.1. Preparation .............................................................................................................. 507
C.2. Configuration ........................................................................................................... 507
C.2.1. Working with chained (subordinate) CAs ......................................................... 509
C.2.2. DEBUGGING: ............................................................................................... 510
Glossary 511 xiv
Index 525 xv
xvi
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 Knowledge
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
This guide contains the following elements:
• Chapter 1, Overview lists Certificate System features, an overview of how the Certificate System works, an architectural overview of Certificate System, and lists the standards used in the product.
• Chapter 2, Installation and Configuration provides step-by-step installation instructions.
• Chapter 3, Administrative Basics provides information and procedures for performing configuration that is common to all subsystems such as using the administrative console, starting and stopping the server, viewing and setting logs, and running self-tests.
• Chapter 4, Certificate Manager provides information and instructions for configuring the Certificate
Manager and an overview of the configuration options.
xvii
About This Guide
• Chapter 6, Online Certificate Status Protocol Responder provides information and instructions for configuring an Online Certificate Status Manager.
• Chapter 7, Data Recovery Manager provides information and an overview of the configuration options for a Data Recovery Manager.
• Chapter 8, Token Processing System describes managing tokens on smart cards through the Token
Processing System (TPS).
• Chapter 9, Token Key Service provides an overview of the Token Key Service (TKS), which manages the master keys required set up a secure communication channel between the TPS and the client.
• Chapter 10, Enterprise Security Client provides an overview of the Enterprise Security Client, a cross-platform client for end users to register and manage keys and certificates on smart cards and tokens.
• Chapter 11, Managing Certificates provides information on requesting, installing, and managing certificates.
• Chapter 12, Managing Tokens provides information on managing user certificates using smart cards.
• Chapter 13, Certificate Profiles provides information and procedures for configuring profiles.
• Chapter 14, Revocation and CRLs provides information and procedures for configuring CRLs and revoking certificates.
• Chapter 15, Publishing provides information and procedures for publishing certificates.
• Chapter 17, User and Group Authorization provides information and procedures for setting up access control lists (ACL) that define authorization, creating users, and assigning users to groups to give them the privileges defined by the group ACLs.
• Chapter 16, Authentication for Enrolling Certificates provides information and procedures for setting up various authentication methods to automate certificate enrollment.
• Chapter 18, Automated Notifications provides information and procedures for configuring notifications.
• Chapter 19, Automated Jobs provides information and procedures for configuring jobs.
• Chapter 20, Configuring the Certificate System for High Availability provides information about clones and configuring the Certificate System for failover support.
• Appendix A, Certificate and CRL Extensions provides general information about certificate and CRL extensions.
• Appendix B, Introduction to Public-Key Cryptography provides general information about public-key cryptography.
xviii
Examples and Formatting
3. Examples and Formatting
3.1. File Locations 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 4 (32 bit) systems. Be certain to use the appropriate commands and files for your platform.
To start the Red Hat Certificate System:
/etc/init.d/rhpki-ca start
Example 1. Example Command
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.
3.2. Using Mozilla LDAP Tools
There is another important consideration with the LDAP utilities. The LDAP tools referenced in this guide are Mozilla LDAP, installed with Red Hat Certificate System in the /usr/dir/mozldap directory on Red Hat Enterprise Linux.
However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP in the /usr/ bin directory. It is possible to use the OpenLDAP commands as shown in the examples, but you must use the -x argument to disable SASL, which OpenLDAP tools use by default.
3.3. Default Port Numbers
After Errata RHSA-2009:0007, Certificate System 7.3 supports port separation. Port separation means that the different subsystem services for administrators, agents, and end entities run on different, userdefined ports.
The default subsystem instances, however, are configured to use a single secure port for all services.
Therefore, any example commands or files reference these default ports.
Susbsystem
CA
RA
DRM
OCSP
TKS
TPS
Table 1. Default Subsystem Ports
SSL Port
9443
12889
10443
11443
13443
7889
Non-SSL Port
9080
12888
10080
11080
13080
7888
3.4. 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.
xix
About This Guide
Formatting Style
Monospace font
Purpose
Monospace is used for commands, package names, files and directory paths, and any text displayed in a prompt.
This type of formatting is used for anything entered or returned in a command prompt.
Monospace with a background
Italicized text
Bolded text
Any text which is italicized is a variable, such as instance_name or hostname . Occasionally, this is also used to emphasize a new term or other phrase.
Most phrases which are in bold are application names, such as
Cygwin , or are fields or options in a user interface, such as a
User Name Here: field or Save button.
Other formatting styles draw attention to important text.
NOTE
A note provides additional information that can help illustrate the behavior of the system or provide more detail for a specific issue.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.
WARNING
A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.
4. Additional Reading
The Certificate System Administrator's Guide describes how to set up, configure, and administer the
Certificate System subsystems and how to configure backend certificate management functions, such as publishing and logging. The Administrator's Guide also describes how to configure subsystems to relate to one another to manage certificates and tokens and how to manage certificates and tokens; this guide is targeted for Certificate System administrators.
The Certificate System Agent's Guide describes how agents — users responsible for processing certificate requests and managing other aspects of certificate management — can use the Certificate
System subsystems web services pages to process certificate requests, key recovery, OCSP requests and CRLs, and other functions.
The documentation for Certificate System includes the following guides:
• Certificate System Administrator's Guide explains all administrative functions for the Certificate
System, such as adding users, creating and renewing certificates, managing smart cards, publishing
CRLs, and modifying subsystem settings like port numbers.
xx
Giving Feedback
• Certificate System Agent's Guide details how to perform agent operations for the CA, RA, DRM, and
TPS subsystems through the Certificate System agent services interfaces.
• Certificate System Command-Line Tools Guide covers the command-line scripts supplied with Red
Hat Certificate System.
• Managing Smart Cards with the Enterprise Security Client explains how to install, configure, and use the Enterprise Security Client, the user client application for managing smart cards, user certificates, and user keys.
• Certificate System Migration Guides cover version-specific procedures for migrating from older versions of Certificate System to Red Hat Certificate System 7.3.
• Release Notes contains important information on new features, fixed bugs, known issues and workarounds, and other important deployment information for Red Hat Certificate System 7.3.
For the latest information about Red Hat Certificate System, including current release notes, complete product documentation, technical notes, and deployment information, see http://www.redhat.com/docs/ manuals/cert-system/ .
5. Giving Feedback
If there is any error in this Administrator's Guide or there is any way to improve the documentation, please let us know. Bugs can be filed against the documentation for Red Hat Certificate System through Bugzilla, http://bugzilla.redhat.com/bugzilla . Make the bug report as specific as possible, so we can be more effective in correcting any issues:
• Select the Red Hat Certificate System product.
• Set the component to Doc - administration-guide .
• Set the version number to 7.3.
• 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 [email protected].
6. Document History
Revision
7.3.15
March 25, 2010 Ella Deon Lackey
Added a section on updating subsystem configuration and updated pkicreate usage examples for changes related to Errata RHBA-2010:0170.
Revision
7.3.14
August 25, 2009 Ella Deon Lackey xxi
About This Guide
Rewrote the section on issuing delta and full CRLs, per Bugzilla #510132.
Changed PK12Export to pk12util in the cloning configuration overview, per Bugzilla #519058.
Revision
7.3.13
June 13, 2009 Ella Deon Lackey [email protected]
Removing references to the CS SDK and Java SDK, per Bugzilla #491405.
Revision
7.3.12
March 7, 2009 Ella Deon Lackey [email protected]
Corrected parameter examples for policyset.set1.p6.default.params.userExtOID, per Bugzilla
#476321.
Revision
7.3.11
February 27, 2009 Ella Deon Lackey [email protected]
Removed incorrect note about useing certutil to process a certificate request, per Bugzilla #241972.
Revision
7.3.10
February 22, 2009 Ella Deon Lackey [email protected]
Removed all references to certificate renewal, per Bugzilla #325361 and #433360.
Corrected error about custom logs, per Bugzilla #449847.
Minor edits for the term "policy," per Bugzilla #472598.
Revision 7.3.9
February 21, 2009 Ella Deon Lackey [email protected]
Fixed Bugzilla #443534, updating key size recommendations in the SSL/TLS section of the overview.
Fixed Bugzilla #446718, correcting some typos in the key archival section.
Revision 7.3.8
February 7, 2009 Ella Deon Lackey [email protected]
Removed section on renewing certificates through the console, since this is not supported.
Revision 7.3.7
January 29, 2009 Ella Deon Lackey [email protected]
Added small note on the new LDAP publishing password configuration parameter to the "Enabling
Publishing" section.
Added information on configuring port separation.
Updated pkicreate example to include a port separation example.
Updated examples and formatting section to define default ports used in examples.
Revision 7.3.6
November 4, 2008 Ella Deon Lackey [email protected]
Corrected the CRL Issuing Points Extension Default parameter descriptions for IssuerName_ and
IssuerType_ per Bugzilla #442405.
Revision 7.3.5
September 10, 2008 Ella Deon Lackey [email protected]
Expanding and clarifying the process for configuring symmetric key changeover and adding a new parameter to use to configure it, per Bugzilla #245267.
Revision 7.3.4
July 24, 2008 Ella Deon Lackey [email protected]
Edits to token management sections per Bugzilla 455345.
Revision 7.3.3
July 16, 2008 Ella Deon Lackey [email protected]
Added information for using the GET method to post OCSP requests and a section for debug logging for Errata RHSA 2008:0577.
Revision 7.3.2
July 1, 2008 Ella Deon Lackey [email protected]
Changes to the User Supplied Extension Default section for Erratum RHSA 2008:0500.
Revision 7.3.1
Sun Aug 19 2007
Resolves Bugzilla 247209
David O'Brien xxii
Chapter 1.
Overview
This chapter provides an overview of Red Hat Certificate System, a highly configurable set of software components and tools for creating, deploying, and managing certificates. Based on open standards for certificate management, Certificate System provides a complete, customizable, robust, scalable, and high-performance certificate management solution for public-key infrastructure (PKI), extranets, and intranets.
1.1. Features
This section discusses the Certificate System features.
1.1.1. Subsystems
The Certificate System is installed on each host running a Certificate System subsystem. The subsystems on that host are then installed with a default configuration covering basic administrative tasks like logging and containing configurable, subsystem-specific plug-in modules. More than one subsystem can be installed on each host, or multiple instances of one subsystem can be installed on the same host or on different hosts.
The Certificate System has five highly-configurable subsystems, which provide flexibility in designing the PKI. The five subsystems that comprise Certificate System are as follows:
• The Certificate Manager is the subsystem that provides Certificate Authority functionality for issuing, revoking, and publishing certificates and creating and publishing CRLs. See Chapter 4, Certificate
Manager for details.
• The Online Certificate Status Manager is an optional subsystem that provides OCSP responder services, which means it stored CRLs for CAs and can distribute the load for verifying certificate status. See Chapter 6, Online Certificate Status Protocol Responder for details.
• The Data Recovery Manager (DRM) is an optional subsystem that provides private encryption key storage and retrieval. See Chapter 7, Data Recovery Manager for details.
• The Token Key Service (TKS) manages one or more master keys required to set up secure channels directly to the token management system. The privileged operations such as key generation can only be requested on the tokens through a secure channel.
• The Token Processing System (TPS) provides the registration authority functionality in the token management infrastructure and establishes secure channels between the Enterprise Security Client and the back-end subsystems. See Chapter 8, Token Processing System for more information on using the TPS to manage tokens.
The subsystems are highly integrated with each other depending on the deployment scenario and use.
OCSP and CA instances work together for CRL publishing and certificate verification. CA and DRM instances work together for key recovery and archival. Smart card tokens, which processed through a user interface called the Enterprise Security Client , are managed by the TPS. The TPS, however, is configured to work with at least two essential subsystem instances, a TKS to generate keys and a CA to process token operations. A TPS can also be configured to use a DRM for server-side key generation and key archival and recovery.
1
Chapter 1. Overview
1.1.2. Interfaces
Each of the subsystems contains interfaces for interaction with various portions of the subsystem. The
CA, DRM, OCSP, and TKS subsystems have an administrative console to manage and configure the subsystem itself, such as adding users and certificates and viewing logs. The CA, OCSP, DRM, and
TPS subsystems have an agent interface specific to that subsystem which allows agents to perform the tasks assigned to them. A Certificate Manager has an end-entity services interface for end entities to enroll in the PKI.
NOTE
Not all subsystems have all types of interfaces. The TKS subsystem does not have an agent interface. The TPS subsystem does not have an administrative console, but rather has administrative functions that are accessible through the HTML agent services page.
Only a CA has an end-entities page.
The three types of interfaces are described as follows:
• Administrative Interface - The administrative interface, a Java ™ application called the Console, provides a GUI interface for performing administrative tasks and configuring plug-in modules. This interface is similar for subsystems. The administrative interface requires user ID and password authentication and can be configured for SSL certificate-based authentication.
• Agent Services Interface - The agent services interface is a customizable HTML interface used to perform agent tasks, such as editing and approving requests for issuing or revoking certificates. The agent services interface for a CA, DRM, OCSP, and TPS are specific to those subsystems.
• End-Entity Services Interface - The end-entity interface is a customizable HTML interface used by end entities to enroll in the PKI, request certificates, revoke certificates, and pick up issued certificates. It contains forms for different types of enrollments and for enrolling different types of end entities. The Certificate Manager has an end-entity services interface; the other subsystems do not.
1.1.3. Logging
The Certificate System and each subsystem produce extensive system and error logs that record system events so that the systems can be monitored and debugged. All log records are stored in the local file system for quick retrieval. Logs are configurable, so logs can be created for specific types of events and at the desired logging level. See Section 3.9, “Logs” for details.
1.1.3.1. Signing Logs
Certificate System allows logs to be signed digitally before archiving them or distributing them for auditing. This feature enables log files to be checked for tampering after being signed. See
Section 3.9.10, “Signing Log Files” for details.
1.1.4. Auditing
The Certificate System maintains audit logs for all events, such as requesting, issuing and revoking certificates and publishing CRLs. These logs are then signed. This allows authorized access or activity to be detected. An outside auditor can then audit the system if required. The assigned auditor user account is the only account which can view the signed audit logs. This user's certificate is used to sign and encrypt the logs. Audit logging is configured to specify the events that are logged. See
Section 3.9.13, “Signed Audit Log” for details.
2
Self-Tests
1.1.5. Self-Tests
The Certificate System provides the framework for system self-tests that are automatically run at startup and can be run on demand. A set of configurable self-tests are already included with the
Certificate System. See Section 3.10, “Self-Tests” for details.
1.1.6. Authorization
Certificate System users can be assigned to groups, and they then have the privileges of whichever group they are members. A user only has privileges for the instance of the subsystem in which the user is created and the privileges of the group to which the user is a member.
The Certificate System provides an authorization framework for creating groups and assigning access control to those groups. The default access control on preexisting groups can be modified, and access control can be assigned to individual users and IP addresses. Access points for authorization have been created for the major portions of the system, and access control rules can be set for each point.
The Certificate System is configured by default with four user types with different access levels to the system:
• Administrators , who can perform any administrative or configuration task.
• Agents , who can edit and approve requests.
• Auditors , who can view and configure audit logs.
• Trusted managers , which are subsystems with trusted relationship with another subsystem.
Additionally, when a security domain is created, the CA subsystem which hosts the domain is automatically granted the role of Security Domain Administrator , which gives the subsystem the ability to manage the security domain and the subsystem instances within it. Other security domain administrator roles can be created for the different subsystem instances. These roles are described in
Section 4.4.2, “Security Domain Roles” .
1.1.7. Security-Enhanced Linux Support
Security-enhanced Linux, or SELinux, is a collection of mandatory access control rules which are enforced across a system to restrict unauthorized access and tampering. These mandatory access controls limit users and applications to the lowest amount of access possible for them to operate.
Processes or applications, such as CGIs, may have special policies in place to enable them to run under the restricted access rules.
The Certificate System is able to run under SELinux configuration, which enhances the security of the information created and maintained by the Certificate System. All Certificate System subsystems can be installed and run with SELinux policies fully enforced. By default, the Certificate System subsystems run unconfined by SELinux policies.
1.1.8. Authentication
Certificate System provides authentication options for certificate enrollment. These include agentapproved enrollment, in which an agent processes the request, and automated enrollment, in which an authentication method is used to authenticate the end entity and then the CA automatically issues a certificate. CMC enrollment is also supported, which automatically processes a request approved by an agent.
3
Chapter 1. Overview
1.1.9. Registration Authority
A Registration Authority (RA) is a subsystem that accepts enrollment requests and authenticates them in a local context (e.g., a department of an organization, or an organization within an association).
Upon the successful authentication, the RA then forwards the enrollment request to the designated
Certificate Authority (CA) to generate the certificate.
Depending on the type of enrollment, an RA can be set up with the appropriate authentication plugin to authenticate the request in an automated fashion. Alternatively, the RA has a local request queue where requests can be stored and reviewed by local RA agents for manual authentication.
1.1.10. SCEP
SCEP (Simple Certificate Enrollment Protocol) is a protocol designed by Cisco. It is designed to specify a way for a router to communicate with an RA/CA for enrollment.
Normally, a router installer enters the RA's URL and a Challenge password (sometimes referred as a one-time PIN) into the router and issues a command to initiate the enrollment. The router then communicates with the RA using the SCEP protocol to:
• Retrieve CA requests
• Submit a PKCS#10 request
• Retrieve the issued certificate
• Queries the request status if the request is pending
SCEP suggests two modes of operation: RA mode; and CA mode. In the RA mode, the enrollment request is encrypted with the RA signing certificate. In the CA mode, the request is encrypted with the
CA signing certificate.
The current implementation of RA and CA only supports the CA mode.
1.1.11. Certificate Issuance
The Certificate System supports enrolling and issuing certificates and processing certificate requests from a variety of end entities, such as web browsers, servers, and virtual private network (VPN) clients. Issued certificates conform to X.509 version 3 standards.
The Certificate Manager can issue certificates with the following characteristics:
• Certificates that are X.509 version 3-compliant
• Unicode support for the certificate subject name and issuer name
• Support for empty certificate subject names
• Support for customized subject name components
• Support for customized extensions
Additionally, smart cards can have certificates enrolled and maintained through the Enterprise Security
Client. The Enterprise Security Client communicates directly with the TPS system, which, in turn, processes requests through the CA and DRM subsystems. Certificates are generated automatically
4
Certificate Profiles when the token is first formatted, and all additional certificates belonging to the user can be imported onto the token. For more information about certificates being issued through the Enterprise Security
Client, see the Certificate System Enterprise Security Client Guide , which is available at http:// redhat.com/docs/manuals/cert-system/ . For information about configuring subsystems to manage smart cards, see Chapter 8, Token Processing System .
1.1.12. Certificate Profiles
The Certificate System uses certificate profiles to configure the content of the certificate, the constraints for issuing the certificate, the enrollment method used, and the input and output forms for that enrollment. A single certificate profile is associated with issuing a particular type of certificate.
A set of certificate profiles is included for the most common certificate types; the profile settings can be modified. Certificate profiles are configured by an administrator, and then sent to the agent services page for agent approval. Once a certificate profile is approved, it is enabled for use. A dynamically-generated HTML form for the certificate profile is used in the end-entities page for certificate enrollment, which calls on the certificate profile. The server verifies that the defaults and constraints set in the certificate profile are met before acting on the request and uses the certificate profile to determine the content of the issued certificate.
See Chapter 13, Certificate Profiles for details.
1.1.13. CRLs
The Certificate System can create certificate revocation lists (CRLs) from a configurable framework which allows user-defined issuing points so a CRL can be created for each issuing point. Delta
CRLs can also be created for any issuing point that is defined. CRLs can be issued for each type of certificate or for a specific subset of a type of certificate. The extensions used and the frequency and intervals when CRLs are published can all be configured.
The Certificate Manager issues X.509-standard CRLs. A CRL can be automatically updated whenever a certificate is revoked or at specified intervals. See Chapter 14, Revocation and CRLs for details.
1.1.14. Publishing
Certificates can be published to files and an LDAP directory, and CRLs to files, an LDAP directory, and an OCSP responder. The publishing framework provides a robust set of tools to publish to all three places and to set rules to define with more detail which types of certificates or CRLs are published where. The default publishing modules can be enabled, disabled, and configured. See Chapter 15,
Publishing for details.
1.1.15. Notifications
The notification feature sets up automated messages when a particular event occurs, such as when a certificate is issued or revoked. The notification framework comes with default modules that can be enabled and configured. See Chapter 18, Automated Notifications for details.
1.1.16. Jobs
The jobs feature sets up automated jobs that run at defined intervals. See Chapter 19, Automated
Jobs for details.
5
Chapter 1. Overview
1.1.17. Dual Key Pairs
The Certificate System supports generating dual key pairs, separate key pairs for signing and encrypting email messages and other data. To support separate key pairs for signing and encrypting data, dual certificates are generated for end entities, and the encryption keys are archived. If a client makes a certificate request for dual key pairs, the server issues two separate certificates.
1.1.18. HSMs and Crypto Accelerators
The Certificate System supports hardware security modules (HSMs) and crypto accelerators provided by third-party vendors of PKCS #11-compliant tokens.
The server can be configured to use different PKCS #11 modules to generate and store key pairs
(and certificates) for all Certificate System subsystems � CA, DRM, OCSP, TKS, and TPS. PKCS #11 hardware devices also provide key backup and recovery features for the information stored on the hardware token. Refer to the PKCS #11 vendor documentation for information on retrieving keys from the tokens.
1.1.19. Support for Open Standards
The Certificate System supports open standards and protocols so that its subsystems can communicate across a heterogeneous computing environment. Some of the standards and areas which the Certificate System supports include the following:
• Formulates, signs, and issues industry-standard X.509 version 3 public-key certificates; version 3 certificates include extensions that make it easy to include organization-defined attributes. These certificates are used for extranet and Internet authentication.
• Supports the RSA public-key algorithm for signing and encryption, and the MD2, MD5, SHA-1,
SHA-256, and SHA-512 algorithms for hashing.
• Supports signature key lengths of up to 4096 bits for RSA.
• Supports multiple message formats, such as KEYGEN/SPAC, CRMF/CMMF, and PKCS #10 and
CMC for certificate requests. All requests are delivered to the Certificate System over HTTP or
HTTPS.
• Supports certificate formats for SSL-based client and server authentication, secure Multipurpose
Internet Mail Extensions (S/MIME) message signing and encryption, and VPN clients.
• Supports generating and publishing CRLs conforming to X.509 version 1 and 2.
• Publishes certificates and CRLs to any LDAP-compliant directory over LDAP and HTTP/HTTPS connections.
• Publishes certificates and CRLs to a flat file for importing into other resources. For example, the sample code for Flat File CRL and certificate publisher can be customized to store certificates and
CRLs in an Oracle RDBMS.
• Publishes CRLs to an online validation authority (or OCSP responder) for real-time certificate verification by OCSP-compliant clients.
6
How the Certificate System Works
1.2. How the Certificate System Works
The Certificate System manages certificates through a flexible, scalable system for issuing and publishing certificates; creating and publishing CRLs; and providing key storage and retrieval capabilities.
The Certificate Manager is the central point of the Certificate System; this subsystem accepts requests, generates and manages certificates, and generates and manages CRLs and revoked certificates. The Online Certificate Status Manager handles validity requests for certificates issued by the Certificate Manager, informing clients whether the certificate is still in effect and valid or has been revoked or expired. The Data Recovery Manager (DRM) stores keys and certificates and can recover the keys if a token is lost or damaged, so that encrypted information can still be accessed. The Token
Key Service and Token Processing System work together to manage tokens which contain the userspecific keys and certificates.
The following sections describe the subsystems in more detail.
1.2.1. About the Certificate Manager
The Certificate Manager subsystem provides the capability of a Certificate Authority (CA). It can issue, revoke, and publish certificates, as well as compile and publish CRLs. Since the Certificate Manager acts as a CA, it can be configured as a self-signing CA, where it is the root CA, or it can act as a subordinate CA, where it obtains its signing certificate from another CA.
1.2.1.1. Certificate Manager Flexibility and Scalability
Multiple CAs can be configured to form a vertical or horizontal chain of CAs. A vertical hierarchy has a root CA (that is either self-signing or subordinate to a public CA) and then one or more CAs subordinate to this root CA. The subordinate CAs can have more CAs below them, forming a chain of
CAs. A horizontal arrangement has a CA which is duplicated, or cloned, so that two CAs are set up in an identical manner and use the same CA signing certificate but issue certificates from a different set of serial numbers.
The different possible Certificate Manager deployments provide flexibility to the PKI through the following features:
• Configuration as either a root or subordinate CA
• High-availability cloning to allow CAs with identical functionality, keys, and certificates to issue certificates with different sets of serial numbers.
1.2.1.1.1. Root or Subordinate CA
The Certificate System CA can function as a root CA , meaning that the server signs its own CA signing certificate as well as other CA signing certificates, creating an organization-specific CA hierarchy. The server can alternatively be configured as a subordinate CA , meaning the server's CA signing key is signed by another CA in an existing CA hierarchy. See Section 2.1.3, “Self-Signed Root
CA or Subordinate CA” for details.
1.2.1.1.2. Linked CA
The Certificate System Certificate Manager can function as a linked CA , chaining up to many thirdparty or public CAs for validation; this provides cross-company trust, so applications can verify
7
Chapter 1. Overview certificate chains outside the company certificate hierarchy. A Certificate Manager is chained to a thirdparty CA by requesting the Certificate Manager's CA signing certificate from the third-party CA.
1.2.1.1.3. CA Cloning
Instead of creating a hierarchy of root and subordinate CAs, it is possible to create multiple clones of a Certificate Manager and configure each clone to issue certificates that fall within a distinct range of serial numbers. Because clone CAs and original CAs use the same CA signing key and certificate to sign the certificates they issue, the issuer name in all the certificates is the same. Clone CAs and the original Certificate Managers issue certificates as if they are a single CA. These servers can be placed on different hosts for high availability failover support. See Chapter 20, Configuring the Certificate
System for High Availability for information on configuring clones for failover in a Certificate System system.
1.2.1.2. Cross-Pair Certificates
It is possible to create a trusted relationship between two separate CAs by issuing and storing crosssigned certificates between these two CAs. By using cross-signed certificate pairs, certificates issued outside the organization's PKI can be trusted within the system.
1.2.1.3. Certificate Manager Functionality
The Certificate Manager issues and revokes certificates when it receives signed requests. These requests can come from its own agents (users who are assigned privileges to approve enrollment and revocation requests) or from a third-party application that uses its agent certificate (this agent certificate must be set up for CMC enroll or revoke with the Certificate Manager).
The Certificate Manager also compiles lists of revoked certificates, called certificate revocation lists
(CRLs), that it can publish to files, an LDAP directory, or an OCSP service.
The Certificate Manager maintains a database of issued certificates and processed requests, so that it can track expiration and revocation.
1.2.1.4. Types of Certificates
Certificate System can issue and manage the following certificates:
• CA signing certificates
• OCSP signing certificates
• Cross-signed pair certificates
• SSL server certificates
• VPN client certificates
• End user certificates
This list is not comprehensive; many other types of certificates can be issued by the Certificate
System.
8
How the Certificate Manager Works
1.2.1.5. Revocation and CRLs
Revoking certificates can be initiated either by an agent or by the end user. An administrator can also revoke the certificates of any of the subsystems or agents.
The Certificate System also supports CMC revocation. When the CMCAuth plug-in is enabled, CMC enrollment and CMC revocation are both enabled. CMC revocation sends signed revocation requests that are automatically processed.
The Certificate System can create certificate revocation lists (CRLs) that it can publish to files, an
LDAP directory, or to an OCSP responder. It is also possible to create CRLs through certificate issuing points, which allows more than one CRL to be defined by the issuing point. Lastly, creating delta CRLs creates a list which contains only the certificates that were revoked since the last CRL was produced.
See Chapter 14, Revocation and CRLs for details.
1.2.2. How the Certificate Manager Works
The next sections describe the different operations of the Certificate Manager and the associated processes and configuration settings.
1.2.2.1. Accepting Enrollment Requests
The Certificate Manager server has an end-entities page with the forms for different types of certificates and users. This interface can be customized to limit the forms that are available, change the appearance of the pages, or add or delete fields. Certificate requests that come through the
Certificate Managers end-entities page are processed by the Certificate Manager. If it is an agentapproved enrollment, an agent of the Certificate Manager must approve the request. If it is an automated enrollment, the request is approved if the end entity supplies the correct information and authenticates successfully.
1.2.2.2. Authentication Methods
Authentication plug-ins set up automated enrollment and configure the methods for the end entity to authenticate itself. For agent-approved enrollment, the agent approves the request by default.
Each end-entity form is associated with a particular authentication method which is configured in the certificate profile, either one of the automated methods or the agent-approved method. The Certificate
Manager processes the request according to the method associated with the form.
1.2.2.3. Processing Requests
When the Certificate Manager processes requests from its end-entities page, it first considers the authentication method. If it is an agent-approved authentication method, the request is queued in the agent services interface where it awaits agent approval. The agent can change some aspects of the certificate that will be issued and can approve, deny, or change the status of the request. For an automated enrollment, the CA authenticates the user and continues processing the request.
The Certificate Manager next evaluates the request to ensure that it meets the certificate profile set for this type of enrollment.
Certificate profiles connect an authentication method and certificate type to a set of constraints and certificate content definitions (defaults). A single module can be configured for a type of certificate to use a specific authentication method and set constraints for the certificate, as well as defining the
9
Chapter 1. Overview certificate content. The default certificate profiles can be modified and new custom modules created.
See Chapter 13, Certificate Profiles for details.
If the policies in the certificate profile are not met, the request is rejected. If they are met, the certificate is issued.
1.2.2.4. Creating Certificates
The Certificate Manager issues certificates when it receives signed requests either from agents (users who are assigned privileges to approve enrollment and revocation requests) or from a third-party application that is set up for CMC enroll with the Certificate Manager.
The Certificate Manager creates the certificate using the information in the request and from the certificate profile that are set.
1.2.2.5. Publishing Certificates
Certificates can be published to a file, an LDAP directory, or OCSP responder. Configuring publishing sets rules to determine which certificates are published using which method and where they are published. See Chapter 15, Publishing for details.
1.2.2.6. Key Archival
If a CA is configured with a DRM, then the private keys are archived in the DRM during certificate enrollment. See Chapter 7, Data Recovery Manager for details.
1.2.2.7. Storing Certificate Requests and Certificates
When it issues a certificate, the Certificate Manager stores both the certificate and the certificate request in its internal database.
1.2.2.8. Revoking Certificates
End entities can submit certificate revocation requests in the end-entities page if they lose their private key or if their certificate has been compromised. When an end entity requests a revocation, the request is sent to the agent services interface for agent approval.
An agent can revoke a certificate if the owner of the certificate is unwilling or unable to do so.
When the certificate is revoked, it is marked revoked in the internal database and in the publishing system. The certificate is added to the certificate revocation list (CRL) produced by the Certificate
Manager. See Chapter 14, Revocation and CRLs for details.
1.2.2.9. CRLs
Whenever a certificate is revoked, any CRLs that are set up are edited and updated in the internal database. It is published to a file, an LDAP directory, or an OCSP responder, if these services have been set up. The CA can be configured to issue CRLs and define CRL issuing points that define which certificates go into each CRL.
CRL configuration grants flexibility to define which CRL is published where, the extensions contained in a CRL, and the frequency and intervals when a CRL are published. Publishing delta CRLs publishes a list of only those certificates that have been revoked since a certain date. See Chapter 14,
Revocation and CRLs for details.
10
Data Recovery Manager
1.2.3. Data Recovery Manager
The Data Recovery Manager (DRM) is an optional subsystem that acts as a Key Recovery Authority.
When configured in conjunction with a Certificate Manager, the DRM stores private encryption keys as part of the certificate enrollment process. Private encryption keys archived in a DRM are recovered in a PKCS #12 file only after multiple key recovery agents approve the recovery request.
NOTE
The DRM archives encryption keys. It does not archive signing keys, since archiving signing keys undermines the non-repudiation properties of signing keys.
1.2.3.1. Key Archival
If a DRM is set up as part of the PKI, the private encryption key for an end entity is requested and stored when the enrollment request is made.
1.2.3.2. Key Retrieval
If a DRM is set up as part of the PKI, the users' private encryption keys can be retrieved to decrypt messages or other documents that have been encrypted with the private encryption key.
Version 7.1 of Red Hat Certificate System introduced a new m-of-n, ACL-based recovery scheme to replace the old m-of-n, secret-splitting-based recovery scheme.
In the old scheme, the password for the storage token was split and protected by individual recovery agent passwords. This made it hard to access the storage private, but it did not allow CS to fully leverage the key protection facility provided by the underlying hardware token.
In the new scheme, CS uses its existing access control scheme to ensure recovery agents are appropiately authenticated via SSL, and ensures that the agent belongs to the specific recovery agent group. The recovery request is executed only when m-of-n recovery agents have granted authorization to the request.
By default, the DRM sets up a 1-of-1 ACL-based recovery scheme, and the agent must belong to the group "Data Recovery Manager Agents". You can change the scheme by modifying the appropriate parameters in the CS.cfg
file. Refer to Chapter 7, Data Recovery Manager for more information on this topic.
1.2.4. Online Certificate Status Manager
The Online Certificate Status Manager is an optional subsystem that acts as an OCSP service.
Although the Certificate Manager is configured with an internal OCSP service, an external OCSP responder is offered as a separate subsystem to provide OCSP service outside a firewall while the
Certificate Manager resides inside a firewall or to balance the load of requests on the Certificate
Manager.
The Online Certificate Status Manager performs the task of an online certificate validation authority by enabling OCSP-compliant clients to verify certificate status. (An online certificate-validation authority is often referred to as an OCSP responder.) The Online Certificate Status Manager can also receive
CRLs from multiple Certificate Managers, and clients can query the Online Certificate Status Manager for the revocation status of certificates issued by all the Certificate Managers.
11
Chapter 1. Overview
When an OCSP responder is set up with a Certificate Manager, and publishing is set up to the OCSP responder, CRLs are published to the OCSP responder when they are issued or updated.
1.2.5. Token Key Service
The Token Key Service (TKS) provides secure channels for communication between smart card tokens and a TPS instance. It creates these channels by using a pre-generated master key to derive secret keys that are specific for each individual token enrolled through the TPS. These secure channels allow the commands and keys sent to the smart card to be encrypted, and the shared secrets between tokens and the TKS help the smart card validate that the privileged commands sent to it are from the appropriate TPS. During server-side key generation, the TKS also generates transport keys which wrap, or encrypt, the user's private keys to secure them during transit.
1.2.6. Token Processing System
The Token Processing System (TPS) is the conduit between the Enterprise Security Client, the user interface for end users to manage their smart cards, and the other subsystems in the Certificate
System. It automatically initiates certificate enrollments with the CA and key recovery through the
DRM. It uses the TKS to generate and store master keys used to derive token-specific secret keys.
1.3. Deployment Scenarios
1.3.1. Single Certificate Manager
Some deployments require a single Certificate Manager to handle all end-entity interactions. No DRM is necessary to provide key archival or recovery capabilities, and no OCSP is required for certificate verification. This Certificate Manager can use a signing certificate issued by a public certificate authority or its self-signed CA signing certificate to sign all the certificates it issues.
12
Certificate Manager and DRM
Figure 1.1. Single-Root Certificate Manager
Figure 1.1, “Single-Root Certificate Manager” shows the relationships between a single Certificate
Manager, end entities, and a publishing directory. The Certificate Manager can publish both end-entity certificates and CRLs to a directory.
1.3.2. Certificate Manager and DRM
In a more complex scenario, the organization requires key archival and recovery capabilities along with the CA; for example, when encrypted mail is widely used, the organization risks data loss if it is unable to recover encryption keys. In this case, the Certificate System deployment has both the
Certificate Manager and a DRM.
To add key storage and recovery, a DRM can be installed on the same machine or on a different machine. Figure 1.2, “Certificate Manager and DRM in Different Instances” illustrates the relationship between a DRM and a Certificate Manager. All communication between the Certificate Manager and the DRM takes place over HTTPS.
13
Chapter 1. Overview
Figure 1.2. Certificate Manager and DRM in Different Instances
NOTE
The DRM is intended for archival and recovery of private encryption keys only. Therefore, end entities must use either a browser that supports dual-key generation.
When determining the location of a DRM, consider possible firewall interactions, the physical security required for each subsystem, and the physical location of the Certificate Manager agent, DRM agent, and other people responsible for administering the Certificate Manager and recovering keys.
Like a Certificate Manager, a DRM has special physical security requirements, since a compromised
DRM has devastating security consequences for the entire PKI. Consider keeping the DRM in a special locked room or building; this consideration can affect the deployment strategy.
1.3.3. Cloned Certificate Manager
A cloned Certificate Manager uses the same CA signing key and certificate as another Certificate
Manager, the master Certificate Manager. Since each Certificate Manager issues certificates with serial numbers in a restricted range, all of the servers together act as a single CA operating in several server processes.
The advantage of cloning is that it distributes the Certificate Manager's load across several processes or even several physical machines. For a CA with a high enrollment demand, the distribution gained from cloning allows more certificates to be signed and issued in a given time interval.
14
Smart Card Enrollment
A cloned Certificate Manager has the same features, such as agent and end-entity gateway functions, of a regular Certificate Manager.
1.3.4. Smart Card Enrollment
Most certificates are enrolled through the CA. This is useful for certificates enrolled through an application such as a web browser or web server. For managing smart cards, or tokens, there is an additional Certificate System client, Enterprise Security Client, which manages all maintenance operations for certificates and keys stored on smart cards.
The Enterprise Security Client communicates directly with a TPS instance. The TPS subsystem handles token-based certificate functions, and the TKS manages keys which protect the secure communication between the TPS subsystem and the Enterprise Security Client. The TKS and TPS subsystems work together to support all token operations, such as enrollment, through the Enterprise
Security Client. Additionally, the TPS subsystem can be configured to use the DRM subsystem to handle server-side key generation and key archival and recovery. The interactions between the TPS,
TKS, DRM, and CA subsystems to process token operations through the Enterprise Security Client are shown in Figure 1.3, “Token Management Configuration” .
For more information on managing subsystems for smart card tokens, see Chapter 8, Token
Processing System . For more information on performing token operations for users, see the Certificate
System Enterprise Security Client Guide , which is available at http://redhat.com/docs/manuals/certsystem/ .
Figure 1.3. Token Management Configuration
1.4. System Architecture
Figure 1.4, “Certificate System Architecture” shows the structure of the Certificate System; this structure is explained in more detail in the following sections.
15
Chapter 1. Overview
Figure 1.4. Certificate System Architecture
16
Certificate System Instance
1.4.1. Certificate System Instance
Within the Certificate System component, a set of common modules, which can all be extended with custom Java ™ plug-ins, are provided for all subsystems. Although some may not be used in the default setting, they are available for further customization.
• Authentication.
• Authorization. The default is access control from the internal LDAP database.
• ACL evaluators. The default is to use user/group evaluators.
• Certificate profiles, which have customizable extensions and constraints.
• The job scheduler, which can be edited to control routinely-scheduled events.
• Email notification.
• Event listeners.
• Publishing. Both the publisher and mapper can be modified.
• Logging, including signed audit logs. The logging mechanism can be extended.
• Self-tests. Both the start-up and manually-initiated self-tests can be extended.
• Servlets, depending on subsystem installation.
• Password quality checker.
1.4.2. HTTP Engine
The Certificate System employs Red Hat Fortitude as its HTTP engine; this runs secure Tomcat for the CA, OCSP, TKS, and DRM subsystems and secure Apache for TPS. Fortitude supports the subsystem instance HTTP interfaces and provides the entry point for all users and applications to access Certificate System subsystem functions through the different user interfaces: administrative console, agent services, and end-entities pages. The subsystem pages are accessed over HTTP, but they are created by subsystem-specific servlets contained in the Certificate System. While the
HTTP engine provides the connection entry points, Certificate System completes the interfaces by providing the servlets specific to each interface. These servlets can return data in HTML or XML formats, making it easier for system administrators to write scripts which interact with these servlets.
For more information, see Section 3.8, “Using Java Servlets” .
1.4.3. User Interfaces
Each of the subsystems contains interfaces for interacting with other parts of the subsystem. Four subsystems (CA, DRM, OCSP, and TPS) have an agent interface for agents to perform the tasks assigned to them; four subsystems (CA, DRM, OCSP, and TKS) also have an administrative console for managing that instance, such as adding users and viewing logs. A CA subsystem also has an endentity services interface for users to enroll in the PKI.
• End-Entities Interface . The CA java servlets in the end-entities page process the HTML forms submitted through the HTTP entry point. From the information in these forms, the servlets enroll and revoke certificates for users and allow users to retrieve issued certificates.
17
Chapter 1. Overview
NOTE
The OCSP, DRM, TKS, and TPS subsystems do not have end-entity pages.
• Agent Services Interface . The agent services page java servlets process HTML form submitted through the agent services HTTP pages. From the information in each submitted form, the agent servlets allow agents to perform agent tasks, such as editing and approving requests for issuing or revoking certificates and approving certificate profiles.
NOTE
The TPS interface is different than the agent services pages for the other three subsystems. This HTML interface also functions as the administrative interface in place of a Java
™
console.
• Administrative Interface (Subsystem Console) . The administrative java servlets process commands from the administrative entry-point. From the information supplied in the commands, the administration servlets allow administrators to perform administrative tasks and configure plug-in modules. This interface is similar for the CA, DRM, OCSP, and TKS subsystems. While there are some common configuration types, there are different plug-ins available, depending on the kind of subsystem. The auditor shares the same interface with the administrator, except with the ability to view all configurations and logs, including audit logs; administrators cannot view audit logs.
NOTE
The TPS subsystem does not have an administrative console; administrator tasks are performed through an HTML interface accessed through the agent services URL.
These servlets can return data in HTML or XML formats, making it easier for system administrators to write scripts which interact with these servlets. For more information, see Section 3.8, “Using Java
Servlets” .
1.4.4. JSS and the JNI Layer
JSS provides a Java
™
interface for security operations performed by NSS. JSS and higher levels of the Certificate System architecture are built with the Java ™ Native Interface (JNI), which provides binary compatibility across different versions of the Java ™ Virtual Machine (JVM). This design allows customized subsystem services to be compiled and built once and run on a range of platforms. JSS supports most of the security standards and encryption technologies supported by NSS. JSS also provides a pure Java
™
interface for ASN.1 types and BER-DER encoding. JSS documentation is available on-line at http://www.mozilla.org/projects/security/pki/jss/index.html
.
1.4.5. NSS
Network Security Services (NSS) is a set of libraries designed to support cross-platform development of security-enabled communications applications. Applications built with the NSS libraries support the SSL protocol for authentication, tamper detection, and encryption, as well as PKCS #11 for
18
PKCS #11 cryptographic token interfaces. Red Hat uses NSS to support these features in a wide range of products, including Certificate System. NSS documentation is available on-line at http:// www.mozilla.org/projects/security/pki/nss/overview.html
.
1.4.6. PKCS #11
Public-Key Cryptography Standard (PKCS) #11 specifies an API used to communicate with devices that hold cryptographic information and perform cryptographic operations. Because it supports PKCS
#11, Certificate System is compatible with a wide range of hardware and software devices.
At least one PKCS #11 module must be available to any Certificate System subsystem instance.
As shown in Figure 1.4, “Certificate System Architecture” , a PKCS #11 module (also called a cryptographic module or cryptographic service provider) manages cryptographic services such as encryption and decryption. PKCS #11 modules are analogous to drivers for cryptographic devices that can be implemented in either hardware or software. Red Hat provides a built-in PKCS #11 module with the Certificate System.
A PKCS #11 module always has one or more slots which can be implemented as physical hardware slots in a physical reader such as smart cards or as conceptual slots in software. Each slot for a
PKCS #11 module can in turn contain a token, which is the hardware or software device that actually provides cryptographic services and optionally stores certificates and keys.
Two cryptographics modules are included in the Certificate System:
• The default internal PKCS #11 module, which comes with two tokens:
• The internal crypto services token, which performs all cryptographic operations such as encryption, decryption, and hashing.
• The internal key storage token ("Certificate DB token" in Figure 1.4, “Certificate System
Architecture” ), which handles all communication with the certificate and key database files that store certificates and keys.
• The FIPS 140-1 module. This module complies with the FIPS 140-1 government standard for cryptographic module implementations. The FIPS 140-1 module includes a single, built-in FIPS
140-1 certificate database token (as shown in Figure 1.4, “Certificate System Architecture” ), which handles both cryptographic operations and communication with the certificate and key database files.
Any PKCS #11 module can be used with the Certificate System. The server uses a file called secmod.db
to track modules that are available. This file can be modified using the modutil tool. This file needs to be modified when there are changes to the system like installing hardware accelerators to use for signing operations. For more information on modutil , see http:// www.mozilla.org/projects/security/pki/nss/tools/ .
1.4.7. Management Tools
The following command-line tools are provided with the Certificate System to help manage the system:
• Audit log signature verification tool ( AuditVerify )
• Enrollment PIN generation tool ( setpin )
• Mass revocation tool ( revoker )
• (Signed) Certificate System request tool
19
Chapter 1. Overview
• Bulk certificate issuance tool ( bulkissuance )
For more information about Certificate System command-line tools, see the Certificate System
Command-Line Tools Guide , which is available at http://redhat.com/docs/manuals/cert-system/ .
1.4.8. JRE
The Java ™ Runtime Environment (JRE) provides the Java ™ Virtual Machine (JVM) and supporting class libraries needed to run the Certificate System.
1.4.9. Internal Database
The Certificate System uses Red Hat Directory Server as its database for storing information such as certificates, requests, users, roles, ACLs, and other internal information. The Certificate System communicates with the internal LDAP database securely through SSL client authentication.
1.4.10. SSL/TLS and Supported Cipher Suites
Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols are universally accepted standards for authenticated and encrypted communication between clients and servers. Both client and server authentication occur over SSL/TLS. SSL/TLS uses a combination of public key and symmetric-key encryption. Symmetric-key encryption is much faster than public-key encryption, but public-key encryption provides better authentication techniques. An SSL/TLS session always begins with an exchange of messages called the SSL handshake , initial communication between the server and client. The handshake allows the server to authenticate itself to the client using public-key techniques, then allows the client and the server to cooperate in the creation of symmetric keys used for rapid encryption, decryption, and tamper detection during the session that follows.
Both of these protocols support using a variety of different cryptographic algorithms, or ciphers , for operations such as authenticating the server and client, transmitting certificates, and establishing session keys. Clients and servers may support different cipher suites, or sets of ciphers. Among other functions, the SSL handshake determines how the server and client negotiate which cipher suite they will use to authenticate each other, to transmit certificates, and to establish session keys.
Key-exchange algorithms such as RSA govern the way the server and client determine the symmetric keys to use during an SSL session. The most common SSL cipher suites use RSA key exchange, and
Certificate System supports RSA public-key systems.
Longer RSA keys are required to provide security as computing capabilities increase. The recommended RSA key-length is 2048 bits. Though many web servers continue to use 1024-bit keys, web servers should migrate to at least 2048 bits. For 64-bit machines, consider using stronger keys.
All CAs should use at least 2048-bit keys, and stronger keys (such as 3072 or 4096 bits) if possible.
Certificate System supports several different cipher suites with the RSA key exchange:
• AES and SHA-1 Message Authentication . Advanced Encryption Standard (AES) ciphers have a fixed block size of 128-bits, and the keys can be either 128-bit or 256-bit. There are 3.4 x 10^38 possible 128-bit keys and 1.1 x 10^77 possible 256-bit keys. There are more possible keys than any other cipher, making AES the strongest cipher supported by SSL. These cipher suites are FIPScompliant.
• Triple DES and SHA-1 Message Authentication . Triple DES (Data Encryption Standard) is the second-strongest cipher supported by SSL, but it is not as fast as RC4. Triple DES uses a key
20
Support for Open Standards three times as long as the key for standard DES. Because the key size is so large, there are approximately 3.7 * 10^50 possible keys. This cipher suite is FIPS-compliant.
• RC4 and RC2 and MD5 Message Authentication . The RC4 and RC2 ciphers have 128-bit encryption, which permits approximately 3.4 * 10^38 possible keys. This makes RC4 or RC2 keys very difficult to crack. RC4 ciphers are faster than RC2 ciphers.
RC4 can use SHA-1 message authentication as well as MD5 message authentication.
• DES and SHA-1 Message Authentication . DES 56-bit encryption permits approximately 7.2
* 10^16 possible keys. This cipher suite is no longer FIPS-compliant because it is too weak cryptographically.
1.5. Support for Open Standards
This section lists the standard message formats and protocols supported by the Certificate System.
1.5.1. Certificate Management Formats and Protocols
The Certificate System supports the following certificate management formats and protocols. For more details about the proposed PKIX standards listed here, see http://www.ietf.org/html.charters/pkixcharter.html
under Internet Drafts .
• Certificate Request Message Format (CRMF).
A message format to send a certificate request to a
CA. A standard from the Internet Engineering Task Force (IETF) PKIX working group.
• Certificate Management Message Formats (CMMF).
Message formats to send certificate requests and revocation requests from end entities to a CA and to return information to end entities. A proposed standard from the IETF PKIX working group. CMMF has been subsumed by another standard, CMC.
• Certificate Management Messages over CS (CMC).
A general interface to public-key certification products based on CS and PKCS #10, including a certificate enrollment protocol for RSA-signed certificates with Diffie-Hellman public-keys. A standard from the IETF PKIX working group. CMC incorporates CRMF and CMMF.
• Cryptographic Message Syntax (CS).
A superset of PKCS #7 syntax used for digital signatures and encryption. A proposed standard from the IETF PKIX working group.
• PKIX Certificate and CRL Profile (PKIX Part 1).
The first part of the four-part standard under development by the IETF for a public-key infrastructure for the Internet. Part 1 specified standards for certificates and CRLs. Certificate System will support the other PKIX parts as they are finalized.
For more information about PKIX Part 1, see ftp://ftp.isi.edu/in-notes/rfc2459.txt
.
1.5.2. Security and Directory Protocols
The Certificate System supports the following security and directory protocols:
• FIPS PUBS 140-1.
Federal Information Standards Publications (FIPS PUBS) 140-1 is a US government standard for implementing cryptographic modules such as hardware or software
21
Chapter 1. Overview that encrypts and decrypts data, creates and verifies digital signatures, and other cryptographics functions.
• Hypertext Transport Protocol (HTTP) and Hypertext Transport Protocol Secure (HTTPS).
Protocols used to communicate with web servers.
• KEYGEN tag.
An HTML tag that generates a key pair for use with a certificate.
• Lightweight Directory Access Protocol (LDAP) v2, v3.
A directory service protocol designed to run over TCP/IP and across multiple platforms. LDAP is a simplified version of Directory Access
Protocol (DAP), used to access X.500 directories. LDAP is under IETF change control and has evolved to meet Internet requirements.
• Public-Key Cryptography Standard (PKCS) #7.
An encrypted data and message format developed by RSA Data Security to represent digital signatures, certificate chains, and encrypted data. This format is used to deliver certificates to end entities.
• Public-Key Cryptography Standard (PKCS) #10.
A message format developed by RSA Data
Security for certificate requests. This format is supported by many server products.
• Public-Key Cryptography Standard (PKCS) #11.
Specifies an API used to communicate with devices such as hardware tokens that hold cryptographic information and perform cryptographic operations.
• X.509 v1, v3.
Digital certificate formats recommended by the International Telecommunications
Union (ITU).
• Secure Sockets Layer (SSL) 2.0, 3.0.
A set of rules governing server authentication, client authentication, and encrypted communication between servers and clients.
• Security-Enhanced Linux.
Security-enhanced Linux, or SELinux, is a set of security protocols enforcing mandatory access control on Linux system kernels. This was developed by the United
States National Security Agency to keep applications from accessing confidential or protected files through lenient or flawed access controls.
22
Chapter 2.
Installation and Configuration
The Certificate System is comprised of subsystems which can be independently installed on different servers, multiple instances installed on a single server, and other flexible configurations for availability, scalability, and failover support. The procedures for downloading, installing, and configuring instances of Certificate System subsystems are described in this chapter.
The Certificate System servers include five subsystems:
• Certificate Authority (CA)
• Data Recovery Manager (DRM), sometimes referred to as a Key Recovery Authority (KRA)
• Online Certificate Status Protocol (OCSP) Responder
• Token Key Service (TKS)
• Token Processing System (TPS)
The Certificate System client is the Enterprise Security Client. For information about the Enterprise
Security Client, see the Certificate System Enterprise Security Client Guide .
There are two steps for installing the Certificate System: the first is installing the server packages, and the second is configuring the subsystem through the HTML-based configuration wizard.
The installation and configuration process for the Certificate System is as follows:
1. Install a Red Hat Directory Server. This can be on a different machine from the Certificate System, which is the recommended scenario for most deployments.
2. Download the Certificate System packages from the Red Hat Network channel. Each subsystem has its own packages, as well as dependencies and related packages. These are listed in
Section 2.2.3, “Packages Installed” .
3. Install the Certificate System CA subsystem. See Section 2.5, “Installing the Certificate System ” for complete instructions on installing the CA.
4. Configure the CA subsystem. For information on configuring the Certificate Manager (CA) subsystem, see Section 2.6, “Configuring the Default Subsystem Instances” .
5. Install the other Certificate System subsystems on the appropriate hosts. See Section 2.5,
“Installing the Certificate System ” for complete instructions on installing the subsystems.
6. Configure each subsystem through its HTML administrative services page. Go through the installation screens. When completed, all necessary CA, server, and agent and user certificates are generated and installed.
See Section 2.6, “Configuring the Default Subsystem Instances” for more information on the subsystem configuration pages.
2.1. Deployment Considerations
Before beginning installation, the following issues must be decided:
• What types of subsystems to install.
23
Chapter 2. Installation and Configuration
• How many subsystems to install.
• On which hosts to install the subsystems.
• How and where to install an available Red Hat Directory Server. Only one Directory Server is required, although there can be more than one. It is recommended that the Directory Server only be used for certificate management.
• To what security domain the subsystem should be added or, for CAs, whether to create a new security domain.
• Whether the subsystem should be a clone of an existing subsystem.
• Whether the Certificate Manager should be a self-signed root CA or a subordinate CA.
2.1.1. Security Domains
A security domain is a registry of PKI services. Certificate System subsystems register information about themselves in these domains so users of PKI services can find other services by inspecting the registry. The security domain service in Certificate System manages both the registration of PKI services for Certificate System subsystems and a set of shared trust policies. Security domains streamline information between subsystems. Each Certificate System subsystem instance must be a member of a security domain; a CA subsystem is the only subsystem which can host a security domain.
The security domain shares the CA internal database for privileged user and group information to determine which users can update the security domain, register new PKI services, and issue certificates. There must be at least one security domain for a PKI, but there can also be multiple domains.
2.1.2. Cloning a Subsystem
More than one subsystem can be configured in an installation of Certificate System. There can be multiple instances of a type of subsystem on a host or across different hosts. For failover support, one configuration option is to duplicate, or clone , an instance so that more than one instance has the same configuration information. Clones and masters share the same set of keys and certificates. Cloned
CAs issue certificates with the same issuer name and keys, but use different sets of serial numbers.
A master and clone function essentially as a single server with failover support. This can also be used for load balancing for high-traffic subsystems. For details about cloning a subsystem, see Chapter 20,
Configuring the Certificate System for High Availability .
2.1.3. Self-Signed Root CA or Subordinate CA
A Certificate Manager can be configured either a root CA or a subordinate CA. A self-signing root CA issues and signs its own CA signing certificate. A subordinate CA can be subordinate to a public CA or to a Certificate System root CA; either way, the other CA signs the subordinate CA's certificates. A subordinate CA is restricted in the types and contents of the certificates it can issue by the contents and settings of the CA signing certificate issued to it, such as the kinds of certificates that it can issue, the extensions that it is allowed to include in certificates, the levels of subordinate CAs the subordinate
CA can create, the validity period of certificates it can issue, and the validity period of the subordinate
CA's signing certificate.
• Subordination to a Public CA . Chaining the Certificate System CA to a third-party public CA introduces the restrictions that public CAs place on the kinds of certificates the subordinate CA can
24
Prerequisites issue and the nature of the certificate chain. This may not be acceptable for some PKI deployments.
One benefit of chaining to a public CA is that the third party is responsible for submitting the root CA certificate to a web browser or other client software, which is a major advantage for certificates that are accessed by different companies with browsers that cannot be controlled by the administrator.
• Subordination to a Certificate System CA . Setting up a Certificate System CA as the root CA means that the Certificate System administrator has control over all subordinate CAs by setting policies that control the contents of the CA signing certificates issued. A subordinate CA issues certificates by evaluating its own authentication and certificate profile configuration, without regard for the root CA's configuration.
It is easiest to make the first CA installed a self-signed root, so that it is not necessary to apply to a third party and wait for the certificate to be issued. Before deploying the full PKI, however, consider whether to have a root CA, how many to have, and where both root and subordinate CAs will be located.
2.2. Prerequisites
This section covers required information such as the supported platforms, the packages installed, and dependencies and programs.
• Section 2.2.1, “Supported Platforms”
• Section 2.2.2, “Required Programs and Dependencies”
• Section 2.2.3, “Packages Installed”
2.2.1. Supported Platforms
Certificate System server packages are available for the following platforms:
• Red Hat Enterprise Linux AS 4 (Intel 32-bit)
• Red Hat Enterprise Linux AS 4 (Intel 64-bit)
• Red Hat Enterprise Linux ES 4 (Intel 32-bit)
• Red Hat Enterprise Linux ES 4 (Intel 64-bit)
• Solaris 9 (Sparc 64-bit)
Certificate System Enterprise Security Client packages are available for the following platforms:
• Apple Macintosh OS X 10.4.x (Tiger) (Power PC 32-bit, Intel Mac)
• Microsoft Windows XP Professional (Intel 32-bit)
• Red Hat Enterprise Linux AS 4 (Intel 32-bit)
• Red Hat Enterprise Linux AS 4 (Intel 64-bit)
• Red Hat Enterprise Linux ES 4 (Intel 32-bit)
• Red Hat Enterprise Linux ES 4 (Intel 64-bit)
25
Chapter 2. Installation and Configuration
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. End-entities should use Mozilla Firefox or Microsoft Internet Explorer.
NOTE
The only browser that is fully-supported for the HTML-based instance configuration wizard is Mozilla Firefox.
2.2.2. Required Programs and Dependencies
The following must be installed before installing the Certificate System:
• Java
™
1.5.0 Java Runtime Environment (JRE).
Certificate System does not support earlier versions of the JRE. This JRE is required for running Tomcat, among other applications for the Certificate
System.
• On 32-bit Red Hat Enterprise Linux 4 platforms, Certificate System 7.3 requires the 32-bit version of the IBM JRE 1.5.0. A pre-packaged binary distribution of this package, the java-1.5.0-ibm rpm package, is available through either the Red Hat Enterprise Linux AS (v. 4 for x86) Extras
Red Hat Network channel or the Red Hat Enterprise Linux ES (v. 4 for x86) Extras Red Hat
Network channel.
A similar package is available for 64-bit Red Hat Enterprise Linux 4 platforms. This package is available through either the Red Hat Enterprise Linux AS (v. 4 for AMD64/EM64T) Extras Red
Hat Network channel or the Red Hat Enterprise Linux ES (v. 4 for AMD64/EM64T) Extras Red
Hat Network channel.
As root , run /usr/sbin/alternatives --config java to insure that the IBM Java ™
1.5.0 JRE is selected.
WARNING
Both the 32-bit xSeries (Intel-compatible) and 64-bit AMD/Opteron/EM64T versions of the IBM J2SE JRE 5.0 RPM packages available through the IBM download site are packaged in a format which is incompatible with Certificate System 7.3.
• For 64-bit Solaris 9 (SPARC) platforms, the user must download and install the latest version of the 64-bit Sun J2SE Java ™ Runtime Environment 5.0 (Update 9) available from the Sun download site, http://java.sun.com/javase/downloads/index.jsp
.
IMPORTANT
The 64-bit Solaris version of the Certificate System requires the user to install the
32-bit version of the JRE as well as installing the 64-bit version. The 32-bit version is used for the applet and Java ™ Web Start support. Read http://java.sun.com/ j2se/1.5.0/README.html
, http://java.sun.com/j2se/1.5.0/ReleaseNotes.html
, and http://java.sun.com/j2se/1.5.0/jre/install-solaris-64.html
before installing the Certificate
System.
26
Required Programs and Dependencies
Under the section Java Runtime Environment (JRE) 5.0 Update 9 , Sun only makes this JRE available through a self-extracting file which is incompatible with Certificate System since this format does not use the native Solaris packaging utility database.
It is possible to obtain the Sun 5.0 JRE in a compatible format. Click Download under the JDK
5.0 Update 9 section, and, under Solaris SPARC Platform - J2SETM Development Kit
5.0 Update 9 , select Solaris SPARC 32-bit packages - tar.Z (jdk-1_5_0_09solaris-sparc.tar.Z) and Solaris SPARC 64-bit packages - tar.Z (use
32-bit version for applet and Java Web Start support) (jdk-1_5_0_09solaris-sparcv9.tar.Z) .
After downloading these two files, uncompress them using the gunzip utility, and extract the contents using the tar utility.
The contents of the 32-bit file, jdk-1_5_0_09-solaris-sparc.tar.Z
, are COPYRIGHT ,
LICENSE , README.html
, SUNWj5cfg , SUNWj5dev , SUNWj5dmo , SUNWj5jmp , SUNWj5man , and
SUNWj5rt .
The contents of the 64-bit file, jdk-1_5_0_09-solaris-sparcv9.tar.Z
, are SUNWj5dmx ,
SUNWj5dvx , and SUNWj5rtx .
Since only the JRE is needed on Solaris 9 systems, use the pkgadd utility to add the 32-bit package, SUNWj5rt , first, and then add the 64-bit package, SUNWj5rtx .
• Java
™
Development Kit (JDK).
A JDK must be present on Red Hat Enterprise Linux systems. See http://kbase.redhat.com/faq/FAQ_54_4667.shtm
for more information. While almost any JDK is sufficient, installing one of these JDKs is recommended:
• For 32-bit Red Hat Enterprise Linux 4 platforms, a pre-packaged binary distribution of the 32-bit version of the IBM JDK 1.5.0, the java-1.5.0-ibm-devel rpm package, is available through either the Red Hat Enterprise Linux AS (v. 4 for x86) Extras Red Hat Network channel or the
Red Hat Enterprise Linux ES (v. 4 for x86) Extras Red Hat Network channel.
• A similar package is available for 64-bit Red Hat Enterprise Linux 4 platforms. This package is available through either the Red Hat Enterprise Linux AS (v. 4 for AMD64/EM64T) Extras Red
Hat Network channel or the Red Hat Enterprise Linux ES (v. 4 for AMD64/EM64T) Extras Red
Hat Network channel.
After installing the JDK, run /usr/sbin/alternatives --config javac as root to insure that a JDK is available.
Solaris 9 systems do not require downloading and installing a JDK; however, it may be required to download and install the Sun JDK 5.0 package in order to obtain a compatible Sun JRE 5.0
package.
• Apache.
Before installing any Certificate System TPS subsystems on Red Hat Enterprise Linux, there should be a local installation of Apache. When installing the TPS subsystem on Solaris 9, a specially-configured Apache server is included as part of the Certificate System 7.3 packages.
• Red Hat Directory Server.
Before a Certificate System can be installed, there must be an installed
Directory Server available because the Certificate System uses the Directory Server user database to store its certificate information.
27
Chapter 2. Installation and Configuration
• The Solaris version of Certificate System was tested on Sun Solaris 9 with patch level 118558-28.
• The following package groups and packages must be installed on all Red Hat Enterprise Linux systems:
• dialup (package group)
• gnome-desktop (package group)
• compat-arch-support (package group)
• web-server (package group)
• kernel-smp (package)
• e2fsprogs (package)
• firefox (package)
• On 64-bit Red Hat Enterprise Linux platforms, be certain that the 64-bit (x86_64) compat-libstdc
++ libraries are installed, and not only the 32-bit (i386) libraries. To confirm this, run the following as root : rpm -qa --queryformat 'compat-libstdc++-%{VERSION}-%{RELEASE}.%{ARCH}.rpm\n' | grep x86_64
Numerous libraries should be displayed.
2.2.3. Packages Installed
Multiple packages are installed with the Certificate System, in addition to the core Certificate System components.
• Section 2.2.3.1, “Red Hat Enterprise Linux RPMs”
• Section 2.2.3.2, “Solaris Packages”
2.2.3.1. Red Hat Enterprise Linux RPMs
RPMs have the format package_name-version_number-release_number-architecture .rpm
; only the package name is shown in the tables.
RPMs for Certificate System subsystems and components osutil rhpki-kra pkisetup rhpki-ca rhpki-manage rhpki-migrate rhpki-common rhpki-console rhpki-native-tools rhpki-ocsp rhpki-java-tools
RPMs for the Enterprise Security Client ccid coolkey pcsc-lite pcsc-lite-doc rhpki-tks rhpki-tps rhpki-util symkey tomcatjss
28
Packages Installed
RPMs for the Enterprise Security Client esc ifd-egate pcsc-lite-libs
RPMs for Tomcat Web Services ant jakarta-commons-discovery avalon-framework avalon-logkit jakarta-commons-el jakarta-commons-fileupload axis bcel classpathx-jaf classpathx-mail eclipse-ecj jakarta-commons-httpclient3 jakarta-commons-launcher jakarta-commons-logging jakarta-commons-modeler jakarta-commons-pool oro regexp rhino tomcat5 tomcat5-jasper tomcat5-servlet-2.4-api velocity werken.xpath
geronimo-specs gnu-crypto-sasl-jdk1.4
jdom jms jakarta-commons-beanutils jpackage-utils jakarta-commons-collections ldapjdk jakarta-commons-daemon log4j jakarta-commons-dbcp jakarta-commons-digester mx4j oldjdom wsdl4j xalan-j2 xerces-j2 xml-commons xml-commons-apis xml-commons-resolver xmlbeans
RPMs for Fortitude Web
Services fortitude-web mod_nss mod_revocator
RPMs for Apache Web Services pdksh perl-HTML-Parser perl-HTML-Tagset perl-Parse-RecDescent perl-URI
RPMs for LDAP Support mozldap mozldap-tools
RPMs for Network Security
Services (NSS) dirsec-jss dirsec-nspr dirsec-nss perl-XML-NamespaceSupport perl-XML-Parser perl-XML-SAX perl-XML-Simple perl-libwww-perl
29
Chapter 2. Installation and Configuration
RPMs for Network Security
Services (NSS) dirsec-nss-tools
RPMs for Java
™ java-1.5.0-ibm java-1.5.0-ibm-devel
2.2.3.2. Solaris Packages
Solaris packages have the format VENDORpackage_name-version_number-release_numberarchitecture .pkg
; only the package name is shown in the tables.
NOTE
Package names for 64-bit Sparc 9 packages always have an x at the end of the primary package name. For example, the 64-bit package for the CA subsystem is named
RHATrhpki-cax-7.3.0-3.noarch.pkg
, with a vendor prefix of RHAT , and an x at the end of the primary package name, rhpki-ca . Since some packages contain subpackages, the x is appended to the end of the primary package name, not the end of the secondary subpackage name. For example, the 64-bit packages for dirsecnss include RHATdirsec-nssx-3.11.3-1.sparcv9.pkg
and RHATdirsec-nssxtools-3.11.3-1.sparcv9.pkg
.
Packages for Certificate System
RHATosutilx RHATrhpki-krax
RHATpkisetupx
RHATrhpki-cax
RHATrhpki-commonx
RHATrhpki-managex
RHATrhpki-migratex
RHATrhpki-native-toolsx
RHATrhpki-consolex
RHATrhpki-java-toolsx
RHATrhpki-ocspx
RHATrhpki-tksx
RHATrhpki-tpsx
RHATrhpki-utilx
RHATsymkeyx
RHATtomcatjssx
Packages for Tomcat Web Services
RHATantx RHATjakarta-commons-elx
RHATavalon-frameworkx RHATjakarta-commonsfileuploadx
RHATavalon-logkitx
RHATaxisx
RHATbcelx
RHATclasspathx-jafx
RHATclasspathx-mailx
RHATregexpx
RHATrhinox
RHATjakarta-commonshttpclient3x
RHATjakarta-commonslauncherx
RHATtomcat5-jasperx
RHATtomcat5-servlet-2-4-apix
RHATjakarta-commonsloggingx
RHATjakarta-commonsmodelerx
RHATtomcat5x
RHATvelocityx
RHATjakarta-commons-poolx RHATwerken-xpathx
30
Packages Installed
Packages for Tomcat Web Services
RHATgeronimo-specsx RHATjdomx
RHATgnu-crypto-sasl-jdk1-4x RHATjmsx
RHATjakarta-commonsbeanutilsx
RHATjpackage-utilsx
RHATjakarta-commonscollectionsx
RHATldapjdkx
RHATjakarta-commonsdaemonx
RHATlog4jx
RHATjakarta-commons-dbcpx RHATmx4jx
RHATjakarta-commonsdigesterx
RHATjakarta-commonsdiscoveryx
RHAToldjdomx
RHATorox
RHATwsdl4jx
RHATxalan-j2x
RHATxerces-j2x
RHATxml-commons-apisx
RHATxml-commons-resolverx
RHATxml-commonsx
RHATxmlbeansx
Packages for Fortitude Web
Services
RHATfortitude-webx
RHATmod-nssx
RHATmod-revocatorx
Packages for Apache Web Services
RHATapr-utilx RHATmod-perlx
RHATaprx
RHATdb4x
RHATdb4x-utils
RHATexpatx
RHAThttpdx
RHAThttpdx-manual
RHATpcrex
RHATperl-HTML-Parserx
RHATperl-HTML-Tagsetx
RHATperl-XML-Parserx
RHATperl-XML-SAXx
RHATperl-XML-Simplex
RHATperl-libwww-perlx
RHATperl-Parse-RecDescentx RHATperlx
RHATperl-URIx
RHATperl-XML-
NamespaceSupportx
Packages for LDAP Support
RHATmozldapx
RHATmozldapx-tools
Packages for Network
Security Services (NSS)
RHATdirsec-jssx
RHATdirsec-nsprx
RHATdirsec-nssx
RHATdirsec-nssx-tools
Packages for Java
™
SUNWj5rt (32-bit JRE)
31
Chapter 2. Installation and Configuration
Packages for Java
™
SUNWj5rtx (64-bit JRE)
2.3. Configuration Preparation
• Section 2.3.1, “Required Information”
• Section 2.3.2, “Default Settings”
2.3.1. Required Information
When the Certificate System subsystems are configured, some outside information must be available.
This includes the following:
• Login PIN.
There is a randomly-generated PIN in the preop.pin
parameter in the CS.cfg
file in the instance conf/ directory. This is used to log into the configuration wizard.
• Security domain information.
CAs can create a new security domain, which requires a unique name and a username and password for the CA agent who administers the domain.
All other subsystems must join an existing security name. Have the username and password of the
CA agent who administers the domain.
• CA information.
If the subsystem is not a CA, then it is necessary to select a CA from a drop-down menu or add an external CA. If a Certificate System CA is selected, then supply the CA agent username and password.
• Subsystem information.
When installing a TPS, the CA and TKS subsystems must be installed and configured before installing the TPS; a DRM subsystem must also be installed and configured if server-side key generation is selected. When configuring the TPS, the TKS and DRM to connect with the TPS are selected from a drop-down list of all subsystems within the security domain. The bind information for the selected subsystems must be available.
• Directory Server hostname and port number.
The Certificate System uses the user database of the Directory Server to store its information, and the hostname and port number of the LDAP directory is required for the Certificate System to access the database.
• Directory Manager DN and password.
The Certificate System must be able to bind to the user database, so a user ID and password must be supplied to bind to the Directory Server. This user is normally the Directory Manager. The default
Directory Manager DN is cn=Directory Manager .
• Certificate and key recovery files.
32
Default Settings
If the subsystem being configured is a clone of another subsystem, then the backup files for the master subsystem must be locally accessible.
2.3.2. Default Settings
The ports and file directories in Table 2.1, “Default Subsystem Instance Ports and File Locations” show the default installation and configuration information.
Susbsystem
CA
DRM
OCSP
TKS
SSL Port
9443
10443
11443
13443
Non-SSL Port
9080
10080
11080
13080
TPS 7889 7888
Table 2.1. Default Subsystem Instance Ports and File Locations
Instance Directory
/var/lib/rhpki-ca
/var/lib/rhpki-kra
/var/lib/rhpki-ocsp
/var/lib/rhpki-tks
/var/lib/rhpki-tps
The following certificates are created by default when any of the following subsystem instances are installed:
• Certificate Manager
• CA signing certificate
• OCSP signing certificate (for the CA's internal OCSP service)
• SSL server certificate
• Subsystem certificate
The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.
• DRM
• Transport certificate
• Storage certificate
• SSL server certificate
• Subsystem certificate
• OCSP
• OCSP signing certificate
• SSL server certificate
• Subsystem certificate
• TKS
• SSL server certificate
33
Chapter 2. Installation and Configuration
• Subsystem certificate
• TPS
• SSL server certificate
• Subsystem certificate
2.4. Configuration Setup Wizard
When the installation process is complete, either when installing the initial subsystems or running the pkicreate tool, the script returns a URL pointing to the configuration page of the new subsystem.
This HTML configuration wizard is used to configure the subsystem settings like the instance name and security domain, to request and generate keys and certificates, and to configure which Directory
Server to use.
This section describes the configuration wizard panels. The panels shown are slightly different for configuring the different subsystems or when configuring a clone.
• Section 2.4.1, “Security Domain Panel”
• Section 2.4.2, “Subsystem Type Panel”
• Section 2.4.3, “PKI Hierarchy Panel”
• Section 2.4.4, “CA Information Panel”
• Section 2.4.5, “TKS Information Panel”
• Section 2.4.6, “DRM Information Panel”
• Section 2.4.7, “Authentication Directory Panel”
• Section 2.4.8, “Internal Database Panel”
• Section 2.4.9, “Key Store Panel”
• Section 2.4.10, “Key Pairs Panel”
• Section 2.4.11, “Subject Names Panel”
• Section 2.4.12, “Requests and Certificates Panel”
• Section 2.4.13, “Export Keys and Certificates Panel”
• Section 2.4.14, “Administrator Panel”
2.4.1. Security Domain Panel
This panel creates a new security domain or adds the new subsystem to an existing security domain. A security domain can be created only if the subsystem being configured is a CA. All other subsystems do not have the option to create a domain, so these subsystems must join an existing security domain. Creating a new domain creates a registry called domain.xml
in the /var/ lib/ CAinstanceID /conf/ directory. Editing the file manually is not recommended.
34
Subsystem Type Panel
The first security domain for the Certificate System is created when the default CA is configured. Every subsystem must belong to a security domain; no system can be successfully configured without an existing security domain. The only subsystem which can host a security domain is a CA.
Figure 2.1. Security Domain
If the subsystem is being added to an existing domain, provide the security domain URL and the administrator UID and password for the domain.
Figure 2.2. Supplying the Security Domain Bind Information
For more information on security domains, see Section 4.4, “Security Domains” .
2.4.2. Subsystem Type Panel
This panel creates a master subsystem or clones an existing subsystem. Creating a master subsystem only requires giving a subsystem name. The subsystem URL is filled automatically. When
35
Chapter 2. Installation and Configuration cloning an existing subsystem, select the master subsystem from the list provided, and give the name of the new cloned subsystem. The list of subsystems in the Clone section list is retrieved from the security domain provided in the Security Domain panel.
Figure 2.3. Creating the Instance
Cloning a subsystem automatically supplies the rest of the subsystem information based on the master's configuration and regenerates the master's certificates.
2.4.3. PKI Hierarchy Panel
This option is only available to CAs; this creates the overall arrangement of CAs. CAs can be arranged in a hierarchy, with root CAs, which sign CA signing certificates and set certificate policies, and layers of subordinate CAs, which have CA signing certificates signed by a root CA and which must obey the issuance policies set by that root. This panel determines where in the CA hierarchy the new CA instance belongs.
Figure 2.4. Setting the PKI Hierarchy
36
CA Information Panel
For a CA, there are two possible configuration options:
• Root CA.
A root CA signs its own CA signing certificate and, therefore, can set its own certificate issuance rules.
• Subordinate CA.
A subordinate CA receives its CA signing certificate from a root CA. The root CA must be referenced here; it can be another Certificate System CA, but, for the default (i.e., first) CA instance, this will probably be an external root CA. The certificate requests generated in this process must be submitted to the external CA and be approved before configuration can be completed.
2.4.4. CA Information Panel
This panel appears only during TPS configuration. This identifies the CA which will work with the TPS to issue and revoke certificates stored on the smart card. The TPS must be associated with a CA within the security domain which can perform the token operations; the CA is selected from a dropdown list of all CAs within the domain.
Figure 2.5. Selecting the CA
2.4.5. TKS Information Panel
This panel is only available when configuring a TPS subsystem. The TPS must be associated with an existing TKS subsystem. Similarly to setting the CA information, the TKS is selected from a list of all configured TKS subsystems within the security domain.
37
Chapter 2. Installation and Configuration
Figure 2.6. Selecting the TKS
2.4.6. DRM Information Panel
This panel is only available when configuring a TPS subsystem. The TPS can be associated with an existing DRM subsystem to enable server-side key generation. Similarly to setting the CA information, the DRM is selected from a list of all configured DRM subsystems within the security domain.
Figure 2.7. Selecting the DRM
38
Authentication Directory Panel
2.4.7. Authentication Directory Panel
This panel is only available when configuring a TPS subsystem. All subsystems are configured to use a Directory Server database for system certificates and users. The TPS subsystem has an additional database for certificates and keys and to authenticate users which access the Enterprise Security
Client. This is configured in the Authentication Directory panel.
Figure 2.8. Configuring the TPS Authentication Database
Directory Server must be installed and available so that information can be supplied in this panel, and the appropriate database and suffix must be created before the TPS is configured; these are not created by the configuration wizard but are accessed by it. Only Red Hat Directory Server 7.1 or higher is supported.
2.4.8. Internal Database Panel
This panel collects information for the internal directory service used for storing certificate requests and certificates.
Directory Server must be installed and available so that information can be supplied in this panel. If the suffix and the database name provided in this screen are not present in the Directory Server instance, then the configuration wizard attempts to create them. It is also possible to provide an existing suffix and database. Only Red Hat Directory Server 7.1 or higher is supported.
39
Chapter 2. Installation and Configuration
Figure 2.9. Configuring the Internal LDAP Database Information
NOTE
Do not share the same suffix and database name for more than one Certificate System subsystem. The same instance can be used for more than one subsystem, but different suffix and database names must be specified. Additionally, if a subsystem is being cloned, the same directory instance cannot be used for both the master and clone.
If a subsystem is cloned, the configuration wizard attempts to configure multi-master replication agreements between the master subsystem's internal database and the new clone's internal database.
2.4.9. Key Store Panel
This panel displays a list of automatically-discovered tokens that can be used to store certificates and keys. The Certificate System automatically discovers Safenet's LunaSA and nCipher's netHSM hardware security modules (HSM) and returns them on this screen. The discovery process assumes that the client software installations for these modules are local on the same system as the Certificate
System subsystem and are in the following locations:
• LunaSA: /usr/lunasa/lib/libCryptoki2.so
• nCipher: /opt/nfast/toolkits/pkcs11/libcknfast.so
NOTE
Previously, all possible slots had to be logged into before configuration could proceed; in
Certificate System 7.3 it is possible to configure the instance while being logged into only one slot.
40
Key Pairs Panel
Figure 2.10. Selecting the Key and Certificate Location
The LunaSA partitions, the nCipher slots, and the NSS internal software token are provided in this screen.
The internal software token is logged in by default. The password to this database is stored in /var/ lib/ instance_ID /conf/password.conf
.
If an HSM module is selected, the administrator provides the password, and password.conf
is updated with this information by default.
The status field in this panel describes the status of the token.
• Found . The token was discovered by Certificate System and added to secmod.db
.
• Not-Found . The Certificate System was unable to find the supported HSMs.
• Logged In . The login attempt to the slot was successful.
• Not Logged In . The subsystem is not logged into the slot yet.
The login button corresponding to the slot brings up a login prompt for the token password.
2.4.10. Key Pairs Panel
This screen shows the type and size of the keys to be generated. The default values are RSA and
2048-bit for all keys.
41
Chapter 2. Installation and Configuration
Figure 2.11. Setting the Key Pair Type
2.4.11. Subject Names Panel
This panel lists the different certificate subject names for all of the certificates issued for the subsystem being installed. This panel also sets which CA will issue these certificates. If the certificates for the subsystem, including certificates for a subordinate CA, will be issued by an external CA such as
VeriSign or a Certificate System CA which is outside the security domain, select External CA from the list.
42
Requests and Certificates Panel
Figure 2.12. Setting the Certificate Subject Name
If an existing subsystem is being cloned, all of these fields are grayed out except the Server
Certificate name field because the server certificate is regenerated.
2.4.12. Requests and Certificates Panel
This panel has links to the certificate requests and the issued certificates, if the certificates were issued successfully. The generated certificate requests are stored in the instance's CS.cfg
configuration file for retrieval later.
43
Chapter 2. Installation and Configuration
Figure 2.13. Certificate Request and Certificate Links
If the certificates are signed by an external CA, such as a third-party CA or a Certificate System CA which is outside the security domain, then action required is shown under the certificate name, and there are action links to submit the certificate. The configuration wizard will not proceed past this panel until the new certificates are pasted into the fields. In this case, the Requests and Certificates panel appears as shown.
2.4.13. Export Keys and Certificates Panel
This panel offers the option to export the new certificate to a .p12
file. A .p12
backup file of a master subsystem's certificates and keys is required when configuring the clone; these files can also be used to restore the keys and certificates if the current certificate repository, such as a token, is lost or damaged.
NOTE
It is not possible to export keys and certificates stored on an HSM to a .p12
file.
44
Administrator Panel
Figure 2.14. Exporting the Certificates and Keys
2.4.14. Administrator Panel
This panel creates the first administrator user for the instance. This user also has agent privileges, so the agent certificates and keys for the agent certificate are generated on the browser used to go through the configuration wizard. This administrator/agent user can use this agent certificate to access the agent interface for managing requests.
Figure 2.15. CA Administrator
45
Chapter 2. Installation and Configuration
Pressing Next causes the browser to generate a key pair which consists of a public key and a private key. The public key is packaged in a certificate request that is submitted to the CA. If the requests are submitted to a Certificate System CA, the CA approves and signs the certificate request automatically, and the certificate is returned in the browser in the next panel.
2.5. Installing the Certificate System
The installation process consists of two main steps: obtaining the packages and configuring the subsystems. This section explains how to obtain and install the Certificate System packages.
There are two ways to obtain and install the subsystem packages. For all supported platforms, the
Certificate System packages can be downloaded as ISO images through the appropriate Red Hat
Network channel. These packages are then installed through a package utility; on Red Hat Enterprise
Linux systems, this is rpm and on Solaris 9, pkgadd .
Alternatively, if the appropriate network access is available, the subsystems and all dependencies can be downloaded and installed on Red Hat Enterprise Linux systems using the up2date command.
Whether downloading and installing the Certificate System from an ISO image or through up2date , several packages are also installed for related applications and dependencies, not only for the subsystem packages. These packages are listed in Section 2.2.3.1, “Red Hat Enterprise Linux RPMs” and Section 2.2.3.2, “Solaris Packages” .
• Section 2.5.1, “Installing from an ISO Image”
• Section 2.5.2, “Installing through up2date”
2.5.1. Installing from an ISO Image
For Sun Solaris and Red Hat Enterprise Linux AS and ES, use the following procedure to install the
Certificate System from an ISO image:
1. Open the appropriate Red Hat Certificate System 7.3
Red Hat Network channel and download the packages.
Solaris packages are contained in a single ISO image; Red Hat Enterprise Linux packages can be downloaded as an ISO image or individually.
2. Log into the machine as the root user.
3. Install the rhpki-manage package and run rhpki-install manually. For example, on Red Hat
Enterprise Linux: rpm -Uvh rhpki-manageversion .noarch.rpm
After you have installed the rhpki-manage package, use the rhpki-install script to install the subsystem. For example: rhpki-install -pki_subsystem= subsystem_type -pki_package_path= /path/to/ISO_image -force
46
Installing from an ISO Image
NOTE
The DONT_RUN_PKICREATE environment variable can stop the pkicreate script from running automatically after the subsystems are installed. This allows the default instances to be installed in user-defined installation directories, instead of the default locations in /var/lib . It can be preferable to install through the ISO image with this environment variable set to block the pkicreate script for deployments where the default instances must be installed in custom locations.
The following options are available for subsystem :
• ca installs the Certificate Authority.
• ra installs the Registration Authority.
• drm installs the Data Recovery Manager.
• ocsp installs the Online Certificate Status Protocol Responder.
• tks installs the Token Key System.
• tps installs the Token Processing System.
• esc installs the Enterprise Security Client.
The force option bypasses any confirmation prompts that may otherwise appear during the installation.
For example, to install the CA and then the DRM, use the following commands: rhpki-install -pki_subsystem=ca -pki_package_path=/media/cdrom/RedHat/RPMS -force rhpki-install -pki_subsystem=drm -pki_package_path=/media/cdrom/RedHat/RPMS -force
The rhpki-install script uses the rpm program on Red Hat Enterprise Linux systems and pkginfo and pkgadd programs on Solaris 9 systems.
4. When the installation process is complete, a URL to access this instance is printed to the screen with the following format.
Configuration Wizard listening on http:// hostname.domainname:unsecure-port/subsystem_type / admin/console/config/login?pin= pin
For example, a new CA may have the following URL: http://server.example.com:9080/ca/admin/console/config/login?pin=Yc6EuvuY2OeezKeX7REk
47
Chapter 2. Installation and Configuration
NOTE
When the first subsystem is installed on a machine, the installation process automatically creates a new user ( pkiuser ) and group ( pkiuser ). All default Certificate System instances will run as this user and group.
2.5.2. Installing through up2date
NOTE
There is an environment variable, DONT_RUN_PKICREATE , which will stop the pkicreate script from running automatically after the subsystems are installed. This allows the default instances to be installed in user-defined installation directories, instead of the default locations in var/lib . It can be preferable to install through the ISO image with this environment variable set to block the pkicreate script for deployments where the default instances must be installed in custom locations.
To install the subsystems on Red Hat Enterprise Linux using the up2date command, run a command like the following for each subsystem: up2date rhpkisubsystem subsystem can be ca for the CA, ra for the RA, kra for the DRM, ocsp for the OCSP, tks for the
TKS, and tps for the TPS.
up2date is used only for the first subsystem instance; any additional subsystem instances should be added using pkicreate .
To install the client using up2date , run the following: up2date esc
2.6. Configuring the Default Subsystem Instances
After the packages have been installed, the subsystem has to be configured by going through the
HTML configuration wizard. The configuration process is similar for the subsystems; differences in the wizard are described in the panel descriptions in Section 2.4, “Configuration Setup Wizard” . The general process is outlined in this section.
• Section 2.6.1, “Configuring a CA”
• Section 2.6.2, “Configuring a DRM, OCSP, or TKS”
• Section 2.6.3, “Configuring a TPS”
2.6.1. Configuring a CA
1. Open the configuration wizard. When the instance is installed, the process returns a success message which includes a URL with the login PIN. For example:
48
Configuring a CA http://server.example.com:9080/ca/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH
Using this URL skips the login screen.
Alternatively, log into the setup wizard through admin link on the services page and supply the preop.pin
value from the CS.cfg
file when prompted.
http://server.example.com:9080/ca/services
2. Create a new security domain.
The default CA instance must create a new security domain; subsequent CAs can create a new domain or join an existing security domain.
3. Enter a name for the new instance.
4. Set up the PKI hierarchy. It is recommended that the first CA be a root, or self-signed, CA, meaning that it signs its own CA signing certificate rather than submitting its certificates to a thirdparty CA for issuance. Subsequent CAs can be subordinate CAs.
5. Fill in the information for the LDAP server which will authenticate the subsystem's users. This requires connection information for the Directory Server instance, such as the hostname, port number, bind DN (username), and password. This step also creates a database in the Directory
Server and a corresponding base directory entry (base DN) to use for the subsystem's entries.
6. Select the key store token; a list of detected hardware tokens and databases is given.
To determine whether a token is detected by the Certificate System, use the TokenInfo tool. For more information on this tool, see the Certificate System Command-Line Tools Guide .
7. Set the key size. The default RSA key size is 2048.
8. Optionally, give subject names for the certificates.
9. The next panels generate and show certificate requests, certificates, and key pairs.
If an external CA is used to issue the certificates, configuration cannot go forward until they are received from the external CA. When they are issued, paste the certificates into this panel to add them to the CA database, and then proceed with the installation. Click Apply to view the certificates as they are imported.
10. If the subsystem will ever be cloned, or as a protection if keys or certificates are ever lost, back up the keys and certificates when prompted.
11. Give the information for the new subsystem administrator.
12. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
13. When the configuration is complete, restart the subsystem.
/etc/init.d/rhpki-ca restart
49
Chapter 2. Installation and Configuration
2.6.2. Configuring a DRM, OCSP, or TKS
1. Open the configuration wizard. When the instance is installed, the process returns a success message which includes a URL with the login PIN. For example: http://server.example.com:10080/kra/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH
Using this URL skips the login screen.
Alternatively, log into the setup wizard through admin link on the services page and supply the preop.pin
value from the CS.cfg
file when prompted.
http://server.example.com:10080/kra/services
2. Join an existing security domain. Supply the hostname and SSL port of the CA which hosts the domain. When the CA is successfully contacted, then supply the admin username and password for the CA so that it can be properly accessed.
3. Enter a name for the new instance.
4. Fill in the information for the LDAP server which will authenticate the subsystem's users. This requires connection information for the Directory Server instance, such as the hostname, port number, bind DN (username), and password. This step also creates a database in the Directory
Server and a corresponding base directory entry (base DN) to use for the subsystem's entries.
5. Select the key store token; a list of detected hardware tokens and databases is given.
To determine whether a token is detected by the Certificate System, use the TokenInfo tool. For more information on this tool, see the Certificate System Command-Line Tools Guide .
6. Set the key size. The default RSA key size is 2048.
7. Select the CA which will generate the subsystem certificates; to use a Certificate System CA, select the CA from the drop-down menu of the CAs configured within the security domain.
Optionally, give subject names to the listed certificates.
8. The next panels generate and show certificate requests, certificates, and key pairs.
If an external CA is used to issue the certificates, configuration cannot go forward until they are received from the CA. When they are issued, paste the certificates into this panel to add them to the subsystem database, and then proceed with the installation. Click Apply to view the certificates as they are imported.
9. If the subsystem will every be cloned, or as a protection if keys or certificates are ever lost, back up the keys and certificates when prompted.
10. Give the information for the new subsystem administrator.
11. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
12. When the configuration is complete, restart the subsystem.
50
Configuring a TPS
/etc/init.d/rhpki-kra restart
2.6.3. Configuring a TPS
1. Open the configuration wizard. When the instance is installed, the process returns a success message which includes a URL with the login PIN. For example: http://server.example.com:7888/tps/admin/console/config/login?pin=kI7E1MByNIUcPJ6RKHmH
Using this URL skips the login screen.
Alternatively, log into the setup wizard through admin link on the services page and supply the preop.pin
value from the CS.cfg
file when prompted.
http://server.example.com:7888/tps/services
2. Join an existing security domain. Supply the hostname and SSL port of the CA which hosts the domain. When the CA is successfully contacted, then supply the admin username and password for the CA so that it can be properly accessed.
3. Enter a name for the new instance.
4. Supply the CA information for the Certificate System CA which will be used to issue and revoke certificates for token operations requested through the TPS subsystem.
5. Supply information about the TKS which will manage the TPS keys. Select the TKS from the dropdown menu of TKS subsystems within the security domain.
6. There is an option for server-side key generation for tokens enrolled through the TPS. If serverside key generation is selected, supply information about the DRM which will be used to generate keys and archive encryption keys. Key and certificate recovery is initiated automatically through the TPS, which is a DRM agent. Select the DRM from the drop-down menu of DRM subsystems within the security domain.
7. Fill in the information for the LDAP server which will authenticate the subsystem's users. This requires connection information for the Directory Server instance, such as the hostname, port number, bind DN (username), and password. This step also creates a database in the Directory
Server and a corresponding base directory entry (base DN) to use for the subsystem's entries.
8. Select the key store token; a list of detected hardware tokens and databases is given.
To determine whether a token is detected by the Certificate System, use the TokenInfo tool. For more information on this tool, see the Certificate System Command-Line Tools Guide .
9. Set the key size.
10. Select the CA which will generate the subsystem certificates; to use a Certificate System CA, select the CA from the drop-down menu of the CAs configured within the security domain.
To select and external CA, select the External CA radio button and supply the appropriate information.
Optionally, give subject names to the listed certificates.
51
Chapter 2. Installation and Configuration
11. The next panels generate and show certificate requests, certificates, and key pairs.
If an external CA is used to issue the certificates, configuration cannot go forward until they are received from the CA. When they are issued, paste the certificates into this panel to add them to the TPS database, and then proceed with the installation. Click Apply to view the certificates as they are imported.
12. Give the information for the new subsystem administrator.
13. Click Next through the remaining panels to import the agent certificate into the browser and complete the configuration.
14. When the configuration is complete, restart the subsystem.
/etc/init.d/rhpki-tps restart
2.7. Creating Additional Subsystem Instances
There can be multiple instances of the same type of subsystem on a single machine or multiple instances can be installed on separate machines throughout a deployment. Creating additional subsystem instances is similar to installing and configuring the default instances; there is a script to run to create a basic installation and then an HTML-based configuration wizard.
All additional CA, RA, DRM, OCSP, TKS, and TPS instances are installed by running a special tool, pkicreate . After that, they are configured through the HTML-based administration page. For more information on pkicreate , see the Certificate System Command-Line Tools Guide .
NOTE
Additional subsystems can be duplicates, or clones, of existing subsystems. Cloning can be used for load balancing for heavily trafficked servers and for failover support. Clones are installed the same as other subsystems, with slight differences in the subsequent configuration. For more information on using cloning as part of a deployment strategy, see
Chapter 20, Configuring the Certificate System for High Availability .
2.7.1. Running pkicreate
1. Run the pkicreate command. Through the options on this tool, the type of subsystem being created, the configuration directory, instance name, port numbers, and other basic configuration information are set. For example, creating a second DRM instance would have the following command: pkicreate -pki_instance_root=/var/lib/rhpki-drm2 -subsystem_type=kra pki_instance_name=rhpki-drm2
-secure_port=10543 -unsecure_port=10180 -tomcat_server_port=1802 -verbose
NOTE
For a TPS subsystem, do not use the tomcat_server_port option since the TPS subsystem uses Apache rather than Tomcat as its web server.
52
Running pkicreate with Port Separation
For more information on the pkicreate tool options, see the Certificate System Command-Line
Tools Guide .
2. When the instance is successfully created, the process returns a URL for the HTML configuration page. For example: http://server.example.com:10180/kra/admin/console/config/login?pin=nt2z2keqcqAZiBRBGLDf
3. Open the new instance URL, and go through the configuration wizard as described in Section 2.6,
“Configuring the Default Subsystem Instances” . Supply the security domain, CA, instance ID, internal LDAP database, and agent information.
4. When the configuration is complete, restart the subsystem.
/etc/init.d/ instance_ID restart
2.7.2. Running pkicreate with Port Separation
To create an instance with three separate ports for the different subsystem services, run pkicreate with three options which specify the services ports: -admin_secure_port , -agent_secure_port , and -ee_secure_port . For CAs only, there is an additional port for end-entity client authentication, ee_secure_client_auth_port .
1. Run the pkicreate command. For example: pkicreate -pki_instance_root=/var/lib/pki-ca2 -subsystem_type=ca -pki_instance_name=pkica2 -admin_secure_port=9545 -agent_secure_port-9544 -ee_secure_port=9543 ee_secure_client_auth_port=9546 -unsecure_port=9180 -tomcat_server_port=1802 -verbose
2. When the instance is successfully created, the process returns a URL for the HTML configuration page. For example: http://server.example.com:10180/kra/admin/console/config/login?pin=nt2z2keqcqAZiBRBGLDf
3. Open the new instance URL, and go through the configuration wizard as described in Section 2.6,
“Configuring the Default Subsystem Instances” . Supply the security domain, CA, instance ID, internal LDAP database, and agent information.
4. When the configuration is complete, restart the subsystem.
/etc/init.d/ instance_ID restart
For more information on the pkicreate tool options, see the Certificate System Command-Line Tools
Guide .
2.8. Cloning a Subsystem
For failover protection and for availability for high-traffic subsystems, it is possible to clone an existing
CA, RA, DRM, TKS, or OCSP subsystem. To clone a subsystem:
1. Create a new instance using pkicreate .
53
Chapter 2. Installation and Configuration
2. Open the configuration wizard.
3. In the Security Domain panel, add the clone to the same security domain to which the master belongs.
4. The Subsystem Type panel sets whether to create a new instance or a clone; select the clone radio button.
Figure 2.16. Selecting the Subsystem to Clone
5. Give the path and filename of the PKCS #12 backup file which was saved when the master instance was created. If a backup was not created at that time, use the pk12util utility to create a PKCS #12 file.
54
Figure 2.17. Supplying the Key and Certificate Information
Silent Installation
NOTE
When cloning a CA, the master and clone instances have the same CA signing key.
6. The subsystem information is automatically supplied from the master instance to the clone instance once the keys are successfully restored. Complete the configuration process.
7. Restart the clone instance.
/etc/init.d/ instance-id restart
For more information on using cloning as part of a deployment strategy, see Chapter 20, Configuring the Certificate System for High Availability .
2.9. Silent Installation
The Certificate System includes a tool, pkisilent , which can completely create and configure an instance. Normally, adding instances requires running the pkicreate utility to create the instance and then accessing the subsystem HTML page to complete the configuration. The pkisilent utility creates and configures the instance in a single step. The pkisilent tool is downloaded independently from the Certificate System packages. It is available through the Red Hat Certificate
System 7.3
Red Hat Network channel.
NOTE
Run this tool on a system which already has a subsystem installed, since this tool depends on having libraries, JRE, and core jar files already installed.
The silent installation tool has the following format: perl pkisilent Configure subsystem_type -options
The options are slightly different between the subsystems; all subsystems except for the CA subsystem require extra options specifying the Certificate Manager to which to submit the certificate requests.
Example 2.1, “Silent Installation of a CA” shows a silent installation script to install a CA subsystem: perl pkisilent ConfigureCA -cs_hostname localhost -cs_port 9543
-client_certdb_dir /tmp/ -client_certdb_pwd redhat
-preop_pin sYY8er834FG9793fsef7et5 -domain_name "testca" -admin_user admin
-admin_email "[email protected]" -admin_password redhat
-agent_name "rhpki-ca2 agent" -agent_key_size 2048 -agent_key_type rsa
-agent_cert_subject "ca agent cert" -ldap_host server -ldap_port 389
-bind_dn "cn=directory manager" -bind_password redhat
-base_dn "o=rhpki-ca2" -db_name "rhpki-ca2" -key_size 2048 -key_type rsa
-save_p12 true -backup_pwd redhat
Example 2.1. Silent Installation of a CA
55
Chapter 2. Installation and Configuration
Example 2.2, “Silent Installation of a TKS” shows a silent installation script to install a TKS subsystem; this script has extra options to point to the CA server: perl pkisilent ConfigureTKS -cs_hostname localhost -cs_port 13543
-ca_hostname server.example.com -ca_port 9080 -ca_ssl_port 9443
-ca_agent_name agent -ca_agent_password redhat
-client_certdb_dir /tmp/ -client_certdb_pwd redhat
-preop_pin fS44I6SASGF34FD76WKJHIW4 -domain_name "testca" -admin_user admin
-admin_email "[email protected]" -admin_password redhat
-agent_name "rhpki-tks2 agent" -ldap_host server -ldap_port 389
-bind_dn "cn=directory manager" -bind_password redhat -base_dn "o=rhpki-tks2"
-db_name "rhpki-tks2" -key_size 2048 -key_type rsa -agent_key_size 2048
-agent_key_type rsa
-agent_cert_subject "tks agent cert" -backup_pwd redhat
Example 2.2. Silent Installation of a TKS
NOTE
The ConfigureCA can be used to create a security domain or to add the CA to an existing domain; the other scripts only add the subsystem to an existing security domain.
perl pkisilent ConfigureTPS -cs_hostname localhost -cs_port 7988
-ca_hostname server.example.com -ca_port 9080 -ca_ssl_port 9443
-ca_agent_name agent -ca_agent_password redhat
-client_certdb_dir /tmp/ -client_certdb_pwd redhat
-preop_pin fS44I6SASGF34FD76WKJHIW4 -domain_name "testca" -admin_user admin
-admin_email "[email protected]" -admin_password redhat
-agent_name "rhpki-tks2 agent" -ldap_host server -ldap_port 389
-bind_dn "cn=directory manager" -bind_password redhat -base_dn "o=rhpki-tps2"
-db_name "rhpki-tks2" -key_size 2048 -key_type rsa -agent_key_size 2048
-agent_key_type rsa -agent_cert_subject "tps agent cert" -ldap_auth_host server
-ldap_auth_port 389 -ldap_auth_base_dn "o=TPS DB,dc=example,dc=com"
Example 2.3. Silent Installation of a TPS
For more information on using this tool, see the Certificate System Command-Line Tools Guide .
2.10. Updating Certificate System Packages
There are many packages, listed in Section 2.2.3.1, “Red Hat Enterprise Linux RPMs” and
Section 2.2.3.2, “Solaris Packages” , installed with Certificate System for related applications and dependencies, not just the subsystem packages. For all supported platforms, individual Certificate
System packages may be updated through the native package utilities, rpm on Red Hat Enterprise
Linux systems and pkgrm and pkgadd on Solaris 9.
Alternatively, if the appropriate network access is available, an individual package can be updated on
Red Hat Enterprise Linux systems using the up2date command.
NOTE
All Certificate System instances must be stopped before beginning any updates.
• Section 2.10.1, “Updating Certificate System on Red Hat Enterprise Linux”
56
Updating Certificate System on Red Hat Enterprise Linux
• Section 2.10.2, “Updating Certificate System on Solaris”
2.10.1. Updating Certificate System on Red Hat Enterprise Linux
For Red Hat Enterprise Linux, and individual package can up updated either by installing the specific
RPM or by running up2date to update the package.
To install the RPM:
1. Stop all Certificate System instances.
/etc/init.d/ instance_ID stop
2. Log in as root .
3. Install the updated package.
rpm -Uvh package_name
For example: rpm -Uvh rhpki-java-tools-7.3.0-4.noarch.rpm
4. Restart the Certificate System instances.
/etc/init.d/ instance_ID start
Alternatively, using the up2date command.
1. Stop all Certificate System instances.
/etc/init.d/ instance_ID stop
2. Log in as root .
3. Run up2date for the package. For example: up2date rhpki-java-tools-7.3.0-4.noarch
4. Restart the Certificate System instances.
/etc/init.d/ instance_ID start
2.10.2. Updating Certificate System on Solaris
Before installing or upgrading Certificate System on Solaris, ensure that all packages and binaries from the previous installation have been removed. To remove all existing Certificate System components:
1. Stop all Certificate System instances.
57
Chapter 2. Installation and Configuration
/etc/init.d/ instance_ID stop
2. Log in as root .
3. Use the following commands to remove the previous instances: pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-ca pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-ocsp pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-tks pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-tps
4. Remove all subsystem binaries using rhpki-uninstall : rhpki-uninstall -pki_subsystem=all
5. Remove the actual install and uninstall scripts: pkgrm RHATrhpki-managex
To install the new CA:
1. Install the install and uninstall scripts: pkgadd -d RHATrhpki-managex-7.3.0-12.sol9.noarch.pkg
2. Use the install script to install the CA: rhpki-install -pki_subsystem=ca -pki_package_path=.
IMPORTANT
Ensure that the current directory contains all the Solaris packages.
3. For the remaining subsystems, use tks , ocsp , etc., as the pki_subsystem parameter.
4. Restart the Certificate System instances.
/etc/init.d/ instance_ID start
NOTE
The Solaris installation uses the same directory structure and configuration as the Red
Hat Enterprise Linux installation.
58
Uninstalling Certificate System Subsystems
2.11. Uninstalling Certificate System Subsystems
It is possible to remove individual subsystem instances or to uninstall all packages associated with an entire subsystem. Instances and subsystems are installed and uninstalled individually. For example, it is possible to uninstall a DRM subsystem while leaving an installed and configured CA subsystem. It is also possible to remove a single CA instance while leaving other CA instances on the machine.
2.11.1. Removing a Subsystem Instance
To remove a subsystem instance, run the following command: pkiremove -pki_instance_root= pki_instance_root -pki_instance_name= pki_instance_ID
The pki_instance_root is the directory path of the instance, such as /var/lib . The pki_instance_name is the instance name, such as rhpki-ca .
pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-ca1
PKI instance Deletion Utility ...
PKI instance Deletion Utility cleaning up instance ...
Stopping rhpki-ca1: process already stopped
Removing dir /var/lib/rhpki-ca1
Removing file /var/log/rhpki-ca1-install.log
Removing file /etc/init.d/rhpki-ca1
Removing file /usr/share/applications/rhpki-ca1-config.desktop
Removing file /usr/bin/dtomcat5-rhpki-ca1
Example 2.4. Removing a CA Instance pkiremove removes the instance and any related files, such as the certificate databases, certificates, keys, and associated users. It does not uninstall the subsystem.
2.11.2. Removing Certificate System Subsystems
To uninstall an individual Certificate System subsystem:
1. Remove all the associated subsystem instances using pkiremove . For example: pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-ca
2. Run the uninstall utility. rhpki-uninstall is one of the tools included in the rhpki-manage package. For example: rhpki-uninstall -pki_subsystem=ca
The subsystem type can be ca , ra , drm , esc , ocsp , tks , tps , or all . This command uninstalls the Certificate System servers as well as the Enterprise Security Client. This also removes all
Certificate System RPMs used by the specified subsystems.
3. If all of the Certificate System subsystems on the machine have been uninstalled, remove the
Certificate System uninstall utility; this means removing the rhpki-manage package.
59
Chapter 2. Installation and Configuration rpm -ev rhpki-manage
60
Chapter 3.
Administrative Basics
This chapter discusses the Certificate System administrative console, the configuration files, and other basic administrative tasks such as starting and stopping the server, managing logs, changing port assignments, and changing the internal database.
3.1. Administrative Console
The Certificate System provides a GUI-based administration tool called the Console that is used for administrative tasks such as managing users and maintaining the subsystem, performs daily operational and managerial duties for the subsystem, and configures the server.
NOTE
The TPS subsystem does not have an administrative console; administrative functions are performed through the HTML services pages and by manually editing the CS.cfg
file.
The Console is launched using the pkiconsole utility, with the hostname, subsystem SSL port, and subsystem type specified.
pkiconsole https:// hostname:SSLport/subsystemType
For a Certificate Manager running a a host named host.example.com
on the default CA SSL port
9443 , the console command would be as follows: pkiconsole https://host.example.com:9443/ca
When the command is run, a prompt, opens for the administrative user ID and password.
The Console can be used to access the server locally or remotely, as long as the Certificate System is installed. The Console has the following tabs:
• The Configuration tab shows information about the subsystem and is the way the configuration settings are modified. The choices available in this tab are different depending on which subsystem type the instance is. All subsystems have the following options:
• Users and groups
• Access control lists
• Logs
• Certificates
61
Chapter 3. Administrative Basics
• The Status tab allows the administrator to view the contents of various logs maintained by the
Certificate System instance. See Section 3.9, “Logs” for more information.
Figure 3.1. Certificate System Console
3.2. Enabling SSL Client Authentication for the Certificate
System Console
Certificate-based authentication to the Certificate System Console can be enabled so that administrators must authenticate using a client certificate before logging into the Certificate System
Console. Store the administrators' certificates before enabling certificate-based authentication.
To enable SSL client authentication, both the client and the server need configured to run over SSL.
First, setup the Certificate System server to use SSL client authentication:
1. Store the certificates for any administrator using this system. The certificate should be either from the CA itself or from whichever CA signed the certificate for the subsystem.
a. Open the subsystem console.
b. Select the Users and Groups option on the left.
c. In the Users tab, select the administrative user, and click Manage Certificates .
d. Click Import .
e. Paste in the base-64 encoded SSL client certificate.
Make sure the client certificate is good for SSL client authentication; otherwise, the server will not accept the client certificate and will post an error message in the error log in the /var/ log/ instanceID /system :
62
Enabling SSL Client Authentication for the Certificate System Console failure (14290): Error receiving connection
SEC_ERROR_INADEQUATE_CERT_TYPE - Certificate type not approved for application.)
2. Stop the subsystem.
/etc/init.d/ instance_ID stop
3. Open the instance configuration directory, /var/lib/ instance_ID /conf .
4. Open the file CS.cfg
.
5. Change the value of the authType parameter from pwd to sslclientauth : authType=sslclientauth
6. Save the file.
7. Open the server.xml
file.
8. Change the clientAuth="false" attribute to clientAuth="true" in the SSL Connector section:
<Connector port="9443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true" clientAuth="true" sslProtocol="SSL"
.....
serverCertFile="/var/lib/rhpki-ca/conf/serverCertNick.conf"
passwordFile="/var/lib/rhpki-ca/conf/password.conf"
passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
certdbDir="/var/lib/rhpki-ca/alias"/>
9. Start the subsystem.
/etc/init.d/ instance_ID start
After setting up the server, then configure the client to use SSL client authentication.
The Console must have access to the administrator certificate and keys used for SSL client authentication to the server. The Console's default certificate and key databases are stored in the
.mcc
directory.
To provide access to the administrator certificate and keys, either export them from the administrator's browser into a .p12
file and then import it by using pk12util , or copy the browser's certificate and key databases into the .mcc
directory. (This procedure assumes that the certificates are exported from the browser into a .p12
file.)
1. Export the certificate and keys into a file, such as admin.p12
.
2. Open the .mcc
directory, and run pk12util to export the certificates.
pk12util -i admin.p12 -d . -W [p12filepassword]
63
Chapter 3. Administrative Basics
If the procedure is successful, the command prints the following: pk12util: PKCS12 IMPORT SUCCESSFUL
3. Start the Console; now, it prompts for a certificate.
3.3. System Passwords
The Certificate System stores passwords used to bind to servers or to unlock tokens when the server starts in a plain text file, password.conf
.
Passwords for the internal database and other database-related passwords for optional features are stored in a plain text file, password.conf
, in the subsystem conf/ directory. The passwords stored within it are used to bind to the various Certificate System services. Since the password.conf
file is in clear text, it is possible to modify them simply through a text editor.
The list of passwords stored in this file includes the following:
• The bind password used by the Certificate System instance to access and update the internal database.
• The bind password used by the Certificate System instance to access and remove PINs from the authentication directory, if the Certificate System is configured to remove PINs from the authentication directory.
• The bind password used by the subsystem to access and update the LDAP directory; this is required only if the Certificate System instance is configured for publishing certificates and CRLs to an LDAP-compliant directory.
• For a TPS instance, the bind password used to access and update the token database.
The password.conf
file also contains the token passwords needed to open the private keys of the subsystem.
• For a Certificate Manager, the token password unlocks the private keys for the Certificate Manager's
CA signing, SSL server, subsystem, and OCSP signing certificates.
• For a DRM, the token password unlocks the private keys for the DRM's storage, transport, subsystem, and SSL server certificates.
• For an OCSP, the token password unlocks the private keys for the OCSP's signing, subsystem, and
SSL server certificates.
• For a TPS, the token password unlocks the private keys for the subsystem and SSL server certificates.
3.3.1. Protecting the password.conf File
Certificate System centralizes all passwords in a clear-text file, password.conf
, in the conf directory. The default configuration creates and stores all required passwords in this file, which keeps password management simple and clean and allows the file to be edited in a text editor and passwords to be manually added, deleted, or modified.
64
Protecting the password.conf File
However, storing passwords in clear text can be dangerous. Setting proper file permissions protects this file. Alternatively, the password.conf
file can be by-passed by doing the following:
1. Back up the password.conf
file.
2. Remove the password.conf
file.
rm password.conf
3. Create a pipe corresponding to password.conf
.
mkfifo password.conf
4. With the password.conf
pipe, start the subsystem instance.
a. Run the standard start script. For example:
/etc/init.d/rhpki-ca start b. Monitor the Tomcat web server log file, catalina.out
, and the debug log. For example: tail -f /var/lib/rhpki-ca/logs/catalina.out /var/lib/rhpki-ca/logs/debug
The server process will hang as it restarts because it is waiting for the input from the default password.conf
file.
c. Redirect the password to the password.conf
pipe. Assuming that the backup file for password.conf
is called password.bak
, run cat password.bak > password.conf
.
Repeat this command until the server is fully started; this is apparent in the debug log.
This process still uses a clear text password file, password.bak
, but this moves the password store so that it is external to the Certificate System instance and can be stored anywhere, such as a smart card. This only requires a utility which can reconstruct the original password file. For example, this processes uses the zip tool to protect the password file:
1. Zip and protect the password.conf
file using zip .
zip -e secret.zip password.conf
2. Delete the password.conf
file, and create a pipe called password.conf
.
3. Run the regular start script.
4. Monitor the Tomcat web server log, catalina.out
, and the debug log.
5. Provide the passwords to the subsystem instance by running the following: unzip -c secret.zip password.conf > password.conf
This is a simple and very flexible way to protect the clear text password file while still allowing passwords to be managed easily through a text editor.
65
Chapter 3. Administrative Basics
3.3.2. Password-Quality Checker
A Certificate System plug-in, password-quality checker , monitors the quality of passwords set within the Certificate System. All passwords used in the Certificate System are checked by the passwordquality checker, which by default checks that the length of a password is at least 8 characters long.
There are no checks regarding which characters are valid or invalid. Trying to set passwords that do not meet the quality rules returns an error message.
NOTE
The TPS subsystem does not have a password-quality checker.
The Certificate System enforces password quality on only those passwords that it creates and manages. Passwords for LDAP directory access are not subjected to quality checks. In an LDAP directory access, the remote directory enforces the quality of the password because it is created and managed by the directory.
3.4. Starting, Stopping, and Restarting Certificate System
Subsystems
Each Certificate System subsystem instance is started, stopped, and restarted separately. This section describes how to start, stop, and restart a subsystem instance.
3.4.1. Starting a Server Instance
A subsystem instance is started like other system programs. To start an instance:
1. Log in as root .
2. Run /etc/init.d/ , specifying the instance name. For example, for an instance named rhpkica , the command is as follows:
/etc/init.d/rhpki-ca start
3.4.2. Stopping a Server Instance
A subsystem instance is stopped like other system programs. To stop an instance:
1. Log in as root .
2. Run /etc/init.d/ , specifying the instance name. For example, for an instance named rhpkica , the command is as follows:
/etc/init.d/rhpki-ca stop
3.4.3. Restarting a Server Instance
A subsystem instance is stopped like other system programs. To stop an instance:
1. Log in as root .
66
Restarting a Subsystem after a Machine Restart
2. Run /etc/init.d/ , specifying the instance name. For example, for an instance named rhpkica , the command is as follows:
/etc/init.d/rhpki-ca restart
3.4.4. Restarting a Subsystem after a Machine Restart
If a computer running a subsystem is shut down unexpectedly, more services than just the subsystem must be restarted, in the proper order, for the subsystem to be available both through the HTML services page and the administrative console.
1. Restart the Directory Server Administration Server.
cd /opt/redhat-ds/
./start-admin
2. Restart the Directory Server.
cd /opt/redhat-ds/slapdinstance_ID
./start-slapd
3. Restart the Certificate System subsystem instance.
/etc/init.d/ instance_ID start
3.5. Mail Server
The notifications and jobs features use the mail server set in the Certificate System CA instances to send notification messages. Set up a mail server by doing the following:
1. Open the CA subsystem administrative console. For example: pkiconsole https://host.example.com:9443/ca
2. In the Configuration tab, highlight the instance name at the top, and select the SMTP tab.
3. Supply the server name and port number of the mail server.
The server name is the fully qualified DNS hostname of the machine on which the mail server is installed, such as mail.example.com
. By default, the hostname of the mail server is localhost instead of the actual hostname.
The default port number on which the SMTP mail server listens is 25 .
4. Click Save .
3.6. Configuration Files
The runtime properties of a Certificate System subsystem are governed by a set of configuration parameters. These parameters are stored in a file that is read by the server during startup.
67
Chapter 3. Administrative Basics
An ASCII file, named CS.cfg
, is created and populated with the appropriate configuration parameters when a subsystem is first installed. The way the instance functions are modified is by making changes through the subsystem console, which is the recommended method. The changes made in the administrative console are reflected in the configuration file.
It is also possible to edit the CS.cfg
configuration file directly. Since the TPS subsystem does not use an administrative console, all configuration changes must be made by editing the CS.cfg
file manually.
3.6.1. Locating the Configuration File
Each instance of a Certificate System subsystem has its own configuration file, CS.cfg
. The file for the subsystem is different depending on the installation choices and on which subsystem type is installed.
The CS.cfg
file is located in the /var/lib/ instance_ID /conf directory.
3.6.2. Editing the Configuration File
WARNING
Do not edit the configuration file directly without being familiar with the configuration parameters or without being sure that the changes are acceptable to the server. The
Certificate System fails to start if the configuration file is modified incorrectly. Incorrect configuration can also result in data loss.
To modify the configuration file:
1. Stop the subsystem instance.
The configuration file is stored in the cache when the instance is started. Any changes made to the instance through the Console are changed in the cached version of the file. When the server is stopped or restarted, the configuration file stored in the cache is written to disk. Stop the server before editing the configuration file or the changes will be overwritten by the cached version when the server is stopped.
2. Open the /var/lib/ instance_ID /conf directory.
3. Open the CS.cfg
file in a text editor.
4. Edit the parameters in the file, and save the changes.
5. Start the subsystem instance.
3.6.3. Guidelines for Editing the Configuration File
This section covers information and tips about the configuration file.
• The format for parameters is as follows:
#comment
[parameter]=value
68
Guidelines for Editing the Configuration File
• Comment lines begin with the pound (#) character. Comment lines, blank lines, unknown parameters, or misspelled parameters are ignored by the server.
• Subsystem-specific parameters are distinguished by a prefix identifying the subsystem as follows:
• ca for the Certificate Manager
• kra for the DRM
• ocsp for the OCSP
• tks for the TKS
• tps for the TPS
• The parameter names and their values are strings. The parameter names can be hierarchically structured with periods separating the levels; for example, ca.Policy.rule.RSAKeyRule.maxSize
. The entries corresponding to a lower level, such as
Policy in the example, can be requested from the configuration corresponding to its higher level, ca in the example.
• The values that need to be localized such as DNs in multibyte format should be entered in utf8 format.
• The values of some parameters are referenced by other parts of the configuration file.
• The configuration file supports the UNIX-style file separator, the forward slash (/). If the backward slash (\) file separator is required, use two backward slashes (\\) instead of one.
• Authentication parameters (CA only):
• All authentication-specific information, such as names of registered authentication plug-in modules and any configured instances, appears in the authentication section of the configuration file.
• Each registered authentication plug-in module is identified by its implementation name and the corresponding Java
™
class.
• Each configured instance of an authentication module is identified by the name or ID set when creating it.
• There can be multiple instances from an implementation; each instance must have a unique name. To do this, copy all of the parameters belonging to the module used to create the instance.
Change the name of each of these parameters to the new name for this instance, and then change the values of all the parameters as appropriate.
• The name of an authentication instance must be used in the corresponding certificate profile so that the server is able to determine the authentication method during end-user enrollment.
• Job Scheduler parameters (CA only):
• All job-specific information, such as registered job modules and configured instances, appears in the job scheduler section of the configuration file.
• Each registered job module is identified by its implementation name and the corresponding
Java ™ class.
69
Chapter 3. Administrative Basics
• Each job or configured instance of a job module is identified by the name specified when the job was created.
• There can be as many instances of an implementation as desired; each instance must have a unique name. To do this, copy all of the parameters belonging to the module used to create the instance. Change the name of each of these parameters to the new name for this instance, and then change the values of all the parameters as appropriate.
3.6.4. Duplicating Configuration from One Instance to Another
When deploying a large number of Certificate System instances that are identical and all these instances should have the same configuration, it is possible to configure one of the instances and then replace the configuration files of the other instances with the one that contains the required configuration.
NOTE
Be careful when replacing configuration of one instance with another. The configuration file for the original instance contains instance-specific parameters. If the new instance's configuration file is directly replaced with that of the first instance, the new instance will fail to start properly if the instance specific parameters are not adjusted to those required by the new instance.
The recommended way to create duplicate instances is to clone the instances when the subsystem instance is configured. For more information on cloning, see Chapter 20,
Configuring the Certificate System for High Availability .
3.6.5. Other File Locations
Certificate System servers consist of subsystems and instances. Server subsystems are contained in non-relocatable RPMs analogous to shared libraries, Java ™ archive files, binaries, and templates which must be stored in a fixed location, while server instances analogous to relocatable, user-specific default and customized forms and data, which can be stored anywhere on a system.
Since Certificate System server RPMs are non-relocatable, the subsystem file locations listed in
Table 3.1, “Server File Locations” are fixed.
Directory Location
/usr/bin
/usr/lib
/usr/lib/dirsec
/usr/lib/java
Contents pkicreate and pkiremove instance configuration scripts and tools (Java ™ , native, and security) shared by the CA, RA, DRM,
OCSP, and TKS subsystems.
Libraries shared by the CA, RA, DRM, OCSP, and TKS subsystems. For 32-bit Red Hat
Enterprise Linux AS and ES i386 machines only.
Security libraries shared by the CA, RA, DRM,
OCSP, and TKS subsystems. For 32-bit Red Hat
Enterprise Linux AS and ES i386 machines only.
JNI Java ™ archive files shared by the CA, RA,
DRM, OCSP, and TKS subsystems. For 32-
70
Other File Locations
Directory Location
/usr/lib/java/dirsec
/usr/lib64
/usr/lib64/dirsec
/usr/lib64/java
/usr/lib64/java/dirsec
/usr/share/doc
/usr/share/java/rhpki
/usr/share/java/rhpki/ subsystem_type
/usr/share/rhpki
/usr/share/rhpki/ subsystem_type
/var/lib/tomcat5/common/lib
/var/lib/tomcat5/server/lib
/usr/lib/httpd/modules
Contents bit Red Hat Enterprise Linux AS and ES i386 machines only.
JNI security Java ™ archive files shared by the
CA, RA, DRM, OCSP, and TKS subsystems. For
32-bit Red Hat Enterprise Linux AS and ES i386 machines only.
Libraries shared by the CA, RA, DRM, OCSP, and TKS subsystems. For 64-bit Red Hat
Enterprise Linux AS and ES x86_64 machines only.
Security libraries shared by the CA, RA, DRM,
OCSP, and TKS subsystems. For 64-bit Red Hat
Enterprise Linux AS and ES x86_64 machines only.
JNI Java ™ archive files shared by the CA, RA,
DRM, OCSP, and TKS subsystems. For 64-bit
Red Hat Enterprise Linux AS and ES x86_64 machines only.
JNI security Java ™ archive files shared by the
CA, RA, DRM, OCSP, and TKS subsystems.
For 64-bit Red Hat Enterprise Linux AS and ES x86_64 machines only.
LICENSE and README text files shared by the
Certificate System subsystems.
Java ™ archive files shared by the CA, RA, DRM,
OCSP, and TKS subsystems.
Java ™ archive files shared by all instances of a subsystem type. For example, /usr/share/ java/rhpki/ca contains files shared by all CA subsystem instances.
Common files and templates used to create CA,
RA, DRM, OCSP, and TKS instances.
Files and templates used to create subsystem instances. For instance, /usr/share/rhpki/ ca contains files used to create CA instances.
Java
™
archive files shared by local Tomcat web applications and shared by the CA, RA, DRM,
OCSP, and TKS subsystems.
Java
™
archive files used by the local Tomcat web server and shared by the CA, RA, DRM,
OCSP, and TKS subsystems.
For TPS subsystems only.
Apache modules shared by TPS subsystems. For 32-bit Red Hat
Enterprise Linux AS and ES i386 machines only.
71
Chapter 3. Administrative Basics
Directory Location
/usr/lib/mozldap
/usr/lib64/httpd/modules
/usr/lib64/mozldap
Contents
For TPS subsystems only.
Mozilla LDAP SDK tools shared by TPS subsystems. For 32-bit Red
Hat Enterprise Linux AS and ES i386 machines only.
For TPS subsystems only.
Apache modules shared by TPS subsystems. For 64-bit Red Hat
Enterprise Linux AS and ES x86_64 machines only.
For TPS subsystems only.
Mozilla LDAP SDK tools shared by TPS subsystems. For 64-bit
Red Hat Enterprise Linux AS and ES x86_64 machines only.
Table 3.1. Server File Locations
3.6.6. Default Server Instance Locations
The Certificate System server instances are created by the pkicreate utility. Although Certificate
System server instances are relocatable, the following are the default instance locations:
• Section 3.6.6.1, “CA Default Instance Location”
• Section 3.6.6.2, “DRM Default Instance Location”
• Section 3.6.6.3, “OCSP Default Instance Location”
• Section 3.6.6.4, “TKS Default Instance Location”
• Section 3.6.6.5, “TPS Default Instance Location”
3.6.6.1. CA Default Instance Location
Default Location
/etc/init.d/rhpki-ca
/etc/rhpki-ca
/var/lib/rhpki-ca
Type of
Object
File
Directory
Directory
/var/log/rhpki-ca
/var/log/rhpki-cainstall.log
Directory
File
/var/run/rhpki-ca.pid
File
Table 3.2. CA Default Instance Location
Description
The script used to start, stop, or restart the CA instance.
Contains the configuration file for the CA instance.
Contains the user-specific default and customized forms and data for the CA instance.
Contains the log files for the CA instance.
A log file containing the configuration steps performed to create the CA instance
A file containing the active process ID of the running CA instance.
72
Default Server Instance Locations
3.6.6.2. DRM Default Instance Location
Default Location Type of
Object
/etc/init.d/rhpki-kra File
Description
/etc/rhpki-kra
/var/lib/rhpki-kra
Directory
Directory
/var/log/rhpki-kra
/var/log/rhpki-krainstall.log
Directory
File
/var/run/rhpki-kra.pid
File
The script used to start, stop, or restart the
DRM instance.
Contains the configuration file for the DRM instance.
Contains the user-specific default and customized forms and data for the DRM instance.
Contains the log files for the DRM instance.
A log file containing the configuration steps performed to create the DRM instance.
A file containing the active process ID of the running DRM instance.
Table 3.3. DRM Default Instance Location
3.6.6.3. OCSP Default Instance Location
Default Location Type of
Object
/etc/init.d/rhpki-ocsp File
Description
/etc/rhpki-ocsp
/var/lib/rhpki-ocsp
Directory
Directory
/var/log/rhpki-ocsp
/var/log/rhpki-ocspinstall.log
Directory
File
/var/run/rhpkiocsp.pid
File
Table 3.4. OCSP Default Instance Location
The script used to start, stop, or restart the
OCSP instance.
Contains the configuration file for the OCSP instance.
Contains the user-specific default and customized forms and data for the OCSP instance.
Contains the log files for the OCSP instance.
A log file containing the configuration steps performed to create the OCSP instance.
A file containing the active process ID of the running OCSP instance.
3.6.6.4. TKS Default Instance Location
Default Location Type of
Object
/etc/init.d/rhpki-tks File
Description
/etc/rhpki-tks Directory
The script used to start, stop, or restart the
TKS instance.
Contains the configuration file for the TKS instance.
73
Chapter 3. Administrative Basics
Default Location
/var/lib/rhpki-tks
Type of
Object
Directory
/var/log/rhpki-tks
/var/log/rhpki-tksinstall.log
Directory
File
/var/run/rhpki-tks.pid
File
Table 3.5. TKS Default Instance Location
Description
Contains the user-specific default and customized forms and data for the TKS instance.
Contains the log files for the TKS instance.
A log file containing the configuration steps performed to create the TKS instance.
A file containing the active process ID of the running TKS instance.
3.6.6.5. TPS Default Instance Location
Default Location Type of
Object
/etc/init.d/rhpki-tps File
Description
/etc/rhpki-tps/conf
/var/lib/rhpki-tps
Directory
Directory
/var/log/rhpki-tps
/var/log/rhpki-tpsinstall.log
Directory
File
/var/log/rhpki-tps/ rhpki-tps.pid
File
Table 3.6. TPS Default Instance Location
The script used to start, stop, or restart the
TPS instance.
Contains the configuration file for the TPS instance.
Contains the user-specific default and customized forms and data for the TPS instance.
Contains the log files for the TPS instance.
A log file containing the configuration steps performed to create the TPS instance.
A file containing the active process ID of the running TPS instance.
3.7. Using Security-Enhanced Linux
Security-enhanced Linux, or SELinux, is a collection of mandatory access control rules which are enforced across a system to restrict unauthorized access and tampering by limiting users and applications to the lowest amount of access possible for them to operate. All Certificate System subsystems can be installed and run with SELinux policies fully enforced.
SELinux is configured through the config configuration file in the /etc/selinux/ directory. The typical SELinux configuration is as follows:
###########################################
# SELINUX= can take one of these three values:
# enforcing - SELinux security policy is enforced.
# permissive - SELinux prints warnings instead of enforcing.
# disabled - SELinux is fully disabled.
SELINUX=enforcing
# SELINUXTYPE= type of policy in use. Possible values are:
# targeted - Only targeted network daemons are protected.
# strict - Full SELinux protection.
74
Using Java Servlets
SELINUXTYPE=targeted
###########################################
NOTE
All of the instances run in un-confined mode with no security-enhanced policies in effect for the server.
3.8. Using Java Servlets
Each subsystem Java ™ servlet supports a parameter called xml , which can have a value of either true or false . This parameter sets what kind of data the servlet returns; by default all of the subsystem interfaces, like the agent services page or the end-entities page, returns data in HTML.
Setting the xml with a value of true returns XML data. This XML information is useful for writing scripts that interact with the server.
The xml parameter is appended to the end of the interface link. For example, the server returns an
HTML page when the following link is accessed: https://server.example.com:9443/ca/ee/ca/displayBySerial?op=displayBySerial&serialNumber=0x1
Appending xml=true to the end of the link returns the same page in XML: https://server.example.com:9443/ca/ee/ca/displayBySerial?
op=displayBySerial&serialNumber=0x1 &xml=true
3.9. Logs
This section explains how to use the Console to configure logs maintained by the Certificate System instance and how to view log contents.
This section contains the following subsections:
• Section 3.9.1, “About Logs”
• Section 3.9.2, “Services That Are Logged”
• Section 3.9.3, “Log Levels (Message Categories)”
• Section 3.9.4, “Buffered Versus Unbuffered Logging”
• Section 3.9.5, “Log File Rotation”
• Section 3.9.6, “Configuring Logs in the Console”
• Section 3.9.7, “Configuring Logs in the CS.cfg File”
• Section 3.9.8, “Configuring TPS Logs”
• Section 3.9.9, “Monitoring Logs”
• Section 3.9.10, “Signing Log Files”
75
Chapter 3. Administrative Basics
• Section 3.9.11, “Registering a Log Module”
• Section 3.9.12, “Deleting a Log Module”
3.9.1. About Logs
The Certificate System subsystems create log files that record events related to activities, such as administration, communications using any of the protocols the server supports, and various other processes employed by the subsystems. While a subsystem instance is running, it keeps a log of information and error messages on all the components it manages. Additionally, the Apache and
Tomcat web servers generate error and access logs.
Log plug-in modules are listeners which are implemented as Java ™ classes and are registered in the configuration framework.
Each subsystem instance maintains its own log files.
All the log files and rotated log files, except for audit logs, are located in the /var/lib/ instance_id / logs directory.
Audit logs, signed and regular, are located in the /var/lib/ instance_id /logs/signedAudit directory. The default location for logs can be changed by modifying the configuration.
3.9.1.1. System Log
This log, system , records information about requests to the server (all HTTP and HTTPS requests) and the responses from the server. Information recorded in this log includes the IP address of the client machine that accessed the server; operations performed, such as search, add, and edit; and the result of the access, such as the number of entries returned. This log is on by default.
3.9.1.2. Transactions Log
This log, transactions , records messages specific to the certificate service, such as certificate requests, revocation requests, and CRL publication, and can detect any unauthorized access or activity. This log is on by default.
3.9.1.3. Debug Logs
Debug logs for each subsystem record much more detailed information than system, transaction, and access logs. Debug logs contain very specific information for every operation performed by the subsystem, including plug-ins and servlets which are run, connection information, and server request and response messages.
The general types of services which are recorded to the debug log are briefly discussed in
Section 3.9.2, “Services That Are Logged” . These services include authorization requests, processing certificate requests, certificate status checks, and archiving and recovering keys, and access to web services.
For example, the CA contains certificate request information:
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.profileapprovedby$ value=admin
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.cert_request
$
value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA63rhLAVqvVrmdjGgcLTWMb5Czx3DdHLrGO4MS8wfl8EP1bFhKDmxpXYOlsCTznAXby4iinwutOcBXcp2xICrNHwoVZPR2A4ZifIV
+vj2qrohyUlTYbL+bTrIWZAnzAW8scKynfMmeRuSPtoBPT1M58SWjB05pTqpuB8Bcc8tEUUCAwEAAakQMA4GA1UdDwEB/
76
About Logs wQEAwIF4DAzMBUGCSsGAQUFBwUBAQwIcmVnVG9rZW4wGgYJKwYBBQUHBQECDA1hdXRoZW50aWNhdG9yoYGTMA0GCSqGSIb3DQEBBQUAA4GBAH8Hg6uvDTVC5pDQtWkB4q2DFhou9pcMp1Ar84OX4d2TMoqCQfKBecx3+e423m9PAjTv
+ck/ xW0Nj8H32krmv7DzWzXkLBD2MSMTmxBORX5dCsxkCdiHCEgCfTOnxCJpdmjHPuSPOaQmtKBpAEVaQoUwnEytOqDkCkhlZ1nt02w1
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.profile$
value=true
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.cert_request_type$ value=crmf
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.requestversion$ value=1.0.0
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.req_locale$
value=en
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requestowner
$ value=RA-test4.redbudcomputer.local-4747
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.dbstatus$
value=NOT_UPDATED
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.subject$
value=uid=jsmith, [email protected]
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.requeststatus$ value=begin
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.auth_token.user$ value=uid=RAtest4.redbudcomputer.local-4747,ou=People,dc=test4.redbudcomputer.local-pki-ca
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.req_key$
value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M
HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M
HTmlOqm4HwFxzy0RRQIDAQAB
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.auth_token.authmgrinstname$ value=raCertAuth
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.auth_token.uid$ value=RA-test4.redbudcomputer.local-4747
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.auth_token.userid$ value=RA-test4.redbudcomputer.local-4747
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.requestor_name$ value=
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.profileid$
value=caRAagentCert
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.auth_token.userdn$ value=uid=RAtest4.redbudcomputer.local-4747,ou=People,dc=test4.redbudcomputer.local-pki-ca
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.requestid$
value=20
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=
$request.auth_token.authtime$ value=1212782378071
[06/Jun/2008:14:59:38][http-9443-Processor24]: ProfileSubmitServlet: key=$request.req_x509info
$ value=MIICIKADAgECAgEAMA0GCSqGSIb3DQEBBQUAMEAxHjAcBgNVBAoTFVJlZGJ1ZGNv^M bXB1dGVyIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X^M
DTA4MDYwNjE5NTkzOFoXDTA4MTIwMzE5NTkzOFowOzEhMB8GCSqGSIb3DQEJARYS^M anNtaXRoQGV4YW1wbGUuY29tMRYwFAYKCZImiZPyLGQBARMGanNtaXRoMIGfMA0G^M
CSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLPHcN0cusY^M
7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChVk9HYDhmJ^M
8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaMHTmlOqm4^M
HwFxzy0RRQIDAQABo4HFMIHCMB8GA1UdIwQYMBaAFG8gWeOJIMt+aO8VuQTMzPBU^M
78k8MEoGCCsGAQUFBwEBBD4wPDA6BggrBgEFBQcwAYYuaHR0cDovL3Rlc3Q0LnJl^M
ZGJ1ZGNvbXB1dGVyLmxvY2FsOjkwODAvY2Evb2NzcDAOBgNVHQ8BAf8EBAMCBeAw^M
HQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMCQGA1UdEQQdMBuBGSRyZXF1^M
ZXN0LnJlcXVlc3Rvcl9lbWFpbCQ=
Likewise, the OCSP shows OCSP request information:
[07/Jul/2008:06:25:40][http-11080-Processor25]: OCSPServlet: OCSP Request:
[07/Jul/2008:06:25:40][http-11080-Processor25]: OCSPServlet:
MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU
77
Chapter 3. Administrative Basics
3.9.1.4. Installation Logs
Every time a subsystem is created either through the initial installation or creating additional instances with pkicreate , an installation file with the complete debug output from the installation, including any errors and, if the installation is successful, the URL and PIN to the configuration interface for the instance. The file is created in the default log directory, /var/log , with a name in the form instance_ID -install.log
. For example:
/var/log/rhpki-ca-install.log
3.9.1.5. Self-Tests Log
The self-tests log records information obtained during the self-tests run when the server starts or when the self-tests are manually run. The tests can be viewed by opening this log. This log is not configurable through the Console. This log can only be configured by changing settings in the CS.cfg
file. The information about logs in this section does not pertain to this log. See Section 3.10, “Self-
Tests” for more information about self-tests.
3.9.1.6. Signed Audit Log
The audit log contains records for events that have been set up as recordable events. If the logSigning attribute is set to true , the audit log is signed with a log signing certificate belonging to the server. This certificate can be used by auditors to verify that the log has not been tampered with.
See Section 3.9.13, “Signed Audit Log” .
3.9.1.7. Apache and Tomcat Error and Access Logs
The CA, RA, DRM, OCSP, and TKS subsystems use a Tomcat web server instance for their agent and end-entities' interfaces. The TPS subsystem uses an Apache web server.
Error and access logs are created by the Apache and Tomcat web servers, which are installed with the
Certificate System and provide HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface.
Apache (TPS) access_log error_log
Tomcat (CA, RA, DRM, OCSP, TKS) admin.
timestamp catalina.
timestamp catalina.out
host-manager.
timestamp localhost.
timestamp localhost_access_log.
timestamp manager.
timestamp
Table 3.7. Logs Created by Apache and Tomcat
These logs are not available or configurable within the Certificate System; they are only configurable within Apache or Tomcat. See the Apache documentation for information about configuring these logs.
78
Services That Are Logged
3.9.2. Services That Are Logged
All major components and protocols of Certificate System log messages to log files. Table 3.8,
“Services Logged” lists services that are logged by default. To view messages logged by a specific service, customize log settings accordingly. For details, see Section 3.9.9, “Monitoring Logs” .
Service
ACLs
Administration
All
Authentication
Certificate Authority
Database
HTTP
Description
Logs events related to access control lists.
Logs events related to administration activities, such as HTTPS communication between the
Console and the instance.
Logs events related to all the services.
Logs events related to activity with the authentication module.
Logs events related to the Certificate Manager.
Logs events related to activity with the internal database.
Logs events related to the HTTP activity of the server.
Key Recovery Authority
LDAP
OCSP
Others
Request Queue
User and Group
Table 3.8. Services Logged
NOTE
HTTP events are actually logged to the errors log belonging to the
Apache server incorporated with the
Certificate System to provide HTTP services.
Logs events related to the DRM.
Logs events related to activity with the LDAP directory, which is used for publishing certificates and CRLs.
Logs events related to OCSP, such as OCSP status GET requests.
Logs events related to other activities, such as command-line utilities and other processes.
Logs events related to the request queue activity.
Logs events related to users and groups of the instance.
3.9.3. Log Levels (Message Categories)
The different events logged by Certificate System services are deteremined by the log levels, which makes identifying and filtering events more simple. The different Certificate System log levels are listed in Table 3.9, “Log Levels and Corresponding Log Messages” and Table 3.10, “TPS Log Levels and Log Entries” .
79
Chapter 3. Administrative Basics
NOTE
All of the Certificate System subsystems (CA, RA, DRM, TKS, and OCSP) have seven log levels, 0 to 6, except for the TPS subsystem, which has eleven log levels (0 to 10).
Log levels are represented by numbers 0 to 6 ( 0 to 10 for TPS), each number indicating the level of logging to be performed by the server. The level sets how detailed the logging should be.
• A higher priority level means less detail because only events of high priority are logged; the highest priority log level is 0 .
• A lower priority level means greater detail because more kinds of events are recorded in the log file; the lowest priority log level is 6 ( 10 for TPS).
Log level
0
1
2
Message category
Debugging
Informational
(default selection for audit log)
Warning
Description
These messages contain debugging information. This level is not recommended for regular use because it generates too much information.
These messages provide general information about the state of the Certificate System, including status messages such as Certificate System initialization complete and Request for operation succeeded .
These messages are warnings only and do not indicate any failure in the normal operation of the server.
3
4
Failure; the default selection for system and error logs
These messages indicate errors and failures that prevent the server from operating normally, including failures to perform a certificate service operation ( User authentication failed or
Certificate revoked ) and unexpected situations that can cause irrevocable errors ( The server cannot send back the request it processed for a client through the same channel the request came from the client ).
MisconfigurationThese messages indicate that a misconfiguration in the server is causing an error.
5 Catastrophic failure
These messages indicate that, because of an error, the service cannot continue running.
6 Securityrelated events
These messages identify occurrences that affect the security of the server. For example, Privileged access attempted by user with revoked or unlisted certificate .
Table 3.9. Log Levels and Corresponding Log Messages
There are an additional four log levels available for TPS subsystem logs:
Log level
7
Message category
PDU related events
(debugging)
Description
These messages contain debugging information for PDU events. This level is not recommended for regular use because it generates too much information for normal use.
80
Buffered Versus Unbuffered Logging
Log level
8
9
Message category
PDU related events
PDU related events
Description
These messages relate transactions and rules processed on a
PDU, such as creating MAC tokens.
This log levels gives verbose log messages for events processed on a PDU, such as creating MAC tokens.
10 All logging levels
This log level enabled all logging levels for the TPS logs.
Table 3.10. TPS Log Levels and Log Entries
Log levels can be used to filter log entries based on the severity of an event. By default, log level 3
(Failure) is set for all services.
The log level is successive; specifying a value of 3 causes levels 4, 5, and 6 to be logged. Log data can be extensive, especially at lower (more verbose) logging levels. Make sure that the host machine has sufficient disk space for all the log files. It is also important to define the logging level, log rotation, and server-backup policies appropriately so that all the log files are backed up and the host system does not get overloaded; otherwise, information can be lost.
3.9.4. Buffered Versus Unbuffered Logging
The Certificate System supports buffered logging for all types of logs. The server can be configured for either buffered or unbuffered logging.
If buffered logging is configured, the server creates buffers for the corresponding logs and holds the messages in the buffers for as long as possible. The server flushes out the messages to the log files only when one of the following conditions occurs:
• The buffer gets full. The buffer is full when the buffer size is equal to or greater than the value specified by the bufferSize configuration parameter. The default value for this parameter is 512
KB.
• The flush interval for the buffer is reached. The flush interval is reached when the time interval since the last buffer flush is equal to or greater than the value specified by the flushInterval configuration parameter. The default value for this parameter is 5 seconds.
• When current logs are read from Console. The server retrieves the latest log when it is queried for current logs.
If the server is configured for unbuffered logging, the server flushes out messages as they are generated to the log files. Because the server performs an I/O operation (writing to the log file) each time a message is generated, configuring the server for unbuffered logging decreases performance.
3.9.5. Log File Rotation
Log files are rotated when either of the following occur:
• The size limit for the corresponding file is reached. The size of the corresponding log file is equal to or greater than the value specified by the maxFileSize configuration parameter. The default value for this parameter is 100 KB.
81
Chapter 3. Administrative Basics
• The age limit for the corresponding file is reached. The corresponding log file is equal to or older than the interval specified by the rolloverInterval configuration parameter. The default value for this parameter is 2592000 seconds (every thirty days).
When a log file is rotated, the old file is named using the name of the file with an appended time stamp. The appended time stamp is an integer that indicates the date and time the corresponding active log file was rotated. The date and time have the forms YYYYMMDD (year, month, day) and
HHMMSS (hour, minute, second).
Log files, especially the audit log file, contain critical information. Periodically archive rotated log files to some archive media. Log files are archived by copying the entire /logs directory to an archive medium.
NOTE
The Certificate System does not provide any tool or utility for archiving log files.
The Certificate System provides a command-line utility, signtool , that signs log files before archiving them as a means of tamper detection. For details, see Section 3.9.10, “Signing Log Files” .
Signing log files is an alternative to the signed audit logs feature. Signed audit logs creates audit logs that are automatically signed; using signtool manually signs archived logs. See Section 3.9.1.6,
“Signed Audit Log” for details about signed audit logs.
By default, rotated log files are not deleted.
3.9.6. Configuring Logs in the Console
This procedure describes how to configure system, transaction, and audit logs.
To configure logs for a Certificate System instance:
1. Open the Console.
2. In the navigation tree of the Configuration tab, select Log .
The Log Event Listener Management tab lists the currently configured listeners.
3. To create a new log instance, click Add , and select a module plug-in from the list in the Select
Log Event Listener Plug-in Implementation window.
To delete a log instance, select a listener to delete in the Log Event Listener list. Click Delete .
To modify an existing log instance, select a listener to modify in the Log Event Listener list. Click
Edit/View .
4. Change the fields in the Log Event Listener Editor window.
• Log Event Listener ID . The unique name that identifies the listener. The names can have any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-), but it cannot contain other characters or spaces.
• type . The type of log file. Set transaction to create a listener that records audit logs. For error and system logs, select system .
82
Configuring Logs in the CS.cfg File
• enabled . Select to enable; deselect to disable. Only enabled logs actually record events.
• level . Sets the log level. The choices are Debug , Information , Warning , Failure ,
Misconfiguration , Catastrophe , and Security . The level field does not have a drop-down list. It is a simple text field that needs to be filled in with one of the above categories. For more information, see Section 3.9.3, “Log Levels (Message Categories)” .
• fileName . The full path, including the filename, to the file to write messages. The server should have read/write permission to the file.
• bufferSize . The buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Section 3.9.4, “Buffered Versus Unbuffered Logging” . Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
• flushInterval . The interval, in seconds, to flush the buffer to the file. The default interval is
5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
• maxFileSize . The file size in kilobytes (KB) for the error log. The default size is 100 KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see Section 3.9.5, “Log File Rotation” .
• rolloverInterval . Sets the frequency at which the server rotates the active error log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly.
For more information, see Section 3.9.5, “Log File Rotation” .
The signed audit log has these additional settings:
• logSigning . Enables signed logging. When this parameter is enabled, provide a value for the signedAuditCertNickname parameter. This feature means, the log can only be viewed by an auditor. See Section 3.9.1.6, “Signed Audit Log” for more information about signed audit logs.
• signedAuditCertNickname . The nickname of the certificate used to sign audit logs. The private key for this certificate must be accessible to the subsystem in order for it to sign the log.
• events . Specifies which events are logged to the audit log. Lists each event separated by a comma with no spaces. Events can be removed from the list. See Table 3.11, “Signed Audit Log
Events” for a complete list of auditable logging events.
5. Click OK .
3.9.7. Configuring Logs in the CS.cfg File
To modify the configuration settings for logs:
1. Stop the subsystem instance.
2. Open the CS.cfg
file in the /var/lib/ instance /conf directory.
3. To create a new log, copy all of the entries for either the system or transactions log. These are the parameters that begin with log.instance.Transactions
or log.instance.System
. Paste all entries at the bottom of the logging section and change the name of this instance by changing the word Transactions or System in each parameter to the new name.
83
Chapter 3. Administrative Basics
4. To configure a log instance, modify the parameters associated with that log. These parameters begin with log.instance
and include the following:
• bufferSize . Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB.
For more information, see Section 3.9.4, “Buffered Versus Unbuffered Logging” . Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
• enable . Specify true to enable; false to disable. Only enabled logs actually record events.
• fileName . Specify the full path, including the filename, to the file to write messages. The server should have read/write permission to the file.
• flushInterval . Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
• level . Specify a log level. The choices are 0 for debug, 1 for information, 2 for warning, 3 for failure, 4 for misconfiguration, 5 for catastrophe, and 6 for security. The default selection is 1.
For more information, see Section 3.9.3, “Log Levels (Message Categories)” .
• maxFileSize . Specify the file size in kilobytes (KB) for the error log. The default size is 100
KB. The maxFileSize determines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started anew. For more information, see Section 3.9.5, “Log File Rotation” .
• register . If this variable is set to false (the default value), the self-test messages are only logged to the log file specified by selftests.container.logger.fileName
. If this variable is set to true , then the self-test messages are written to both the log file specified by selftests.container.logger.fileName
as well as to the log file specified by log.instance.Transactions.fileName
.
• rolloverInterval . Specify the frequency at which the server rotates the active error log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 3.9.5, “Log File Rotation” .
• type . Set to transaction or system .
5. Save the file.
6. Start the subsystem instance.
3.9.8. Configuring TPS Logs
Logging TPS instance activities is handled differently than in the other subsystems. There are three
TPS instance logs:
• tps-debug.log
• tps-error.log
• tps-audit.log
These logs are stored in the /var/log/ instance_ID directory. Other types of logs, such as transaction logs and system logs, are not generated by the TPS instance.
84
Monitoring Logs
Additionally, certain log features that are available to the other subsystems' logs do not apply to TPS logging:
• Log rotation
• Log signing
• Registering and deleting log modules
• Buffered logging
For each log generated by a TPS instance, there are three parameters which can be configured:
• enable , which sets whether the log is generated.
• filename , which sets the name and location of the log.
• level , which sets the log level, the amount of information, and types of events logged. The log level is a number between 0 and 10 . The log levels are described in Section 3.9.3, “Log Levels
(Message Categories)” .
Since the TPS subsystem does not utilize an administrative console, the logging levels and log information is configured directly in the CS.cfg
file. The following parameters configure the three TPS logs: logging.audit.enable=true logging.audit.filename=/var/lib/rhpki-tps/logs/tps-audit.log
logging.audit.level=10 logging.debug.enable=true logging.debug.filename=/var/lib/rhpki-tps/logs/tps-debug.log
logging.debug.level=7 logging.error.enable=true logging.error.filename=/var/lib/rhpki-tps/logs/tps-error.log
logging.error.level=10
3.9.9. Monitoring Logs
To troubleshoot the subsystem, check the error or informational messages that the server has logged.
Examining the log files can also monitor many aspects of the server's operation. Some log files can be viewed through the Console or by opening the files directly. See Section 3.9.1, “About Logs” for information on the location of logs and the log files available.
To view the contents of an active or rotated system log file:
1. Log into the Console.
2. Select the Status tab.
3. Under Logs , select the log to view.
4. Set the viewing preferences in the Display Options section.
• Entries . The maximum number of entries to be displayed. When this limit is reached, the
Certificate System returns any entries that match the search request. Zero (0) means no messages are returned. If the field is blank, the server returns every matching entry, regardless of the number found.
85
Chapter 3. Administrative Basics
• Source . Select the Certificate System component or service for which log messages are to be displayed. Choosing All means messages logged by all components that log to this file are displayed. For more information, see Section 3.9.2, “Services That Are Logged” .
• Level . Select a message category that represents the log level for filtering messages. For more information on log levels, see Section 3.9.3, “Log Levels (Message Categories)” .
• Filename . Select the log file to view. Choose Current to view the currently active system log file.
5. Click Refresh .
The table displays the system log entries. The entries are in reverse chronological order, with the most current entry placed at the top. Use the scroll arrows on the right edge of the panel to scroll through the log entries.
Each entry has the following information shown:
• Source . The component or resource that logged the message.
• Level . The severity of the corresponding entry; see Table 3.9, “Log Levels and Corresponding
Log Messages” for more information.
• Date . The date on which the entry was logged.
• Time . The time at which the entry was logged.
• Details . A brief description of the log.
6. To view a full entry, double-click it, or select the entry, and click View .
3.9.10. Signing Log Files
The Certificate System can digitally sign log files before they are archived or distributed for audit purposes. This feature allows files to be checked for tampering.
This is an alternative to the signed audit logs feature. The signed audit log feature creates audit logs that are automatically signed; this tool manually signs archived logs. See Section 3.9.1.6, “Signed
Audit Log” for details about signed audit logs.
For signing log files, use a command-line utility called the Signing Tool ( signtool ). For details about this utility, see http://www.mozilla.org/projects/security/pki/nss/tools/ .
The utility uses information in the certificate, key, and security module databases of the subsystem instance.
To sign the log directories, use the following command with the appropriate information: signtool -d secdb_dir -k cert_nickname -Z output input
• secdb_dir specifies the path to the directory that contains the certificate, key, and security module databases for the CA.
• cert_nickname specifies the nickname of the certificate to use for signing.
86
Registering a Log Module
• output specifies the name of the JAR file (a signed zip file).
• input specifies the path to the directory that contains the log files.
3.9.11. Registering a Log Module
New log plug-in modules can be registered through the Console. Registering a new module involves specifying the name of the module and the full name of the Java ™ class that implements the log interface.
Before registering a plug-in module, put the Java ™ class for the module in the classes directory; the implementation must be on the class path.
To register a log plug-in module with a subsystem instance:
1. Log into the Console.
2. In the Configuration tab, select Logs from the navigation tree. Then select the Log Event
Listener Plug-in Registration tab.
3. Click Register .
The Register Log Event Listener Plug-in Implementation window appears.
4. Give the name for the plug-in module and the Java ™ class name.
The Java ™ class name is the full path to the implementing Java ™ class. If this class is part of a package, include the package name. For example, registering a class named customLog in a package named com.customplugins
, the class name would be com.customplugins.customLog
.
5. Click OK .
3.9.12. Deleting a Log Module
Unwanted log plug-in modules can be deleted through the Console. Before deleting a module, delete all the listeners based on this module; see Section 3.9.5, “Log File Rotation” .
To delete a module:
1. Log into the Console.
2. In the Configuration tab, select Logs , and then select the Log Event Listener Plug-in
Registration tab.
3. In the Plug-in Name list, select the module to delete, and click Delete .
4. When prompted, confirm the delete.
3.9.13. Signed Audit Log
The signed audit log creates a log recording system events; the events that are recorded are selected from a list of potential events. This feature, when enabled, records all selected system events and produces a verbose set of messages about the activity. Be careful to provide enough space in the filesystem for this log when using signed audit logs. The signed audit log feature is disabled by default.
87
Chapter 3. Administrative Basics
NOTE
The audit logs for a TPS subsystem cannot be signed.
A log is set to a signed audit log by setting the logSigning parameter to enable and providing the nickname of the certificate used to sign the log.
When a log is set as a signed audit log, only a user with auditor privileges can access and view the log. Auditors can use the AuditVerify tool to verify that signed audit logs have not been tampered with.
If there is not a dedicated certificate to sign audit logs, the subsystem signing certificate can be used to sign logs. To do this for a Certificate Manager, specify caSigningCert certCA_instance name as the value in the signedAuditCertNickname parameter. For other systems, specify the appropriate signing certificate.
Which events are recorded in the log are configured by adding or deleting the event type from the value of the events parameter. Table 3.11, “Signed Audit Log Events” lists the loggable events. To add an event, add the logging event to the list; to delete an event, remove it from the list. Log events are separated by commas with no spaces.
Logging Event
AUDIT_LOG_STARTUP
AUDIT_LOG_SHUTDOWN
ROLE_ASSUME
CONFIG_CERT_PROFILE
CONFIG_CRL_PROFILE
CONFIG_OCSP_PROFILE
CONFIG_AUTH
CONFIG_ROLE
CONFIG_ACL
CONFIG_SIGNED_AUDIT
Type of Log Messages Generated
The start of the subsystem, and thus the start of the audit function.
The shutdown of the subsystem, and thus the shutdown of the audit function.
A user assuming a role. A user assumes a role after passing through authentication and authorization systems. Only the default roles of administrator, auditor, and agent are tracked.
Custom roles are not tracked.
A change is made to the configuration settings for the certificate profile framework.
A change is made to the configuration settings for the CRL framework, such as to the extensions, frequency, and CRL format.
A change is made to the configuration settings for the OCSP.
A change is made to the configuration settings for the authentication framework.
A change is made to the configuration settings for roles, including changes made to users or groups.
A change is made to the configuration settings for the ACL framework.
A change is made to the configuration settings for the signed audit feature.
88
Logging Event
CONFIG_ENCRYPTION
CONFIG_TRUSTED_PUBLIC_KEY
CONFIG_DRM
SELFTESTS_EXECUTION
AUDIT_LOG_DELETE
LOG_PATH_CHANGE
PRIVATE_KEY_ARCHIVE
PRIVATE_KEY_ARCHIVE_PROCESSED
KEY_RECOVERY_REQUEST
KEY_RECOVERY_AGENT_LOGIN
KEY_RECOVERY_PROCESSED
KEY_GEN_ASYMMETRIC
NON_PROFILE_CERT_REQUEST
PROFILE_CERT_REQUEST
CERT_REQUEST_PROCESSED
CERT_STATUS_CHANGE_REQUEST
Signed Audit Log
Type of Log Messages Generated
A change is made to the encryption settings, including certificate settings and SSL cipher preferences.
The Certificate Setup Wizard is used to import certificates into the certificate database or any activity in Manage Certificates .
The configuration associated with a DRM changes.
The self-tests are executed.
The signed audit log expires or is deleted.
NOTE
The authorization system should not allow a signed audit log to be deleted.
The path or name for the signed audit, system, transaction or any customized log is changed.
NOTE
The authorization system should not allow such a change.
Shows when an encryption private key is requested during enrollment.
Shows when a private encryption key is archived in the DRM.
Shows when a request is made to recover a private encryption key stored in the DRM.
Shows when DRM agents log in as recovery agents to approve key recovery requests.
Shows when a key recovery has been processed.
Shows when asymmetric keys are generated.
Shows when a certificate request is made outside the certificate profile framework.
Shows when a certificate request is made through the certificate profile framework.
Shows when a certificate request is being processed.
Shows when the request is made to change the status of a certificate.
89
Chapter 3. Administrative Basics
Logging Event
AUTHZ_SUCCESS
AUTHZ_FAIL
INTER_BOUNDARY
AUTH_FAIL
AUTH_SUCCESS
CERT_PROFILE_APPROVAL
PROOF_OF_POSSESSION
CRL_RETRIEVAL
CRL_VALIDATION
CMC_SIGNED_REQUEST_SIG_VERIFY
Type of Log Messages Generated processed.
Shows when a user is successfully processed by the authorization servlets.
Shows when a user is not successfully processed by the authorization servlets.
Records stat transfer between different subsystems.
Shows when a user does not successfully authenticate.
Shows when a user successfully authenticates.
Shows when a certificate profile sent by an administrator is approved by an agent.
Shows when proof of possession is checked during certificate enrollment.
Shows when a CRL is retrieved by the OCSP.
Shows when a CRL is retrieved and the validation process occurs.
Used when CMC (agent pre-signed) certificate requests or revocation requests are submitted and the signature is verified.
Shows when the audit buffer is signed and flushed to disk.
AUDIT_LOG_SIGNING
Table 3.11. Signed Audit Log Events
3.9.13.1. Setting up Signed Audit Logs
To set up signed audit logs:
1. Set up the caAuditCert certificate profile. See Section 13.3, “Setting up Certificate Profiles” for information about setting up certificate profiles.
2. Approve the caAuditCert certificate profile by approving it in the agent services interface.
If the request for this certificate is received in the end-entities page of a Certificate Manager, enable the caAuditCert profile in that Certificate Manager.
3. Use the Certificate Setup Wizard to obtain a certificate request for the private keys and certificates that will be used to sign the log files. When running the wizard, specify that the request is of the type Other .
4. Submit the PKCS#10 request generated to the Manual Log Signing Certificate Enrollment form in the end-entities page of the Certificate Manager that will issue the certificate.
5. Set the signed audit log . Follow the procedure in the section Section 3.9.6, “Configuring
Logs in the Console” . Specify the nickname of the log in the previous step as the value of the signedAuditCertNickname parameter, and set the events that will be logged in the events parameter.
90
Self-Tests
6. Assign auditor users by creating the user and assigning that entry to the auditor group. Members of the auditor group are the only users who can view and verify the signed audit log. See
Section 17.2, “Creating Users” for details about setting up auditors.
Auditors can view signed audit logs from the IT environment. Auditors can verify logs by using the
AuditVerify tool. See the Certificate System Command-Line Tools Guide for details about using this tool.
3.9.13.2. Audit Logging Failures
There are events that could cause the audit logging function to fail, so events cannot be written to the log. For example, audit logging can fail when the filesystem containing the audit log file is full or when the file permissions for the log file are accidentally changed. If audit logging fails, the Certificate
System instance shuts down in the following manner.
• Servlets are disabled and will not process new requests.
• All pending and new requests are killed.
• The subsystem is shut down.
When this happens, administrators and auditors should work together with the operating system administrator to resolve the disk space or file permission issues. When the IT problem is resolved, the auditor should make sure that the last audit log entries are signed. If not, they should be preserved by manual signing ( Section 3.9.10, “Signing Log Files” ), archived, and removed to prevent audit verification failures in the future. When this is completed, the administrators can restart the Certificate
System.
3.10. Self-Tests
The Certificate System has the added functionality to allow self-tests of the server. The self-tests are run at start up and can also be run on demand. The startup self-tests run when the server starts and keep the server from starting if a critical self-test fails. The on-demand self-tests are run by clicking the self-tests button in the subsystem console.
NOTE
There are no self-tests available for the TPS subsystem.
To run an on-demand self-test:
1. Log into the Console.
2. Select the subsystem name at the top of the left pane.
3. Select the Self Tests tab.
4. Click Run .
The self-tests that are configured for the subsystem will run. If any critical self-tests fail, the server will stop.
91
Chapter 3. Administrative Basics
5. The On-Demand Self Tests Results window appears, showing the logged events for this run of the self-tests.
3.10.1. Self-Test Logging
A new log, selftest.log
, is added to the log directory that contains reports for both the start up self-tests and the on-demand self-tests. This log is configured by changing the setting for the log in the
CS.cfg
file. See Section 3.10.3, “Modifying Self-Test Configuration” for details.
3.10.2. Self-Test Configuration
The self-tests feature and individual self-tests are registered and configured in the CS.cfg
file. If a self-test is enabled, that self-test is listed for either on-demand or start up and is either empty or set as critical .
Critical self-tests have a semi-colon and the word critical after the name of the self-test.
Otherwise, nothing is in this place. The server shuts down when a critical self-test fails during on demand self-tests; the server will not start when a critical self-test fails during start up.
The implemented self-tests are automatically registered and configured when the instance was installed. The self-tests that are registered and configured are those associated with the subsystem type.
Self-tests are turned off or the criticality is changed by changing those setting in the CS.cfg
file. To turn a self-test off, remove is from the list of self-tests.
3.10.3. Modifying Self-Test Configuration
To modify the configuration settings for self-tests:
1. Stop the subsystem instance.
2. Open the CS.cfg
file located in the instance's conf/ directory.
3. To edit the settings for the self-test log, edit the entries that begin with selftests.container.logger
. These include the following parameters:
• bufferSize . Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. For more information, see Section 3.9.4, “Buffered Versus Unbuffered Logging” . Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
• enable . Specify true to enable; false to disable. Only enabled logs actually record events.
• fileName . Specify the full path, including the filename, to the file to write messages. The server must have read/write permission to the file.
• flushInterval . Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The flushInterval is the amount of time before the contents of the buffer are flushed out and added to the log file.
• level . The default selection is 1; this log is not set up for any level beside 1.
• maxFileSize . Specify the file size in kilobytes (KB) for the error log. The default size is 100
KB. The maxFileSize determines how large a log file can become before it is rotated. Once
92
Ports it reaches this size, the file is copied to a rotated file, and a new log file is started. For more information, see Section 3.9.5, “Log File Rotation” .
• register . If this variable is set to false (the default value), the self-test messages are only logged to the log file specified by selftests.container.logger.fileName
.
If this variable is set to true , then the self-test messages are written to both the log file specified by selftests.container.logger.fileName
and the log file specified by log.instance.Transactions.fileName
.
• rolloverInterval . Specify the frequency at which the server rotates the active error log file. The choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 3.9.5, “Log File Rotation” .
• type . Set to transaction ; do not change this.
4. To edit the order in which the self-test are run, specify the order by listing any of the self-test as the value of the following parameters separated by a comma and a space.
To mark a self-test critical, add a colon and the word critical to the name of the self-test in the list.
To disable a self-test, remove it as the value of either the selftests.container.order.onDemand
or selftests.container.order.startup
parameters.
5. Save the file.
6. Start the subsystem.
3.11. Ports
3.11.1. About Ports
The Certificate System subsystem instances listen on different ports for requests from different types of users. As illustrated in Figure 3.2, “Certificate System Ports” , it listens on an an agent port and an end-entity port.
93
Chapter 3. Administrative Basics
Figure 3.2. Certificate System Ports
3.11.1.1. Port Considerations
When choosing ports for a subsystem, consider the following:
• Choose ports that are unique on the host system.
To verify that a port is available for use, check the appropriate file for the operating system; port numbers for network-accessible services are usually maintained in a file named services .
• Since the default Certificate System instances are installed as root , all of the port numbers used are below port 1024, but for security reasons, it may not be desirable to use those ports directly. Also, since the Certificate System is installed as root yet it runs as a nonroot user, the subsystems may not be able to access the restricted ports. It is possible to direct traffic to nonrestricted ports while still using the default port numbers by configuring the iptables settings. For example:
/sbin/iptables -A FORWARD -p tcp
--destination-port 443 -j ACCEPT
/sbin/iptables -t nat -A PREROUTING -j REDIRECT
-p tcp --destination-port 443 --to-port 8443
/sbin/iptables -A FORWARD -p tcp
--destination-port 80 -j ACCEPT
/sbin/iptables -t nat -A PREROUTING -j REDIRECT
-p tcp --destination-port 80 --to-port 8080
/sbin/iptables-save
This redirects all of the agent and administrator traffic on the CA HTTPS port ( 443 ) and the Tomcat port ( 80 ).
94
About Ports
3.11.1.2. Web Port
The HTML-based services, such as the agent and end-entities' services pages and the Console, are accessed through the web. The Tomcat web server is used for the CA, RA, DRM, OCSP, and TKS subsystem services, and the Apache web server is used for the TPS subsystem services.
3.11.1.3. Agent Port
The agent port is an SSL (encrypted) port on which the subsystem listens to requests from agents; agents make these requests through the agent services pages.
• The Certificate Manager agent uses the agent port to process certificate issuance and management requests from end entities and to perform other privileged operations over HTTPS.
• DRM agents use the agent port for recovering end users' encryption private keys over HTTPS.
Agent functions always require SSL client authentication.
When a new subsystem instance is created, any number between 1 and 65535 can be specified as the secure port number. The number the agent port affects agent users since all agents access the subsystem by specifying the name of the server (the Certificate System instance) and the agent port number in the URL. For example, if the port number is 4430, the URL would look like this: https://server.example.com:4430/ca/agent/ca
This port number is also used to open the subsystem administrative console.
pkiconsole https://server.example.com:4430/ca/
If the port number is ever changed, the agents must be informed.
3.11.1.4. End-Entity Ports
For requests from end entities, the Certificate System listens on both the SSL (encrypted) port and non-SSL port. End entities make requests through the end-entities page.
Both the HTTP port and HTTPS port can be used to service end-entity-initiated PKI requests, such as enrollment and revocation. Enrollment requests can include revocation requests; general certificate retrieval requests, such as retrieving a single certificate identified by a serial number; listing certificates based on certain criteria like an LDAP search filter defined over standard attributes; and getting a CA's certificate chain.
The HTTP port can be disabled if it is not used.
The HTTPS port uses SSL authentication to provide a secure transfer of data. Like the HTTP port, the HTTPS port can be disabled. For example, to keep end entities from interacting with a Certificate
Manager, disable the HTTPS port. For details, see Section 3.11.2, “Changing a Port Number” .
If the subsystem instance is for a Certificate Manager configured to service OCSP requests from
OCSP-compliant clients, then this port must be enabled so that the clients can successfully query the
Certificate Manager for the revocation status of a certificate. For details, see Section 6.2, “CA OCSP
Services” .
95
Chapter 3. Administrative Basics
3.11.2. Changing a Port Number
To change a port number for a CA, RA, DRM, OCSP, or TKS subsystem:
1. Stop the subsystem instance.
2. Open the instance's configuration directory.
cd /var/lib/ instance_ID /conf
3. Open the server.xml
file, and edit the appropriate port numbers. For example:
#Define a non-SSL HTTP/1.1 Connector on port 8080 <Connector port="9080"
maxHttpHeaderSize="8192"
====
# Define a SSL HTTP/1.1 Connector on port 8443 <Connector port="9443"
maxHttpHeaderSize="8192"
4. Restart the subsystem.
To change a port number for a TPS subsystem:
1. Stop the TPS instance.
2. Open the instance's configuration directory.
cd /var/lib/ instance_ID /conf
3. Open the httpd.conf
file, and edit the non-SSL port number. For example:
Listen 0.0.0.0:7888
4. Open the nss.conf
file, and edit the SSL port numbers. For example:
Listen 0.0.0.0:7889
<VirtualHost _default_:7889>
5. Open the CS.cfg
file, and edit the both the SSL and non-SSL port numbers. For example: service.securePort=7889 service.unsecurePort=7888 op.format.tokenKey.issuerinfo.value=http://server.example.com:7888/cgi-bin/home/index.cgi
6. Restart the subsystem.
3.11.3. Configuring Port Separation
For security reasons, some deployments require different TCP ports for the different subsystem interfaces (administrative, agent, and end-entities). New instances can be installed with separated ports, but existing instances (including the default instances) must have port separation configured separately.
96
Configuring Port Separation
Only the subsystems which have separate services interfaces (CA, OCSP, DRM, and TKS) can be configured for port separation. The other subsystems (RA and TPS) cannot.
NOTE
Port separation is required to apply Errata RHBA-2010:0170 1
and resolve a vulnerability in the TLS/SSL protocols.
For example:
1. Open the directory instance.
cd /var/lib/rhpki-ca/
2. Open the configuration directory.
cd conf/
3. Edit the server.xml
file.
By default, there is one service defined, between the <Service> and </Service> tags.
Copy this entry so that all three services have an entry. Add a <Connector port="..." line with the TCP port and an <Host appBase="..." entry to identify the location of the web directory for the service. The appBase directory should be something like webapps.admin
and located in the subsystem's instance directory.
... default entry, used as the agent service ...
<Service name="Catalina" >
<Connector port="9080" ... /> the insecure port definition, which is used by all
services
<Connector port="9444" ... />
<Engine name="Catalina" defaultHost="localhost">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">
<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="common" resolveHosts="false"/>
</Host>
</Engine>
</Service>
... admin services entry ...
<Service name="CatalinaAdmin" >
97
Chapter 3. Administrative Basics
<Connector port="9445" />
<Engine name="CatalinaAdmin" defaultHost="localhost">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>
<Host name="localhost" appBase="webapps.admin"
unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">
<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="common" resolveHosts="false"/>
</Host>
</Engine>
</Service>
... end-entities services entry ...
<Service name="CatalinaEE" >
<Connector port="9443" ... />
<Engine name="CatalinaEE" defaultHost="localhost">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase"/>
<Host name="localhost" appBase="webapps.ee"
unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">
<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="common" resolveHosts="false"/>
</Host>
</Engine>
</Service>
4. Go up into the instance directory, /var/lib/rhpki-ca .
cd ../
5. Copy the webapps/ directory for the separate services to use.
cp -r webapps webapps.ee
cp -r webapps webapps.admin
6. Each web directory contains templates for the three services pages: agent , admin , and ee . For each directory, move the two unused templates so they cannot be accessed. For example, this moves the agent and admin templates in the ee directory:
98
Redirecting Subsystem Communications to Secure End-Entities Port cd webapps.ee
mv agent agent.orig
mv admin admin.orig
Do this for all three services.
7. Still in the webapps.ee/ directory, open the WEB-INF directory.
cd WEB-INF/
8. Edit the web.xml
file and comment out the caauths servlet mapping.
<!-- <servlet-mapping>
<servlet-name> caauths </servlet-name>
<url-pattern> /auths </url-pattern>
</servlet-mapping>
-->
Do this for the agent and end-entities services, but not for the administrative service because the admin service has to be able to access the caauths admin interface.
9. Open the lib/ directory and move the osutil.jar
file so that the common version, not the local version, is used by the service.
cd lib/ mv osutil.jar osutil.jar.orig
Do this for all three services.
10. Move the osutil.jar
symlink from common/lib/ to the shared/lib/ directory.
cd /var/lib/pki-ca/shared/lib cp -d /var/lib/pki-ca/common/lib/osutil.jar .
rm /var/lib/pki-ca/common/lib/osutil.jar
11. Restart the subsystem.
/etc/init.d/rhpki-ca restart
3.11.4. Redirecting Subsystem Communications to Secure End-
Entities Port
NOTE
These changes are not required if all clients accessing Certificate Systems are upgraded to support RFC 5746.
Transport Layer Security (TLS) is a protocol which establishes a secure connection between a client and a server. Marsh Ray of PhoneFactor discovered a flaw in the TLS protocol itself which could allow an attack to insert plain text into an existing session during a TLS renegotiation operation.
99
Chapter 3. Administrative Basics
The Educated Guesswork blog has a good description of this kind of attack at http:// www.educatedguesswork.org/2009/11/understanding_the_tls_renegoti.html
.
Either a client or a server may request a renegotiation of an existing TLS/SSL session (for instance, to renew session encryption keys or to use different cipher suite). When TLS/SSL is used to secure access to an HTTP service and a client attempts to access some protected resource, server-initiated renegotiation asks client to authenticate with a certificate. In Certificate System, this kind of session renegotiation occurs if a user connects to an end-entity port that doesn't require client authentication, but then attempts to submit a certificate enrollment form for an enrollment profile that requires client authentication. The Certificate System server requests and then parses a client certificate for the user.
Several erratas were release for Red Hat Certificate System 7.3 to address this vulnerability, including
Errata RHBA-2010:0170 2
and Errata RHBA-2010:0165 3
. These erratas allow Certificate System to use the (updated) system NSS packages on Red Hat Enterprise Linux, create a new secure authentication port for end-entities to use, and reconfigure client connections for subsystems like the RA, TPS, and
SCEP services to use the new ports.
IMPORTANT
In Certificate System 7.3, no port is configured to require client authentication at the initial connection. The workaround here configures the agent secure port to require client authentication and directs requests for profiles that require client authentication to this port.
The workarounds here assume that Certificate System has been configured to use separate agent, end-entities, and admin ports, as described in Section 3.11.3,
“Configuring Port Separation” . However, port separation is only available on Certificate
System 7.3 if the server is updated to the latest version and then the subsystems are manually configured to use port separation.
3.11.4.1. Updating the CA Configuration
1. Update the NSS packages by installing the system nss packages.
up2date nss
2. Before making any edits to the CA configuration, back up the following files:
• /var/lib/ instance_name /conf/server.xml
• /var/lib/ instance_name /web-apps.ee/ca/ee/ca/ProfileSelect.template
3. Open the server.xml
file.
vim /var/lib/ instance_name /conf/server.xml
4. In the server.xml
file, change the clientAuth directive in the agent connector to true .
<Connector name="Agent" port="9443" maxHttpHeaderSize="8192"
2
https://rhn.redhat.com/errata/RHBA-2010-0170.html
3 https://rhn.redhat.com/errata/RHBA-2010-0165.html
100
Redirecting Subsystem Communications to Secure End-Entities Port
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true" clientAuth="true" sslProtocol="SSL"
5. Open the profile selection template.
vim /var/lib/ instance_name /web-apps.ee/ca/ee/ca/ProfileSelect.template
6. Replace value in the uri line with the URL to the agent port. The original line is: uri = 'profileSubmitSSLClient';
The updated line will look like the following: uri = 'https://server.example.com:9444/ca/ee/ca/profileSubmitSSLClient';
7. Create a new end-entities web services directory to contain the files for the new URL referenced in the ProfileSelect.template
file.
mkdir -p /var/lib/ instance_name /webapps/ca/ee/ca cp /var/lib/ instance_name /webapps.ee/ca/ee/ca/ProfileSubmit.template /var/ lib/ instance_name /webapps/ca/ee/ca cp /var/lib/ instance_name /webapps.ee/ca/ee/ca/ProfileSubmit.html /var/lib/ instance_name / webapps/ca/ee/ca/ProfileSubmit.html
chown -R pkiuser: /var/lib/ instance_name /webapps/ca/ee
8. Restart the CA. For example:
/etc/init.d/rhpki-ca restart
3.11.4.2. Updating the DRM
1. Update the NSS packages by installing the system nss packages.
up2date nss
2. First, in the CA, edit the CS.cfg
file to contain the connector information with the agent's SSL port. For example: vim /var/lib/rhpki-ca/conf/CS.cfg ca.connector.KRA.port=10443
3. Then, for the DRM, open the server.xml
file.
vim /var/lib/rhpki-kra/conf/server.xml
4. Change the clientAuth directive in the agent connector to true. For example:
101
Chapter 3. Administrative Basics
<Connector name="Agent" port="10443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true" clientAuth="true" sslProtocol="SSL"
5. Restart the subsystem. For example:
/etc/init.d/rhpki-kra restart
3.11.4.3. Updating the OCSP and TKS
1. Update the NSS packages by installing the system nss packages.
up2date nss
2. Open the server.xml
file.
vim /var/lib/ instance_name /conf/server.xml
3. Change the clientAuth directive in the agent connector to true . For example:
<Connector name="Agent" port="11443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true" clientAuth="true" sslProtocol="SSL"
4. Restart the subsystem. For example:
/etc/init.d/rhpki-ocsp restart
3.11.4.4. Updating the TPS
1. Update the NSS packages by installing the system nss packages and install the new TPS packages.
up2date nss pki-tps
2.
On Linux systems only.
For an existing subsystem, edit the init script to preload the system NSS library rather than dirsec-nss .
vim /etc/init.d/ instance_name
3. Remove the line:
LD_PRELOAD="/usr/lib64/dirsec/libssl3.so ${LD_PRELOAD}"
Replace it with the following:
102
The Internal LDAP Database
LD_PRELOAD="/usr/lib64/libssl3.so ${LD_PRELOAD}"
On 32-bit systems, the path is /usr/lib/ .
4. Restart the subsystem. For example:
/etc/init.d/rhpki-tps restart
3.11.4.5. Updating the RA
1. Update the NSS packages by installing the system nss packages and install the new RA packages.
up2date nss pki-ra
2.
On Linux systems only.
For an existing subsystem, edit the init script to preload the system NSS library rather than dirsec-nss .
vim /etc/init.d/ instance_name
3. Remove the line:
LD_PRELOAD="/usr/lib64/dirsec/libssl3.so ${LD_PRELOAD}"
Replace it with the following:
LD_PRELOAD="/usr/lib64/libssl3.so ${LD_PRELOAD}"
On 32-bit systems, the path is /usr/lib/ .
4. Restart the subsystem. For example:
/etc/init.d/rhpki-ra restart
3.12. The Internal LDAP Database
The Certificate System performs certificate- and key-management functions in response to the requests it receives. These functions include the following:
• Storing and retrieving certificate requests
• Storing and retrieving certificate records
• Storing CRLs
• Storing ACLs
• Storing privileged user and role information
• Storing and retrieving end users' encryption private key records
103
Chapter 3. Administrative Basics
To fulfill these functions, the Certificate System is incorporated with a Red Hat Directory Server, referred to as the internal database or local database . The Directory Server is referenced as part of the Certificate System configuration; when the Certificate System subsystem is configured, a new database is created within the Directory Server. This database is used as an embedded database exclusively by the Certificate System instance and can be managed using directory management tools that come with the Directory Server.
The Certificate System instance database is listed with the other Directory Server databases in the serverRoot /slapdDS_name /db/ directory. These databases are named by default in the format hostname-CS_instance_ID , which is the default format given during the instance configuration. For example, for a Certificate Manager named ca1 , the database name would be host.example.comca1 . The database name can be anything, depending on the name given during the configuration.
The subsystems use the database for storing different objects. A Certificate Manager stores all the data, certificate requests, certificates, CRLs, and related information, while a DRM only stores key records and related data.
WARNING
The internal database schema are configured to store only Certificate System data. Do not make any changes to it or configure the Certificate System to use any other LDAP directory. Doing so can result in data loss.
Additionally, do not use the internal LDAP database for any other purpose.
3.12.1. Changing the Internal Database Configuration
To change the Directory Server instance that a subsystem instance uses as its internal database:
1. Log into the subsystem administrative console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, select the Internal Database tab.
3. Change the Directory Server instance by changing the hostname, port, and bind DN fields.
The hostname is the fully qualified hostname of the machine on which the Directory Server is installed, such as certificates.example.com
. The Certificate System uses this name to access the directory.
By default, the hostname of the Directory Server instance used as the internal database is shown as localhost instead of the actual hostname. This is done to insulate the internal database from being visible outside the system since a server on localhost can only be accessed from the local machine. Thus, the default configuration minimizes the risk of someone connecting to this
Directory Server instance from outside the local machine.
The hostname can be changed to something other than localhost if the visibility of the internal database can be limited to a local subnet. For example, if the Certificate System and Directory
Server are installed on separate machines for load balancing, specify the hostname of the machine in which the Directory Server is installed.
The port number is the TCP/IP port used for non-SSL communications with the Directory Server.
104
Enabling SSL Client Authentication with the Internal Database
The DN should be the Directory Manager DN. The Certificate System subsystem uses this DN when it accesses the directory tree to communicate with the directory.
4. Click Save .
The configuration is modified. If the changes require restarting the server, a prompt appears with that message. In that case, restart the server.
3.12.2. Enabling SSL Client Authentication with the Internal
Database
1. Stop the Certificate System instance.
2. Open the subsystem configuration directory.
3. Open the CS.cfg
file.
4. Edit the following lines to the indicated values: internaldb.ldapAuthentication.authtype=SslClientAuth internaldb.ldapAuthentication.bindDN=CN=Directory Manager internaldb.ldapAuthentication.bindPWPrompt=Internal LDAP Database internaldb.ldapconn.host= ldap_hostname internaldb.ldapconn.port= ldap_httpsport internaldb.ldapconn.secureConn=true internaldb.ldapAuthentication.clientCertNickname=Server-Cert certinstance_name
5. Open the Directory Server Console.
6. Create an entry for the suffix which matches the subject DN of the Certificate System subsystem certificate for the subsystem using this internal database. For example, if the CA server certificate has the subject name c=jupiter.example.com,ou=marketing,o=example,l=mv,c=us then create a suffix o=example,l=mv,c=us .
a. Go to the Configuration tab.
b. Right-click and select Data .
c. Click on New Suffix , and add the suffix.
7. Go to the Directory tab, and right-click DirectoryServer .
8. Add the new certificate entry to the Configuration Administrators group.
9. Click Set Access Control Permission , and then click Add .
10. Fill in ACIName.clientauth
.
Check all the rights in the Rights tab.
Click This Entry in the Targets tab.
11. Click OK .
105
Chapter 3. Administrative Basics
3.12.3. Restricting Access to the Internal Database
The Red Hat Directory Server Console displays an entry or icon for the Directory Server instance that the Certificate System uses as its internal database.
Unlike the Certificate System Console, in which access is restricted to users with Certificate System administrator privileges, the Directory Server Console can be accessed by any user. The user can open the Directory Server Console for the internal database and change to the data stored there, such as deleting users from the Certificate System administrators group or adding his own entry to the group.
Access can be restricted to the internal database to only those users who know the Directory Manager
DN and password. This password can be changed by modifying the single sign-on password cache.
1. Log into the Directory Server Console.
2. Select the Certificate System internal database entry, and click Open .
3. Select the Configuration tab.
4. In the navigation tree, expand Plug-ins , and select Pass-Through Authentication .
5. In the right pane, deselect the Enable plugin checkbox.
6. Click Save .
The server prompts to restart the server.
7. Click the Tasks tab, and click Restart the Directory Server .
8. Close the Directory Server Console.
9. When the server is restarted, open the Directory Server Console for the internal database instance.
The Login to Directory dialog box appears; the Distinguished Name field displays the Directory
Manager DN; enter the password.
The Directory Server Console for the internal database opens only if the correct password is entered.
3.13. Backing up and Restoring Certificate System
Backup and restore tools are no longer included with the Certificate System. However, the Certificate
System components can still be archived and restored manually, and this can be necessary for deployments where information cannot be accessed if certificate or key information is lost. There are three major parts of the Certificate System which need backed up routinely in case of data loss or hardware failure:
• Internal database.
The Directory Server provides its own back up scripts and procedures; see the
Directory Server documentation for more information on backing up the LDAP database.
• Security databases.
The security databases store the certificate and key material. If these are stored on an HSM, then consult the HSM vendor documentation for information on how to back up the
106
Backing up and Restoring Certificate System data. If the information is stored in the default directories in the instance alias directory, then it is backed up with the instance directory. To back it up separately, use a utility such as tar or zip .
• Instance directory.
The instance directory contains all configuration files, security databases, and other instance files. This can be backed up using a utility such as tar or zip .
For example, back up the alias directory or the instance directory:
1. Stop the subsystem instance.
/etc/init.d/ instance_ID stop
2. Save the directory to a compressed file. For example: cd /var/lib/rhpki-ca/ tar -cvf /export/archives/ca/alias.tar alias/
3. Restart the subsystem instance.
/etc/init.d/ instance_ID start
NOTE
Stop the subsystem instance before backing up the instance or the security databases.
The Directory Server database can be restored using Directory Server-specific tools; see the Directory
Server documentation for more information on restoring the LDAP database.
The Certificate System backup files, both the alias database backups and the full instance directory backups, can be used to replace the current directories if the data are corrupted or hardware is damaged. To restore the data, uncompress the archive file using the unzip or tar tool, and copy the archive over the existing files.
To restore the alias directory or the instance directory:
1. Uncompress the archive; for example, untar an alias directory archive: cd /export/archive/ca/ tar -xvf alias.tar
2. Stop the subsystem instance if it has not already been stopped.
/etc/init.d/ instance_ID stop
3. Copy the archived files to the directory. For example, restore the alias directory: cp -r /export/archives/ca/alias /var/lib/rhpki-ca/alias
4. Restart the subsystem instance.
107
Chapter 3. Administrative Basics
/etc/init.d/ instance_ID start
NOTE
Stop the subsystem instance before restoring the instance or the security databases.
108
Chapter 4.
Certificate Manager
The Certificate Manager subsystem serves as a Certificate Authority (CA) in the PKI. It can issue and revoke certificates; create and issue CRLs; and publish certificates and CRLs.
This chapter discusses the Certificate Manager subsystem. It provides an overview of the subsystem including an overview of processes, information about cross-signed CA certificates, and other information for maintaining the Certificate Manager.
4.1. How the Certificate Manager Works
This section explains how the Certificate Manager works during certificate enrollment and revocation and when publishing certificates and CRLs to give a better understanding of how the Certificate
System needs configured for better performance of the PKI.
4.1.1. Enrollment
An end entity enrolls in the PKI by submitting an enrollment request through the end-entity interface.
There can be many kinds of enrollment that use different enrollment methods or require different authentication methods. For each enrollment, there is a separate enrollment page created that is specific to the type of enrollment, type of authentication, and the certificate profiles associated with the type of certificate. The forms associated with enrollment can be customized for both appearance and content. Alternatively, the enrollment process can be customized by creating certificate profiles for each enrollment type. Certificate profiles dynamically-generate forms which are customized by configuring the inputs associated with the certificate profile.
4.1.1.1. The Certificate Enrollment Process
When an end entity enrolls in a PKI by requesting a certificate, the following events can occur, depending on the configuration of the PKI and the subsystems installed:
1. The end entity provides the information in one of the enrollment forms and submits a request.
The information gathered from the end entity is customizable in the form depending on the information collected to store in the certificate or to authenticate against the authentication method associated with the form. The form creates a request that is then submitted to the Certificate
Manager.
2. The enrollment form triggers the creation of the public and private keys or for dual-key pairs for the request.
3. The end entity provides authentication credentials before submitting the request, depending on the authentication type. This can be LDAP authentication, PIN-based authentication, or certificatebased authentication.
4. The request is submitted either to an agent-approved enrollment process or an automated process.
• The agent-approved process, which involves no end-entity authentication, sends the request to the request queue in the agent services interface, where an agent must processes the request.
An agent can then modify parts of the request, change the status of the request, reject the request, or approve the request.
109
Chapter 4. Certificate Manager
Automatic notification can be set up so an email is sent to an agent any time a request appears in the queue. Also, an automated job can be set to send a list of the contents of the queue to agents on a preconfigured schedule. See Chapter 18, Automated Notifications and Chapter 19,
Automated Jobs .
• The automated process, which involves end-entity authentication, processes the certificate request as soon as the end entity successfully authenticates.
5. The form collects information about the end entity from an LDAP directory when the form is submitted. For certificate profile-based enrollment, the defaults for the form can be used to collect the user LDAP ID and password.
6. The certificate profile associated with the form determine aspects of the certificate that is issued.
Depending on the certificate profile, the request is evaluated to determine if the request meets the constraints set, if the required information is provided, and the contents of the new certificate.
7. The form can also request that the user export the private encryption key. If the DRM subsystem is set up with this CA, the end entity's key is requested, and an archival request is sent to the DRM.
This process generally requires no interaction from the end entity.
8. The certificate request is either rejected because it did not meet the certificate profile or authentication requirements, or a certificate is issued.
9. The certificate is delivered to the end entity.
• In automated enrollment, the certificate is delivered to the user immediately. Since the enrollment is normally through an HTML page, the certificate is returned as a response on another HTML page.
• In agent-approved enrollment, the certificate can be retrieved by serial number or request Id in the end-entity interface.
• If the notification feature is set up, the link where the certificate can be obtained is sent to the end user.
10. An automatic notice can be sent to the end entity when the certificate is issued or rejected.
11. The new certificate is stored in the Certificate Manager's internal database.
12. If publishing is set up for the Certificate Manager, the certificate is published to a file or an LDAP directory.
13. The internal OCSP service checks the status of certificates in the internal database when a certificate status request is received.
The end-entity interface has a search form for certificates that have been issued and for the CA certificate chain.
4.1.2. Revocation
End entities can request that their own certificates be revoked. When an end entity makes the request, the certificate has to be presented to the CA. If the certificate and the keys are available, the request is processed and sent to the Certificate Manager, and the certificate is revoked. The Certificate Manager marks the certificate as revoked in its database and adds it to any applicable CRLs.
110
Certificate Manager Certificates
An agent can revoke any certificate issued by the Certificate Manager by searching for the certificate in the agent services interface and then marking it revoked. Once a certificate is revoked, it is marked revoked in the database and in the publishing directory, if the Certificate is set up for publishing.
If the internal OCSP service has been configured, the service determines the status of certificates by looking them up in the internal database.
Automated notifications can be set to send email messages to end entities when their certificates are revoked by enabling and configuring the certificate revoked notification message.
4.2. Certificate Manager Certificates
When a Certificate Manager is installed, the keys and requests for the CA signing certificate, SSL server certificate, and OCSP signing certificate are generated. The certificates are created before the configuration can be completed, either by the CA itself, by being automatically submitted to the root
CA in the PKI, or by submitting the requests to a third-party CA.
The CA certificate request is either submitted as a self-signing request to the CA, which then issues the certificate and finishes creating the self-signed root CA, a third-party public CA, or another
Certificate System CA. When the external CA returns the certificate, the certificate is installed, and installation of the subordinate CA is completed.
4.2.1. CA Signing Key Pair and Certificate
Every Certificate Manager has a CA signing certificate with a public key corresponding to the private key the Certificate Manager uses to sign the certificates and CRLs it issues. This certificate is created and installed when the Certificate Manager is installed. The default nickname for the certificate is caSigningCert certinstance_ID , where instance_ID identifies the Certificate Manager instance.
The default validity period for the certificate is five years.
The subject name of the CA signing certificate reflects the name of the CA that was set during installation. All certificates signed or issued by the Certificate Manager include this name to identify the issuer of the certificate.
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, which affects the subject name on the certificates.
• If the Certificate Manager is a root CA, its CA signing certificate is self-signed, meaning the subject name and issuer name of the certificate are the same.
• If the Certificate Manager is a subordinate CA, its CA signing certificate is 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.
NOTE
The CA name cannot be changed or all previously-issued certificates are invalidated.
Similarly, reissuing a CA signing certificate with a new key pair invalidates all certificates that were signed by the old key pair.
111
Chapter 4. Certificate Manager
4.2.2. OCSP Signing Key Pair and Certificate
The key type, key size, key algorithm, and validity period provided for the CA signing key pair are used to generate the OCSP signing key pair. The subject name of the OCSP signing certificate is in the form cn=OCSP certinstance_ID , and it contains extensions, such as OCSPSigning and
OCSPNoCheck , required for signing OCSP responses.
The default nickname for the OCSP signing certificate is ocspSigningCert certinstance_ID , where instance_ID identifies the Certificate Manager instance.
The OCSP private key, corresponding to the OCSP signing certificate's public key, is used by the
Certificate Manager to sign the OCSP responses to the OCSP-compliant clients when queried about certificate revocation status.
4.2.3. SSL Server Key Pair and Certificate
Every Certificate Manager has at least one SSL server certificate that was first generated when the Certificate Manager was installed. The default nickname for the certificate is Server-Cert certinstance_ID , where instance_ID identifies the Certificate Manager instance.
The Certificate Manager SSL server certificate was issued by the CA to which the certificate signing request was submitted, which is the Certificate Manager itself, another Certificate System CA, or a public CA.
By default, the Certificate Manager uses a single SSL server certificate for authentication. However, additional server certificates can be requested to use for different operations, such as configuring the
Certificate Manager to use separate server certificates for authenticating to the end-entity services interface and agent services interface.
If the Certificate Manager is configured for SSL-enabled communication with a publishing directory, it uses its SSL server certificate for client authentication to the publishing directory by default. The
Certificate Manager can also be configured to use a different certificate for SSL client authentication.
If the Certificate Manager is configured to function as a trusted manager , the Certificate Manager uses its subsystem certificate for client authentication to another subsystem. For details on trusted managers, see Section 17.1.2.5, “Trusted Managers” . The Certificate Manager can also be configured to use a different certificate to authenticate to the DRM.
4.2.4. Certificate Considerations
There are certain details of the certificate contents that are set during the Certificate Manager configuration. These are described in the following sections.
4.2.4.1. CA Distinguished Name
The core elements of a CA are a signing unit and the Certificate Manager identity. The signing unit digitally signs certificates requested by end entities. A Certificate Manager must have its own distinguished name (DN), which is listed in every certificate it issues.
Like any other certificate, a CA certificate binds a DN to a public key. A DN is a series of namevalue pairs that in combination uniquely identify an entity. For example, the following DN identifies a
Certificate Manager for the Engineering department of a corporation named Example Corporation:
112
Cross-Pair Certificates cn=demoCA, o=Example Corporation, ou=Engineering, c=US
Many combinations of name-value pairs are possible for the Certificate Manager's DN. The DN must be unique and readily identifiable, since any end entity can examine it.
4.2.4.2. CA Signing Certificate Validity Period
Every certificate, including a Certificate Manager signing certificate, must have a validity period. The
Certificate System does not restrict the validity period that can be specified. Set as long a validity period as possible, depending on the place of the CA in the certificate hierarchy and the requirements of any public CAs that are included in the PKI.
A Certificate Manager cannot issue a certificate that has a validity period longer than the validity period of its CA signing certificate. If a request is made for a period longer than the CA certificate's validity period, the requested validity date is ignored and the CA signing certificate validity period is used.
4.2.4.3. Signing Key Type and Length
Longer keys are considered cryptographically stronger than shorter keys. However, longer keys require more time for signing operations.
The default RSA key length in the configuration wizard is 2048 bits; for certificates that provide access to highly sensitive data or services, consider increasing the length to 4096 bits.
4.2.4.4. Serial Number Ranges for the CA
The starting and ending serial numbers that a CA can issue can be set in the Certificate System
Console. This is useful when installing cloned CAs; each cloned CA is given a specific range of serial numbers that it can issue so that none of the cloned CAs can issue the same serial number.
The serial number range is not set during installation or configuration of the subsystem but can be configured through the Certificate System Console by an administrator.
4.2.5. 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.
For more information on using cross-pair certificates, see Chapter 11, Managing Certificates .
4.3. CA Hierarchy
When there are multiple CAs in a PKI, the CAs are structured in a hierarchy or chain. The CA above another CA in a chain is called an root CA ; a CA below another CA in the chain is called a subordinate
CA . A CA can also be subordinate to a root outside of the Certificate System deployment; for example,
113
Chapter 4. Certificate Manager a CA which functions as a root CA within the Certificate System deployment can be subordinate to a third-party CA.
A Certificate Manager (or CA) is subordinate to another CA because its CA signing certificate, the certificate that allows it to issue certificates, is issued by another CA. The CA that issued the subordinate CA signing certificate controls the CA through the contents of the CA signing certificate.
The CA can constrain the subordinate CA through the kinds of certificates that it can issue, the extensions that it is allowed to include in certificates, the number of level of subordinate CAs the subordinate CA can create, and the validity period of certificates it can issue, as well as the validity period of the subordinate CAs signing certificate.
NOTE
Although a subordinate CA can create certificates that violate these constraints, a client authenticating a certificate that violates those constraints will not accept that certificate.
A self-signed root CA signs its own CA signing certificate and sets its own constraints as well as setting constraints on the subordinate CA signing certificates it issues.
A Certificate Manager can be configured either a root CA or a subordinate CA. It is easiest to make the first CA installed a self-signed root, so that it is not necessary to apply to a third party and wait for the certificate to be issued. Before deploying the full PKI, however, consider whether to have a root
CA, how many to have, and where both root and subordinate CAs will be located.
4.3.1. Subordination to a Public CA
Chaining the Certificate System CA to a third-party public CA introduces the restrictions that public
CAs place on the kinds of certificates the subordinate CA can issue and the nature of the certificate chain. For example, a CA that chains to a third-party CA might be restricted to issuing only Secure
Multipurpose Internet Mail Extensions (S/MIME) and SSL client authentication certificates, but not
SSL server certificates. There are other possible restrictions with using a public CA. This may not be acceptable for some PKI deployments.
One benefit of chaining to a public CA is that the third party is responsible for submitting the root CA certificate to a web browser or other client software. This can be a major advantage for an extranet with certificates that are accessed by different companies with browsers that cannot be controlled by the administrator. Creating a root CA in the CA hierarchy means that the local organization must get the root certificate into all the browsers which will use the certificates issued by the Certificate System.
There are tools to do this within an intranet, but it can be difficult to accomplish with an extranet.
4.3.2. Subordination to a Certificate System CA
Setting up a Certificate System CA as the root CA means that the Certificate System administrator has control over all subordinate CAs by setting policies that control the contents of the CA signing certificates issued. A subordinate CA issues certificates by evaluating its own authentication and certificate profile configuration, without regard for the root CA's configuration.
4.4. Security Domains
A security domain is a registry of PKI services. PKI services, such as CAs, register information about themselves in these domains so users of PKI services can find other services by inspecting the
114
The domain.xml File registry. The security domain service in Certificate System manages both the registration of PKI services for Certificate System subsystems and a set of shared trust policies.
The registry provides a complete view of all PKI services provided by the subsystems within that domain. Each Certificate System subsystem must be either a host or a member of a security domain.
A CA subsystem is the only subsystem which can host a security domain. The security domain shares the CA internal database for privileged user and group information to determine which users can update the security domain, register new PKI services, and issue certificates.
4.4.1. The domain.xml File
The security domain registry is an XML file, domain.xml
, which is hosted on a designated CA.
The domain.xml
file is created when the CA is configured as the security domain host, and every subsystem which is added to the domain is added as an entry to the registry. The domain.xml
file looks like the following example:
<?xml version="1.0" encoding="UTF-8"?>
<DomainInfo><Name>Example Domain</Name>
<KRAList>
<KRA>
<SubsystemName>rhpki-kra</SubsystemName>
<Host>server.example.com</Host>
<SecurePort>10443</SecurePort>
<DomainManager>false</DomainManager>
<Clone>false</Clone>
</KRA>
<SubsystemCount>1</SubsystemCount>
</KRAList>
<TPSList>
<SubsystemCount>0</SubsystemCount>
</TPSList>
<OCSPList>
<OCSP>
<SubsystemName>rhpki-ocsp</SubsystemName>
<Host>server.example.com</Host>
<SecurePort>11443</SecurePort>
<DomainManager>false</DomainManager>
<Clone>false</Clone>
</OCSP>
<SubsystemCount>1</SubsystemCount>
</OCSPList>
<RAList>
<SubsystemCount>0</SubsystemCount>
</RAList>
<TKSList>
<TKS>
<SubsystemName>rhpki-tks</SubsystemName>
<Host>server.example.com</Host>
<SecurePort>13443</SecurePort>
<DomainManager>false</DomainManager>
<Clone>false</Clone>
</TKS>
<SubsystemCount>1</SubsystemCount>
</TKSList>
115
Chapter 4. Certificate Manager
<CAList>
<CA>
<SubsystemName>rhpki-ca</SubsystemName>
<Host>server.example.com</Host>
<SecurePort>9543</SecurePort>
<DomainManager>true</DomainManager>
<Clone>false</Clone>
</CA>
<SubsystemCount>1</SubsystemCount>
</CAList>
</DomainInfo>
The URL to the CA uniquely identifies the security domain. The security domain is also given a friendly name, such as Example Corp Intranet PKI . All other subsystems -- DRM, TPS, TKS, OCSP, and other CAs -- must become members of the security domain by supplying the security domain URL when configuring the subsystem.
The registration involves adding the following information to the security domain's subsystem registry file, domain.xml
:
• A user-friendly name such as Employee Certificate Authority
• A service URL
• The type of subsystem, either CA, OCSP, DRM, TKS, or TPS
Each subsystem within the security domain shares the same trust policies and trusted roots which can be retrieved from different servers and browsers.
The information available in the security domain is used during configuration of a new subsystem, which makes the configuration process streamlined and automated. For example, when a TPS needs to connect to a CA, it can consult the security domain to get a list of available CAs.
A subsystem retrieves information in the security domain through XML messages over HTTPS.
The subsystem authenticates to the security domain using a subsystem certificate. To issue a certificate automatically during configuration, a security domain administrator must authenticate to the security domain using a UID and password. More information on security domain roles is given in
Section 4.4.2, “Security Domain Roles” .
4.4.2. Security Domain Roles
The security domain allows the roles defined in Table 4.1, “Security Domain User Roles” .
Role
Security Domain Administrators
Description
• Add and modify users in the security domain's user and group database.
• Manage the shared trust policies.
• Manage the access controls on the domain services.
By default, the CA administrator of the CA hosting the domain is assigned as the security domain administrator.
116
Creating a Security Domain
Role
Enterprise CA Administrators
Enterprise DRM Administrators
Enterprise OCSP Administrators
Description
• Automatically approve any sub-CA, server, and subsystem certificate from any CA in the domain.
• Register and unregister CA subsystem information in the security domain.
• Automatically approve any transport, storage, server, and subsystem certificate from any CA in the domain.
• Register and unregister DRM subsystem information in the security domain.
• Push KRA connector information to any CA.
• Automatically approve any OCSP, server, and subsystem certificate from any CA in the domain.
• Register and unregister OCSP subsystem information in the security domain.
Enterprise TKS Administrators
Enterprise TPS Administrators
• Push CRL publishing information to any CA.
• Automatically approve any server and subsystem certificate from any CA in the domain.
• Register and unregister TKS subsystem information in the security domain.
• Automatically approve any server and subsystem certificate from any CA in the domain.
• Register and unregister TPS subsystem information in the security domain.
Table 4.1. Security Domain User Roles
As necessary, the security domain administrator can manage access controls on the security domain and on the individual subsystems. For example, the security domain administrator can restrict access so that only finance department DRM administrators can set up finance department DRMs.
Enterprise subsystem administrators are given enough privileges to perform operations on the subsystems in the domain. For example, an enterprise CA administrator has the privileges to have sub-CA certificates approved automatically during configuration. Alternatively, a security domain administrator can restrict this right if necessary.
4.4.3. Creating a Security Domain
A security domain can be created during the CA configuration. During CA configuration, the wizard asks if a security domain should be created. If Yes is chosen, then a user-friendly name must be provided for the security domain. The name is used as the default Organization component in the issuer DN.
117
Chapter 4. Certificate Manager
By default, the CA administrator is assigned as the security domain administrator, with the privileges to manage the domain.
A domain.xml
file is created in the CA instance conf/ directory. This file contains all the important information about the domain. The user and group information is stored in the internal database of CA subsystem hosting the domain.
At the end of the configuration, the CA registers its information in the domain.
4.4.4. Joining a Security Domain
During configuration, if the Join an existing security domain option is selected, provide the service URL to the security domain. This URL usually has the form https:// host:port and requires credentials such as a UID and password. (It is not necessary to give the exact URL to the domain.xml
file). The UID and password must be previously obtained from a security domain administrator. The credential information must belong to a member of an enterprise subsystem administrator group.
The browser is then redirected to the security domain for authentication. If authentication is successful, an authentication token (cookie) is issued. The browser then transfers this cookie to the configuration wizard, which uses the token to manage multiple subsystems as necessary. Each subsystem contacts the security domain to validate the token before handling the request.
At the end of the configuration, the configuration registers the subsystem information to the security domain.
4.4.5. Additional Security Domain Information
The following information can be considered when planning the security domain:
• The CA hosting the security domain can be signed by an external authority.
• Multiple security domains can be set up within an organization. However, each subsystem can belong to only one security domain.
• Subsystems within a domain can be cloned. Cloning subsystem instances distributes the system load and provides failover points.
• The security domain streamlines configuration between the CA and DRM; the DRM can push its KRA connector information and transport certificates automatically to the CA instead of administrators having to manually copy the certificates over to the CA.
• The Certificate System security domain allows an offline CA to be set up. In this scenario, the offline root has its own security domain. All online subordinate CAs belong to a different security domain.
• The security domain streamlines configuration between the CA and OCSP. The OCSP can push its information to the CA for the CA to set up OCSP publishing and also retrieve the CA certificate chain from the CA and store it in the internal database.
4.5. Configuring the Certificate Manager Instance
After the installation and basic configuration of the CA subsystem, further configuration to features such as logging and certificate contents can be made through the Certificate System administrative console. This console allows user and group management, authorization settings, internal LDAP
118
Configuring the Certificate Manager Instance database information, self-tests, and other administrative tasks. General subsystem configuration is outlined in Table 4.2, “General Subsystem Configuration Links” .
Configuration
Adding additional CA instances.
General configuration and management such as changing port numbers, setting up logging, running self-tests, and managing the internal database.
Adding and deleting users, agents, and administrators.
Managing the access control lists (ACLs) for user authorization.
Requesting and installing certificates and managing tokens.
Section
Section 2.7, “Creating Additional Subsystem
Instances”
Chapter 3, Administrative Basics
Section 17.2, “Creating Users”
Section 17.6, “Authorization for Certificate
System Users”
Section 11.2, “Requesting and Receiving
Certificates”
Section 11.4.1, “Installing Certificates in the
Certificate System Database”
Section 11.4.1.3, “About CA Certificate Chains” Installing a certificate chain in the database to provide the chain of CAs to a trusted CA.
Managing hardware security module (HSM) tokens.
Setting up trusted managers.
Changing the subsystem security settings.
Changing subsystem passwords
Managing user authentication. Authentication is part of certificate enrollment.
Section 12.1, “Tokens for Storing Certificate
System Keys and Certificates”
Section 17.1.2.5, “Trusted Managers”
Section 11.5, “Configuring the Server Certificate
Use Preferences”
Section 3.3, “System Passwords”
Chapter 16, Authentication for Enrolling
Certificates
Section 16.3.1, “Setting up Directory-Based
Authentication”
Section 16.3.2, “Setting up PIN-based
Enrollment”
Section 16.4, “Setting up CMC Enrollment”
Chapter 13, Certificate Profiles Configuring certificate profiles. This includes modifying enrollment forms and inputs, editing profiles, and other management tasks.
Configuring publishing.
Configuring jobs.
Configuring notifications.
Configuring the internal OCSP service.
Setting up CRLs and revoking certificates.
Chapter 15, Publishing
Chapter 19, Automated Jobs
Chapter 18, Automated Notifications
Chapter 6, Online Certificate Status Protocol
Responder
Chapter 14, Revocation and CRLs
119
Chapter 4. Certificate Manager
Configuration
Configuring cloning.
Table 4.2. General Subsystem Configuration Links
Section
Chapter 20, Configuring the Certificate System for High Availability
4.6. CA Certificate Reissuance
When a CA signing certificate expires, all certificates signed with the CA's corresponding signing key become invalid. End entities use information in the CA certificate to verify the certificate's authenticity.
If the CA certificate itself has expired, applications cannot chain the certificate to a trusted CA.
Reissuing a CA certificate involves issuing a new CA certificate with a new name, public and private key material, and validity period. All certificates issued by the old CA certificate, including those that have not yet expired, must be replaced by the new CA certificate.
NOTE
Correct use of extensions, for example the authorityKeyIdentifier extension, can affect the transition from an old CA certificate to a new one.
4.7. Changing the Rules for 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 serial number range the CA is able to use to issue certificates.
• The signing algorithm used to sign certificates.
Subordinate CAs have constraints for the validity periods, types of certificates, and the types of extensions which they can issue. It is possible for a subordinate CA to issue certificates that violate these constraints, but a client authenticating a certificate that violates those constraints will not accept that certificate. Check the constraints set on the CA signing certificate before changing the issuing rules for a subordinate CA.
To change the certificate issuance rules, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:port /ca
2. Select the Certificate Manager item in the left navigation tree of the Configuration tab.
120
Changing the Rules for Issuing Certificates
Figure 4.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 set 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.
NOTE
The serial number range cannot be updated manually through the console if the CA is a not clone or serial management has not been manually enabled, so 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.
dbs.beginSerialNumber=1
dbs.enableSerialManagement= true
dbs.endReplicaNumber=100
dbs.endRequestNumber=10000000
dbs.endSerialNumber=10000000
121
Chapter 4. Certificate Manager
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. To ensure that two distinct certificates issued by the same authority do not contain the same serial number, make sure the serial number ranges do not overlap among cloned CAs.
When a CA exhausts all its serial numbers, it can be revived it by changing the values in the
Next serial number and Ending serial number fields and restarting the Certificate Manager.
• 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 .
4.8. Setting Restrictions on CA Certificates through
Certificate Extensions
When a subordinate CA is created, the root CA can generate a CA signing certificate with restrictions on the types of certificates that the subordinate CA can sign with that signing certificate. These restrictions are set by setting the constraints in the CA signing certificate profile. The default CA signing certificate request profile is the caCACert profile. By default, there are no restrictions on the types of certificates that can be signed. The type restrictions are set through the Basic Constraints or through the Key Usage or Extended Key Usage extensions.
NOTE
Subordinate CA signing certificates can have constraints for the types of extensions which they can attach to a certificate. It is possible for a subordinate CA to issue certificates that violate these constraints, but a client authenticating a certificate that violates those constraints will not accept that certificate.
All CA certificates should contain the basicConstraints extension, as this is the standard way to identify a CA certificate.
Extensions Present
Only basicConstraints
Only a key usage extension
Neither extension
Both extensions
122
Description
The certificate is a CA certificate if the cA component is true.
Path length processing is done as described in Section A.3.3,
“basicConstraints” .
Either the Key Usage or the Extended Key Usage extension can be set to indicate that the certificate is a CA certificate if the extension constraints are set for SSL or S/MIME certificates.
The certificate is not a CA.
The certificate is a CA certificate if the cA component of basicConstraints is true. If the constraints for SSL or S/
Setting Restrictions on CA Certificates through Certificate Extensions
Extensions Present
A certificate chain generally consists of an entity certificate, zero or more intermediate CA certificates, and a root CA certificate. Typically, the root CA certificate is self-signed and 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 either the Basic Constraints extension, a Key Usage or Extended Key
Usage extension set to issue SSL or email certificates, or both.
• If CAs issue multiple certificates for the same identity, for example for separate signing and encryption keys, they must include the Key Usage extension in the subject certificates.
• If CAs will ever generate new keys, they must add the Authority Key Identifier extension to all subject certificates. If the key ID is anything other than the SHA-1 hash of the CA certificates subjectPublicKeyInfo field, then the CA certificate should contain the Subject Key Identifier extension. This will allow for a smooth transition when the new issuing certificate becomes active.
These extensions can be configured through the certificate profile enrollment pages. To set the default in the CA signing certificate profile, do the following:
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:9443/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 the Key Usage extension, here are several settings for a CA signing certificate: digitalSignature and nonRepudiation , which allows a
123
Description
MIME certificates is set in the Key Usage or Extended Key
Usage extension, then the CA is limited to issuing certificates for the specified application areas; otherwise, the CA can issue certificates for any application.
Chapter 4. Certificate Manager
CA to issue server certificates and email certificates; cRLSign , which allows a CA to sign CRLS; and then several options for encrypting data. For the Extended Key Usage extension, there are several OIDs which can be set for email, server authentication, or client authentication. For more information, see Section 13.7.8, “Key Usage Extension Default” and Section 13.7.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 13.7.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 13.3, “Setting up Certificate
Profiles” and the Certificate System Agent's Guide .
4.9. Creating Certificate Manager Agents and
Administrators
When the subsystem is configured, there is a default user created with both administrator and agent privileges. This user can perform both administrator and agent operations and access the Console and the agent services page.
To create an additional administrator, agent, or auditor, create a user in the Certificate System instance where the user will have privileges and assign the user to the appropriate group. An agent or auditor must have a certificate stored in the subsystem's internal database. If the Console is configured for
SSL client authentication, all administrators must also have an SSL client certificate.
To create a new user entry, do the following:
1. Log into the administrative console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Users and Groups . Click Add .
3. Fill in the information in the Edit User Information dialog.
124
Checking the Revocation Status of Agent Certificates
Figure 4.2. Creating a New User
The group to which the user belongs determines what privileges the user has. Assign agents and administrators to the appropriate subsystem group.
4. Store the user's certificate.
a. Request and approve an SSL client certificate for the user if one has not already been generated.
b. Copy the base-64 encoded certificate to a local file or to the clipboard.
c. Select the new user entry, and click Certificates .
d. Click Import , and paste in the base-64 encoded certificate.
For more information on editing user entries and managing user certificates, see Section 17.4,
“Modifying Certificate System User Entries” .
4.10. Checking the Revocation Status of Agent Certificates
A Certificate Manager can be configured to check the revocation status of an agent's certificate the server receives during SSL client authentication. For information about setting up an OCSP responder, see Chapter 6, Online Certificate Status Protocol Responder .
125
Chapter 4. Certificate Manager
NOTE
The subsystem CS.cfg
configuration file includes a parameter, jss.ocspcheck.enable
, which sets whether a Certificate Manager should use an
OCSP to verify the revocation status of the certificate it receives as a part of SSL client or server authentication. Changing the value of this parameter to true means the
Certificate Manager reads the Authority Information Access extension in the certificate and verifies the revocation status of the certificate from the OCSP responder specified in the extension.
The configuration files of the Certificate Manager include parameters to specify whether the server should do the revocation checking and at what interval. Revocation-status verification works only for agent certificates that have been issued by the Certificate Manager, not by any third-party CAs.
To configure a Certificate Manager to verify the revocation status of its agents' certificates, do the following:
1. Stop the subsystem instance.
/etc/init.d/ instance_ID stop
2. Open the instanceDirectory /conf/ directory.
3. Open the CS.cfg
file.
4. Edit the following parameters:
• revocationChecking.bufferSize
. Sets the total number of last-checked certificates the server should maintain in its cache. For example, if the buffer size is 2, the server retains the last two certificates checked in its cache. By default, the server caches the last 50 certificates.
• revocationChecking.
subsystem . Gives the name of the Certificate System instance.
subsystem indicates whether the subsystem is a Certificate Manager ( ca ). Do not change the default values.
• revocationChecking.enabled
. Sets revocation checking. true enables checking; false disables checking. By default, the feature is enabled.
• revocationChecking.unknownStateInterval
. Sets how frequently the server checks the revocation status. The default interval is 0 seconds.
• revocationChecking.validityInterval
. Sets how long the cached certificates are considered valid. Be judicious when choosing the interval. For example, if the validity period is 60 seconds, the server discards the certificates in its cache every minute and attempts to retrieve them from their source. The Certificate Manager uses its internal database to retrieve and verify the revocation status of the certificates. The default validity period is 120 seconds (2 minutes).
5. Start the Certificate System instance.
/etc/init.d/ instance_ID start
126
CRL Signing Key Pair and Certificate
4.11. CRL Signing Key Pair and Certificate
A Certificate Manager uses the key pair corresponding to the CA signing certificate for signing certificates and certificate revocation lists (CRLs). To use a different key pair to sign the CRLs that the Certificate Manager generates, then a CRL signing certificate can be created. The Certificate
Manager's CRL signing certificate must be signed or issued by itself.
To enable a Certificate Manager to sign CRLs with a different key pair, do the following:
1. Request and install a CRL signing certificate for the Certificate Manager.
This can be done through the certificate wizard in System Keys and Certificates in the console.
Use the wizard to request a certificate of the "other" type, and specify "crlSigning" as the certificate type.
Alternatively, use the certutil tool to generate a key pair, request a certificate for the key pair, and install the certificate in the Certificate Manager's certificate database. For more information about the certutil tool, see http://www.mozilla.org/projects/security/pki/nss/tools/ .
2. When the certificate request has been created, submit it through the Certificate Manager endentities page. The page has a URL in the following format: https:// hostname:port /ca/ee/ca
3. After the request is submitted, log into the agent services page.
4. Check the request for required extensions. The CRL signing certificate must contain the Key
Usage extension with the crlSigning bit set.
5. Approve the request.
6. After the CRL signing certificate is generated, install the certificate in the Certificate Manager's database through System Keys and Certificates in the console.
7. Stop the Certificate Manager.
8. Update the Certificate Manager's configuration to recognize the new key pair and certificate.
a. Open the Certificate Manager instance configuration directory.
/var/lib/rhpki-ca/conf b. Open the CS.cfg
file.
c. Add the following lines to the configuration file: ca.crl_signing.cacertnickname= nickname certinstance_ID ca.crl_signing.defaultSigningAlgorithm= signing_algorithm ca.crl_signing.tokenname= token_name nickname is the name assigned to the CRL signing certificate; instance_ID is the name of the Certificate Manager instance; signing_algorithm is MD5withRSA , MD2withRSA , or
127
Chapter 4. Certificate Manager
SHA1withRSA , if the key type is RSA; and token_name is the name of the token used for generating the key pair and the certificate. If the internal/software token is used, use
Internal Key Storage Token as the value.
For example, the entries might look like this: ca.crl_signing.cacertnickname=crlSigningCert cert-rhpki-ca ca.crl_signing.defaultSigningAlgorithm=MD5withRSA ca.crl_signing.tokenname=Internal Key Storage Token d. Save the changes, and close the file.
9. Restart the Certificate Manager.
/etc/init.d/rhpki-ca restart
Now the Certificate Manager is ready to use the CRL signing certificate to sign the CRLs it generates.
4.12. DNs in the Certificate System
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 4.3, “Allowed Characters for Value Types” lists the attributes supported by default. The set of attributes is extensible.
Attribute cn ou o c l st street title uid mail dc serialnumber unstructuredname
Value Type
DirectoryString
DirectoryString
DirectoryString
PrintableString , twocharacter
DirectoryString
DirectoryString
DirectoryString
DirectoryString
DirectoryString
IA5String
IA5String
PrintableString
IA5String
Object Identifier
2.5.4.3
2.5.4.11
2.5.4.10
2.5.4.6
2.5.4.7
2.5.4.8
2.5.4.9
2.5.4.12
0.9.2342.19200300.100.1.1
1.2.840.113549.1.9.1
0.9.2342.19200300.100.1.2.25
2.5.4.5
1.2.840.113549.1.9.2
128
Extending Attribute Support
Attribute Value Type unstructuredaddress PrintableString
Table 4.3. Allowed Characters for Value Types
Object Identifier
1.2.840.113549.1.9.8
4.12.1. Extending Attribute Support
By default, the Certificate System supports the attributes identified in Table 4.3, “Allowed Characters for Value Types” . This list of supported attributes can be extended by creating or adding new attributes. The syntax for adding additional X.500Name
attributes, or components, is as follows:
X500Name.
NEW_ATTRNAME .oid= n.n.n.n
X500Name.
NEW_ATTRNAME .class= string_to_DER_value_converter_class
The value converter class converts a string to an ASN.1 value; this class must implement the netscape.security.x509.AVAValueConverter
interface. The string-to-value converter class can be one of the following:
• netscape.security.x509.PrintableConverter
converts a string to a PrintableString value. The string must have only printable characters.
• netscape.security.x509.IA5StringConverter
converts a string to an IA5String value.
The string must have only IA5String characters.
• netscape.security.x509.DirStrConverter
converts a string to a DirectoryString . The string is expected to be in DirectoryString format according to RFC 2253.
• netscape.security.x509.GenericValueConverter
converts a string character by character in the following order, from the smallest characterset to the largest:
• Printable
• IA5String
• BMPString
• Universal String
An attribute entry looks like the following:
X500Name.MY_ATTR.oid=1.2.3.4.5.6
X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter
4.12.1.1. Adding New or Proprietary Attributes
To add a new or proprietary attribute to the Certificate System schema, do the following:
1. Stop the Certificate Manager.
/etc/init.d/rhpki-ca stop
2. Open the /var/lib/rhpki-ca/conf directory.
129
Chapter 4. Certificate Manager
3. Open the configuration file, CS.cfg
.
4. Add the new attributes to the configuration file.
For example, to add three proprietary attributes, MYATTR1 that is a DirectoryString , MYATTR2 that is an IA5String , and MYATTR3 that is a PrintableString , add the following lines at the end of the configuration file:
X500Name.attr.MYATTR1.oid=1.2.3.4.5.6
X500Name.attr.MYATTR1.class=netscape.security.x509.DirStrConverter
X500Name.attr.MYATTR2.oid=11.22.33.44.55.66
X500Name.attr.MYATTR2.class=netscape.security.x509.IA5StringConverter
X500Name.attr.MYATTR3.oid=111.222.333.444.555.666
X500Name.attr.MYATTR3.class=netscape.security.x509.PrintableConverter
5. Save the changes, and close the file.
6. Restart the Certificate Manager.
/etc/init.d/rhpki-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.
4.12.1.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:
130
Extending Attribute Support
• Printable
• IA5String
• UniversalString
• BMPString
• UTF8String
For example, the DER-encoding ordered can be listed as follows:
X500Name.dirEncodingOrder=Printable,BMPString
To change the DirectoryString encoding, do the following:
1. Stop the Certificate Manager.
/etc/init.d/rhpki-ca stop
2. Open the /var/lib/rhpki-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.
/etc/init.d/rhpki-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 .
131
132
Chapter 5.
Registration Authority
A registration authority is a subsystem which processes and validates certificate requests, before sending them to a certificate authority to issue the certificate. RAs lighten the load on CAs by performing request approval separately from certificate issuance, and also allow for more localized control over request approval criteria.
This chapter explains RAs in more detail and describes how to configure and use RAs in a Red Hat
Certificate System deployment.
5.1. Introduction
The following sections provide an introduction to the Red Hat Registration Authority, its features and characteristics, and how it can be used with the Certificate System.
5.1.1. What is a Registration Authority?
A Registration Authority (RA) is a subsystem that accepts enrollment requests and authenticates them in a local context (for example, a department of an organization, or an organization within an association). Upon successful authentication, the RA then forwards the enrollment request to the designated Certificate Authority (CA) to generate the certificate.
Depending on the type of enrollment, an RA can be set up with the appropriate authentication plugin to authenticate the request in an automated fashion. Alternatively, the RA has a local request queue where requests can be stored and reviewed by local RA agents for manual authentication.
The RA is normally set up outside of the firewall, and the CA is set up behind the firewall. This enables requests to be made from outside the protected environment (for example, the Internet), while the CA remains under the protection of the site's security measures.
The connection between the RA and the CA is protected by SSL. The RA uses its subsystem certificate to identify itself to the CA. For authorization, the CA will check if the RA belongs to an RA subsystem group in the CA.
5.1.2. Enrollment Types
The RA currently provides the following enrollment types:
• SCEP enrollment
• Server certificate enrollment
• User certificate enrollment
• RA agent enrollment
The RA also supports:
• Request status checks
• Certificate retrieval
• Email notification on request creation and approval
133
Chapter 5. Registration Authority
The RA also supports a range of reusable Perl objects. This enables administrators to build their own enrollment work flow.
5.1.3. Roles
The RA currently supports the following roles:
• End Users — people who submit enrollment requests
• RA Agents — privileged RA users. They are responsible for daily operations such as request approval.
• Administrator — the person responsible for installing and configuring the RA. An Administrator has the necessary privileges to issue RA Agent status to End Users.
5.1.4. Interfaces
The RA provides three main interfaces: End User (or End Entity, EE); Agent; and Administrator.
5.1.4.1. End User Interface
The End User interface provides the following enrollment options:
SCEP Enrollment
In a SCEP enrollment scenario, you use the EE interface to submit a request in order to retrieve a one-time PIN. The RA agent is notified of the request and, after validating the requestor, approves it. Approving the request generates a PIN.
The manager gives this PIN to the router installer. On the router, the installer enters the URL to the
RA and provides the one-time PIN. The enrollment can then be initiated.
Enrolling a Server Certificate
In a server certificate enrollment scenario, a server administrator provides site information and the server certificate request in the enrollment form. The RA Agent is notified of the request and, after validating the requestor, approves it.
The request is then forwarded from the RA to the CA, which in turn generates a certificate and returns it to the RA. The RA sends a notification to the server administrator who collects the certificate by following a URL provided in the notification (typically an email).
Enrolling a User Certificate
In a user certificate enrollment scenario, the user accesses an enrollment page where user information is collected, and key generation is initiated. The RA Agent is notified of the request and, after validating the requestor, approves it.
The RA sends a notification to the user, who then collects the certificate by visiting a specified
URL.
In addition to enrolling user certificates, you can use the end entity interface to renew a valid user certificate in your browser. The renewal feature reuses the keys and the CSR of the selected user certificate to generate a new certificate.
134
Installation and Configuration
Enrolling an Agent Certificate
In this scenario, you use the RA's EE interface to request a PIN. The request is approved by an existing agent, and the PIN generated.
The agent returns the PIN to the user, who then accesses the enrollment page to enter their information, one-time PIN. Key generation is now initiated on the browser and CSR is submitted together with this request. After this information has been submitted, the certificate is generated and immediately returned to the user.
5.1.4.2. Agent Interface
The Agent interface provides the following features:
Authentication of Certificates
To access the agent interface, the agent must have an agent certificate in the browser.
Listing of Requests
Requests are assigned to a group by default. Only agents who belong to that group can see the requests. Valid request states are OPEN, APPROVED, and CANCELLED.
Approval of Requests
Approval of certificate requests.
Cancellation of Requests
Cancellation of certificate requests.
Listing of Certificates
Provide a listing of current certificates.
Addition of Further Certificate Information
Addition of further information to certificate requests.
5.1.4.3. Administrative Interface
The Administrative interface provides the following features:
Listing and Creating New Users and Agent Groups
Create a new user and a new agent group
Associating Certificates with Users
Associate a certificate with a user
Assigning Users to Agent Groups
Assign users to an agent group
5.2. Installation and Configuration
The Red Hat Certificate System is provided via the Red Hat Network either as a direct download of the RPM file, or from the ISO files available from the Certificate System 7.3 download area on the Red
Hat Network. At the end of the installation, a URL is provided which directs the administrator to the configuration page. A further URL is provided with details of the PKI services.
The following Red Hat Network channels are available for obtaining Certificate System:
135
Chapter 5. Registration Authority
• Red Hat Certificate System 7.3 (for AS v. 4 for x86)
• Red Hat Certificate System 7.3 (for AS v. 4 for AMD64/EM64T)
• Red Hat Certificate System 7.3 (for ES v. 4 for x86)
• Red Hat Certificate System 7.3 (for ES v. 4 for AMD64/EM64T)
• Red Hat Certificate System 7.3 (for Solaris 9)
The following is a partial, sample output of an RA installation:
Installing: rhpki-ra ######################### [8/8]
PKI instance creation Utility ...
PKI instance creation completed ...
Starting rhpki-ra: [ OK ]
PKI service(s) are available at https://dhcp-87.brisbane.redhat.com:12889
Server can be operated with /etc/init.d/rhpki-ra start | stop | restart
Please start the configuration by accessing: http://dhcp-87.brisbane.redhat.com:12888/ra/admin/console/config/login?
pin=QgSU3EZSgISshGrKtYPa
Install finished.
5.2.1. Configuration
Before you can install and configure an RA, you need to install and configure a CA that is capable of issuing certificates. Refer to the following sections for further information:
• Section 2.5, “Installing the Certificate System ”
• Section 2.6, “Configuring the Default Subsystem Instances”
You can install the RA from the Red Hat Network (RHN), or by using the rpm command. For example:
# rpm -ivh rhpki-ra-7.3.0-27.el4
Procedure 5.1. Configuring an RA
The following procedure describes the steps for configuring an RA after a successful installation. The addresses, port numbers and other values used in this procedure are examples only.
1. Copy the address provided at the end of the installation procedure, and paste into your web browser. This launches the RA Configuration Wizard. Refer to the example below. The information after the pin= string is the initial login PIN, and is different for every RA instance creation. Note that this example has been formatted for display purposes.
http://dhcp-87.brisbane.redhat.com:12888 \
/ra/admin/console/config/login?pin=QgSU3EZSgISshGrKtYPa
Click Next to move to the Security Domain page.
136
Configuration
2. On the Security Domain page, ensure that Join an Existing Security Domain is selected, and enter the URL of the Security Domain that you are going to join.
In this example, the Security Domain is available at https:// willow.brisbane.redhat.com:9443 .
Figure 5.1. Specifying the Security Domain
Click Next to move to the Display Certificate Chain page.
3. The Display Certificate Chain page is an information page, and displays a list of all certificates that are chained, or linked, up to the root certificate.
Click Next to move to the Security Domain Login page.
4. The Security Domain Login page registers the RA subsystem with the Security Domain. Enter the
CA Administrator UID and Password to authenticate against the Security Domain.
Click Next to move to the Subsystem Type page.
5. If this is the first RA that you are configuring, select Configure this Instance as new
Registration Authority Subsystem . Provide a name for the subsystem in the Subsystem Name field. The Subsystem URL is automatically determined; it cannot be edited.
If you have previously configured an RA, you can elect to clone that subsystem. You need to provide a new name for the clone and a suitable URL.
137
Chapter 5. Registration Authority
Figure 5.2. Specifying the Subsystem Type
Click Next to move to the CA Information page.
6. On the CA Information page, you need to select the CA that is responsible for issuing certificates.
Select the appropriate CA from the list.
Click Next to move to the Internal Database page.
7. The Internal Database page is an information page only. It indicates that an SQLite database will be created to store internal RA information.
Click Next to move to the Security Modules page.
8. The Security Modules page is an information page that indicates the type of security modules that have been recognized by the system. This includes both hardware and software modules. Refer to the help text on the page for more information about the supported security modules.
Click Next to move to the Key Pairs page.
9. Use the Key Pairs page to specify information about the key pairs that you want to generate.
Unless you have a special reason for doing so, you should accept the default values.
Click Next to start generating the key pairs, and to move to the Subject Names page.
10. The Subject Names page is used to collect information that is used to generate unique names for certificates associated with the RA instance. You can accept the default information or change it to suit your needs.
138
Configuration
Figure 5.3. Specifying the Subject Names
Click Next to generate the Certificate Requests and to move to the Certificate Requests page.
11. The Certificate Requests page provides information about the status of the Certificate Signing
Requests (CSRs). Refer to the help text on the page for more information about these CSRs.
Click Next to move to the Administrator page.
12. The Administrator is a privileged user who manages the RA subsystem. Enter the required information that the Administrator will use to access the system.
Click Next to create the Administrator's Certificate and to move to the Import Administrator
Certificate page.
13. The Import Administrator Certificate page is an information page which indicates that the
Administrator's Certificate was created and imported into the browser.
Click Next to move to the final page of the wizard.
14. The final page of the wizard describes how to restart the RA server, and provides a link to the
Services page.
At this point, the RA should be completely installed and configured, and able to accept and process
CSRs.
During the configuration of the RA, the following certificates are also created:
139
Chapter 5. Registration Authority
• Server Certificate — this is used to communicate with RA users. (This is the server identity of the
RA.)
• Subsystem Certificate — this is used to communicate with the CA. (This is the client identity of the
RA.)
Multiple RA instances can communicate with a single CA. Additional RA instances can be created using the /usr/bin/pkicreate command.
Note
Unlike the CA, the RA uses SQLite as the persistent store for internal data such as requests and user information.
5.2.2. Directory Structure
The following tables list and describe the principle files and directories that comprise the RA:
Directory
/var/lib/rhpki-ra
/var/lib/rhpki-ra/conf
/var/lib/rhpki-ra/logs
/var/lib/rhpki-ra/alias
/var/lib/rhpki-ra/docroot/ee
Description
Main instance directory
Configuration directory
Logs directory
NSS security database where keys and certificates are stored
CGIs and templates for end-users (EE)
/var/lib/rhpki-ra/docroot/agent CGIs and templates for agents
/var/lib/rhpki-ra/docroot/admin CGIs and templates for administrators
Table 5.1. Principle RA Directories
File
/etc/init.d/rhpki-ra
/var/lib/rhpki-ra/conf/CS.cfg
Table 5.2. Principle RA Files
Description
Start/stop script
Main configuration file
Note
The paths described here are those used for a default RA instance. Administrators have the option of using the pkicreate command to create further RA instances anywhere on the system.
5.2.3. Configuration Parameters
This section describes various configuration parameters that are used when setting up the RA. These parameters are specified in the /var/lib/rhpki-ra/conf/CS.cfg
file.
admin.authorized_groups
Specifies the groups of users who have permission to access the Administration interface.
Example:
140
Configuration Parameters admin.authorized_groups=administrators agent.authorized_groups
Specifies the groups of users who have permission to access the Agent interface.
Example: agent.authorized_groups=administrators database.dbfile
Specifies the location of the SQLite database.
Example: database.dbfile=/var/lib/rhpki-ra/conf/dbfile logging.audit.enable
Specifies whether or not to enable audit logging. Valid values are "true" and "false".
logging.audit.filename
Specifies the filename of the audit log file.
logging.audit.level
Specifies the level to which audit logging should occur.
logging.debug.enable
Specifies whether or not to enable debug logging. Valid values are "true" and "false".
logging.debug.filename
Specifies the filename of the debug log file.
logging.debug.level
Specifies the level to which debug logging should occur.
logging.error.enable
Specifies whether or not to enable debug logging. Valid values are "true" and "false".
logging.error.filename
Specifies the filename of the error log file.
logging.error.level
Specifies the level to which error logging should occur.
The following example shows the set of parameters used to specify the connection from the RA to the
CA: conn.ca1.clientNickname=subsystemCert cert-rhpki-ra conn.ca1.hostport=water.sfbay.redhat.com:9443 conn.ca1.keepAlive=true conn.ca1.retryConnect=3 conn.ca1.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient
141
Chapter 5. Registration Authority conn.ca1.servlet.revoke=/ca/subsystem/ca/doRevoke conn.ca1.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke conn.ca1.servlet.addagent=/ca/admin/ca/registerRaUser conn.ca1.timeout=100
5.2.4. RA Request Queue Plugins
Request Queue plugins are small Perl programs that the RA uses to perform certain tasks. These plugins are located in /var/lib/rhpki-ra/lib/perl/PKI/Request/Plugin . The following plugins are currently available:
PKI::Request::Plugin::CreatePin
Creates a one-time PIN for SCEP enrollment.
PKI::Request::Plugin::AutoAssign
Automatically assigns a request to a group of agents.
PKI::Request::Plugin::EmailNotification
Sends email notification.
PKI::Request::Plugin::RequestToCA
Sends an enrollment request to the CA.
Specifying which plugins to call
In the /var/lib/rhpki-ra/conf/CS.cfg
file, the administrator can specify how the request queue engine should react to the certificate signing request.
The following variables are currently available: request.
<request_type> .approve_request
Specifies which plugins to call when a request is approved.
request.
<request_type> .cancel_request
Specifies which plugins to call when a request is canceled.
request.
<request_type> .create_request
Specifies which plugins to call when a request is created.
For example, you may see the following for SCEP enrollment: request.scep.approve_request.0.pinFormat=$site_id request.scep.approve_request.0.plugin=PKI::Request::Plugin::CreatePin request.scep.approve_request.num_plugins=1 request.scep.cancel_request.num_plugins=0 request.scep.create_request.0.assignTo=agents request.scep.create_request.0.plugin=PKI::Request::Plugin::AutoAssign [email protected]
request.scep.create_request.1.plugin=PKI::Request::Plugin::EmailNotification request.scep.create_request.1.templateDir=/usr/share/rhpki/ra/conf request.scep.create_request.1.templateFile=mail_create_request.vm
request.scep.create_request.num_plugins=2 request.scep.profileId=caAgentServerCert request.scep.reqType=pkcs10
142
Libraries
5.2.5. Libraries
The RA also provides the following Perl libraries to facilitate the creation of custom enrollment workflows:
Library
PKI::Base::CertStore
( /var/lib/rhpki-ra/ lib/perl/PKI/Base/
CertStore )
PKI::Base::PinStore ( / var/lib/rhpki-ra/lib/ perl/PKI/Base/PinStore )
Description
Perl interface to access the certificate store in the RA.
Perl interface to access the one-time PIN store.
PKI::Base::PinStore
( /var/lib/rhpki-ra/ lib/perl/PKI/Base/
UserStore )
PKI::Conn::CA ( /var/ lib/rhpki-ra/lib/perl/
PKI/Conn/CA )
Perl interface to access the user and group database.
Perl interface to access the CA for enrollment.
PKI::Request::Queue ( / var/lib/rhpki-ra/lib/ perl/PKI/Request/Queue )
Perl interface to access the request queue in the RA.
Table 5.3. Perl libraries available for creating enrollment work flow
In the RA, the CGI that handles the SCEP request is running at http://example.com:12888/ee/scep/ pkiclient.cgi
Note
The RA only supports CA mode over SCEP.
5.3. Working With the Registration Authority
The following sections describe how to work with the Registration Authority, including listing, adding and deleting users and groups, and associating users with groups. They also describe how to add new
Agents and Administrators.
Additional topics describe how to submit CSRs and to perform SCEP, Server, User, and Agent
Enrollment requests.
5.3.1. Configuring Additional RA Instances
The following sections describe how to add and configure additional RA instances to an existing security domain.
By default, when you install an RA, it is automatically added to a default Registration Managers Group on the CA. This means the default RA instance will have the correct identification information for authentication and authorization.
143
Chapter 5. Registration Authority
A particular site might require more than one RA instance, each having its own set of RA agents. If the site policy is to disallow cross-management between the RA instances, then extra configuration is needed to ensure that the policy is not violated.
The following procedure describes how to add a new RA instance to an existing security domain. You need administrator privileges to the system and also to the CA to perform this procedure.
Procedure 5.2. Adding a new RA instance to an existing security domain
1. On the CA, use the following procedure to add the new RA group: a. Use the following command to start the pkiconsole. Replace "example.com" with your CA server name.
# /usr/bin/pkiconsole https:// <example.com> :9443/ca/& b. Click Users and Groups , and then click Groups .
c.
Click Add to display the Edit Group Information dialog box.
d. Enter the group name and description: for example, "Registration Manager2 Agents".
e. Click OK .
2. Add the new RA authentication instance in the CA: a. Change to the CA configuration directory, and edit the CS.cfg
file cd /var/lib/rhpki-ca/conf vi CS.cfg
b. Search for the lines containing the string "raCertAuth".
c.
Copy both lines and paste them immediately below the existing lines.
d. Make the following changes: i.
Change auths.instance.raCertAuth.agentGroup=Registration Manager
Agents to auths.instance.ra2CertAuth.agentGroup=Registration
Manager2 Agents ii.
Change auths.instance.raCertAuth.pluginName=AgentCertAuth to auths.instance.ra2CertAuth.pluginName=AgentCertAuth
3. Add the new RA user enrollment profile to utilize the new RA authentication instance a. Change to the CA profiles directory cd /var/lib/rhpki-ca/profiles/ca b. Create the new configuration file as follows:
144
Configuring Additional RA Instances cp caDualRAuserCert.cfg caDualRAi2userCert.cfg
c.
Edit the new file to suit the new profile: vi caDualRAi2userCert.cfg
d. Search for "raCertAuth" and change it to "ra2CertAuth" e. Save and close the file.
4. Change to the CA configuration directory, and edit the CS.cfg
file cd /var/lib/rhpki-ca/conf vi CS.cfg
a. Search for "profile.list" and add ",caDualRA2userCert" to the end of the list. Notice the comma at the beginning of the new entry.
b. Search for "caDualRAuserCert".
c.
Copy the two "class" and "config" lines and paste them immediately after the existing lines.
d. In the two pasted lines, change "caDualRAuserCert" to "caDualRA2userCert".
e. Save and close the file.
5. Add a new URI mapping to allow registering the new RA agent with the new RA group (for example, "Registration Manager2 Agent"): a. Change to the CA Web Applications directory, and edit the web.xml
file: cd /var/lib/rhpki-ca/webapps/ca/WEB-INF vi web.xml
b. Search for "caRegisterRaUser" c.
Copy everything between the <servlet> and </servlet> tags, and paste it immediately after the existing container. Ensure that you include the opening and closing <servlet> tags.
d. Change "caRegisterRaUser" to "caRegisterRa2User".
e. Change "Registration Manager Agents" to "Registration Manager2 Agents".
f.
Search for "caRegisterRaUser".
g. Copy everything between the <servlet-mapping> and </servlet-mapping> tags, and paste it immediately after the existing container. Ensure that you include the opening and closing
<servlet-mapping> tags.
h. Change "caRegisterRaUser" to "caRegisterRa2User".
145
Chapter 5. Registration Authority i.
Change "/admin/ca/registerRaUser" to "/admin/ca/registerRa2User".
j.
Save and close the file.
6. Use the following command to restart the CA:
/etc/rc.d/init.d/rhpki-ca restart
The following procedure describes how to create a new RA instance, and must be performed on the server that hosts the RA. You need administrator privileges to the system and also to the RA to perfom this procedure.
Procedure 5.3. Create the new RA instance
1. Use the following command to create a new RA instance. Notice that this command uses backslash (\) characters for line formatting. You must enter this command all on one line. Note that this instance uses different port numbers from the original RA:
# pkicreate -pki_instance_root=/var/lib \
-subsystem_type=ra -pki_instance_name=rhpki-ra2 -secure_port=12899 \
-unsecure_port=12898 -verbose -user=pkiuser -group=pkiuser
2. Edit the configuration file for the new RA instance: cd /var/lib/rhpki-ra2/conf/ vi CS.cfg
3. Locate the "registerRaUser" string and change it to "registerRa2User". Refer to the example below: conn.ca1.servlet.addagent=/ca/admin/ca/registerRa2User
4. Update the CS configuration file to point to the new enrollment profile and new authentication instance as follows:
In the /var/lib/rhpki-ra2/conf/CS.cfg
file, locate "caDualRAuserCert" and change it to
"caDualRA2userCert".
Do this for both the request.user.approve_request.0.profileId
and the request.renewal.approve_request.0.profileId
request queue parameters.
5. Use the following command to restart the new RA instance:
# /etc/rc.d/init.d/rhpki-ra2 restart
6. Navigate to the URL generated at the end of the pkicreate command to configure RA2.
146
Customizing the Subject DN in the CSR
7. When you have finished configuring the new RA, restart the instance using the command above.
Note
If any errors occurred and you need to recreate the RA2 instance, you can remove the existing RA2 instance using the pkiremove command, as follows:
# pkiremove -pki_instance_root=/var/lib -pki_instance_name=rhpki-ra2
You can then run the pkicreate procedure again.
5.3.2. Customizing the Subject DN in the CSR
This section describes how to customize the Subject Distinguished Name (DN) in the Certificate
Signing Request (CSR).
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, [email protected]". You can customize the DN by editing the user.vm
file for the RA. This procedure is covered below.
Note
There is no graphical interface for performing this customization.
Procedure 5.4. Customizing the DN
1. Edit the <instance_root> /docroot/ee/user/user.vm
file. This is typically /var/lib/ rhpki-ra/docroot/ee/user/user.vm
2. Locate the "validate" function and formulate your preferred DN in the var dn= statement.
The default value is var dn = "uid="+x+".e="+e; where "x" is the UID and "e" is the email from the user input.
3. When you have finished specifying the new Subject DN, save and close the file.
5.3.2.1. Updating the CSR Form
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 you have made the appropriate changes to the enrollment form, you need to use the previous procedure to customize the Subject DN to utilize the information collected from the user.
147
Chapter 5. Registration Authority
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/rhpki-ca/profiles/ca/caDualRAuserCert.cfg
.
Consider the following 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.
5.3.3. Using the End Users Services Interface
The following sections describe the functionality provided by the End Users Services Interface. This interface provides enrollment services for SCEP, Server, User, and Agent Enrollment, as well as status check functionality for submitted CSRs.
5.3.3.1. Cisco Router Certificate Enrollment on an RA Using SCEP
This section describes the process of using a Cisco router to enroll a certificate on an RA using SCEP
1
(Simple Certificate Enrollment Protocol). This protocol was designed by Cisco to provide a way for a router to communicate with an RA or a CA for certificate enrollment purposes.
Normally, the Router Administrator enters the URL of the RA and a challenge password (sometime referred to as a one-time PIN) into the router, and then issues a command to initiate the enrollment.
The router then communicates with the RA using the SCEP protocol to:
• Retrieve the CA certificate
• Submit the certificate request
• Retrieve the issued certificate
• Query the request status if the request is pending
SCEP specifies two modes of operation: RA mode; and CA mode. In RA mode, the enrollment request is encrypted with the RA signing certificate. In CA mode, the request is encrypted with the CA signing certificate.
The current implementation of RA and CA only supports the CA mode.
Previously known as CEP (Cisco Enrollment Protocol)
148
Using the End Users Services Interface
5.3.3.1.1. Configuration
CA Configuration
If the router communicates directly with the CA, the administrator must add the following to the /var/ lib/rhpki-ca/conf/flatfile.txt
file (one-time PIN file) on the CA:
UID: <IP address of the router>
PWD: <One-time PIN>
For example:
UID:172.16.24.238
PWD:1212
Note
If the router communicates directly with the RA, the above configuration is not required.
RA Configuration
On the RA, the PIN is generated when the request is approved, and stored in the SQLite database.
Consequently, no configuration is required.
Procedure 5.5. Submitting the certificate request
After the CA and the RA have been installed and appropriately configured, the Router Administrator submits the certificate request.
1. On the RA, navigate to the SSL End Users Services page, and then click SCEP Enrollment .
2. Click Request Submission - Manager
3. Enter the following information:
• Client ID: cisco1
• Site ID: <site IP address>
• Your mail: <[email protected]> . This is the address to which the certificate approval notice will be sent.
4. Click Submit . You should see a response similar to the following:
Your request has been successfully submitted.
Request ID: 1
149
Chapter 5. Registration Authority
Note
Use the following command to retrieve the Cisco router IP address: scep>show ip interface ethernet0/0
This command should return information similar to the following (irrelevant output has been trimmed):
Ethernet0/0 is up, line protocol is up
Internet address is 10.14.1.94/24
Broadcast address is 255.255.255.255
Address determined by setup command
MTU is 1500 bytes
...
.../
Procedure 5.6. Approving the Certificate Request
After the certificate request has been received, it needs to be approved by the RA, which also provides the one-time PIN to the router installer.
1. On the RA, navigate to the Agent interface and click List Requests .
2. Click the ID of the SCEP request that you want to approve.
3. Click Approve to approve the request.
This step produces an "Output" PIN. This is the password that you need to enter when performing the "Crypto CA enroll CA" step on the router.
Procedure 5.7. Retrieving the Certificate and Enrolling
After the certificate request has been approved, and the RA has provided the one-time PIN, the Router
Administrator needs to go to the provided URL to complete the certificate enrollment.
1. On the RA, navigate to the End User interface. Click SCEP Enrollment , and then click SCEP
Enrollment - Installer .
2. The "SCEP enrollment URL for the router" is the URL you should enter at the scep(config) prompt when performing the "Crypto CA identity CA" step.
3. Log in to the router and proceed with the certificate enrollment. Refer to Appendix C, Enrolling a
Certificate in a Cisco Router for instructions on how to enroll the certificate.
5.3.3.2. Server Enrollment on an RA
Server Administrators use this page to submit a CSR for approval by an RA Agent. When the Agent approves the request, an email notification is sent to the Server Administrator who can then retrieve the server certificate.
150
Using the End Users Services Interface
Procedure 5.8. Submitting a Server CSR
1. On the Services page on the RA, click SSL End Users Services .
2. Click Server Enrollment to display the Server Enrollment page, and then click Request
Submission - Administrator .
3. Enter the required details for the Server ID , Site ID and other fields, and then click Submit . This sends the CSR to the RA.
4. When the RA has approved the request, the Server Administrator receives an email with details about how to collect the certificate.
5.3.3.3. User Enrollment on an RA
Users access the User Enrollment page to submit a CSR to the RA. This page provides functionality for requesting a new certificate and for renewing an existing certificate.
Procedure 5.9. Submitting a User CSR
1. On the Services page on the RA, click SSL End Users Services .
2. Click User Enrollment to display the User Enrollment page.
a. To submit a new CSR: i.
Click Request Submission - User .
ii.
Enter the required details for the UID , Site ID and email address, and then click Submit .
This sends the CSR to the RA.
b. To submit a certificate renewal request: i.
Click Renewal - User .
ii.
On the User Renewal Interface, click Renewal to submit the current certificate to the RA for renewal.
3. When the RA has approved the request, the User receives an email with details about how to collect the certificate.
5.3.3.4. Agent Enrollment on an RA
To become an RA Agent, you first need to obtain a certificate. This can potentially be any user certificate capable of performing SSL client authentication. In other words, if the site decides that the certificates enrolled from the "User Enrollment" is sufficient, then that certificate can be used for agents.
The recommended (and default) practice, however, is to provide separate enrollment profiles on the
CA for these two distinct categories. The Agent Enrollment is obtained via the PIN Request followed by the actual enrollment.
This section describes the procedures necessary to enroll as an RA Agent.
151
Chapter 5. Registration Authority
Requesting a one-time PIN
The first step in becoming an RA Agent is for the user to apply for a PIN and have it approved by the
RA. This PIN is then used to apply for an Agent Certificate.
Procedure 5.10. To request a one-time PIN:
1. On the Certificate System Services page, click SSL End Users Services to display the RA
Services page.
2. Click Agent Enrollment to display the Agent Enrollment page.
3. Click PIN Creation Request to display the Agent Interface page.
4. Enter an appropriate UID and email address.
5. Click Submit to send the PIN request to the RA. The request is assigned an ID that you can use for status checks and other referrals.
Approving the Request
The next step in becoming an RA Agent is for the RA to approve the PIN Request submitted by the user.
Procedure 5.11. To approve the PIN request:
1. On the Certificate System Services page, click Agent Services to display the Agent Interface.
2. Click List Requests . The PIN request should be listed in a table with a status of OPEN.
3. Click the Request ID to display the details of the request.
4. If required, you can add an explanatory note in the text box at the bottom of the screen. Click Add
Note to save the note with the request.
5. Click Approve to approve the request. This generates the PIN that the new Agent requires to complete the Agent Enrollment.
Using the PIN to Apply for an Agent Certificate
After the RA has approved the PIN Request, the user must use the PIN to apply for Agent Enrollment and to receive their Agent Certificate.
Procedure 5.12. To apply for an agent certificate:
1. On the Certificate System Services page, click SSL End Users Services to display the RA
Services page.
2. Click Request Status Check to display the Request Status page.
3. In the Request ID field, enter the ID of the PIN request. If the RA has approved the PIN request, the value of the Status field should be APPROVED.
4. Click the value in the Import Certificate field to display the one-time PIN. You can now use the
PIN to enroll for an Agent Certificate.
152
Using the Agent Services Interface
Upon successful enrollment, the base64 encoding of the certificate is displayed and can be copied.
5.3.3.5. Requesting Status Checks
You use the Request Status page to request the status of any submitted CSR.
To request the status of a CSR, enter the request ID in the Request Id field and click Check . This returns a page with the status of the CSR, including any error messages.
5.3.4. Using the Agent Services Interface
You use the Agent Services interface to list certificate requests and certificates.
The List Requests page provides a table of CSRs and their current status. You can display CSRs according to their status, either OPEN, APPROVED, REJECTED, or FAILED.
The List Certificates page provides information on each of the approved requests. The request with the lowest ID (typically 1) is displayed first.
5.3.5. Using the Administrator Interface
The following sections describe the functionality provided by the Administrator Interface. This includes the basic procedures for working with users and groups in the Certificate System, such as adding and deleting users and groups, associating users with groups, etc.
Note
These procedures require Administrator access to the Certificate System
Listing Users and Groups
You can use the Administrator interface of the RA to list existing users and groups, as described below.
Procedure 5.13. To list existing users and groups:
1. Navigate to the Certificate System Services page, and click Administrator Services .
2. On the Administrator interface, click List Users or List Groups . The details of existing users and groups are displayed in a table, which includes UID, Name, and Email information, as appropriate.
Adding Users and Groups
You can use the Administrator interface of the RA to add users and groups, and also to associate users with groups, as described below.
Procedure 5.14. To add a new user or group:
1. Navigate to the Certificate System Services page, and click Administrator Services .
153
Chapter 5. Registration Authority
2. On the Administrator interface, click Add New User or Add New Group , and enter the required details.
3. When you have entered all of the required details, click Add User or Add Group , as appropriate.
Note
If you are adding a new user, this user must have already enrolled for and received a certificate.
Procedure 5.15. To add a user to a group:
1. Navigate to the Certificate System Services page, and click Administrator Services .
2. On the Administrator interface, click List Groups to display the list of existing groups.
3. Click the GID of the group to which you want to add the user.
4. Select the user from the New Member list, and then click Add .
Deleting Users and Groups
You can use the Administrator interface of the RA to delete existing users and groups, as described below.
Procedure 5.16. To delete a user:
1. Navigate to the Certificate System Services page, and click Administrator Services .
2. On the Administrator interface, click List Users to display the list of existing users.
3. Click the UID of the user that you want to delete.
4. Scroll to the bottom of the User Information page, and click Delete .
Procedure 5.17. To delete a group:
1. Navigate to the Certificate System Services page, and click Administrator Services .
2. On the Administrator interface, click List Groups to display the list of existing groups.
3. Click the GID of the group that you want to delete, and then click Delete This Group .
Note
Deleting a group has no effect on the users who may be members of that group. That is, these users will still exist in Certificate System. Their membership in any other groups is not affected.
Procedure 5.18. To delete a user from a group:
1. Navigate to the Certificate System Services page, and click Administrator Services .
154
Command-line Operations
2. On the Administrator interface, click List Groups to display the list of existing groups.
3. Click the GID of the group from which you want to delete the user.
4. In the Member section, locate the user that you want to delete from the group, and click the associated Delete link.
Adding New Agents and Administrators
After the initial installation and configuration of the RA, you may need to add new Agents and
Administrators. This involves adding a new user to the Certificate System, specifying the role for the user (Agent or Administrator), and importing the certificate for that user.
Note
You need to be an RA Administrator with access to the Administration Interface to perform this procedure.
Procedure 5.19. To add a new agent or administrator
1. Create a new user as described above.
2. Add the new user to the required group as described above.
Note
If you create a new group, ensure that you modify the admin.authorized_groups
and agent.authorized_groups
parameters in CS.cfg
to include the new group to reflect the required authorization levels for the new group.
5.3.6. Command-line Operations
Most of the day-to-day RA operations can be performed using the browser-based interfaces. You can also use the command line to perform more complex tasks, or where a browser is unavailable. The following section describes some of these tasks.
Using SQL to Query the Database
RA administrators can query the SQLite database using a simple tool like sqlite3 from the command line.
Procedure 5.20. To query the database using SQL:
1. Launch sqlite3 from command line, as follows:
[redhat@willow ~]$ sqlite3 /var/lib/rhpki-ra/conf/dbfile
When a connection is established to the database, you should see the sqlite prompt: sqlite>
2. You can now use standard sqlite commands to query the database, for example:
155
Chapter 5. Registration Authority
• To display all user information, use the following command: sqlite> select * from users;
• To display all request information, use the following command: sqlite> select * from requests;
• To display a list of available tables, use the following command: sqlite> .tables
156
Chapter 6.
Online Certificate Status Protocol
Responder
This chapter provides an overview of an Online Certificate Status Protocol (OCSP) service and explains how the OCSP service verifies the current status of the certificates issued by the Certificate
Manager. The chapter also explains how to configure the Online Certificate Status Managers to publish CRLs.
6.1. About OCSP Services
The Certificate System CA supports the Online Certificate Status Protocol (OCSP) as defined in
PKIX standard RFC 2560 (see http://www.ietf.org/rfc/rfc2560.txt
). The OCSP protocol enables OCSPcompliant applications to determine the state of a certificate, including the revocation status, without having to directly check a CRL published by a CA to the validation authority. The validation authority, which is also called an OCSP responder , checks for the application.
1. A CA is set up to issue certificates that include the Authority Information Access extension, which identifies an OCSP responder that can be queried for the status of the certificate.
2. The CA periodically publishes CRLs to an OCSP responder.
3. The OCSP responder maintains the CRL it receives from the CA.
4. An OCSP-compliant client sends requests containing all the information required to identify the certificate to the OCSP responder for verification. The applications determine the location of the
OCSP responder from the value of the Authority Information Access extension in the certificate being validated.
5. The OCSP responder determines if the request contains all the information required to process it. If it does not or if it is not enabled for the requested service, a rejection notice is sent. If it does have enough information, it processes the request and sends back a report stating the status of the certificate.
6.1.1. OCSP Response Signing
Every response that the client receives, including a rejection notification, is digitally signed by the responder; the client is expected to verify the signature to ensure that the response came from the responder to which it submitted the request. The key the responder uses to sign the message depends on how the OCSP responder is deployed in a PKI setup. RFC 2560 recommends that the key used to sign the response belong to one of the following:
• The CA that issued the certificate that's status is being checked.
• A responder with a public key trusted by the client. Such a responder is called a trusted responder .
• A responder that holds a specially marked certificate issued to it directly by the CA that revokes the certificates and publishes the CRL. Possession of this certificate by a responder indicates that the
CA has authorized the responder to issue OCSP responses for certificates revoked by the CA. Such a responder is called a CA-designated responder or a CA-authorized responder .
The end-entities page of a Certificate Manager includes a form for manually requesting a certificate for the OCSP responder. The default enrollment form includes all the attributes that identify the certificate
157
Chapter 6. Online Certificate Status Protocol Responder as an OCSP responder certificate. The required certificate extensions, such as OCSPNoCheck and
Extended Key Usage, can be added to the certificate when the certificate request is submitted.
For more information about the certificates associated with the OCSP Manager, see Section 6.3,
“Online Certificate Status Manager Certificates” .
6.1.2. OCSP Responses
The OCSP response that the client receives indicates the current status of the certificate as determined by the OCSP responder. The response could be any of the following:
• Good or Verified . Specifies a positive response to the status inquiry, meaning the certificate has not been revoked. It does not necessarily mean that the certificate was issued or that it is within the certificate's validity interval. Response extensions may be used to convey additional information on assertions made by the responder regarding the status of the certificate.
• Revoked . Specifies that the certificate has been revoked, either permanently or temporarily.
Based on the status, the client decides whether to validate the certificate.
NOTE
The OCSP responder will never return a response of Unknown . The response will always be either Good or Revoked .
6.2. CA OCSP Services
There are two ways to set up OCSP services:
• The OCSP built into the Certificate Manager.
• The Online Certificate Status Manager.
6.2.1. The Certificate Manager's Internal OCSP Service
The Certificate Manager has a built-in OCSP service, which can be used by OCSP-compliant clients to query the Certificate Manager directly about the revocation status of the certificate. When the
Certificate Manager is installed, an OCSP signing certificate is issued and the OCSP service is turned on by default. This OCSP signing certificate is used to sign all responses to OCSP service requests.
Since the internal OCSP service checks the status of certificates stored in the Certificate Manager's internal database, publishing does not have to be configured to use this service.
Clients can query the OCSP service through the non-SSL end-entity port of the Certificate Manager.
When queried for the revocation status of a certificate, the Certificate Manager searches its internal database for the certificate, checks its status, and responds to the client. Since the Certificate
Manager has real-time status of all certificates it has issued, this method of revocation checking is the most accurate.
6.2.2. Online Certificate Status Manager
In addition to the built-in OCSP service, the Certificate Manager can publish CRLs to an OCSPcompliant validation authority. CAs can be configured to publish CRLs to the Certificate System
158
Online Certificate Status Manager Certificates
Online Certificate Status Manager. The Online Certificate Status Manager stores each Certificate
Manager's CRL in its internal database and uses the appropriate CRL to verify the revocation status of a certificate when queried by an OCSP-compliant client.
The Certificate Manager can generate and publish CRLs whenever a certificate is revoked and at specified intervals. Because the purpose of an OCSP responder is to facilitate immediate verification of certificates, the Certificate Manager should publish the CRL to the Online Certificate Status
Manager every time a certificate is revoked. Publishing only at intervals means that the OCSP service is checking an outdated CRL.
NOTE
If the CRL is large, the Certificate Manager can take a considerable amount of time to publish the CRL.
The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL to verify certificates. The Online Certificate Status Manager can also use the
CRL published to an LDAP directory, meaning the Certificate Manager does not have to update the
CRLs directly to the Online Certificate Status Manager.
6.3. Online Certificate Status Manager Certificates
When the Online Certificate Status Manager is installed, the keys for the OCSP signing certificate and SSL server certificate are created, and the certificate requests for the signing and the SSL server certificates are made.
These requests can be submitted either to a Certificate Manager or to a third party public CA. If the certificate is sent to a third party CA, then the certificate must be installed when it is received. If the
OCSP signing certificate is made when the subsystem is configured and it issued by a Certificate
Manager, the certificate is installed immediately; if the Certificate Setup Wizard is used, the request is submitted to the Certificate Manager and can be retrieved when it is issued.
6.3.1. OCSP Signing Key Pair and Certificate
Every Online Certificate Status Manager has a certificate, the OCSP signing certificate, which has a public key corresponding to the private key the Online Certificate Status Manager uses to sign
OCSP responses. The Online Certificate Status Manager's signature provides persistent proof that the Online Certificate Status Manager has processed the request. This certificate is generated when the Online Certificate Status Manager is configured. The default nickname for the certificate is ocspSigningCert certinstance_ID , where instance_ID identifies either the Online Certificate
Status Manager or the CA instance with the internal OCSP service.
6.3.2. SSL Server Key Pair and Certificate
Every Online Certificate Status Manager has at least one SSL server certificate which was generated when the Online Certificate Status Manager was configured. The default nickname for the certificate is Server-Cert certinstance_ID , where instance_ID identifies the Online Certificate Status
Manager instance name.
The Online Certificate Status Manager uses its server certificate for server-side authentication for the
Online Certificate Status Manager agent services page.
159
Chapter 6. Online Certificate Status Protocol Responder
The Online Certificate Status Manager uses a single server certificate for authentication purposes.
Additional server certificates can be installed and used for different purposed. For instructions, see
Section 11.5, “Configuring the Server Certificate Use Preferences” .
6.3.3. Recognizing Online Certificate Status Manager Certificates
Depending on the CA which signed the Online Certificate Status Manager's SSL server certificate, it may be necessary to get the certificate and issuing CA recognized by the Certificate Manager.
• If the Online Certificate Status Manager's server certificate is signed by the CA that is publishing
CRLs, then nothing needs done.
• If the Online Certificate Status Manager's server certificate is signed by the same root CA that signed the subordinate Certificate Manager's certificates, then the root CA must be marked as a trusted CA in the subordinate Certificate Manager's certificate database.
• If the Online Certificate Status Manager's SSL server certificate is signed by a different root CA, then the root CA certificate must be imported into the subordinate Certificate Manager's certificate database and marked as a trusted CA.
If the Online Certificate Status Manager's server certificate is signed by a CA within the selected security domain, the certificate chain is imported and marked when the Online Certificate Status
Manager is configured. No other configuration is required. However, if the server certificate is signed by an external CA, the certificate chain has to be imported for the configuration to be completed.
NOTE
Not every CA within the security domain is automatically trusted by the OCSP Manager when it is configured. Every CA in the certificate chain of the CA configured in the CA panel is, however, trusted automatically by the OCSP Manager. Other CAs within the security domain but not in the certificate chain must be added manually.
6.4. Configuring the Online Certificate Status Manager
After the installation and basic configuration of the Online Certificate Status Manager subsystem, further configuration to features such as logging and certificate contents can be made through the Certificate System administrative console. This console allows user and group management, authorization settings, internal LDAP database information, self-tests, and other administrative tasks.
General subsystem configuration is outlined in Table 6.1, “General Subsystem Configuration Links” .
Configuration
Adding additional Online Certificate Status
Manager instances.
General configuration and management such as changing port numbers, setting up logging, running self-tests, and managing the internal database.
Adding and deleting users, agents, and administrators.
Section
Section 2.7, “Creating Additional Subsystem
Instances”
Chapter 3, Administrative Basics
Section 17.2, “Creating Users”
160
Creating Online Certificate Status Manager Agents and Administrators
Configuration
Managing the access control lists (ACLs) for user authorization.
Requesting and installing certificates and managing tokens.
Section
Section 17.6, “Authorization for Certificate
System Users”
• Section 11.2, “Requesting and Receiving
Certificates”
• Section 11.4.1, “Installing Certificates in the
Certificate System Database”
Section 11.4.1.3, “About CA Certificate Chains” Installing a certificate chain in the database to provide the chain of CAs to a trusted CA.
Managing tokens.
Changing the subsystem security settings.
Changing subsystem passwords
Configuring the internal OCSP service.
Setting up CRLs and revoking certificates.
Configuring cloning.
Section 12.1, “Tokens for Storing Certificate
System Keys and Certificates”
Section 11.5, “Configuring the Server Certificate
Use Preferences”
Section 3.3, “System Passwords”
Chapter 6, Online Certificate Status Protocol
Responder
Chapter 14, Revocation and CRLs
Chapter 20, Configuring the Certificate System for High Availability
Table 6.1. General Subsystem Configuration Links
6.5. Creating Online Certificate Status Manager Agents and
Administrators
When the subsystem is configured, there is a default user created with both administrator and agent privileges. This user can perform both administrator and agent operations and access the Console and the agent services page.
To create additional administrator, agent, or auditor users, create a user in the Certificate System instance where the user will have privileges and assign the user to the appropriate group. An agent or auditor must have a certificate stored in the subsystem's internal database. If the Console is configured for SSL client authentication, all administrators must also a certificate.
To create a new user entry, do the following:
1. Log into the administrative console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Users and Groups . Click Add .
3. Fill in the information in the Edit User Information dialog.
161
Chapter 6. Online Certificate Status Protocol Responder
Figure 6.1. Creating a New User
The group to which the user belongs determines what privileges the user has. Assign agents and administrators to the appropriate subsystem group.
4. Store the user's certificate.
a. Request and approve an SSL client certificate for the user if one has not already been generated.
b. Copy the base-64 encoded certificate to a local file or to the clipboard.
c. Select the new user entry, and click Certificates .
d. Click Import , and paste in the base-64 encoded certificate.
For more information on editing user entries and managing user certificates, see Section 17.4,
“Modifying Certificate System User Entries” .
6.6. Configuring the Certificate Manager's Internal OCSP
Service
Every CA's built-in OCSP service is turned on at installation. However, to use this service, the CA needs to issue certificates with the Authority Information Access extension
162
Setting up the OCSP Responder
1. Go to the CA's end-entities page. For example: https://server.example.com:9443/ca/ee/ca/
2. Find the CA signing certificate.
3. Look for the Authority Info Access extension in the certificate, and note the Location URIName value, such as http://server.example.com:9080/ca/ocsp .
4. Update the enrollment profiles to enable the Authority Information Access extension, and set the
Location parameter to the Certificate Manager's URI. For information on editing the certificate profiles, see Section 13.3, “Setting up Certificate Profiles” .
5. Restart the CA instance.
/etc/init.d/ instance_ID restart
To disable the Certificate Manager's internal OCSP service, edit the CA's CS.cfg
file and change the value of the ca.ocsp
parameter to false .
ca.ocsp=false
6.7. Setting up the OCSP Responder
If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the OCSP service. The CA's CRL publishing is set up automatically, and its signing certificate is automatically added and trusted in the Online
Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the OCSP service must be manually configured after the Online Certificate Status Manager is configured.
NOTE
Not every CA within the security domain to which the OCSP Manager belongs is automatically trusted by the OCSP Manager when it is configured. Every CA in the certificate chain of the CA configured in the CA panel is trusted automatically by the
OCSP Manager. Other CAs within the security domain but not in the certificate chain must be trusted manually.
To set up the Online Certificate Status Manager for a Certificate Manager outside the security domain, do the following:
1. Configure the CRLs for every CA that will publish to an OCSP responder. See Chapter 14,
Revocation and CRLs for details.
2. Enable publishing, set up a publisher, and set publishing rules in every CA that the OCSP service will handle. See Chapter 15, Publishing for details. This is not necessary if the Certificate
Managers publish to an LDAP directory and the Online Certificated Status Manager is set up to read from that directory.
163
Chapter 6. Online Certificate Status Protocol Responder
3. The certificate profiles must be configured to include the Authority Information Access extension, pointing to the location at which the Certificate Manager listens for OCSP service requests. See
Section 6.6, “Configuring the Certificate Manager's Internal OCSP Service” for more information.
4. Configure the OCSP Responder. See Section 6.4, “Configuring the Online Certificate Status
Manager” .
• Configuring the Revocation Info stores. See Section 6.8.2, “Configure the Revocation Info
Stores” .
• Identify every publishing Certificate Manager to the OCSP responder. See Section 6.8,
“Identifying the CA to the OCSP Responder” for details.
• If necessary, configure the trust settings for the CA which signed the OCSP signing certificate.
See Section 11.4.4, “Changing the Trust Settings of a CA Certificate” for details.
5. Restart both subsystems after configuring them.
6. Verify that the CA is properly connected to the OCSP responder; see Section 6.8.1, “Verify
Certificate Manager and Online Certificate Status Manager Connection” .
6.8. Identifying the CA to the OCSP Responder
Before a CA is configured to publish CRLs to the Online Certificate Status Manager, the CA must be identified to the Online Certificate Status Manager by storing the CA signing certificate in the internal database of the Online Certificate Status Manager. The Certificate Manager signs CRLs with the key pair associated with this certificate; the Online Certificate Status Manager verifies the signature against the stored certificate.
NOTE
If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the Online Certificate Status
Manager to recognize the CA; the CA signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a nonsecurity domain CA is selected, then the CA signing certificate must be manually added to the certificate database after the Online Certificate Status Manager is configured.
It is not necessary to import the certificate chain for a CA which will publish its CRL to the Online
Certificate Status Manager. The only time a certificate chain is needed for the OCSP service is if the
CA connects to the Online Certificate Status Manager through SSL authentication when it publishes its
CRL. Otherwise, the Online Certificate Status Manager does not need to have the complete certificate chain.
However, the Online Certificate Status Manager must have the certificate which signed the CRL, either a CA signing certificate or a separate CRL signing certificate, in its certificate database. The OCSP service verifies the CRL by comparing the certificate which signed the CRL against the certificates in its database, not against a certificate chain. If both a root CA and one of its subordinate CAs publish
CRLs to an Online Certificate Status Manager, the Online Certificate Status Manager needs the CA signing certificate of both CAs.
To import the CA or CRL signing certificate which is used to sign the certificates the CA is publishing to the Online Certificate Status Manager, do the following:
164
Verify Certificate Manager and Online Certificate Status Manager Connection
1. Get the Certificate Manager's base-64 CA signing certificate from the end-entities page of the CA.
2. Open the Online Certificate Status Manager agent page. The URL has the format https:// hostname:SSLport /ocsp/agent/ocsp .
3. In the left frame, click Add Certificate Authority .
4. In the form, paste the encoded CA signing certificate inside the text area labeled Base 64 encoded certificate (including the header and footer) .
5. To verify that the certificate is added successfully, in the left frame, click List Certificate
Authorities .
The resulting form should show information about the new CA. The This Update , Next Update , and
Requests Served Since Startup fields should show a value of zero (0).
6.8.1. Verify Certificate Manager and Online Certificate Status
Manager Connection
When the Certificate Manager is restarted, it tries to connect to the Online Certificate Status Manager's
SSL port. To verify that the Certificate Manager did indeed communicate with the Online Certificate
Status Manager, check the This Update and Next Update fields, which should be updated with the appropriate timestamps of the CA's last communication with the Online Certificate Status Manager.
The Requests Served Since Startup field should still show a value of zero (0) since no client has tried to query the OCSP service for certificate revocation status.
6.8.2. Configure the Revocation Info Stores
The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL store for verifying the revocation status of certificates. The Online Certificate
Status Manager can be configured to use the CRL published to an LDAP directory, instead of the CRL in its internal database.
To configure the Online Certificate Status Manager to use the CRLs in its internal database or an
LDAP directory for verifying revocation status of certificate, do the following:
1. Open the Online Certificate Status Manager Console.
pkiconsole https:// hostname:SSLhost /ocsp
2. In the Configuration tab, select Online Certificate Status Manager , and then select Revocation
Info Stores .
The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
3. Select the appropriate option:
• To use the CRLs in its internal database, select defStore , and click Edit/View .
• To use the CRLs in LDAP directories, click Set Default to enable the ldapStore option, select ldapStore , and click Edit/View .
165
Chapter 6. Online Certificate Status Protocol Responder
4. For defStore , fill in the following values:
• notFoundAsGood.
Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is
UNKNOWN, which, when encountered by a client, results in an error message.
• includeNextUpdate.
The Online Certificate Status Manager can include the timestamp of the next CRL update time.
For ldapStore , fill in the following values:
• numConns.
The total number of LDAP directories the OCSP service should check. By default, this is set to 0. Setting this value shows the corresponding number of host , port , baseDN , and refreshInSec fields.
• host.
The fully-qualified DNS hostname of the LDAP directory.
• port.
The non-SSL port of the LDAP directory.
• baseDN.
The DN to start searching for the CRL. For example, O=example.com
.
• refreshInSec.
How often the connection is refreshed. The default is 86400 seconds (daily).
• caCertAttr.
Leave the default value, cACertificate;binary , as it is. It is the attribute to which the Certificate Manager publishes its CA signing certificate.
• crlAttr.
Leave the default value, certificateRevocationList;binary , as it is. It is the attribute to which the Certificate Manager publishes CRLs.
• notFoundAsGood.
Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is
UNKNOWN, which, when encountered by a client, results in an error message.
• includeNextUpdate.
The Online Certificate Status Manager can include the timestamp of the next CRL update time.
6.9. Testing the OCSP Service Setup
Test whether the Certificate Manager can service OCSP requests properly by doing the following:
1. Turn on revocation checking in the browser or client.
2. Request a certificate from the CA that has been enabled for OCSP services.
3. Approve the request.
4. Download the certificate to the browser or client.
5. Make sure the CA is trusted by the browser or client.
6. Check the status of Certificate Manager's internal OCSP service.
Open the CA agent services page, and select the OCSP Services link.
7. Test the independent Online Certificate Status Manager subsystem.
166
Submitting OCSP Requests Using the GET Method
Open the Online Certificate Status Manager agent services page, and click the List Certificate
Authorities link.
The page should show information about the Certificate Manager configured to publish CRLs to the Online Certificate Status Manager. The page also summarizes the Online Certificate Status
Manager's activity since it was last started.
8. Revoke the certificate.
9. Verify the certificate in the browser or client. The server should return that the certificate has been revoked.
10. Check the Certificate Manager's OCSP-service status again to verify that these things happened:
• The browser sent an OCSP query to the Certificate Manager.
• The Certificate Manager sent an OCSP response to the browser.
• The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
11. Check the independent OCSP service subsystem again to verify that these things happened:
• The Certificate Manager published the CRL to the Online Certificate Status Manager.
• The browser sent an OCSP response to the Online Certificate Status Manager.
• The Online Certificate Status Manager sent an OCSP response to the browser.
• The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
6.10. Submitting OCSP Requests Using the GET Method
OCSP requests which are smaller than 255KB can be submitted to the Online Certificate Status
Manager using a GET method, as described in RFC 2560. To submit OCSP requests over GET:
1. Generate an OCSP request for the certificate that's status is being queried. For example:
# OCSPClient server.example.com 11443 /var/lib/pki-ca/alias 'caSigningCert cert-pki-ca' 1
/export/output.txt 1
URI: /ocsp/ee/ocsp
Data Length: 68
Data: MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ
44kgy35o7xW5BMzM8FTvyTwCAQE=
The Certificate System's OCSPClient tool has the format:
OCSPClient host port /path/to/CA_cert_database 'CA_signing_cert_nickname' serial_number output_file times
An OCSP request can also be generated using OpenSSL tools, as described at http://openssl.org/ docs/apps/ocsp.html
, or through a browser such as Internet Explorer 7.0.
167
Chapter 6. Online Certificate Status Protocol Responder
2. Paste the URL in the address bar of a web browser to return the status information. The browser must be able to handle OCSP requests.
https://server.example.com:11443/ocsp/ee/ocsp/MEIwQDA
+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewd
Dnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
3. The OCSP Manager responds with the certificate status which the browser can interpret. The possible statuses are GOOD, REVOKED, and UNKNOWN.
Alternatively, run the OCSP from the command line by using a tool such as wget to send the request and checking the OCSP logs for the response. For example:
1. Generate an OCSP request for the certificate that's status is being queried.
# OCSPClient server.example.com 11443 /var/lib/pki-ca/alias 'caSigningCert cert-pki-ca' 1
/export/output.txt 1
URI: /ocsp/ee/ocsp
Data Length: 68
Data: MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ
44kgy35o7xW5BMzM8FTvyTwCAQE=
2. Connect to the OCSP Manager using wget to send the OCSP request.
wget https://server.example.com:11443/ocsp/ee/ocsp/MEIwQDA
+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4J
pmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE= --no-check-certificate
--16:34:34-- https://server.example.com:11443/ocsp/ee/ocsp/MEIwQDA
+MDwwOjAJBgUrDgMCGgUABBT4cyABky
iCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
=>`MEIwQDA
+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE='
Resolving server.example.com... 192.168.123.224
Connecting to server.example.com|192.168.123.224|:11443... connected.
WARNING: Certificate verification error for server.example.com: self signed certificate
in certificate chain
HTTP request sent, awaiting response... 200 OK
Length: 2,362 (2.3K) [application/ocsp-response]
100%[======================================================================>] 2,362 --.--
K/s
16:34:34 (474.43 MB/s) - `MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewd
Dnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=' saved [2362/2362]
3. The status for the specified certificate is written to the OCSP's debug log and can be GoodInfo ,
RevokeInfo , or UnknownInfo .
[16/Jul/2008:16:48:47][http-11443-Processor24]: Serial Number: 1
Status: com.netscape.cmsutil.ocsp.GoodInfo
For certificates issued by a 7.1 CA with the Authority Information Access extension to be sent to the
OCSP with the GET method, a redirect needs to be created to forward the requests to the appropriate
URL, as described in Section 6.11, “Setting up a Redirect for Certificates Issued in Certificate System
7.1 and Earlier” .
168
Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier
6.11. Setting up a Redirect for Certificates Issued in
Certificate System 7.1 and Earlier
The location for the OCSP user pages, specified in the URL with the file root /ocsp/ee/ocsp/ , is different in Certificate System 7.3 than the location in Certificate System 7.1, which was simply / ocsp/ . In order for certificates issued by a 7.1 CA with the Authority Information Access extension to be sent to the OCSP, create a redirect to forward the requests to the appropriate URL.
IMPORTANT
Errata RHSA 2008:0566 or later must be applied to your Certificate System installation before creating the redirect for the OCSP end entities' pages.
NOTE
Setting the redirect is only required to manage certificates issued by a 7.1 CA with the
Authority Information Access extension. If the certificates are issued by a later version
Certificate Manager or do not contain the Authority Information Access extension, then this configuration is not necessary.
1. Stop the OCSP Responder. For example:
/etc/init.d/rhpki-ocsp stop
2. Open the OCSP's web applications directory. For example: cd /var/lib/rhpki-ocsp/webapps
3. Open the ROOT/WEB-INF/ directory in the ROOT folder of the OCSP's web applications directory.
For example: cd /var/lib/rhpki-ocsp/webapps/ROOT/WEB-INF/
4. Create and open the lib/ directory in the ROOT folder of the OCSP's web applications directory.
For example: mkdir lib cd lib/
5. Create a symlink that links back to the /usr/share/java/rhpki/cms.jar
JAR file. For example: ln -s /usr/share/java/rhpki/cms.jar cms.jar
6. Move up to the ROOT/WEB-INF/ directory.
cd ../
169
Chapter 6. Online Certificate Status Protocol Responder
7. Move up to the main web application directory. For example: cd /var/lib/rhpki-ocsp/webapps/
8. Rename the current instance ( ocsp ) directory. For example: mv /var/lib/rhpki-ocsp/webapps/ocsp /var/lib/rhpki-ocsp/webapps/ocsp2
9. Open the WEB-INF/ directory in the original ocsp/ directory. For example: cd /var/lib/rhpki-ocsp/webapps/ocsp/WEB-INF
10. In original ocsp/WEB-INF/ directory, edit the web.xml
file and add lines mapping between the eeocspAddCRL and csadmin-wizard servlets.
<servlet-mapping>
<servlet-name> ocspOCSP </servlet-name>
<url-pattern> /ee/ocsp/* </url-pattern>
</servlet-mapping>
11. Create and install the web.xml
file in the ROOT directory. For example:
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app>
<display-name>Welcome to Tomcat</display-name>
<description>
Welcome to Tomcat
</description>
<servlet>
<servlet-name>ocspProxy</servlet-name>
<servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class>
<init-param>
<param-name>destContext</param-name>
<param-value>/ocsp2</param-value>
</init-param>
<init-param>
<param-name>destServlet</param-name>
<param-value>/ee/ocsp</param-value>
</init-param>
</servlet>
<servlet>
<servlet-name>ocspOther</servlet-name>
<servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class>
<init-param>
<param-name>destContext</param-name>
<param-value>/ocsp2</param-value>
</init-param>
<init-param>
<param-name>srcContext</param-name>
<param-value>/ocsp</param-value>
</init-param>
<init-param>
<param-name>destServlet</param-name>
<param-value></param-value>
</init-param>
170
Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier
<init-param>
<param-name>matchURIStrings</param-name>
<param-value>/ocsp/registry,/ocsp/acl,/ocsp/jobsScheduler,/ocsp/ug,/ocsp/server,/ocsp/log,
/ocsp/auths,/ocsp/start,/ocsp/ocsp,/ocsp/services,/ocsp/agent,/ocsp/ee,
/ocsp/admin</param-value>
</init-param>
<init-param>
<param-name>destServletOnNoMatch</param-name>
<param-value>/ee/ocsp</param-value>
</init-param>
<init-param>
<param-name>appendPathInfoOnNoMatch</param-name>
<param-value>/ocsp</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>ocspProxy</servlet-name>
<url-pattern>/ocsp</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ocspOther</servlet-name>
<url-pattern>/ocsp/*</url-pattern>
</servlet-mapping>
</web-app>
12. Edit the /var/lib/rhpki-ocsp/conf/context.xml
, changing the following line:
<Context>
to
<Context crossContext="true" >
13. Edit the /var/lib/rhpki-ocsp/webapps/ocsp2/services.template
file and change the following line: result.recordSet[i].uri);
to result.recordSet[i].uri + "/");
14. Start the OCSP instance. For example:
/etc/init.d/rhpki-ocsp start
171
172
Chapter 7.
Data Recovery Manager
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 form of server-side key generation is handled in
Chapter 8, Token Processing System . 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.
7.1. PKI Setup for Archiving and Recovering Keys
To archive private encryption keys and recover them later, the PKI configuration must include the following elements:
• Clients that can generate dual keys and that support the key archival option (using the CRMF/
CMMF protocol).
• An installed and configured DRM.
• HTML forms with which end entities can request dual certificates (based on dual keys) and key recovery agents can request key recovery.
Only keys that are used exclusively for encrypting data should be archived; signing keys in particular should never be archived. Having two copies of a signing key makes it impossible to identify with certainty who used the key; a second archived copy could be used to impersonate the digital identity of the original key owner.
Clients that generate single key pairs use the same private key for both signing and encrypting data, so a private key derived from a single key pair cannot be archived and recovered. Clients that can generate dual key pairs use one private key for encrypting data and the other for signing data. Since the private encryption key is separate, it can be archived.
In addition to generating dual key pairs, the clients must also support archiving the encryption key in certificate requests. This option archives keys at the time the private encryption keys are generated as a part of issuing the certificate.
7.2. Data Recovery Manager Certificates
The DRM uses the following key pairs and certificates:
• Section 7.2.1, “Transport Key Pair and Certificate”
173
Chapter 7. Data Recovery Manager
• Section 7.2.2, “Storage Key Pair”
• Section 7.2.3, “SSL Server Certificate”
7.2.1. Transport Key Pair and Certificate
Every DRM has a transport certificate. The public key of the key pair that is used to generate the transport certificate is used by the client software to encrypt an end entity's private encryption key before it is sent to the DRM for archival; only those clients capable of generating dual-key pairs use the transport certificate. For more information on how this certificate is used, see Section 7.4,
“Overview of Archiving Keys” .
7.2.2. Storage Key Pair
Every DRM has a storage key pair.
The DRM uses the public component of this key pair to encrypt (or wrap) private encryption keys when archiving the keys. It uses the private component to decrypt (or unwrap) the archived key during recovery. For more information on how this key pair is used, see Chapter 7, Data Recovery Manager .
NOTE
The public component of the storage key pair is not certified; there is no certificate that corresponds to the public key. It is a self-signed certificate.
Keys encrypted with the storage key can be retrieved only by authorized key recovery agents. For details, see Section 7.5.1, “Key Recovery Agents and Their Passwords” .
7.2.3. SSL Server Certificate
Every Certificate System DRM has at least one SSL server certificate. The first SSL server certificate is generated when the DRM is configured. The default nickname for the certificate is Server-Cert certinstance_id , where instance_id identifies the DRM instance is installed.
The DRM's SSL server certificate was issued by the CA to which the certificate request was submitted, which can be a Certificate System CA or a third-party CA. To view the issuer name, open the certificate details in the System Keys and Certificates option in the DRM Console.
The DRM uses its SSL server certificate for server-side authentication to the DRM agent services interface. By default, the Data Recovery Manager uses a single SSL server certificate for authentication. However, additional SSL server certificates can be requested and installed for the
DRM.
7.3. Forms for Users and Key Recovery Agents
End entity private encryption keys are archived by the DRM when they are generated. When a Certificate Manager processing a certificate request detects the request for key archival, it automatically requests the service of the DRM. Because the DRM transport certificate is stored within the CA's CS.cfg
file, the CA enrollment form can automatically trigger the key archival.
Initiating the key recovery process also requires its own HTML form. By default, the DRM agent services page provides the forms needed for initiating the process and retrieving keys.
174
Overview of Archiving Keys
7.4. Overview of Archiving Keys
The DRM automatically archives private encryption keys if archiving is configured. For instructions on setting up a key archival and recovery infrastructure, see Section 7.6, “Configuring Key Archival and
Recovery Process” .
7.4.1. Reasons to Archive Keys
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.
There are some common situations when it is necessary to recover encryption keys:
• An employee loses the private encryption key and cannot read encrypted mail messages.
• An employee is on an extended leave, and someone needs to access an encrypted document.
• An employee leaves the company, and company officials need to perform an audit that requires gaining access to the employee's encrypted mail.
7.4.2. Where the Keys Are Stored
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.
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. For details on how this process works, see Section 7.5.1, “Key Recovery Agents and Their Passwords” .
The DRM indexes stored keys by key number, owner name, and a hash of the public key, allowing for highly efficient searching. The key recovery agents have the privilege to insert, delete, and search for key records.
• When the key recovery agents search by the key ID, only the key that corresponds to that ID is returned.
• When the agents search by user name, all stored keys belonging to that owner are returned.
• When the agents search by the public key in a certificate, only the corresponding private key is returned.
7.4.3. How Key Archival Works
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. To archive the key, the DRM uses two special key pairs:
• A transport key pair and corresponding certificate.
• A storage key pair.
175
Chapter 7. Data Recovery Manager
Figure 7.1, “How the Key Archival Process Works” illustrates how the key archival process occurs when an end entity requests a certificate.
Figure 7.1. How the Key Archival Process Works
1. The client requests and generates a dual key pair.
a. The end entity, using a client which can generate dual key pairs, submits a request through the Certificate Manager enrollment form.
b. The client detects the JavaScript in the enrollment form and exports only the private encryption key, not the private signing key.
c. The Certificate Manager detects the key archival option in the request and asks the client for the private encryption key.
d. The client encrypts the private encryption key with the public key from the DRM's transport certificate embedded in the enrollment form.
2. After approving the certificate request and issuing the certificate, the Certificate Manager sends it to the DRM for storage, along with the public key). The Certificate Manager waits for verification from the DRM that the private key has been received and stored and that it corresponds to the public encryption key.
3. The DRM decrypts it with the private key. After confirming that the private encryption key corresponds to the public encryption key, the DRM encrypts it again with its public key pair of the storage key before storing it in its internal database.
4. Once the private encryption key has been successfully stored, the DRM uses the private key of its transport key pair to sign a token confirming that the key has been successfully stored; the DRM then sends the token to the Certificate Manager.
5. The Certificate Manager issues two certificates for the signing and encryption key pairs and returns them to the end entity.
176
Overview of Key Recovery
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.
7.5. Overview of Key Recovery
The DRM supports agent-initiated key recovery. Agent-initiated recovery is 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.
7.5.1. Key Recovery Agents and Their Passwords
NOTE
DRM agents are also known as key recovery agents.
Key recovery agents have the authority to retrieve private encryption keys. Any user can be designated as a recovery agent. Recovery agents need to do the following:
• Be added to the Data Recovery Manager Agents group.
• Obtain a client certificate identifying themselves. The DRM administrator needs to add that user certificate to the DRM's internal database.
• Be available to retrieve private encryption keys. It is not necessary for all key recovery agents to be available for the key recovery operation; the required number to authorize the recovery of a key is configured by the administrator. See Section 7.5.2, “Key Recovery Agent Scheme” . However, the specified number of key recovery agents must all present their certificates to authorize the recovery of the specific private key.
7.5.1.1. Interface for the Key Recovery Process
With the key recovery form provided in the DRM agent services page, key recovery agents can collectively authorize and retrieve private encryption keys and associated certificates in a PKCS #12 package, which can then be imported into the client.
The DRM agent's certificate is required to access the key recovery form. For information on DRM agents, see Section 17.1.2.3, “Agents” .
7.5.1.2. Key Recovery Authorization and How it Works
DRM agents can authorize key recovery. This is explained in more detail in the Certificate System
Agent's Guide . 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.
177
Chapter 7. Data Recovery Manager
The DRM informs the agent who initiated the key recovery process of the status of the authorizations.
NOTE
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.
WARNING
The PKCS #12 package contains the private key. To minimize the risk of key compromise, the recovery agent must use a secure method to deliver the PKCS #12 package and password to the key recipient. The agent should use a good password to encrypt the
PKCS #12 package and set up an appropriate delivery mechanism.
7.5.2. Key Recovery Agent Scheme
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.
These parameters set in the CS.cfg
configuration file determine which group of users and how many users recover keys: kra.noOfRequiredRecoveryAgents=1 kra.recoveryAgentGroup=Data Recovery Manager Agents
This is the default key recovery agent scheme.
Editing these two parameters is all that is necessary to create a new scheme for the number of required key recovery agents for a DRM and the agent group allowed to perform key recovery.
7.6. Configuring Key Archival and Recovery Process
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.
7.6.1. Setting up Key Archival
To set up key archival, do the following:
1. Connect the Certificate Manager and the DRM.
178
Setting up Key Recovery
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 17.3, “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.
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-rhpki-ca ca.connector.KRA.port=10443 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
7.6.2. Setting up Key Recovery
The DRM supports agent-initiated key recovery, in which private encryption keys are recovered by designated key recovery agents. To set up agent-initiated key recovery, do the following:
1. Set the number of recovery managers to require to approve a recovery, and set the group to which these users must belong. These parameters are set in the DRM's CS.cfg
configuration file: kra.noOfRequiredRecoveryAgents=1 kra.recoveryAgentGroup=Data Recovery Manager Agents
This is the default key agent scheme, which requires a single agent from the Data Recovery
Manager Agents group to be in charge of authorizing key recovery.
2. Customize the appearance key recovery form.
179
Chapter 7. Data Recovery Manager
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.
If this form is customized, do not to delete any of the information that is vital to the functioning of the form; it is recommended that changes be restricted to the content in and appearance of the form.
7.6.3. Testing the Key Archival and Recovery Setup
To test whether a key can be successfully archived a key, do the following:
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: 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
180
Creating Data Recovery Manager Agents and Administrators 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.
7.7. Creating Data Recovery Manager Agents and
Administrators
When the subsystem is configured, there is a default user created with both administrator and agent privileges.This user can perform both administrator and agent operations and access the Console and the agent services page.
To create an additional administrator, agent, or auditor, create a user in the Certificate System instance where the user will have privileges and assign the user to the appropriate group. An agent or auditor must have a certificate stored in the subsystem's internal database. If the Console is configured for
SSL client authentication, all administrators must also a certificate.
To create a new user entry, do the following:
1. Log into the administrative console.
pkiconsole https://server.example.com:10443/kra
2. In the Configuration tab, select Users and Groups . Click Add .
3. Fill in the information in the Edit User Information dialog.
181
Chapter 7. Data Recovery Manager
Figure 7.2. Creating a New User
The group to which the user belongs determines what privileges the user has. Assign agents and administrators to the appropriate subsystem group.
4. Store the user's certificate.
a. Request and approve an SSL client certificate for the user if one has not already been generated.
b. Copy the base-64 encoded certificate to a local file or to the clipboard.
c. Select the new user entry, and click Certificates .
d. Click Import , and paste in the base-64 encoded certificate.
For more information on editing user entries and managing user certificates, see Section 17.4,
“Modifying Certificate System User Entries” .
182
Chapter 8.
Token Processing System
The Token Processing System (TPS) serves as the conduit between the Enterprise Security Client and the other subsystems (CA, TKS, DRM) in the Certificate System and is the only means for the client to communicate with the other subsystems. It provides the following functionalities for users managing their smart cards through the Enterprise Security Client:
• Working with multiple instances of a subsystem
• Formatting smart cards
• Resetting the PIN on smart card tokens
• Upgrading the applet for smart card tokens
• Enrolling smart cards through the Enterprise Security Client
• Performing LDAP authentication
• Managing the token database
• Logging token events
The TPS must be configured to work with two Certificate System subsystems: the CA, which will process all of the certificate enrollment and revocation requests initiated through the Enterprise
Security Client, and the Token Key Service, which generates a master key which is used to derive secret keys specific to each smart card, which are used to wrap (encrypt) the certificates and commands transmitted between the TPS and the client. The TPS can be optionally configured to work with a DRM instance, which will perform server-side key generation and key archival and recovery for the keys and certificates stored on the smart cards.
After the TPS is configured ( Section 2.6.3, “Configuring a TPS” ), it is operational. It is possible to further customize the TPS for specific deployments. This chapter explains how to customize the TPS instance.
NOTE
Unlike the other subsystems, the TPS does not have a Java ™ -based Console to change configuration parameters. The TPS configuration file, CS.cfg
, must be edited directly. For more information on editing the CS.cfg
file, see Section 3.6.2, “Editing the Configuration
File” .
8.1. Working with Multiple Instances of a Subsystem
The TPS must be configured to work with a specific instance of a CA and TKS subsystem. It can optionally be configured to work with a DRM subsystem. While the TPS is configured to work with a single instance of each subsystem when it is initially installed, it can work with multiple instances for one of two reasons:
• To provide fail-over support.
The TPS can be configured to communicate with multiple instances of CA, TKS, or DRM subsystems, so if one instance is unavailable, the TPS can still process user operations initiated through the Enterprise Security Client. The instances in these cases all have the same policies in effect. This is described in Section 8.1.1, “Configuring Failover Support” .
183
Chapter 8. Token Processing System
• To perform different operations under different policies.
The TPS can route its jobs to different subsystem instances when there are different types of tokens or operations. For example, enrollment requests for temporary tokens can be sent to one CA with one set of policies while enrollments for regular tokens are sent to a different CA. This is described in Section 8.1.2,
“Configuring Multiple Instances for Different Functions” .
8.1.1. Configuring Failover Support
The subsystem instance to which the TPS connects is set in the conn.
subsystem# .hostport
parameter of the CS.cfg
configuration file. For example, the CA instance is set in the following parameter: conn.ca1.hostport=aCA.example.com:9443
To configure failover support, list multiple instances in the conn.
subsystem# .hostport
parameter, separated by spaces. For example: conn.ca1.hostport=aCA.example.com:9443 bCA.example.com:9543 cCA.example.com:9643
For failover support to be properly configured, all of the subsystem instances must have the same policies and configuration; this means all of the subsystems must be clones. For example, if the TPS is configured to communicate with three CAs, the three CAs must be clones of each other. This means that the values of the other configuration parameters are the same between the instances.
The CA configuration parameters are listed in Table 8.2, “CA Connection Settings” . The TKS configuration parameters are listed in Table 8.3, “TKS Connection Settings” . The DRM configuration parameters are listed in Table 8.4, “DRM Connection Settings” .
8.1.2. Configuring Multiple Instances for Different Functions
Along with configuring multiple instances for failover support, the TPS can be configured to use multiple instances of a subsystem to perform different functions for different TPS profiles. For instance, the TPS can be configured to use CA1 to enroll temporary tokens (type userKeyTemporary ) and
CA2 to enroll regular tokens (type userKey ).
1. Open the TPS CS.cfg
file.
2. Create additional instance entries.
Each subsystem configured for the TPS has its own set of parameters, beginning with conn.
subsystem# . To configure multiple instances of a subsystem, create a new set of connection parameters, and increment the # . For example: conn.ca1.clientNickname=subsystemCert cert-rhpki-tps conn.ca1.hostport=aCA.example.com:9443 conn.ca1.keepAlive=true conn.ca1.retryConnect=3 conn.ca1.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient conn.ca1.servlet.revoke=/ca/subsystem/ca/doRevoke conn.ca1.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke conn.ca1.timeout=100 conn.ca2.clientNickname=subsystemCert cert-rhpki-tps conn.ca2.hostport=bCA.example.com:9543
184
Configuring Multiple Instances for Different Functions conn.ca2.keepAlive=true conn.ca2.retryConnect=3 conn.ca2.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient conn.ca2.servlet.revoke=/ca/subsystem/ca/doRevoke conn.ca2.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke conn.ca2.timeout=100
3. Set up the operation parameters to use the different instances to perform the different TPS functions.
The parameters for the different operations set the type of operation, the type of token profile, the subsystem type, and other parameters specific to the operation and the subsystem type.
For example, the TKS subsystem connection to use for regular enrollment operations would be as follows: op.enroll.userKey.tks.conn=tks1
The CA configuration parameters to enroll and format that kind of token are as follows: op.enroll.userKey.keyGen.encryption.ca.conn=ca1 op.enroll.userKey.keyGen.signing.ca.conn=ca2 op.enroll.userKeyTemporary.keyGen.auth.ca.conn=ca2 op.format.tokenKey.ca.conn=ca11
The CA parameters not only specify the type of token ( userKey ) but also the type of certificate
( encryption ). It would be possible in this case to use different CAs for signing and encryption certificate enrollments.
The DRM parameters also specify the types of keys being generated and archived: op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=drm1 op.enroll.tokenKey.keyGen.encryption.serverKeygen.drm.conn=drm2
The format operation parameters are listed in Table 8.10, “Format Operation Preferences” ; the reset operation parameters are listed in Table 8.9, “PIN Reset Operation Preferences” ; and the enroll operation parameters are listed in Table 8.8, “Enrollment Operation Preferences” .
4. Set the mapping parameters for the different tokenType operations. The mapping parameters help the TPS distinguish between the different types of tokens, assign the correct tokenType to the token, and direct their requests to appropriate operation handling parameters. For example: op.enroll.mapping.0.filter.appletMajorVersion=1 op.enroll.mapping.0.filter.appletMinorVersion=5 op.enroll.mapping.0.filter.tokenATR= op.enroll.mapping.0.filter.tokenCUID.end=1000 op.enroll.mapping.0.filter.tokenCUID.start=4000 op.enroll.mapping.0.filter.tokenType=userKey op.enroll.mapping.0.target.tokenType=userKey
185
Chapter 8. Token Processing System
The mapping and filter parameters are listed in Table 8.7, “Mapping and Filters” .
8.2. Formatting Smart Cards
When the TPS is contacted by a smart card for a format operation, there are several different operations the TPS can perform, depending on the status of the smart card.
• Whether an empty token should be rejected or have the required applet (card format) uploaded, so it is made usable.
• Whether a smart card with an outdated applet should be upgraded and, if so, which version of applet to upload.
• Whether a smart card with outdated keys should be updated with new symmetric keys. Keys can become outdated if the TKS had a master key changeover.
• Whether to revoke the certificates associated with the token.
For example, to configure the TPS to reject a smart card without an applet, to update a smart card with new symmetric keys, and to revoke certificates associated with the smart card, the following parameters are set: op.format.tokenKey.revokeCert=true op.format.tokenKey.update.applet.emptyToken.enable=true op.format.tokenKey.update.symmetricKeys.enable=true
The different format operations can be configured to happen automatically by setting the appropriate parameters in the CS.cfg
file. The TPS can also be configured with other options, such as requiring
LDAP authentication and setting which subsystem instances will process the formatting operations.
The parameters are listed in Table 8.10, “Format Operation Preferences” .
8.3. Resetting the Smart Card PIN
The PIN is the password which protects the certificates and keys on the smart card. The TPS can place two restrictions on the PIN: the maximum length and the minimum length. For example, to require PINs to be between 6 and 12 characters, the following parameters are set: op.pinReset.userKey.pinReset.pin.maxLen=12 op.pinReset.userKey.pinReset.pin.minLen=6
Like the formatting operation, the TPS can be configured to upload or update the applet version on the smart card, update the symmetric key, and required LDAP authentication, as well as setting which subsystem instances will process the operation. The CS.cfg
file parameters for resetting the PIN are listed in Table 8.9, “PIN Reset Operation Preferences” .
8.4. Applet Upgrade
The TPS communicates with an applet on the smart card. The smart cards can be manufactured with both a card manager applet and a vendor applet or with only the card manager applet. If the cards only have the card manager applet, the TPS can install the Certificate System applet onto the smart
186
Enrolling Smart Cards through the Enterprise Security Client card. Similarly, an old applet can be replaced with a new applet. Any keys or certificates created or managed with the old applet are destroyed.
To upgrade the applet in the TPS, put the new applet in the applet directory, and set the update.applet.enable
parameter in the CS.cfg
file to true . For example, to update the applet when enrolling a smart card of the type userKey , the parameters would be the following: op.enroll.userKey.update.applet.enable=true op.enroll.userKey.update.applet.emptyToken.enable=false op.enroll.userKey.update.applet.requiredVersion=1.3.4255CC01
op.enroll.userKey.update.applet.directory=/usr/share/rhpki/tps/applets op.enroll.userKey.update.applet.encryption=true
If a smart card only has the card manager, then the card manager capability must be enabled by editing the following parameter: op.
operation.key_type
.update.applet.emptyToken.enable=true
NOTE
If the filename set in the update.applet.requiredVersion
parameter contains any alphabetic characters, then all of these alphabetic characters must always be uppercase letters; this applies to the actual name of the file, as well as the update.applet.requiredVersion
parameter.
The TPS queries the applet version on the smart card before trying to execute any operations.
If the update feature is enabled and the applet version from the client is different from the one specified by the update.applet.requiredVersion
parameter, the TPS updates the applet automatically.
NOTE
The TPS audit log shows whether the applet update worked successfully.
The parameters to enable upgrading the applets are set in the TPS operation configurations. The parameters for upgrading the applet during a formatting operation are in Table 8.10, “Format Operation
Preferences” ; the parameters for upgrading the applet when resetting the PIN are listed in Table 8.9,
“PIN Reset Operation Preferences” ; and the parameters for upgrading the applet during an enrollment operation are in Table 8.8, “Enrollment Operation Preferences” .
8.5. Enrolling Smart Cards through the Enterprise Security
Client
There are several parameters relating to smart card certificate enrollment — such as enabling SSL and configuring symmetric key changes — which are not configured during when the TPS is first set up. The TPS is fully operational without any further customization, but setting these extra parameters allows more flexibility to using the TPS with the Enterprise Security Client.
187
Chapter 8. Token Processing System
• Section 8.5.1, “Enabling SSL in the TPS”
• Section 8.5.2, “Configuring Server-Side Key Generation and Archival of Encryption Keys”
• Section 8.5.3, “Looking at Smart Card Certificate Enrollment Profiles”
• Section 8.5.4, “Automating Encryption Key Recovery”
• Section 8.5.5, “Configuring Symmetric Key Changeover”
• Section 8.5.6, “Setting Token Types for Specified Smart Cards”
8.5.1. Enabling SSL in the TPS
By default, the TPS communicates with the Enterprise Security Client over standard HTTP. It may be desirable to protect the TPS-client communications by using HTTP over SSL (HTTPS). To enable the
TPS to communicate over SSL, so that following:
1. Open the TPS instance configuration directory.
/var/lib/rhpki-tps
2. Edit the virtual host section in the nss.conf
file with the SSL configuration. There are two parameters to add to the default virtual host configuration, ScriptAlias and DocumentRoot .
Additionally, the NSSVerifyClient parameter is reset to none and the port numbers should be reset to the TPS secure port. For example:
Listen 0.0.0.0: 7890
<VirtualHost _default_: 7890 >
ScriptAlias /cgi-bin/ "/var/lib/rhpki-tps/cgi-bin/"
DocumentRoot "/var/lib/rhpki-tps/docroot"
ErrorLog /var/lib/rhpki-tps/logs/error1_log
TransferLog /var/lib/rhpki-tps/logs/access1_log
NSSEngine on
NSSCipherSuite
-des,-desede3,-rc2,-rc2export,-rc4,-rc4export,+rsa_3des_sha,
-rsa_des_56_sha,+rsa_des_sha,-rsa_null_md5,-rsa_null_sha,
-rsa_rc2_40_md5,+rsa_rc4_128_md5,-rsa_rc4_128_sha,-rsa_rc4_40_md5,
-rsa_rc4_56_sha,-fortezza,-fortezza_rc4_128_sha,-fortezza_null,
-fips_des_sha,+fips_3des_sha,-rsa_aes_128_sha,-rsa_aes_256_sha,
+ecdhe_ecdsa_aes_256_sha
NSSProtocol SSLv3,TLSv1
NSSNickname "Server-Cert cert-rhpki-tps"
NSSCertificateDatabase /var/lib/rhpki-tps/alias
NSSVerifyClient none
<Files ~ "\.(cgi|shtml|phtml|php3?)$">
NSSOptions +StdEnvVars
</Files>
<Directory "/cgi-bin">
NSSOptions +StdEnvVars
</Directory>
188
Configuring Server-Side Key Generation and Archival of Encryption Keys
</VirtualHost>
3. Restart the TPS instance.
/etc/init.d/rhpki-tps restart
4. The Enterprise Security Client needs to be configured to communicate with the TPS over SSL; this is done by setting the Phone Home URL , which is the default URL the Enterprise Security Client uses to connect to the TPS.
Resetting the Enterprise Security Client's Phone Home URL is described in more detail in
Managing Smart Cards with the Enterprise Security Client .
a. Open the Enterprise Security Client.
/usr/lib/esc-1.0.1/esc b. Insert a new, blank token into the machine.
Blank tokens are unformatted, so they do not have an existing Phone Home URL, and the URL must be set manually. Formatted tokens (and tokens can be formatted by the manufacturer or by your IT department) already have the URL set, and thus do not prompt to set the Phone Home URL.
c. Fill in the new TPS URL with the SSL port information. For example: http s ://server.example.com: 7890 /cgi-bin/home/index.cgi
8.5.2. Configuring Server-Side Key Generation and Archival of
Encryption Keys
The global platform environment prevents removing private keys from the smart card. For encryption keys, it is often necessary to back up the key material for later recovery, which means the keys should be generated outside the smart card and then imported. The keys are generated in the DRM subsystem, where the keys can also be archived. The TPS, TKS, and DRM must all be configured to support server-side generation and archival for encryption keys.
To configure server-side key generation for tokens enrolled through the token management system:
1. Add the TPS to the DRM as a key recovery agent.
2. Import the DRM transport key into the TKS.
3. Configure the TPS to generate and archive keys.
8.5.2.1. Step 1: Adding the TPS as a DRM Recovery Agent
1. Open the DRM Console.
2. In the Configuration tab, select Users and Groups .
3. In the Users tab, click Add , and create the new user; give this user a name such as TPS
Recovery Agent . Add this user to the Data Recovery Manager Agents group.
189
Chapter 8. Token Processing System
4. Select the TPS user, click Certificates , and import the TPS susbsystem certificate.
8.5.2.2. Step 2: Importing the DRM Transport Key into the TKS
Several different keys are used to encrypt the communications between the TKS, TPS, DRM, and token, and all of these certificates and keys are secured, at some point, by the DRM's transport key.
The DRM creates a transport certificate which works with the TKS to provide a secure way to deliver the generated keys to the token. The server transport key must be imported into the TKS certificate database in order to establish secure communication between the DRM and TKS through the TPS.
Additionally, the TKS can derive a key encryption key (KEK) which is only known by the token and the TKS and never leaves either the TKS or the token without proper encryption. This key has to be secured.
The TKS also generates a session key for the DRM to use to transport the server-generated private key securely back to the token.
The server transport key delivers the session key in two different forms to the TPS:
• The session key wrapped with server transport key which the DRM uses to wrap the generated private key for token
• The session key wrapped with token's KEK which the token uses to unwrap the private key generated on DRM
The TPS then forwards the session key to the DRM, wrapped with the KEK and the server transport key, along with the server-side key generation request.
To import the DRM transport key into the TKS certificate database:
1. Retrieve the DRM transport certificate from the issuing CA, and save it to file.
2. Import the transport certificate into the TKS security databases in the /var/lib/ instance_ID / alias/ directory. In the TKS Console, click Subsystem Keys and Certificates in the left navigation panel. In the Local Certificates tab, click Add , and paste in the certificate information.
Alternatively, use the certutil to import the certificate.
certutil -d . -P cert-db-prefix -A -n DRM Transport -t ,, -a -i certfilename
3. Stop the TKS.
/etc/init.d/ instance_ID stop
4. Edit the CS.cfg
file by adding the DRM transport certificate information to the following parameter: tks.drm_transport_cert_nickname=DRM Transport
5. Restart the TKS.
/etc/init.d/ instance_ID restart
190
Looking at Smart Card Certificate Enrollment Profiles
8.5.2.3. Step 3: Configuring the TPS to Generate and Archive Keys
1. Stop the TPS.
/etc/init.d/ instance_ID stop
2. Edit the following parameters in the TPS CS.cfg
file to use the appropriate DRM connection information:
conn.drm.totalConns=1
conn.drm1.hostport= DRM_HOST:DRM_SSLPORT
conn.drm1.clientNickname=Server-Cert
conn.drm1.servlet.GenerateKeyPair=/kra/GenerateKeyPair
conn.drm1.servlet.TokenKeyRecovery=/kra/TokenKeyRecovery
conn.drm1.retryConnect=3
conn.drm1.SSLOn=true
conn.drm1.keepAlive=false
3. Also edit the smart card profiles in the TPS CS.cfg
file.
The TPS CS.cfg
file has a section defining each type of smart card profile to maintain. In the default configuration, the userKey is defined under the op.enroll.userKey
subsection. The keyGen subsection of the userKey profile defines each type of key/certificate pair allowed for that type of smart card. In the default configuration, one of the key/certificate pairs is encryption . Set the following parameters to enable server-side key generation and to archive keys: op.enroll.userKey.keyGen.encryption.serverKeygen.enable=true op.enroll.userKey.keyGen.encryption.serverKeygen.drm.conn=drm1 op.enroll.userKey.keyGen.encryption.serverKeygen.archive=true op.enroll.userKey.keyGen.encryption.serverKeygen.encryptPrivKey=true
4. Restart the TPS subsystem.
/etc/init.d/ instance_ID restart
8.5.3. Looking at Smart Card Certificate Enrollment Profiles
The CA subsystem has four default smart card enrollment profiles which the TPS is configured, by default, to use:
• caTokenUserEncryptionKeyEnrollment.cfg
• caTokenUserSigningKeyEnrollment.cfg
• caTempTokenUserEncryptionKeyEnrollment.cfg
• caTempTokenUserSigningKeyEnrollment.cfg
The profile configuration files are in the /var/lib/ instance_ID /profiles/ca/ directory.
Administrators have the ability to customize these profiles. 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:
191
Chapter 8. Token Processing System 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.
8.5.4. Automating Encryption Key Recovery
The Certificate System allows for a semi-automated recovery if a user loses, destroys, or misplaces a token. The TPS automatically recovers the appropriate encryption keys and certificates for a permanently or temporarily lost token, depending on the circumstances of the token loss. To prevent misuse of the recovery feature, the TPS requires that a user must have a single active token.
When a user loses a token, the user must first get a replacement token. If a new enrollment is attempted with this new token, the TPS blocks the enrollment since the user already has an active token.
The token status in the database must be changed to lost . This action is performed through the TPS agent services page. The TPS agent, after affirmatively identifying the user, can search for the user's
ID in the Search tokens link. The TPS agent select the active token and update the status, with the appropriate reason to recover the key.
• This token has been physically damaged.
Used if the token is known to be destroyed.
• This token has been permanently lost.
Used if the token is lost or stolen, so the key is compromised.
The certificates on the token are revoked
• This token has been temporarily lost.
Used if the token is mislaid. The certificates on the token are revoked
There are two different schemes for recovery: GenerateNewKey , to create a new key and certificate, and RecoverLast , to recover the last encryption key and associated certificate.
The user can enroll for a replacement token. It is preferred that signing keys be generated on the smart card and not archived so that if the smart card is lost, new signing keys and certificates must be regenerated on the token, and temporary certificates created. The definition for which keys should be regenerated and which keys should be recovered is set in the following TPS CS.cfg
parameters:
• For damaged tokens: op.enroll.userKey.keyGen.recovery.destroyed.keyType.num=2 op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.0=signing op.enroll.userKey.keyGen.recovery.destroyed.keyType.value.1=encryption op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert.reason=0 op.enroll.userKey.keyGen.signing.recovery.destroyed.scheme=GenerateNewKey
192
Automating Encryption Key Recovery op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert=false op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0 op.enroll.userKey.keyGen.encryption.recovery.destroyed.scheme=RecoverLast
• For tokens which are permanently lost: op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.num=2 op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.value.0=signing op.enroll.userKey.keyGen.recovery.keyCompromise.keyType.value.1=encryption op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert.reason=1 op.enroll.userKey.keyGen.signing.recovery.keyCompromise.scheme=GenerateNewKey op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1 op.enroll.soKey.keyGen.encryption.recovery.keyCompromise.scheme=GenerateNewKey
• For tokens which are temporarily lost: op.enroll.userKey.keyGen.recovery.onHold.keyType.num=2 op.enroll.userKey.keyGen.recovery.onHold.keyType.value.0=signing op.enroll.userKey.keyGen.recovery.onHold.keyType.value.1=encryption op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert.reason=6 op.enroll.userKey.keyGen.signing.recovery.onHold.scheme=GenerateNewKey op.enroll.soKey.keyGen.encryption.recovery.onHold.revokeCert=true op.enroll.soKey.keyGen.encryption.recovery.onHold.revokeCert.reason=6 op.enroll.soKey.keyGen.encryption.recovery.onHold.scheme=GenerateNewKey
Set revokeCert=true to revoke certificates if a token's certificates are replaced after being lost.
for the signing key op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.destroyed.revokeCert.reason=0 op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.keyCompromise.revokeCert.reason=1 op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert=true op.enroll.userKey.keyGen.signing.recovery.onHold.revokeCert.reason=6 op.enroll.userKey.keyGen.signing.revokeCert=true for the encryption key op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert=false op.enroll.userKey.keyGen.encryption.recovery.destroyed.revokeCert.reason=0 op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert=true op.enroll.userKey.keyGen.encryption.recovery.keyCompromise.revokeCert.reason=1 op.enroll.userKey.keyGen.encryption.recovery.onHold.revokeCert=true op.enroll.userKey.keyGen.encryption.recovery.onHold.revokeCert.reason=6 op.enroll.userKey.keyGen.encryption.revokeCert=true
193
Chapter 8. Token Processing System
8.5.4.1. Replacing Lost or Stolen Smart Cards
If the smart card loss is temporary, the user can be enrolled for a temporary replacement. The profile for the replacement smart card is defined in the userKeyTemporary parameter in the TPS CS.cfg
file. The certificate used through this profile is valid for seven days by default.
8.5.4.1.1. If the Smart Card Is Found
If the user locates the original token, he must return to the TPS agent to reactivate the original token by changing the status to This temporarily lost token has been found . Changing the status of the original token to active also takes the certificates off hold; when this is done, the status of the temporary token is automatically updated and its certificates revoked.
8.5.4.1.2. If the Smart Card Is Not Found
If the user cannot locate the original token, the TPS agent must change the status of the original token to This temporarily lost token cannot be found (becomes permanently lost) .
The certificates on the original token are revoked. The status of the temporary token is updated to inactive and its certificates revoked. The user is then permitted to enroll for a permanent token.
8.5.4.1.3. Terminating a Smart Card
If the user of the token has been terminated or has left the company, then the administrator can disassociate the user from the token. The TPS agent can change the status to This token has been terminated , which terminates the certificates and keys on the token and breaks the association between the token and the user. The physical token can still be formated and reused afterward, but this change of status will mark a record of the termination event.
8.5.5. Configuring Symmetric Key Changeover
When global platform-compliant smart cards are made, the manufacturer burns a set of symmetric keys onto the token. The smart card user shares a master symmetric key with the manufacturer. The smart card TKS is configured to use these symmetric keys. However, during enrollment, it is desirable to replace these symmetric keys with a set that is not shared by the manufacturer to restrict the set of entities that can manipulate the token.
NOTE
Changing the symmetric keys can render the smart cards unusable if the master key is lost. Use key changeover in controlled conditions, and be aware of the implications of erasing a TKS instance. This section contains information on returning the keys to the factory state.
The TKS and TPS are configured for key changeover by enabling the appropriate parameters in the
CS.cfg
file for both the enroll and format operations.
1. Stop the TKS instance. For example:
/etc/init.d/rhpki-tks stop
2. On the TKS instance, generate new keys to use for token-client communications.
a. Open the TKS instance alias/ directory.
194
Configuring Symmetric Key Changeover cd /var/lib/ instance_ID /alias/ b. Generate the new master key. For example: tksTool -M -n new_master -d /var/lib/rhpki-tks/alias -h token_name
Generating a new master key on the TKS is described in more detail in Section 9.2, “Using Master
Keys” .
3. Open the TKS's configuration file.
vi /etc/rhpki-tks/CS.cfg
4. Map the new master key's identifier, 02 , to its PKCS #11 object nickname in the TKS's CS.cfg
file by adding the tks.mk_mappings.#02#01 and tks.defKeySet.mk_mappings.#02#01 parameters.
tks.mk_mappings.#02#01= token_name:nickname tks.defKeySet.mk_mappings.#02#01= token_name:nickname
The values for the token_name and nickname follow the parameters outlined in Table 8.13, “TKS
Configuration Parameters for Key Update” .
Mapping master keys in the TKS configuration is described in more detail in Section 9.3,
“Configuring the TKS to Associate the Master Key with Its Version” .
5. Start the TKS instance.
/etc/init.d/rhpki-tks start
6. Stop the TPS instance to edit its configuration.
/etc/init.d/rhpki-tps stop
7. Edit the TPS's configuration file.
vi /etc/rhpki-tps/CS.cfg
8. Change the symmetricKeys.enable
and requiredVersion parameters to use the newlygenerated master keys on the TKS. For example:
op.
operation_type .update.
symmetricKeys.enable=true
op.
operation_type .userKey.update.symmetricKeys.
requiredVersion=2
• For the enroll operation, the lines begin with op.enroll
.
• For the format operation, the lines begin with op.format
.
195
Chapter 8. Token Processing System requiredVersion is the numeric key set identifier required for the operation to proceed. If the smart card does not have the key set specified by the requiredVersion parameter, key changeover will occur, and the operation process continues.
The TPS audit log shows whether the key changeover worked successfully.
While testing this feature, change an Axalto Web Store smart card back to the original static 4041..
key set. To do this, change the requiredVersion parameter back to 1 and set a new format. Do this before removing a TKS instance, or else the smart card cannot be managed.
8.5.6. Setting Token Types for Specified Smart Cards
The TPS can be configured to use specific token profiles based on the smart card ATR or a range of serial numbers for the smart cards. This is useful to manage two types of smart card profiles in a single deployment to determine the smart card profile based on physical distribution of those cards, rather than some software process change. The TPS can configure a mapping that specifies the types of tokens, ATRs, and range of serial numbers (CUID).
Each type of operation contains a parameter mapping.order
containing mapping IDs.
NOTE
If the mapping.order
parameter contains more than one mapping ID, then each mapping ID is processed in sequential order until a target is determined or an error is returned. If the mapping.order
parameter is missing, then the code returns an error.
Each mapping ID references a series of parameters called filters . Each filter may contain a specific value for the request to be tested against. Empty or missing filters act as a wildcard and allow the request to contain any value and are thus inherently true. If the request passes all filters, the the specified target token profile is used.
For an example of using token types, see Example 8.1, “Configuring Two Different Token Types” .
For the configuration file parameters used to set up mapping and filters, see Table 8.7, “Mapping and
Filters” .
The TPS can be configured to distinguish between two different sets of tokens by their CUIDs. These sets have the following settings:
• The development team has 100 tokens and the token set CUIDs from 1000-0000-0000-0000 to
1000-0000-0000-0100.
• The QA team that has 100 tokens and the token set CUIDs from 2000-0000-0000-0000 to
2000-0000-0000-0100.
• The development team uses the LDAP server ldap-dev, and the QA team uses the LDAP server ldap-qa for authentication.
Configuring the format operation in the TPS involves the following changes to the TPS configuration file, CS.cfg
.
##########################################################################
# Create two mappings
########################################################################## op.format.mapping.0.filter.tokenCUID.start=1000000000000000
196
Setting Token Types for Specified Smart Cards op.format.mapping.0.filter.tokenCUID.end=1000000000000100
########################################################################## op.format.mapping.1.filter.tokenCUID.start=2000000000000000 op.format.mapping.1.filter.tokenCUID.end=20000000000001000
##########################################################################
# Profile for DevKey
########################################################################## op.format.devKey.update.applet.emptyToken.enable=true op.format.devKey.update.applet.requiredVersion=1.3.427BDDB8
op.format.devKey.update.applet.directory=/usr/share/rhpki/tps/applets op.format.devKey.update.applet.encryption=true op.format.devKey.update.symmetricKeys.enable=false op.format.devKey.update.symmetricKeys.requiredVersion=1 op.format.devKey.revokeCert=true op.format.devKey.ca.conn=ca1 op.format.devKey.loginRequest.enable=true op.format.devKey.tks.conn=tks1 op.format.devKey.auth.id=ldap-dev op.format.devKey.auth.enable=true
##########################################################################
# Profile for QAKey
########################################################################## op.format.qaKey.update.applet.emptyToken.enable=true op.format.qaKey.update.applet.requiredVersion=1.3.427BDDB8
op.format.qaKey.update.applet.directory=/usr/share/tps/applets op.format.qaKey.update.applet.encryption=true op.format.qaKey.update.symmetricKeys.enable=false op.format.qaKey.update.symmetricKeys.requiredVersion=1 op.format.qaKey.revokeCert=true op.format.qaKey.ca.conn=ca1 op.format.qaKey.loginRequest.enable=true op.format.qaKey.tks.conn=tks1 op.format.qaKey.auth.id=ldap-qa op.format.qaKey.auth.enable=true
##########################################################################
# LDAP Connection settings for devKey
########################################################################## auth.instance.0.type=LDAP_Authentication auth.instance.0.libraryName=/usr/lib/libldapauth.so
auth.instance.0.libraryFactory=GetAuthentication auth.instance.0.authId=ldap-dev auth.instance.0.hostport=ldap-dev.example.com:1111 auth.instance.0.SSLOn=false auth.instance.0.retries=1 auth.instance.0.retryConnect=3 auth.instance.0.baseDN=o=dev auth.instance.0.ui.title.en=LDAP Authentication auth.instance.0.ui.description.en=This authenticates user against the DEV
LDAP directory.
auth.instance.0.ui.id.UID.name.en=LDAP User ID auth.instance.0.ui.id.PASSWORD.name.en=LDAP Password auth.instance.0.ui.id.UID.description.en=DEV LDAP User ID auth.instance.0.ui.id.PASSWORD.description.en=DEV LDAP Password
##########################################################################
# LDAP Connection settings for qaKey
########################################################################## auth.instance.1.type=LDAP_Authentication auth.instance.1.libraryName=/usr/lib/libldapauth.so
auth.instance.1.libraryFactory=GetAuthentication auth.instance.1.authId=ldap-qa auth.instance.1.hostport=ldap-qa.example.com:2222 auth.instance.1.SSLOn=false auth.instance.1.retries=1 auth.instance.1.retryConnect=3
197
Chapter 8. Token Processing System auth.instance.1.baseDN=o=qa auth.instance.1.ui.title.en=LDAP Authentication auth.instance.1.ui.description.en=This authenticates user against the QA
LDAP directory.
auth.instance.1.ui.id.UID.name.en=LDAP User ID auth.instance.1.ui.id.PASSWORD.name.en=LDAP Password auth.instance.1.ui.id.UID.description.en=QA LDAP User ID auth.instance.1.ui.id.PASSWORD.description.en=QA LDAP Password
##########################################################################
• The two format operation profiles are devKey and qaKey .
• The two mapping order 0 refers to the devKey and 1 refers to the qaKey .
• The two authentication instances 0 and 1 correspond to ldap-dev and ldap-qa , respectively.
The format operation is very simple, with the user inserting a token and clicking a button, then the rest of the process occurring in the backend:
1. The user inserts the token. The token is recognized by its CUID in the Enterprise Security Client.
2. The user selects the token and clicks Format .
3. The Enterprise Security Client prompts for LDAP authentication.
4. The format operation completes.
When the token is selected in the Enterprise Security Client, the Enterprise Security Client sends in the applet version, CUID, ATR, and other information about the token to the TPS server. TPS server checks the op.format.mapping..
section in the CS.cfg
file and figures out which tokenType to use for the token, either devKey or qaKey . It then uses the appropriate op.format...
section to perform LDAP authentication to the appropriate server and to the corresponding TKS for generating session keys.
Example 8.1. Configuring Two Different Token Types
8.6. Configuring LDAP Authentication
The TPS can be configured to require the user to authenticate to an LDAP directory when a smart card operation request is received. There are three parameters for this which can be set for the format, reset PIN, or enrollment operation: op.
operation.key_type
.auth.enable
op.
operation.key_type
.auth.id
op.
operation.key_type
.loginRequest.enable
Setting these parameters set whether LDAP authentication is required, the LDAP directory to use for the authentication, and to send the login request to the smart card.
NOTE
The user must have an existing LDAP user entry in the LDAP server instance specified in the TPS's CS.cfg
file in order to complete the operation.
198
Token Database
Like configuring multiple subsystem instances, there can be multiple LDAP directories configured.
Additional LDAP parameters, such as the base DN under which to search for entries and the Directory
Server hostname and port, are listed in Table 8.5, “LDAP Authentication” .
8.7. Token Database
The TPS uses an LDAP database called the token database or tokenDB is used to keep specific information for each registered token. It also associates tokens with certificates and users. The token database is accessible through the Administrator tab of the TPS HTML services page/ The agent/admin services page is used to check token status, edit token information, and view token information, like certificates and past operations. For information on managing the token database, see the Certificate System Agent's Guide .
The parameters used to configure the token database in the TPS are listed in Table 8.11, “Token
Database Preferences” .
8.8. Configuring TPS Logging
Log files are configured by changing the relevant lines in the CS.cfg file: logging.[audit|error|debug].enable=[true|false] logging.[audit|error|debug]=/var/logs/[filename] logging.[audit|error|debug].level=[level number]
Log level 0 is least verbose; 10 is most verbose. For example:
[2005-04-29 13:47:08] b65b9828 Upgradeop='applet_upgrade' app_ver='1.2.416DA155'
new_app_ver='1.3.42659461'
[2005-04-29 13:47:08] b65b9828 Formatstatus='success' app_ver='1.3.42659461'
key_ver='0' cuid='40900062FF02000065C5' msn='FFFFFFFF' uid=''
time='45389 msec'
[2005-04-29 15:56:06] b65b9828 Enrollmentstatus='success' app_ver='1.3.42659461'
key_ver='0101' cuid='40900062FF020000649D' msn='FFFFFFFF'
uid='Steve Parkinson' time='21058 msec' key_ver gives the key set version ID. A key version of 0101 is mapped to the TKS key version identifier #01#01. cuid gives the card unique identifier, the unique serial number of the smart card.
app_ver gives the applet version number. time gives the elapsed time of the operation.
8.8.1. Thread Correlation
In this example, b65b9828 is the thread ID number. All interactions performed with a particular smart card are done on a single thread, so the operations all have the same thread ID. In the case where
TPS is interacting with multiple smart cards simultaneously, log messages pertaining to the smart card operations are interleaved. The thread ID can be used to correlate messages for a single smart card.
8.9. TPS Configuration Parameters
This section outlines all the TPS configuration parameters, their descriptions and valid values that are typically used for smart card certificate enrollment, key archivals, key recovery, formatting smart cards, and PIN reset operations.
199
Chapter 8. Token Processing System
Parameter logging.debug.enable
logging.debug.filename
logging.debug.level
logging.audit.enable
logging.audit.filename
logging.audit.level
logging.error.enable
logging.error.filename
logging.error.level
Description
Enables debug logging. The valid values are true|false .
The full path to the debug log file name. For example, /tmp/tps-debug.log
.
The debug log levels. The levels range from 0 to
10.
• 0 - No logging.
• 4 - LL_PER_SERVER. Messages that happen only during startup or shutdown.
• 6 - LL_PER_CONNECTION. Messages that happen per connection.
• 8 - LL_PER_PDU. Messages that happen for every transaction.
• 9 - LL_ALL_DATA_IN_PDU. Dumps all data in the PDU.
• 10 - All logging.
Enables audit logging. The valid values are true|false .
The full path to the audit log file name. For example, /tmp/tps-audit.log
The audit log level. The levels range from 0 to
10.
• 0 - No logging.
• 4 - LL_PER_SERVER. Messages that happen only during startup or shutdown.
• 6 - LL_PER_CONNECTION. Messages that happen per connection.
• 8 - LL_PER_PDU. Messages that happen for every transaction.
• 9 - LL_ALL_DATA_IN_PDU. Dumps all data in the PDU.
• 10 - All logging.
Enables error logging. The valid values are true|false .
The full path to the error log file name. For example, /tmp/tps-error.log
.
The error log level. The levels range from 0 to
10.
200
Parameter failover.pod.enable
Table 8.1. Logging
Parameter conn.ca
n .hostport
conn.ca
n .clientNickname
conn.ca
n .servlet.enrollment
conn.ca1.servlet.revoke
conn.ca1.servlet.unrevoke
conn.ca
n .retryConnect
conn.ca
n .timeout
TPS Configuration Parameters
Description
• 0 - No logging.
• 4 - LL_PER_SERVER. Messages that happen only during startup or shutdown.
• 6 - LL_PER_CONNECTION. Messages that happen per connection.
• 8 - LL_PER_PDU. Messages that happen for every transaction.
• 9 - LL_ALL_DATA_IN_PDU. Dumps all data in the PDU.
• 10 - All logging.
Specifies whether to use a pod-type failover mechanism. The valid values are true| false . If there are two CA connections, two
TKS connections, and two DRM connections configured from the TPS, when pod-type failover is enabled, if the TPS fails to connect to the first
CA, for the next enrollment it will use the second pod, meaning it will connect to the second CA,
DRM, and TKS host and port.
Description
The Certificate Authority hostname and port number. The format is hostname:port . This should be the CA's end-entity SSL port.
The client certificate nickname. This certificate is used by the TPS when connecting to the CA.
This client certificate should be trusted by the
CA, and the client should be a configured CA agent.
The servlet that performs profile-based certificate enrollment. The value must be /ca/ee/ca/ profileSubmitSSLClient .
The servlet that performs certificate revocation; for example, /ca/subsystem/ca/doRevoke .
The servlet that unrevokes a certificate; for example, /ca/subsystem/ca/doUnrevoke .
The number of times the TPS tries to reconnect to the CA if the connection fails. The valid values are integers. For example, 3 .
The number of seconds before the TPS times out after failing to connect to the CA. For example,
30 .
201
Chapter 8. Token Processing System
Parameter conn.ca
n .SSLOn
conn.ca
n .keepAlive
Table 8.2. CA Connection Settings
Parameter conn.tks
n .hostport
conn.tks
n .clientNickname
conn.tks
n .retryConnect
conn.tks
n .SSLOn
conn.tks
n .keepAlive
conn.tks
n .serverKeygen
conn.tks1.servlet.computeSessionKey
conn.tks1.servlet.createKeySetData
conn.tks1.servlet.encryptData
Table 8.3. TKS Connection Settings
Parameter conn.drm
n .hostport
conn.drm
n .clientNickname
Description
Sets if SSL needs to be turned on to connect to the CA. This value must be true .
Sets whether to keep the connection to the CA alive or terminate it after every operation. The valid values are true|false .
Description
The TKS subsystem hostname and port number.
The format is hostname:port . This should be the
TKS's agent port.
The client certificate nickname to use. This certificate is used by the TPS when connecting to the TKS. This client certificate should be trusted by the TKS, and the client should be a configured
TKS agent.
The number of times the TPS tries to reconnect to the TKS after a connection attempt fails. The valid values are integers. For example, 3 .
Sets whether SSL needs to be turned on for the connection to the TKS. This value must be true .
Sets whether to keep the connection to the TKS alive or terminate it after every operation. The valid values are true|false .
Sets where key generation happens. When set to true , key generation happens on the server.
When set to false , key generation happens on the client, or token.
The servlet to compute session key for the secure channel; for example, /tks/agent/ tks/computeSessionKey .
The servlet to create key set data; for example,
/tks/agent/tks/createKeySetData . This servlet is used for key upgrade.
The servlet which encrypts data with token's
KEK key; for example, /tks/agent/tks/ encryptData .
Description
The DRM subsystem hostname and port number.
The format is hostname:port This should be the
DRM agent port.
The client certificate nickname to use. This certificate is used by TPS when connecting to the
DRM. This client certificate should be trusted by
202
Parameter conn.drm
n .retryConnect
conn.drm
n .SSLOn
conn.drm
n .keepAlive
conn.drm1.servlet.GenerateKeyPair
conn.drm1.servlet.TokenKeyRecovery
Table 8.4. DRM Connection Settings
Parameter auth.instance.
n .attributes
auth.instance.
auth.instance.
auth.instance.
auth.instance.
n n n n
.type
.libraryName
.libraryFactory
.authId
auth.instance.
n .hostport
auth.instance.
n .SSLOn
auth.instance.
n .retries
TPS Configuration Parameters
Description the DRM, and the client should be a configured
DRM agent.
The number of times the TPS tries to reconnect to the DRM after a connection attempt fails. The valid values are integers. For example, 3 .
Sets whether SSL needs to be turned on for the connection to the DRM. This value must be true .
Sets whether to keep the connection to the DRM alive or terminate it after every operation. The valid values are true|false .
The servlet for handling server-side key pair generation; for example, /kra/agent/kra/
GenerateKeyPair .
The servlet for handling smart card key recovery; for example, /kra/agent/kra/
TokenKeyRecovery .
Description
The LDAP attributes of the user entry to be retrieved, if attributes are present, such as auth.instance.0.attributes=mail,cn,uid .
Once retrieved, these attributes can be used in other parameter entries as $auth.
attr name $ . For example, op.enroll.userKey.keyGen.tokenName=
$userid$ [$auth.cn$] .
The authentication type to use. This must be
LDAP_Authentication .
The library to use for LDAP authentication.
Provide the full path to the library. The filename must be libldapauth.so
.
The function name to use for
LDAP authentication. This must be
GetAuthentication .
Specifies this authentication instance ID to use to define operations. For example, ldap1 .
The LDAP hostname and port number. The format is ldap-hostname:ldap-port .
Sets whether SSL should be turned on. The valid values are true|false .
The number of times authentication is tried after failure. The valid values are integers. For example, 1 .
203
Chapter 8. Token Processing System
Parameter auth.instance.
n .retryConnect
Description
The number of times the TPS tries to reconnect to the LDAP server after a connection attempt fails. The valid values are integers. For example,
3 .
auth.instance.
n .baseDN
The base DN from which to start the LDAP search. For example, o=example.com
.
auth.instance.
n .ui.title.en
The title of the LDAP authentication plug-in. For example, LDAP Authentication .
auth.instance.
n .ui.description.en
The description of the LDAP authentication activity. For example, This authenticates the user against the LDAP dev directory .
auth.instance.
n .ui.id.UID.name.en
The UID parameter name. For example, LDAP
User ID .
auth.instance.
n .ui.id.PASSWORD.name.en
The password parameter name. For example,
LDAP Password .
auth.instance.
n .ui.id.UID.description.en
The description of the UID parameter.
auth.instance.
n .ui.id.PASSWORD.description.en
The description of the password parameter.
Table 8.5. LDAP Authentication
Parameter Description channel.encryption
Sets whether the data being transmitted between the TPS and the token is to be encrypted. The valid values are true|false .
Table 8.6. Encrypted Channels Between the TPS and Tokens
Operation can be enroll, PIN reset, or format. n is an integer.
Parameter op.
Operation .mapping.order
op.
op.
Operation
Operation
.mapping.
.mapping.
n n
.filter.tokenType
.filter.tokenATR
Description
The order of the mappings. The format is n,n,n .
For example, 0,1,2 . These mapping IDs must be defined in op.Operation.mapping.
n parameters, where n is one of the mapping IDs specified in the order.
The filter based on the tokenType sent by the Enterprise Security Client. This is the expected tokenType that TPS will receive from the Enterprise Security Client. For example, userKey . The target tokenType will be matched if the tokenType sent by the
Enterprise Security Client also matches.
The filter based on the ATR sent by the
Enterprise Security Client. This is the expected
ATR that the TPS will receive from the Enterprise
Security Client. For example, 1234 . The target tokenType will be matched if the ATR of the token and the ATR mentioned here matches.
204
TPS Configuration Parameters
Parameter op.
Operation .mapping.
n .filter.tokenCUID.start
Description
The filter based on the CUID range. The target tokenType will be matched if the CUID falls within the start-end range.
op.
Operation .mapping.
n .filter.tokenCUID.end
The filter based on the CUID range. The target tokenType will be matched if the CUID falls within the start-end range.
op.
Operation .mapping.
n .filter.appletMajorVersion The filter based on the applet version. This filter can be empty or an applet major version specified by the client. If both the major and minor versions are both zero, this indicates there is no applet on the token.
op.
Operation .mapping.
n .filter.appletMinorVersion The filter based on the minor applet version. For an applet file named 1.3.423FFAZ.ijc
, 3 is the minor version. The target tokenType will be matched if the applet's minor version sent by the Enterprise Security Client matches this parameter.
op.
Operation .mapping.
n .target.tokenType
Set this parameter to the tokenType to select for this mapping. For example, userKey .
Table 8.7. Mapping and Filters
Parameter Description op.enroll.
tokenType .temporaryToken.tokenType
The tokenType to use for temporary tokens.
tokenType typically refers to the profile defining how many certificates should be generated, how keys should be recovered, and what format should be used.
op.enroll.
tokenType .keyGen.recovery.destroyed.keyType.num
keyTypes . The default value is 2 .
op.enroll.
tokenType .keyGen.recovery.destroyed.keyType.value.
n . The valid values are signing|encryption .
op.enroll.
tokenType .keyGen.signing.recovery.destroyed.scheme
for destroyed tokens. The default value is
GenerateNewKey . The other possible value is
RecoverLast .
op.enroll.
tokenType .keyGen.signing.recovery.destroyed.revokeCert
revoked. The valid values are true|false . The default value is true.
op.enroll.
tokenType .keyGen.signing.recovery.destroyed.revokeCert.reason
reason should be. The default value is 0 . The valid values are as follows:
• 0 - Unspecified.
• 1 - Key compromised.
• 2 - CA key compromised.
205
Chapter 8. Token Processing System
Parameter Description
• 3 - Affiliation changed.
• 4 - Certificate superseded.
• 5 - Cessation of operation.
• 6 - Certificate is on hold.
op.enroll.
tokenType .keyGen.encryption.recovery.destroyed.scheme
scheme for destroyed tokens. The default value is RecoverLast . The other possible value is
GenerateNewKey .
op.enroll.
tokenType .keyGen.encryption.recovery.destroyed.revokeCert
revoked. The valid values are true|false . The default value is true .
op.enroll.
tokenType .keyGen.encryption.recovery.destroyed.revokeCert.reason
op.enroll.
tokenType .keyGen.encryption.recovery.destroyed.revokeCert.reason
revocation reason should be. The default value is
0 . The valid values are as follows:
• 0 - Unspecified.
• 1 - Key compromised.
• 2 - CA key compromised.
• 3 - Affiliation changed.
• 4 - Certificate superseded.
• 5 - Cessation of operation.
• 6 - Certificate is on hold.
op.enroll.
tokenType .keyGen.recovery.keyCompromise.keyType.num
tokens whose keys are compromised.
op.enroll.
tokenType .keyGen.recovery.keyCompromise.keyType.value.
n . The default values are signing|encryption .
op.enroll.
tokenType .keyGen.signing.recovery.keyCompromise.scheme
for tokens whose keys are compromised. The default value is GenerateNewKey . The other possible value is RecoverLast .
op.enroll.
tokenType .keyGen.signing.recovery.keyCompromise.revokeCert
revoked if the original token's key has been comprised. The valid values are true|false .
op.enroll.
tokenType .keyGen.signing.recovery.keyCompromise.revokeCert.reason
reason should be. The default value is 0 . The valid values are as follows:
• 0 - Unspecified.
• 1 - Key compromised.
206
TPS Configuration Parameters
Parameter Description
• 2 - CA key compromised.
• 3 - Affiliation changed.
• 4 - Certificate superseded.
• 5 - Cessation of operation.
• 6 - Certificate is on hold.
op.enroll.
tokenType .keyGen.encryption.recovery.keyCompromise.scheme
for tokens whose key is compromised. The valid values include GenerateNewKey and
RecoverLast .
op.enroll.
tokenType .keyGen.encryption.recovery.keyCompromise.revokeCert
revoked if the token's key has been comprised.
The valid values are true|false .
op.enroll.
tokenType .keyGen.encryption.recovery.keyCompromise.revokeCert.reason
reason should be. The default value is 0 . The valid values are as follows:
• 0 - Unspecified.
• 1 - Key compromised.
• 2 - CA key compromised.
• 3 - Affiliation changed.
• 4 - Certificate superseded.
• 5 - Cessation of operation.
• 6 - Certificate is on hold.
op.enroll.
tokenType .keyGen.recovery.onHold.keyType.num
hold for temporary loss reasons. The valid values are integers. The default is 2 .
op.enroll.
tokenType .keyGen.recovery.onHold.keyType.value.
n . The default values are signing|encryption .
op.enroll.
tokenType .keyGen.signing.recovery.onHold.scheme
for tokens that are to be put on hold. The valid values are GenerateNewKey and
RecoverLast .
op.enroll.
tokenType .keyGen.signing.recovery.onHold.revokeCert
revoked if the token's key has been comprised.
The valid values are true|false .
op.enroll.
tokenType .keyGen.signing.recovery.onHold.revokeCert.reason
reason should be. The default value is 0 . The valid values are as follows:
• 0 - Unspecified.
207
Chapter 8. Token Processing System
Parameter Description
• 1 - Key compromised.
• 2 - CA key compromised.
• 3 - Affiliation changed.
• 4 - Certificate superseded.
• 5 - Cessation of operation.
• 6 - Certificate is on hold.
op.enroll.
tokenType .keyGen.encryption.recovery.onHold.scheme
for tokens that are to be put on hold. The valid values are GenerateNewKey and
RecoverLast .
op.enroll.
tokenType .keyGen.encryption.recovery.onHold.revokeCert
revoked if the token's key has been comprised.
The valid values are true|false .
op.enroll.
tokenType .keyGen.encryption.recovery.onHold.revokeCert.reason
reason should be. The default value is 0 . The valid values are as follows:
• 0 - Unspecified.
• 1 - Key compromised.
• 2 - CA key compromised.
• 3 - Affiliation changed.
• 4 - Certificate superseded.
• 5 - Cessation of operation.
• 6 - Certificate is on hold.
op.enroll.
tokenType .keyGen.tokenName
The name of the token to use. The TPS can substitute some special strings. For example, if using cuid , the tokenName is substituted with the CUID of the token; if using uid , the tokenName is substituted with the UID of the authenticating user.
op.enroll.
tokenType .keyGen.keyType.num
The number of keys/certificates to be generated for the profile. The values are integers. The default is 2 .
op.enroll.
tokenType .keyGen.keyType.value.
n Specifies keyType . The default values are signing|encryption .
op.enroll.
tokenType .keyGen.signing.keySize
Specifies the key size to use for key generation.
The default is 1024 .
Do not alter these values.
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.encrypt
208
TPS Configuration Parameters
Parameter Description
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.sign
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.signRecover
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.decrypt
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.derive
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.unwrap
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.wrap
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.verifyRecover
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.verify
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.sensitive
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.private
• op.enroll.
tokenType .keyGen.signing.public.keyCapabilities.token
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.encrypt
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.sign
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.signRecover
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.decrypt
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.derive
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.unwrap
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.wrap
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.verifyRecover
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.verify
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.sensitive
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.private
• op.enroll.
tokenType .keyGen.signing.private.keyCapabilities.token
op.enroll.
tokenType .keyGen.signing.label
The token label for the signing certificate. The valid values are $pretty_cuid$ , $cuid$ ,
$msn$ , $userid$ , and $profileId$ . These variables are replaced by the user-supplied information when the certificate is generated.
op.enroll.
tokenType .keyGen.signing.cuid_label
op.enroll.
tokenType .keyGen.signing.overwrite
The CUID to show in the certificate.
Specifies if the TPS should overwrite the existing signing certificate. The valid values are true| false .
209
Chapter 8. Token Processing System
Parameter Description op.enroll.
tokenType .keyGen.signing.ca.profileId
The CA profile that should be used for creating the signing certificate. The default is caTokenUserSigningKeyEnrollment .
op.enroll.
tokenType .keyGen.signing.ca.conn
The CA connection to use. The default value is ca1 .
op.enroll.
tokenType .keyGen.encryption.keySize
The key size for the encryption key. The default is 1024 .
Do not alter these values.
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.encrypt
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.sign
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.signRecover
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.decrypt
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.derive
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.unwrap
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.wrap
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.verifyRecover
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.verify
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.sensitive
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.private
• op.enroll.
tokenType .keyGen.encryption.public.keyCapabilities.token
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.encrypt
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.sign
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.signRecover
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.decrypt
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.derive
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.unwrap
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.wrap
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.verifyRecover
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.verify
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.sensitive
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.private
210
TPS Configuration Parameters
Parameter Description
• op.enroll.
tokenType .keyGen.encryption.private.keyCapabilities.token
op.enroll.
tokenType .keyGen.encryption.label
The token label for the encryption certificate.
The valid values are $pretty_cuid$ , $cuid$ ,
$msn$ , $userid$ , and $profileId$ . These variables are replaced by the user-supplied information when the certificate is generated.
op.enroll.
tokenType .keyGen.encryption.cuid_label The CUID to show in the certificate.
op.enroll.
tokenType .keyGen.encryption.overwrite Specifies if the encryption certificate on the token should be overwritten. The valid values are true|false .
op.enroll.
tokenType .keyGen.encryption.ca.profileId The CA profile to use for enrolling encryption certificates. The default value is caTokenUserEncryptionKeyEnrollment .
op.enroll.
tokenType .keyGen.encryption.ca.conn
The CA connection to use to generate encryption certs. The default value is ca1 .
op.enroll.
tokenType .update.applet.emptyToken.enable
to the token when it does not have one. The valid values are true|false .
op.enroll.
tokenType .update.applet.enable
Specifies if applet upgrade is turned on. The valid values are true|false .
op.enroll.
tokenType .update.applet.requiredVersion The version of the applet to use. It should be the filename of the applet without the .ijc
extension.
op.enroll.
tokenType .update.applet.directory
The local filesystem directory where the applets are located.
op.enroll.
tokenType .update.symmetricKeys.enable Specifies if the key changeover feature should be enabled. The valid values are true| false . When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion
.
op.enroll.
tokenType .update.symmetricKeys.requiredVersion
op.enroll.
tokenType .loginRequest.enable
Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true| false .
op.enroll.
tokenType .pinReset.enable
Specifies if the token's PIN should be reset.
The default value is true . The valid values are true|false .
op.enroll.
tokenType .pinReset.pin.minLen
op.enroll.
tokenType .pinReset.pin.maxRetries
The minimum number of characters for the PIN.
The maximum number of times PIN authentication can be attempted on the token before the key is locked. This value is set on the token when the PIN is reset.
op.enroll.
tokenType .pinReset.pin.maxLen
The maximum number of characters for the PIN.
211
Chapter 8. Token Processing System
Parameter op.enroll.
tokenType .tks.conn
op.enroll.
tokenType .auth.id
op.enroll.
tokenType .auth.enable
Table 8.8. Enrollment Operation Preferences
Description
The TKS connection to use.
The LDAP authentication instance to use. The default value is ldap1 .
Specifies whether to authenticate the user information. The valid values are true|false .
Parameter op.pinReset.
tokenType .update.applet.enable
Description op.pinReset.
tokenType .update.applet.emptyToken.enable
to the token when it does not have one. The valid values are true|false .
Specifies if applet upgrade is turned on. The valid values are true|false .
op.pinReset.
tokenType .update.applet.requiredVersion
op.pinReset.
tokenType .update.applet.directory
The local filesystem directory where the applets are located.
op.pinReset.
tokenType .update.symmetricKeys.enable
be enabled. The valid values are true| false . When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion
.
op.pinReset.
tokenType .update.symmetricKeys.requiredVersion
op.pinReset.
tokenType .loginRequest.enable
Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true| false .
op.pinReset.
tokenType .pinReset.pin.minLen
The minimum number of characters for the PIN.
op.pinReset.
tokenType .pinReset.pin.maxRetries
The maximum number of times PIN authentication can be attempted on the token before the key is locked. This value is set on the token when the PIN is reset.
op.pinReset.
tokenType .pinReset.pin.maxLen
op.pinReset.
tokenType .tks.conn
op.pinReset.
tokenType .auth.id
The maximum number of characters for the PIN.
The TKS connection to use.
The LDAP authentication instance to use. The default value is ldap1 .
op.pinReset.
tokenType .auth.enable
Specifies whether to authenticate the user information. The valid values are true|false .
Table 8.9. PIN Reset Operation Preferences
Parameter Description op.format.
tokenType .update.applet.emptyToken.enable
to the token when it does not have one. The valid values are true|false .
212
TPS Configuration Parameters
Parameter Description op.format.
tokenType .update.applet.requiredVersionThe version of the applet to use. It should be the file name of the applet without the .ijc
extension.
op.format.
tokenType .update.applet.directory
The local filesystem directory where the applets are located op.format.
tokenType .update.symmetricKeys.enableSpecifies if the key changeover feature should be enabled. The valid values are true| false . When enabled, TPS checks to see the key version sent by the token matches symmetricKeys.requiredVersion
.
op.format.
tokenType .update.symmetricKeys.requiredVersion
op.format.
tokenType .revokeCert
Specifies if TPS should revoke the certificates associated with the token during this format operation. The default is true . The valid values are true|false .
op.format.
tokenType .ca.conn
op.format.
tokenType .loginRequest.enable
The CA connection to use.
Specifies if the login request should be sent to the token. This parameter enables authentication. The valid values are true| false .
op.format.
tokenType .tks.conn
op.format.
tokenType .auth.id
The TKS connection to use.
The LDAP authentication instance to use. The default value is ldap1 .
op.format.
tokenType .auth.enable
Specifies whether to authenticate the user information. The valid values are true|false .
op.format.
tokenType .issuerinfo.enable
Specifies whether the Phone Home information for the Enterprise Security Client is set. The valid values are true|false .
op.format.
tokenType .issuerinfo.value
Sets the Phone Home URL; this is the URL for the TPS which the Enterprise Security Client will contact for token operations; this value is set on the token when it is formatted. For example, https://tps.example.com:7888/cgibin/home/index.cgi
.
Table 8.10. Format Operation Preferences
Parameter tokendb.auditLog
tokendb.hostport
tokendb.bindDN
Description
The full path to the audit log file. For example,
/var/lib/rpki-tps/logs/tokendbaudit.log
.
The token database (LDAP) hostname and port number. The format is hostname:port .
The bind DN to bind to the token database. The default value is cn=directory manager .
213
Chapter 8. Token Processing System
Parameter tokendb.bindPassPath
tokendb.templateDir
tokendb.userBaseDN
tokendb.baseDN
tokendb.activityBaseDN
tokendb.certBaseDN
Description
The path to a local password file which contains the subsystem passwords. The default file is /var/lib/rhpki-tps/conf/ password.conf
.
The directory where the templates for the TPS agent page are located.
The LDAP suffix where the user entries are.
The LDAP suffix where the token entries should be added and modified by the TPS. The default value is ou=Tokens, baseDN .
The LDAP suffix where the token-based activities should be recorded by the TPS. The default value is ou=Activities, baseDN .
The LDAP suffix where the certificate entries should be added by the TPS. The default value is ou=certificates, baseDN .
Change these templates only to change the appearance of the TPS agent page
• tokendb.indexTemplate
• tokendb.indexAdminTemplate
• tokendb.newTemplate
• tokendb.showTemplate
• tokendb.showCertTemplate
• tokendb.errorTemplate
• tokendb.searchTemplate
• tokendb.searchResultTemplate
• tokendb.searchCertificateResultTemplate
• tokendb.editTemplate
• tokendb.editResultTemplate
• tokendb.addResultTemplate
• tokendb.deleteTemplate
• tokendb.deleteResultTemplate
• tokendb.searchActivityTemplate
• tokendb.searchActivityResultTemplate
• tokendb.showAdminTemplate
214
TKS Configuration File Parameters
Parameter tokendb.defaultPolicy
Description
• tokendb.doTokenTemplate
• tokendb.doTokenConfirmTemplate
• tokendb.revokeTemplate
• tokendb.editAdminTemplate
• tokendb.editAdminResultTemplate
• tokendb.searchAdminTemplate
• tokendb.searchAdminResultTemplate
The default policy to use. The valid values are
PIN_RESET=YES|NO; and RE_ENROLL=YES|
NO; .
Table 8.11. Token Database Preferences
8.9.1. TKS Configuration File Parameters
There are several parameters which should be set in the TKS configuration file to use the TPS for server-side key generation and for key updates. These are listed in Table 8.12, “TKS Configuration
Parameters for Key Generation” and Table 8.13, “TKS Configuration Parameters for Key Update” .
Parameter tks.drm_transport_cert_nickname=
Transport nickname
DRM
Description
The DRM transport certificate nickname. This needs to be set to enable server-side key generation.
Table 8.12. TKS Configuration Parameters for Key Generation
Parameter Description tks.mk_mappings.#01#01= tokenname:nickname The version 1 master key nickname.
tks.mk_mappings.#02#01= tokenname:nickname The version 2 master key nickname.
NOTE
Master keys are generated using the tksTool utility. The version 1 key set is the default set by the smart card manufacturer. Smart cards can optionally be upgraded to the version
2 key set.
Table 8.13. TKS Configuration Parameters for Key Update
215
216
Chapter 9.
Token Key Service
The Certificate System Token Management System consists of three components, the Token
Processing System (TPS), the Token Key Service (TKS), and the Enterprise Security Client. This chapter explains the TKS, which manages the master keys required set up a secure communication channel between the TPS and the client.
9.1. Overview
A TKS manages the master and transport keys required to generate and distribute keys for smart cards or tokens. A master key is a Triple DES symmetric key stored either in software or hardware token. When supplied with the token CUID, a TKS can derive the corresponding three symmetric keys
� authentication key, Mac key, and key encryption key (KEK) � on each token. This effectively shares secrets between the Certificate System and the token without having to store these symmetric keys on the server.
The Certificate System TPS subsystem uses the TKS subsystem to generate the token keys the TPS uses to communicate with the Enterprise Security Client. The TPS communicates with the TKS over
SSL. The TKS provides the security between tokens and the TPS since the security relies on the relationship between the master key and the token keys.
The functions provided by the TKS include the following:
• Helps establish a secure channel (signed and encrypted) between the token and TPS.
• Provides proof of presence for the security token during enrollment.
• Supports key changeover when the master key changes on the TKS. Tokens with older keys get new token keys.
• Helps generate a symmetric session key for the DRM to wrap (encrypt) the entity's private key for
(optional) server-side key generation, where the entity's encryption keys are generated on the DRM
NOTE
Because of the sensitivity of the data that the TKS manages, the TKS should be set behind the firewall with restricted access.
9.2. Using Master Keys
Generate new master and transport keys using the tksTool utility. The transport key is used to send the master key securely to the facility where the tokens are generated. Tokens that are generated with a particular master key can only be used with that master key.
1. Open the TKS instance alias/ directory.
cd /var/lib/ instance_ID /alias/
2. Generate the new master key. For example: tksTool -M -n new_master -d /var/lib/rhpki-tks/alias -h token_name -p certDBPrefix
217
Chapter 9. Token Key Service
3. Create a transport key called transport .
tksTool -T -d . -n transport -p certDBPrefix -p certDBPrefix
The tksTool utility prints out the KCV values for each of the three session keys that are generated. Save them to file since these are all necessary to regenerate the transport key if it is lost.
4. When prompted, fill in the database password, then type in some noise to seed the random number generator.
5. Use the transport key to generate and wrap a master key and store it in a file called file .
tksTool -W -d . -n new_master -t transport -o file -p certDBPrefix
Enter Password or Pin for "NSS Certificate DB":
Retrieving the transport key (for wrapping) from the specified token . . .
Generating and storing the master key on the specified token . . .
Naming the master key "wrapped_master" . . .
Successfully generated, stored, and named the master key!
Using the transport key to wrap and store the master key . . .
Writing the wrapped data (and resident master key KCV) into the
file called "file" . . .
wrapped data: 47C0 06DB 7D3F D9ED
FE91 7E6F A7E5 91B9
master key KCV: CED9 4A7B
(computed KCV of the master key residing inside the wrapped data)
6. Use the transport key to unwrap a master key called new_master stored in a file called file .
tksTool -U -d . -n new_master -t transport -i file
Enter Password or Pin for "NSS Certificate DB":
Retrieving the transport key from the specified token (for
unwrapping) . . .
Reading in the wrapped data (and resident master key KCV) from
the file called "file" . . .
wrapped data: 47C0 06DB 7D3F D9ED
FE91 7E6F A7E5 91B9
master key KCV: CED9 4A7B
(pre-computed KCV of the master key residing inside the wrapped data)
Using the transport key to temporarily unwrap the master key to recompute its KCV value to check against its pre-computed KCV value . . .
master key KCV: CED9 4A7B
(computed KCV of the master key residing inside the wrapped data)
master key KCV: CED9 4A7B
(pre-computed KCV of the master key residing inside the wrapped data)
Using the transport key to unwrap and store the master key on the
specified token . . .
Naming the master key "new_master" . . .
Successfully unwrapped, stored, and named the master key!
The tksTool utility generates a new master key, wraps it with the transport key, and then extracts it to the output file which can be used as a backup if the master key is lost.
218
Configuring the TKS to Associate the Master Key with Its Version
Using the tksTool is explained in more detail in the Certificate System Command-Line Tools Guide .
9.3. Configuring the TKS to Associate the Master Key with
Its Version
Master keys have a numeric identifier such as 01. The TKS maps these IDs to PKCS #11 object nicknames specified in masterKeyId . To map the keys, add a mapping parameter like the following to the CS.cfg
file: tks.mk_mappings.#02#01= tokenname:masterKeyId
NOTE
Stop the TKS instance before editing the configuration file.
To reference the security database, set the tokenname to internal . All numeric key identifiers in mapping configurations must be suffixed with #01 . #02 represents the master key version.
NOTE
Smart cards from the Axalto Web Store come with a default developer key set where all keys are set to 404142434445464748494a4b4c4d4e4f . TKS has this key built-in, and it is referred to with the master key set #01. TKS uses key set #01 by default.
9.4. Using HSM for Generating Keys
By default the TKS is configured to use the internal software token to generate and store its master keys, but some deployments may require using a hardware security module (HSM) instead of the software token.
To generate keys on HSMs:
1. Install the TKS subsystem.
2. After the TKS instance is configured, generate the TKS master key on the HSM using the tksTool . By default during installation, the TKS master key is generated on the software token.
For example: tksTool -M -n new_master -d /var/lib/rhpki-tks/alias -h nethsm
This generates a master key named new_master on the nethsm token for the rhpki-tks instance.
For more information on using the tksTool , see the Certificate System Command-Line Tools
Guide .
3. Update the TKS instance's CS.cfg
to contain the following values:
219
Chapter 9. Token Key Service
# useSoftToken tells whether to use software token or no. by default it's true,
# even if it's not set tks.useSoftToken=false
# mk_mappings maps key version to key name on token name
# in this example, #02 is the version number, nethsm is the token name,
# and new_master is the key name tks.mk_mappings.#02#01=nethsm:new_master
It is not necessary to change the defaultSlot value; it can remain the default value for the software database: tks.defaultSlot=Internal Key Storage Token
4. Restart the TKS instance.
/etc/init.d/rhpki-tks restart
5. Update the CS.cfg
for every Token Processing System (TPS) which uses the edited TKS instance. Set the requiredVersion parameter and enable key upgrade in all profiles with the parameters update.symmetricKeys.enable
and update.symmetricKeys.requiredVersion
in the parameter name. For example:
# note that the "requiredVersion" needs to map with the version number
# specified in the mk_mappings parameter of TKS's CS.cfg
op.enroll.userKey.update.symmetricKeys.enable=true op.enroll.userKey.update.symmetricKeys.requiredVersion=2
6. Restart the TPS instance.
/etc/init.d/rhpki-tps restart
9.5. Creating Token Key Service Agents and Administrators
When the subsystem is configured, there is a default user created with both administrator and agent privileges.This user can perform both administrator and agent operations and access the Console and the agent services page.
To create an additional administrator, agent, or auditor, create a user in the Certificate System instance where the user will have privileges and assign the user to the appropriate group. An agent or auditor must have a certificate stored in the subsystem's internal database. If the Console is configured for
SSL client authentication, all administrators must also a certificate.
To create a new user entry:
1. Log into the administrative console.
pkiconsole https://server.example.com:12443/tks
2. In the Configuration tab, select Users and Groups . Click Add .
3. Fill in the information in the Edit User Information dialog.
220
Creating Token Key Service Agents and Administrators
Figure 9.1. Creating a New User
The group to which the user belongs determines what privileges the user has. Assign agents and administrators to the appropriate subsystem group.
4. Store the user's certificate.
a. Request and approve an SSL client certificate for the user if one has not already been generated.
b. Copy the base-64 encoded certificate to a local file or to the clipboard.
c. Select the new user entry, and click Certificates .
d. Click Import , and paste in the base-64 encoded certificate.
For more information on editing user entries and managing user certificates, see Section 17.4,
“Modifying Certificate System User Entries” .
221
222
Chapter 10.
Enterprise Security Client
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.
223
224
Chapter 11.
Managing Certificates
This chapter gives an overview of using certificates: what types and formats are available, how to request and create them through the HTML end-entity forms and through the Certificate System
Console, and how to install certificates in the Certificate System and on different clients. Additionally, there is information on managing certificates through the Console and configuring the servers to use them.
NOTE
For information on revoking certificates and creating CRLs, see Chapter 14, Revocation and CRLs .
For information on publishing certificates and CRLs, see Chapter 15, Publishing .
11.1. Certificate Overview
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 are important to manage both the PKI and the Certificate System instances.
• Section 11.1.1, “Types of Certificates”
• Section 11.1.2, “Determining Which Certificates to Install”
• Section 11.1.3, “Certificate Data Formats”
• Section 11.1.4, “Certificate Setup Wizard”
11.1.1. Types of Certificates
There are several different types of certificates that can be created and requested through the
Certificate System, depending on the functions for which the certificate will be used. The following are some of the major certificates that are used:
• CA signing certificates
• OCSP signing certificates
• CRL signing certificates
• DRM transport certificates
• DRM storage certificates
• SSL server certificates
• SSL client certificates
• User certificates
• Dual key pairs/certificates
• Cross-pair certificates
225
Chapter 11. Managing Certificates
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:// hostname:SSLport /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. The default certificates created for each subsystem type are listed in Section 2.3.2, “Default Settings” . Common certificate types are explained in the following sections.
• Section 11.1.1.1, “CA Signing Certificates”
• Section 11.1.1.2, “Other Signing Certificates”
• Section 11.1.1.3, “SSL Server and Client Certificates”
• Section 11.1.1.4, “User Certificates”
• Section 11.1.1.5, “Dual-Key Pairs”
• Section 11.1.1.6, “Cross-Pair Certificates”
11.1.1.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. For more information on CA chains and hierarchies, see Chapter 4,
Certificate Manager .
11.1.1.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.
226
Determining Which Certificates to Install
11.1.1.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.
11.1.1.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.
11.1.1.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.
11.1.1.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.
11.1.2. Determining Which Certificates to Install
When a Certificate System subsystem is first installed and configured, the certificates necessary to access and administer it are automatically created. These include an agent's certificate, server certificate, and subsystem-specific certificates. These initial certificates are shown in Table 11.1, “Initial
Subsystem Certificates” .
Subsystem
Certificate Manager
Certificates
• CA signing certificate
• OCSP signing certificate
227
Chapter 11. Managing Certificates
Subsystem
OCSP
DRM
Certificates
• SSL server certificate
• Subsystem certificate
• User's (agent/administrator) certificate
• OCSP signing certificate
• SSL server certificate
• Subsystem certificate
• User's (agent/administrator) certificate
• Transport certificate
• Storage certificate
• SSL server certificate
• Subsystem certificate
• User's (agent/administrator) certificate
• SSL server certificate TKS
• User's (agent/administrator) certificate
Table 11.1. Initial Subsystem Certificates
There are some cautionary considerations about replacing existing subsystem certificates.
• Generating new key pairs when creating a new self-signed CA certificate for a root CA will invalidate all certificates issued under the previous CA certificate.
This means none of the certificates issued or signed by the CA using its old key will work; subordinate Certificate Managers, DRMs, OCSPs, TKSs, and TPSs will no longer function, and agents can no longer to access agent interfaces.
This same situation occurs if a subordinate CA's CA certificate is replaced by one with a new key pair; all certificates issued by that CA are invalidated and will no longer work.
• If the CA is configured to publish to the OCSP and it has a new CA signing certificate or a new CRL signing certificate, the CA must be identified again to the OCSP.
• If a new transport certificate is created for the DRM, the DRM information must be updated in the
CA's configuration file, CS.cfg
. The existing transport certificate must be replaced with the new one in the ca.connector.KRA.transportCert
parameter.
• If a CA is cloned, then when creating a new SSL server certificate for the master Certificate
Manager, the clone CAs' certificate databases all need updated with the new SSL server certificate.
• If the Certificate Manager is configured to publish certificates and CRLs to an LDAP directory and uses the SSL server certificate for SSL client authentication, then the new SSL server certificate must be requested with the appropriate extensions. After installing the certificate, the publishing directory must be configured to use the new server certificate.
• All subsystems can have an unlimited number of SSL server certificates.
228
Certificate Data Formats
11.1.3. Certificate Data Formats
Certificate requests and certificates can be created, stored, and installed in several different formats.
All of these formats conform to X.509 standards.
11.1.3.1. Binary
The following binary formats are recognized:
• DER-encoded certificate.
This is a single binary DER-encoded certificate.
• PKCS #7 certificate chain . This is a PKCS #7 SignedData object. The only significant field in the
SignedData object is the certificates; the signature and the contents, for example, are ignored. The
PKCS #7 format allows multiple certificates to be downloaded at once.
• Netscape Certificate Sequence.
This is a simpler format for downloading certificate chains in a PKCS #7 ContentInfo structure, wrapping a sequence of certificates. The value of the contentType field should be netscape-cert-sequence , while the content field has the following structure:
CertificateSequence ::= SEQUENCE OF Certificate
This format allows multiple certificates to be downloaded at once.
11.1.3.2. Text
Any of the binary formats can be imported in text form. The text form begins with the following line:
-----BEGIN CERTIFICATE-----
Following this line is the certificate data, which can be in any of the binary formats described. This data should be base-64 encoded, as described by RFC 1113. The certificate information is followed by this line:
-----END CERTIFICATE-----
11.1.4. Certificate Setup Wizard
The Certificate System provides a wizard in the administrative console, called the Certificate Setup
Wizard , that automates the process of requesting and installing the certificates required by the
Certificate System subsystem instances.
• Request and install new certificates for the subsystem certificates installed in a Certificate System instance; issuing or requesting a new certificate means getting a certificate based on a new public and private key pair.
• Install CA certificates in the certificate or trust database of a Certificate System instance.
• Install CA certificate chains in the certificate database of a Certificate System instance.
The wizard performs different tasks depending whether it is launched from the CA Certificates tab or the Local Certificates tab.
229
Chapter 11. Managing Certificates
Open the wizard by clicking Add or Add/Renew in the System Keys and Certificates Console menu item.
The Local Certificates -based wizard has the option to request or install a certificate. The CA
Certificate -based wizard has the option to install a trusted or untrusted certificate chain.
To install certificates, except for self-signed CA certificates, the wizard must be run twice: once to request the certificate and once to install the certificate. If the certificate request is being submitted to an outside CA, even another Certificate System CA, the certificate must be issued and retrieved before it can be installed through the wizard.
11.2. Requesting and Receiving Certificates
The process of receiving a certificate is simple:
1. An end entity requests a certificate.
2. The certificate request is submitted to the CA.
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 end entity retrieves the new certificate.
The Certificate System provides three ways to request a certificate:
• Through the enrollment forms of the Certificate Manager end entity pages
• Through the subsystems' administrative console
• By using the certutil command-line tool
There are also three ways that the request is submitted the CA to generate a certificate and to add it to the certificate database:
• Through the enrollment forms of the Certificate Manager end entity pages. Requests are submitted immediately when the request is created through the enrollment form; requests can also be submitted that were created by the administrative console or the certutil tool.
• Through the subsystems' administrative console. The Console has an option to submit the request to a specified CA.
• By using the certutil command-line tool.
The authentication process is determined by the certificate profiles that are associated with the enrollment forms used. This can be done automatically by the server applying preset criteria or by manual approval from an agent. Once the request is approved, it is available through the CA's endentities page for the entity to retrieve.
NOTE
For more information on authentication for enrollment, see Chapter 16, Authentication for
Enrolling Certificates and Chapter 13, Certificate Profiles .
230
Requesting Certificates
• Section 11.2.1, “Requesting Certificates”
• Section 11.2.2, “Submitting Certificate Requests”
• Section 11.2.3, “Retrieving Certificates from the End-Entities Page”
11.2.1. Requesting Certificates
The different methods of requesting certificates allow different types of certificates which can be requested. End users can request client certificates, either agent or user certificates for the Certificate
System or for use with other applications. Administrators can request certificates for servers and
Certificate System instances.
• End-Entities Page: User and Agent Certificates
The end-entities pages can be accessed by any user. Those enrollment forms can be used to request user and agent certificates. See Section 11.2.1.1, “Requesting a User or Agent Certificate through the End-Entities Page” .
• Certificate Wizard: Server and Subsystem Certificates
The administrative console can only be accessed by administrators. The Console can be used to create requests for CA, OCSP, and CRL signing certificates; SSL server certificates; client certificates; and DRM transport certificates. See Section 11.2.1.2, “Requesting a Subsystem, Server, or Signing Certificate through the Console” .
• certutil: All Certificates
The certutil utility can be used by administrators or users to generate any certificate.
11.2.1.1. Requesting 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 forms 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
231
Chapter 11. Managing Certificates required, the user can also use a hardware token, such as a smart card, to store the key pair and the certificate.
To create a user certificate, do the following:
1. Open the Certificate Manager's end-entities page.
https://server.example.com:9443/ca/ee/ca
2. Select the user certificate enrollment form from the list of certificate profiles.
3. Fill in the user information.
Figure 11.1. User Certificate Request Form
4. Click Submit .
5. The key pairs for the user certificate are generated, and the certificate request is sent to the agent queue. Alternatively, if automatic enrollment is configured, the certificate is approved (or rejected) by the server, and the new certificate is displayed in the web browser window.
232
Requesting Certificates
11.2.1.2. Requesting a Subsystem, Server, or Signing Certificate through the Console
The Certificate Setup Wizard for the different subsystems creates requests for any of the certificates used by that subsystem. These certificates can be a server certificate, OCSP signing certificate, or subsystem-specific certificate, such as a CA signing certificate or DRM transport certificate.
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.
To create a certificate request using the subsystem administrative console, do the following:
1. Open the subsystem console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select System Keys and Certificates in the navigation tree.
3. In the right panel, select the Local Certificates tab.
4. Click Add/Renew .
Figure 11.2. Certificate Request Wizard
233
Chapter 11. Managing Certificates
5. Select the Request a certificate radio button.
6. Choose the certificate type to request. The types of certificates that can be requested varies depending on the subsystem:
• For a CA:
• CA signing certificate
• OCSP signing
• SSL server certificates
• Other certificate
• For a DRM:
• Transport certificate
• OCSP signing
• SSL server certificates
• Other certificate
• For an OCSP or TKS:
• OCSP signing
• SSL server certificates
• Other certificate
NOTE
If selecting to create an "other" certificate, the Certificate Type field becomes active.
Fill in the type of certificate to create, either caCrlSigning for the CRL signing certificate or client for an SSL client certificate.
234
Requesting Certificates
Figure 11.3. Selecting the Certificate Type
7. For requests submitted through a Certificate Manager, after selecting the type of certificate, select which type of CA will sign the request:
• For a CA signing certificate, the options are to use a root CA or a subordinate CA.
• For all other certificates, the options are to use the local CA signing certificate or to create a request to submit to another CA.
235
Chapter 11. Managing Certificates
8. Set the key-pair information.
Figure 11.4. Generating the Key Pair
• Set the token, either the security database directory (internal) or one of the listed external tokens.
• Generate a new key pair. Set the key algorithm and size. The key algorithm must be RSA . The recommended length for an RSA key is 2048 bits or higher to be crytpographically strong.
9. Select the message digest algorithm; the choices are MC2 , MD5 , SHA1 , SHA256 , and SHA512 .
236
Requesting Certificates
Figure 11.5. Setting the Hashing Algorithm
10. Give the subject name. Either enter values for individual DN attributes to build the subject DN or enter the full string.
237
Chapter 11. Managing Certificates
Figure 11.6. Setting the Subject Name
NOTE
For an SSL server certificate, the common name must be the fully-qualified host name of the Certificate System in the format machine_name.domain.domain
.
11.
Only when requesting a certificate through the Certificate Manager Console and submitting the request to the Certificate Manager automatically.
Specify the start and end dates of the validity period for the certificate and the time at which the validity period will start and end on those dates.
238
Requesting Certificates
Figure 11.7. Setting the Validity Period
The default validity period is five years.
12.
Only when requesting a certificate through the Certificate Manager Console submitting the request to the Certificate Manager automatically.
Set the standard extensions for the certificate. The required extensions are chosen by default. To change the default choices, read the guidelines explained in Appendix A, Certificate and CRL Extensions .
239
Chapter 11. Managing Certificates
240
Figure 11.8. Setting the Certificate Extensions
NOTE
Certificate extensions are required to set up a CA hierarchy. Subordinate CAs must have certificates that include the extension identifying them as either a subordinate
SSL CA (which allows them to issue certificates for SSL) or a subordinate email
CA (which allows them to issue certificates for secure email). Disabling certificate extensions means that CA hierarchies cannot be set up.
• Basic Constraints. The associated fields are CA setting and a numeric setting for the certification path length.
• Extended Key Usage.
• Authority Key Identifier.
• Subject Key Identifier.
Requesting Certificates
• Key Usage. The digital signature (bit 0), non-repudiation (bit 1), key certificate sign (bit 5), and
CRL sign (bit 6) bits are set by default. The extension is marked critical as recommended by the
PKIX standard and RFC 2459. See http://www.ietf.org/rfc/rfc2459.txt
for a description of the Key
Usage extension.
• Base-64 SEQUENCE of extensions. This is for custom extensions. Paste the extension in MIME
64 DER-encoded format into the text field.
To add multiple extensions, use the ExtJoiner program. For information on using the tools, see the Certificate System Command-Line Tools Guide .
13. The wizard generates the key pairs and displays the certificate signing request.
241
Chapter 11. Managing Certificates
242
Figure 11.9. Getting the Certificate Request
The request is in base-64 encoded PKCS #10 format and is bounded by the marker lines
-----BEGIN NEW CERTIFICATE REQUEST---- and -----END NEW CERTIFICATE
REQUEST----. For example:
-----BEGIN NEW CERTIFICATE REQUEST-----
MIICJzCCAZCgAwIBAgIBAzANBgkqhkiG9w0BAQQFADBC6SAwHgYDVQQKExdOZXRzY2FwZSBDb21tdW5pY2
Requesting Certificates
F0aW9uczngjhnMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTk4MDgyNzE5MDAwMFoXDTk5MDIyMzE5MDA wMnbjdgngYoxIDAeBgNVBAoTF05ldHNjYXBlIENvbW11bmljYXRpb25zMQ8wDQYDVQQLEwZQZW9wbGUxFz
AVBgoJkiaJkIsZAEBEwdzdXByaXlhMRcwFQYDVQQDEw5TdXByaXlhIFNoZXR0eTEjMCEGCSqGSIb3Dbndg
JARYUc3Vwcml5Yhvfggsvwryw4y7214vAOBgNVHQ8BAf8EBAMCBLAwFAYJYIZIAYb4QgEBAQHBAQDAgCAM
A0GCSqGSIb3DQEBBAUAA4GBAFi9FzyJlLmS+kzsue0kTXawbwamGdYql2w4hIBgdR+jWeLmD4CP4x
-----END NEW CERTIFICATE REQUEST-----
The wizard also copies the certificate request to a text file it creates in the configuration directory, which is located at /var/lib/ instance_id /conf/ . The name of the text file depends on the type of certificate requested. The possible text files are listed in Table 11.2, “Files Created for Certificate
Signing Requests” .
Filename cacsr.txt
ocspcsr.txt
Certificate Signing Request
CA signing certificate
Certificate Manager OCSP signing certificate
DRM transport certificate kracsr.txt
ocspcsr.txt
sslcsr.txt
OCSP signing certificate
SSL server certificate othercsr.txt
Other certificates, such as Certificate Manager
CRL signing certificate or SSL client certificate
Table 11.2. Files Created for Certificate Signing Requests
Do not modify the certificate request before sending it to the CA. The request can either be submitted automatically through the wizard or copied to the clipboard and manually submitted to the CA through its end-entities page.
NOTE
The wizard's auto-submission feature can submit requests to a remote Certificate
Manager only. It cannot be used for submitting the request to a third-party CA.
14. Submit the certificate request to a CA.
• Submit the request to a remote Certificate System CA through the wizard. See Section 11.2.2.1,
“Submitting Certificate Requests through the Console” .
• Copy the request to the clipboard to submit the request through the CA enrollment forms. See
Section 11.2.2.2, “Submitting Certificate Requests through the End-Entities Page” .
• Submit the request to a third-party CA. See Section 11.2.2.3, “Submitting a Certificate Request to a Third-Party CA” .
NOTE
Requests created through a Certificate Manager Console are automatically submitted to the CA without this step.
11.2.1.3. Requesting Certificates Using certutil
To request subsystem certificates using the certutil utility, do the following:
243
Chapter 11. Managing Certificates
1. Open the certificate database directory of the instance for which the certificate is being requested.
cd /var/lib/ instance_ID /alias
2. Run the certutil command, defining the key settings, subject name, validity period, and extentions.
certutil -R -k rsa -g 2048 -s "CN=example cert server.example.com,O=Example Domain" -o
request.cert -v 12 -d . -1 -3 -6
The required options are listed in Table 11.3, “Options for Requesting Certificates with certutil” .
Option
R k g s o v d numbers 1-8
Description
Flag to generate a certificate request.
The key type to use; the only option is rsa .
The key size. The recommended size for RSA keys is 2048.
The subject name of the certificate.
The output file to which to save the certificate request.
The validity period, in months.
Certificate database directory; this is the directory for the subsystem instance.
These set the available certificate extensions.
Only eight can be specified through the certutil tool:
• Key Usage: 1
• Basic Constraints: 2
• Certificate Authority Key ID: 3
• CRL Distribution Point: 4
• Netscape Certificate Type: 5
• Extended Key Usage: 6
• Email Subject Alternative Name: 7
• DNS Subject Alternative Name: 8 a Outputs the certificate request to an ASCII file instead of binary.
Table 11.3. Options for Requesting Certificates with certutil
Once the request is generated, submit the certificate request in the output file to the issuing CA through the CA's enrollment forms.
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/ nss/tools/certutil.html
.
244
Submitting Certificate Requests
11.2.2. Submitting Certificate Requests
There are three ways to submit a certificate request. The best method for submitting a request depends on how the request was created.
• Through the Console's Certificate Wizard.
The final screen when creating a certificate request through the subsystem administrative console has the option to submit the request automatically to a specified Certificate System CA. This is only possible for subsystem certificate requests created through the Console.
• Through the Certificate System CA end-entities page.
The Certificate Manager end-entities services page has a list of different enrollment forms for submitting certificate requests, depending on the subsystem and purpose of the certificate. Certificates created through the Console or through the certutil command-line utility can be submitted through an enrollment form.
• Through a third-party CA.
Outside CAs, such as VeriSign, have online or other types of certificate request enrollments; the requests created by the Certificate System administrative console can be submitted there.
11.2.2.1. Submitting Certificate Requests through the Console
To send the certificate signing request automatically to a Certificate System Certificate Manager using the wizard, select the Send the request to a remote Certificate System now checkbox.
245
Chapter 11. Managing Certificates
Figure 11.10. Submitting the Certificate Request
• Host name . The fully-qualified host name of the Certificate System CA.
• EE port number . The end-entity port number.
• Yes, it's the SSL secure server port . Indicates that the end entity port number specified is the
SSL port.
The certificate wizard returns a request ID for the request, which can be used in the end-entities page later, and the request is queued for agent approval. When the request is approved, the CA signs the
246
Submitting Certificate Requests certificate and contacts the email address in the request. Once the certificate has been issued, use the request ID to import the certificate into the wizard. Alternatively, install the certificate as described in
Section 11.4.1.1, “Installing Certificates through the Console” .
11.2.2.2. Submitting Certificate Requests through the End-Entities Page
1. Copy the certificate request, including the marker lines -----BEGIN NEW CERTIFICATE
REQUEST---- and -----END NEW CERTIFICATE REQUEST---- to a text file or into the clipboard.
2. Open the end-entity services page of the Certificate Manager.
https://ca.example.com:9443/ca/ee/ca
3. In Certificate Profiles of the Enrollment tab, click on the appropriate form to submit the request.
Some of the common forms are as follows:
• For user certificates, including agent certificates:
• Manual User Dual-Use Certificate Enrollment
• Manual User Signing & Encryption Certificates Enrollment
• For server certificates:
• Manual Server Certificate Enrollment
• Manual TPS Server Certificate Enrollment
• For client certificates:
• Other Certificate Enrollment
• For subsystem-specific certificates:
• Manual Certificate Manager Signing Certificate Enrollment
• Manual OCSP Manager Signing Certificate Enrollment
• Manual Data Recovery Manager Transport Certificate Enrollment
4. In the certificate enrollment form, enter the required information.
247
Chapter 11. Managing Certificates
Figure 11.11. Submitting the Certificate Request
The standard requirements are as follows:
• Certificate Request Type . This is either PKCS#10 or CRMF. Certificate requests created through the subsystem administrative console are PKCS #10; those created through the certutil tool and other utilities are usually PKCS #10.
• Certificate Request . Paste the base-64 encoded blob, including the -----BEGIN NEW
CERTIFICATE REQUEST---- and -----END NEW CERTIFICATE REQUEST---- marker lines.
• Requester Name . This is the common name of the person requesting the certificate.
• Requester Email . This is the email address of the requester. The agent or CA system will use this address to contact the requester when the certificate is issued. For example, [email protected]
.
• Requester Phone . This is the contact phone number of the requester.
The submitted request is queued for agent approval. An agent needs to process and approve the certificate request, which the CA signs then and delivers back to the email address specified in the request. If the requester has agent access, the requester can log in as an agent and approve the request.
248
Retrieving Certificates from the End-Entities Page
When the CA issues the certificate, save the certificate to a file, and install it following the instructions in Section 11.4.1.1, “Installing Certificates through the Console” .
11.2.2.3. Submitting a Certificate Request to a Third-Party CA
An external CA is any public or third-party CA. Before sending a certificate request to a public
CA, make sure that the CA can issue the type of certificate that is being requested. Also, read the statement published by the CA to see whether the CA imposes any restrictions on the validity period or usage of the certificate.
To send a certificate request manually to an external or third-party CA, do the following:
1. Copy the certificate request, including the marker lines -----BEGIN NEW CERTIFICATE
REQUEST---- and -----END NEW CERTIFICATE REQUEST----, to a text file or the clipboard.
2. Open the external CA's home page in a web browser, submit the certificate request in the appropriate form for the certificate type.
3. When the CA responds, save the information in a text file.
4. When the certificate is retrieved from the CA, install it following the instructions in Section 11.4.1.1,
“Installing Certificates through the Console” .
11.2.3. Retrieving Certificates from the End-Entities Page
When the certificate is issued, it can be retrieved by the user in the end-entities page of the issuing
Certificate Manager.
NOTE
Certificates which are created in the Certificate Manager Console are generated at the time they are requested, unless the request is specifically for a third-party CA.
1. Open the Certificate Manager end-entities page.
https://server.example.com:9443/ca/ee/ca
2. Click the Retrieval tab.
249
Chapter 11. Managing Certificates
Figure 11.12. Retrieval Search
3. Fill in the request ID number that was created when the certificate request was submitted, and click Submit .
4. The next page shows the status of the certificate request. If the status is complete , then there is a link to the certificate. Click the Issued certificate link.
Figure 11.13. New Certificate Link
5. The new certificate information is shown in pretty-print format, in base-64 encoded format, and in
PKCS #7 format.
250
Managing User Certificates
Figure 11.14. Certificate Information
There are two actions that can be taken through this page:
• To install this certificate on a server or other application, scroll down to the Installing This
Certificate in a Server section, which contains the base-64 encoded certificate.
• If this is a client certificate that will be installed directly in the web browser, scroll down to the
Importing This Certificate section, and click the Import your certificate or Import S/MIME certificate button.
6. Copy the base-64 encoded certificate, including the -----BEGIN CERTIFICATE---- and
-----END CERTIFICATE---- marker lines, to a text file. Save the text file, and use it to store a copy of the certificate in a subsystem's internal database. See Section 17.2, “Creating Users” .
11.3. Managing User Certificates
User certificates have to be imported into the appropriate applications for users and agents to be able to perform certain operations. For subsystem agents to perform agent operations, for example, their
SSL client certificates must be imported into the Certificate System user database and into the web browser used to access the agent services pages.
• Section 11.3.1, “Managing Certificate System User and Agent Certificates”
• Section 11.3.2, “Importing Certificates into Mozilla Firefox”
251
Chapter 11. Managing Certificates
For information on importing subsystem certificates into the security databases, see Section 11.4.1,
“Installing Certificates in the Certificate System Database” .
11.3.1. Managing Certificate System User and Agent Certificates
Certificates for a user must be stored in the certificate database of the subsystem to which the user belongs. Especially user certificates for agents and administrators must be stored in the certificate database so that the subsystem can authenticate the user, and the user can perform required subsystem operations.
To view the user's certificates, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, select Users and Groups from the left navigation tree.
3. Select a user, and click Certificates . A list of certificates installed for that user is shown.
Add users' certificates by doing the following:
1. Log into the subsystem console.
pkiconsole https:// hostname:SSLport/subsystem
2. In the Configuration tab, select Users and Groups .
3. In the Users tab, select a user, and click Certificates .
4. In the Manage User Certificates dialog, click Import .
5. In the text area of the Import Certificate dialog, paste the user's certificate in base-64 encoded form. Include the -----BEGIN CERTIFICATE---- and -----END CERTIFICATE----marker lines.
6. To view the certificate, select it, and click View . The certificate information appears.
To delete a user certificate, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, select Users and Groups from the left navigation tree.
3. Select a user, and click Certificates . A list of certificates installed for that user is shown.
4. Select the certificate to delete, and click Delete .
5. When prompted, confirm the delete.
252
Importing Certificates into Mozilla Firefox
11.3.2. Importing Certificates into Mozilla Firefox
Some client certificates, such as agent certificates, must be imported into a web browser for the user to perform necessary operations, including Certificate System agent services.
Mozilla Firefox can import certificates. There are several MIME content types that are used to indicate what type of certificate is being imported; the most common certificate MIME types are as follows:
• application/x-x509-user-cert . The certificate being downloaded is a user certificate belonging to the user operating Firefox. If the private key associated with the certificate does not exist in the user's local key database, then Firefox generates an error dialog and the certificate is not imported. If a certificate chain is being imported, then the first certificate in the chain must be the user certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database.
• application/x-x509-ca-cert . The certificate being downloaded represents a CA. When it is downloaded, a sequence of dialogs goes through the process of accepting the CA and deciding whether to trust sites certified by the CA.
If a certificate chain is imported, the first certificate in the chain must be the CA certificate. Any subsequent certificates in the chain are added to the local database as untrusted CA certificates.
• application/x-x509-email-cert . The certificate being downloaded is a user certificate belonging to another user for use with S/MIME. If a certificate chain is imported, the first certificate in the chain must be the user certificate. All subsequent certificates are added to the local database as untrusted CA certificates. This process allows people or CAs to post their email certificates on web pages for download by other users who want to send them encrypted mail.
NOTE
Firefox checks that the size of the object being downloaded matches the size of the encoded certificates. Therefore, it is important that no extra characters, such as NULL or
Newline , are added at the end of the object.
To import a certificate into Firefox, do the following:
1. Open Mozilla Firefox.
2. Click Edit in the top menu, and select Preferences from the drop-down menu.
3. Click the Advanced icon.
4. In the Certificates section, click Manage Certificate .
5. Click Import , and choose the text file containing the client certificate.
NOTE
If the certificate is not in PKCS #12 format, the certutil tool can be used to convert it. For more information on using certutil , see http://www.mozilla.org/projects/ security/pki/nss/tools/ .
6. Supply the token password if prompted.
253
Chapter 11. Managing Certificates
7. Click OK .
The new certificate is listed in the Your certificates tab.
NOTE
If there are multiple client certificates installed, the Certificate System subsystem may not automatically find the appropriate client certificate. Set the Ask every time in the Client certificate selection section of the Firefox Advanced tab, which will prompt for the user to select the client certificate every time a website requests one.
11.4. Managing the Certificate Database
Each Certificate System instance has a certificate database, which is maintained in its internal token.
This database contains certificates belonging to the subsystem installed in the Certificate System instance and various CA certificates the subsystems use for validating the certificates they receive.
Even if an external token is used to generate and store key pairs, Certificate System always maintains its list of trusted and untrusted CA certificates in its internal token.
This section explains how to view the contents of the certificate database, delete unwanted certificates, and change the trust settings of CA certificates installed in the database using the
Certificate System window. For information on adding certificates to the database, see Section 11.4.1,
“Installing Certificates in the Certificate System Database” .
NOTE
The Certificate System command-line utility certutil can be used to manage the certificate database by editing trust settings and adding and deleting certificates. For details about this tool, see http://www.mozilla.org/projects/security/pki/nss/tools/ .
Administrators should periodically check the contents of the certificate database to make sure that it does not include any unwanted CA certificates. For example, if the database includes CA certificates that should not ever be trusted within the PKI setup, delete them.
11.4.1. Installing Certificates in the Certificate System Database
If new server certificates are issued for a subsystem, they must be installed in that subsystem database. Additionally, user and agent certificates must be installed in the subsystem databases. If the certificates are issued by an external CA, then usually the corresponding CA certificate or certificate chain needs installed.
Certificates can be installed in the subsystem certificate database through the Console's Certificate
Setup Wizard or using the certutil utility.
• Section 11.4.1.1, “Installing Certificates through the Console”
• Section 11.4.1.2, “Installing Certificates Using certutil”
• Section 11.4.1.3, “About CA Certificate Chains”
• Section 11.4.1.4, “Importing Cross-Pair Certificates”
254
Installing Certificates in the Certificate System Database
11.4.1.1. Installing Certificates through the Console
The Certificate Setup Wizard can install or import the following certificates into either an internal or external token used by the Certificate System instance:
• Any of the certificates used by a Certificate System subsystem
• Any trusted CA certificates from external CAs or other Certificate System CAs
• Certificate chains
A certificate chain includes a collection of certificates: the subject certificate, the trusted root CA certificate, and any intermediate CA certificates needed to link the subject certificate to the trusted root. However, the certificate chain the wizard imports must include only CA certificates; none of the certificates can be a user certificate.
In a certificate chain, each certificate in the chain is encoded as a separate DER-encoded object.
When the wizard imports a certificate chain, it imports these objects one after the other, all the way up the chain to the last certificate, which may or may not be the root CA certificate. If any of the certificates in the chain are already installed in the local certificate database, the wizard replaces the existing certificates with the ones in the chain. If the chain includes intermediate CA certificates, the wizard adds them to the certificate database as untrusted CA certificates.
The subsystem console uses the same wizard to install certificates and certificate chains. To install certificates in the local security database, do the following:
1. Open the Console.
pkiconsole https:// hostname:SSLport /ca
2. In the Configuration tab, select System Keys and Certificates from the left navigation tree.
3. There are two tabs where certificates can be installed, depending on the subsystem type and the type of certificate.
• The CA Certificates tab is for installing CA certificates and certificate chains. For Certificate
Managers, this tab is used for third-party CA certificates or other Certificate System CA certificates; all of the local CA certificates are installed in the Local Certificates tab. For all other subsystems, all CA certificates and chains are installed through this tab.
• The Local Certificates tab is where all server certificates, subsystem certificates, and local certificates such as OCSP signing or DRM transport are installed.
Select the appropriate tab.
4. To install a certificate in the Local Certificates tab, click Add/Renew . To install a certificate in the
CA Certificates tab, click Add . Both will open the Certificate Setup Wizard.
a. When the wizard opens, select the Install a certificate radio button, and click Next .
b. Select the type of certificate to install. The options for the drop-down menu are the same options available for creating a certificate, depending on the type of subsystem, with the additional option to install a cross-pair certificate.
255
Chapter 11. Managing Certificates c. Paste in the certificate body, including the -----BEGIN CERTIFICATE---- and -----
END CERTIFICATE----, into the text area, or specify the absolute file location; this must be a local file.
The certificate will look like the following:
-----BEGIN CERTIFICATE-----
MIICKzCCAZSgAwIBAgIBAzANgkqkiG9w0BAQQFADA3MQswCQYDVQQGEw
JVUzERMA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncy
BDQTAeFw05NzEwMTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBg
NVBAYTAlVTMREwDwYDVQQKEwhOZXRzY2FwZTENMAsGA1UECxMEUHawcz
EXMBUGA1UEAxMOU3Vwcml5YSBTaGV0dHkwgZ8wDQYJKoZIhdfNAQEBBQ
ADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG7SdATYzBcABu1AVyd7 chRFOGD3wNktbf6hRo6EAmM5R1Askzf8AW7LiQZBcrXpc0k4du+2j6xJ u2MPm8WKuMOTuvzpo+SGXelmHVChEqooCwfdiZywyZNmgaMa2MS6pUkf
QVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgD
-----END CERTIFICATE-----
5. The wizard displays the certificate details. Review the fingerprint to make sure this is the correct certificate, or use the Back button to go back and submit a different one. Give a nickname for the certificate.
The wizard installs the certificate.
6. Any CA that signed the certificate must be trusted by the subsystem. Make sure that this CA's certificate exists in the subsystem's certificate database (internal or external) and that it is trusted.
If the CA certificate is not listed, add the certificate to the certificate database as a trusted CA.
If the CA's certificate is listed but untrusted, change the trust setting to trusted, as shown in
Section 11.4.4, “Changing the Trust Settings of a CA Certificate” .
When installing a certificate issued by a CA that is not stored in the Certificate System certificate database, add that CA's certificate chain to the database. To add the CA chain to the database, copy the CA chain to a text file, start the wizard again, and install the CA chain.
11.4.1.2. Installing Certificates Using certutil
To install subsystem certificates in the Certificate System instance's security databases using certutil , do the following:
1. Open the subsystem's security database directory.
cd /var/lib/ instance_ID /alias
2. Run the certutil command with the -A to add the certificate and -i pointing to the file containing the certificate issued by the CA.
certutil -A -n cert-name -t trustargs
-d . -a -i certificate_file
256
Installing Certificates in the Certificate System Database
NOTE
If the Certificate System instance's certificates and keys are stored on an HSM, then specify the token name using the -h option.
For example: certutil -A -n "ServerCert cert-example" -t u,u,u -d . -a -i /tmp/example.cert
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/ nss/tools/certutil.html
.
11.4.1.3. About CA Certificate Chains
Any client or server software that supports certificates maintains a collection of trusted CA certificates in its certificate database. These CA certificates determine which other certificates the software can validate. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It is also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy.
The first certificate in the chain is processed in a context-specific manner, which varies according to how it is being imported. For Mozilla Firefox, this handling depends upon the MIME content type used on the object being downloaded. For Red Hat servers, it depends upon the options selected in the server administration interface.
Subsequent certificates are all treated the same. If the certificates contain the SSL-CA bit in the
Netscape Certificate Type certificate extension and do not already exist in the local certificate database, they are added as untrusted CAs. They can be used for certificate chain validation as long as there is a trusted CA somewhere in the chain.
11.4.1.4. Importing Cross-Pair Certificates
Both cross-pair certificates can be imported into the Certificate System databases using the certutil tool or by selecting the Cross-Pair Certificates option from the Certificate Setup
Wizard. When both certificates have been imported into the database, a crossCertificatePair entry is formed and stored in the database. The original certificates are deleted once the crossCertificatePair entry is created.
The database can be searched for the crossCertificatePair entry using the Certificate System
LDAP search command.
ldapsearch -h hostname -p CAInternalDBPort
-b "o=netscapeCertificateServer" -D "cn=Directory Manager" -w DirectoryManagerPassword
"cn=crossCerts"
The Certificate Policies Extension profile default can be edited to specify cross-pair certificates either through the Console or by setting the attribute value in the CS.cfg
to
HTTP_PARAMS.certType==fbca . This profile is then associated with an end-entity enrollment page which has been customized to enroll for cross-pair certificates by providing the hidden value certType==fbca .
257
Chapter 11. Managing Certificates
For information on publishing cross-pair certificates, Section 15.7, “Publishing Cross-Pair Certificates” .
11.4.2. Viewing Database Content
The certificates stored in the subsystem certificates database, cert8.db
, can be viewed through the subsystem administrative console. Alternatively, the certificates can be listed using the certutil utility. certutil must be used to view the TPS certificates because the TPS subsystem does not use an administrative console.
• Section 11.4.2.1, “Viewing Database Content through the Console”
• Section 11.4.2.2, “Viewing Database Content Using certutil”
NOTE
The certificates listed in the cert8.db
database are the subsystem certificates used for subsystem operations. User certificates are stored with the user entries in the LDAP internal database. To view user certificates, see Section 11.3.1, “Managing Certificate
System User and Agent Certificates” .
11.4.2.1. Viewing Database Content through the Console
To view the contents of the database through the administrative console, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, select System Keys and Certificates from the left navigation tree.
3. There are two tabs, CA Certificates and Local Certificates , which list different kinds of certificates.
• CA Certificates lists CA certificates for which the corresponding private key material is not available, such as certificates issued by third-party CAs such as Entrust or Verisign or external
Certificate System Certificate Managers.
• Local Certificates lists certificates kept by the Certificate System subsystem instance, such as the DRM transport certificate or OCSP signing certificate.
258
Viewing Database Content
Figure 11.15. Certificate Database Tab
4. The Certificate Database Management table lists the all of the certificates installed on the subsystem. The following information is supplied for each certificate:
• Certificate Name
• Serial Number
• Issuer Names , the common name ( cn ) of the issuer of this certificate.
• Token Name , the name of the cryptographic token holding the certificate; for certificate stored in the database, this is internal .
To view more detailed information about the certificate, select the certificate, and click View . This opens a window which shows the serial number, validity period, subject name, issuer name, and certificate fingerprint of the certificate.
11.4.2.2. Viewing Database Content Using certutil
To view the certificates in the subsystem database using certutil , open the instance's certificate database directory, and run the certutil with the -L option. For example: cd /var/lib/ instance_ID /alias certutil -L -d .
Certificate Authority - Example Domain CT,c, subsystemCert cert-rhpki-tks u,u,u
Server-Cert cert-rhpki-tks u,u,u
259
Chapter 11. Managing Certificates
To view the keys stored in the subsystem databases using certutil , run the certutil with the -K option. For example: cd /var/lib/ instance_ID /alias certutil -K -d .
Enter Password or Pin for "NSS Certificate DB":
<0> subsystemCert cert-rhpki-tks
<1>
<2> Server-Cert cert-rhpki-tks
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/ nss/tools/certutil.html
.
11.4.3. Deleting Certificates from the Database
Removing unwanted certificates reduces the size of the certificate database.
NOTE
When deleting CA certificates from the certificate database, be careful not to delete the intermediate CA certificates , which help a subsystem chain up to the trusted CA certificate. If in doubt, leave the certificates in the database as untrusted CA certificates; see Section 11.4.4, “Changing the Trust Settings of a CA Certificate” .
• Section 11.4.3.1, “Deleting Certificates through the Console”
• Section 11.4.3.2, “Deleting Certificates Using certutil”
11.4.3.1. Deleting Certificates through the Console
To delete a certificate through the Console, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, select System Keys and Certificates from the left navigation tree.
3. Select the certificate to delete, and click Delete .
4. When prompted, confirm the delete.
11.4.3.2. Deleting Certificates Using certutil
To delete a certificate from the database using certutil , do the following:
1. Open the instance's certificate databases directory.
cd /var/lib/ instance_ID /alias
2. List the certificates in the database by running the certutil with the -L option. For example:
260
Changing the Trust Settings of a CA Certificate certutil -L -d .
Certificate Authority - Example Domain CT,c, subsystemCert cert-subsystem u,u,u
Server-Cert cert-example u,u,u
3. Delete the certificate by running the certutil with the -D option.
certutil -D -d . -n certificate_nickname
For example: certutil -D -d . -n "ServerCert cert-example"
4. List the certificates again to confirm that the certificate was removed.
certutil -L -d .
Certificate Authority - Example Domain CT,c, subsystemCert cert-subsystem u,u,u
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/ nss/tools/certutil.html
.
11.4.4. Changing the Trust Settings of a CA Certificate
Certificate System subsystems use the CA certificates in their certificate databases to validate certificates received during an SSL-enabled communication.
It can be necessary to change the trust settings on a CA stored in the certificate database, temporarily or permanently. For example, if there is a problem with access or compromised certificates, marking the CA certificate as untrusted prevents entities with certificates signed by that CA from authenticating to the Certificate System. When the problem is resolved, the CA can be marked as trusted again.
To untrust a CA permanently, consider removing its certificate from the trust database. For instructions, see Section 11.4.3, “Deleting Certificates from the Database” .
11.4.4.1. Changing Trust Settings through the Console
To change the trust setting of a CA certificate, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, System Keys and Certificates from the left navigation tree.
3. Select the CA certificates tab.
4. Select the CA certificate to modify, and click Edit .
261
Chapter 11. Managing Certificates
5. A prompt opens which reads The Certificate chain is (un)trusted, are you sure you want to
(un)trust it?
Clicking yes changes the trust setting of the certificate chain; pressing no preserves the original trust relationship.
11.4.4.2. Changing Trust Settings Using certutil
To change the trust setting of a certificate using certutil , do the following:
1. Open the instance's certificate databases directory.
cd /var/lib/ instance_ID /alias
2. List the certificates in the database by running the certutil with the -L option. For example: certutil -L -d .
Certificate Authority - Example Domain CT,c, subsystemCert cert-subsystem u,u,u
Server-Cert cert-example u,u,u
3. Change the trust settings for the certificate by running the certutil with the -M option.
certutil -M -n cert_nickname -t trust -d .
For example: certutil -M -n "Certificate Authority - Example Domain" -t TCu,TCu,TCu -d .
4. List the certificates again to confirm that the certificate trust was changed.
certutil -L -d .
Certificate Authority - Example Domain CTu,CTu,CTu subsystemCert cert-subsystem u,u,u
Server-Cert cert-example u,u,u
For information about using the certutil command, see http://www.mozilla.org/projects/security/pki/ nss/tools/certutil.html
.
11.5. Configuring the Server Certificate Use Preferences
Configuring a Certificate System manager's security preferences involves identifying the following:
• The SSL client certificate a Certificate Manager must use for authenticating to the publishing directory if the Certificate Manager is configured to publish certificates and CRLs to the directory.
• Whether bridged or cross-pair certificates are used and that they are properly installed.
262
Configuring the Server Certificate Use Preferences
• The version of SSL used during SSL communication. The latest version is SSL version 3, but many older clients use SSL version 2. Because client authentication is required for performing privileged operations, enable SSL version 3 ciphers.
263
264
Chapter 12.
Managing Tokens
This chapter gives an overview of using hardware security modules, also called HSMs or tokens , to generate and store Certificate System instance certificates and keys. This chapter includes installation and usage considerations for supported HSMs, describes different tasks for managing tokens, and contains other information for using hardware tokens with Certificate System.
12.1. Tokens for Storing Certificate System Keys and
Certificates
A token is a hardware or software device that performs cryptographic functions and stores public-key certificates, cryptographic keys, and other data.
The Certificate System defines two types of tokens, internal and external , for storing key pairs and certificates that belong to the Certificate System subsystems.
12.1.1. Internal Tokens
An internal (software) token is a pair of files, usually called the certificate database and key database , that the Certificate System uses to generate and store its key pairs and certificates. The Certificate
System automatically generates these files in the filesystem of its host machine when first using the internal token. These files were created during the Certificate System subsystem configuration if the internal token was selected for key-pair generation.
In the Certificate System, the certificate database is named cert8.db
; the key database is named key3.db
. These files are located in the instanceID /alias directory.
12.1.2. External Tokens
An external token refers to an external hardware device, such as a smart card or hardware security module (HSM), that the Certificate System uses to generate and store its key pairs and certificates.
The Certificate System supports any hardware tokens that are compliant with PKCS #11.
PKCS #11 is a standard set of APIs and shared libraries which isolate an application from the details of the cryptographic device. This enables the application to provide a unified interface for PKCS #11compliant cryptographic devices.
The PKCS #11 module implemented in the Certificate System supports cryptographic devices supplied by many different manufacturers. This module allows the Certificate System to plug in shared libraries supplied by manufacturers of external encryption devices and use them for generating and storing keys and certificates for the Certificate System managers.
Consider using external tokens for generating and storing the key pairs and certificates used by
Certificate System. These devices are another security measure to safeguard private keys because hardware tokens are sometimes considered more secure than software tokens.
12.1.3. Considerations for External Tokens
• All system keys for a subsystem must be generated on the same token.
• Install the subsystem in an empty HSM slot. If the HSM slot has previously been used to store other keys, then use the HSM vendor's utilities to delete the contents of the slot. The Certificate System
265
Chapter 12. Managing Tokens has to be able to create certificates and keys on the slot with default nicknames. If not properly cleaned up, the names of these objects may collide with previous instances.
• Before restarting the server when completing the configuration wizard, do the following:
1. Stop the server.
2. Edit to the server.xml
file. Add the HSM token name to the serverCert parameter. For example: serverCert="lunasa2-ca:Server-Cert cert-rhpki-ca instanceID
3. Start the server.
12.2. Using Hardware Security Modules with Subsystems
The Certificate System supports two hardware security modules (HSM), nCipher netHSM and
SafeNet's LunaSA. For the Certificate System to use the HSM, the hardware must be installed according to the hardware manufacturer's installation and configuration procedures before beginning to configure the Certificate System. Certificate System-supported HSMs are automatically added to the secmod.db
database with modutil during the pre-configuration stage of the installation, if the
PKCS #11 library modules are in the default installation paths.
During configuration, the Key Store panel displays the supported modules, along with the NSS internal software PKCS #11 module. All supported modules that are detected show a status of
Found and is individually marked as either Logged in or Not logged in . If a token is found but not logged in, it is possible to log in using the Login under Operations . If the administrator can log into a token successfully, the password is stored in a configuration file. At the next start or restart of the
Certificate System instance, the passwords in the password store are used to attempt a login for each corresponding token.
Administrators are allowed to select any of the tokens that are logged in as the default token, which is used to generate system keys.
When an HSM is selected as the default token, the following parameters are set in the CS.cfg
file to configure the HSM:
#RHCS supported modules preop.configModules.module0.commonName=NSS Internal PKCS #11 Module preop.configModules.module0.imagePath=../img/mozilla.png
preop.configModules.module0.userFriendlyName=NSS Internal PKCS #11 Module preop.configModules.module1.commonName=nfast preop.configModules.module1.imagePath=../img/ncipher.png
preop.configModules.module1.userFriendlyName=nCipher's nFast Token Hardware Module preop.configModules.module2.commonName=lunasa preop.configModules.module2.imagePath=../img/safenet.png
preop.configModules.module2.userFriendlyName=SafeNet's LunaSA Token Hardware Module
#selected token preop.module.token=Internal Key Storage Token
In addition, the following parameter is set in the password.conf
for the HSM password:
266
Chrysalis LunaSA HSM hardware-lunasa2-ca=caPassword
12.2.1. Chrysalis LunaSA HSM
To make sure that the LunaSA HSM works with Red Hat Certificate System, add this configuration parameter to /etc/Chrystoki.conf
:
Misc { NetscapeCustomize=1023; }
12.2.2. Installing External Tokens and Unsupported HSM
To use HSMs which are not officially supported by the Certificate System, the modutil tool can be used to add that module to the subsystem database manually. If the desired HSM does not appear in the Key Store panel, check that the HSM is installed and activated correctly. Then run modutil manually to add the module to the secmod.db
database as follows:
To use external encryption devices or tokens, do the following:
1. Install the cryptographic device.
To install the drivers provided by the device manufacturer, follow the vendor's instructions. When installing a hardware token, there is an opportunity to name it. Use a name that will help identify the token later.
2. Install the PKCS #11 module.
The PKCS #11 module is installed using the modutil command-line utility.
a. Open the alias directory for the subsystem which is being configured with the PKCS #11 module. For example: cd /var/lib/rhpki-ca/alias/ b. The required security module database file, secmod.db
, should be created by default when the subsystem is created. If it does not exist, use the modutil utility to create secmod.db
.
modutil -dbdir . -nocertdb -create c. Use the modutil utility to set the library information.
modutil -dbdir . -nocertdb / -add module_name -libfile library_file library_file specifies the path to the library file containing the PKCS #11 interface module and module_name gives the name of the PKCS #11 module which was set when the drivers were installed.
• For the LunaSA HSM, do the following: modutil -dbdir . -nocertdb -add lunasa -libfile /usr/lunasa/lib/libCryptoki2.so
267
Chapter 12. Managing Tokens
• For an nCipher HSM, do the following: modutil -dbdir . -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/ libcknfast.so
12.3. Managing Tokens Used by the Subsystems
There are two main tasks involved in managing the tokens used by Certificate System:
• Viewing tokens
• Changing the token passwords
12.3.1. Viewing Tokens
To view a list of the tokens currently installed for a Certificate System instance, use the modutil utility.
1. Open the instance alias directory. For example: cd /var/lib/rhpki-ca/alias
2. Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the modutil tool.
modutil -dbdir . -nocertdb -list
12.3.2. Changing a Token's Password
The token, internal or external, that stores the key pairs and certificates for the subsystems is protected (encrypted) by a password. To decrypt the key pairs or to gain access to them, enter the token password. This password is set when the token is first accessed, usually during Certificate
System installation.
It is good security practice to change the password that protects the server's keys and certificates periodically. Changing the password minimizes the risk of someone finding out the password. To change a token's password, use the certutil command-line utility.
For information about certutil , see http://www.mozilla.org/projects/security/pki/nss/tools/ .
The single sign-on password cache stores token passwords in the password.conf
file. This file must be manually updated every time the token password is changed. For more information on managing passwords through the password.conf
file, see Section 3.3, “System Passwords” .
12.4. Detecting Tokens
To see if a token can be detected by Certificate System to be installed or configured, use the
TokenInfo utility.
268
Hardware Cryptographic Accelerators
TokenInfo
This utility will return all tokens which can be detected by the Certificate System, not only tokens which are installed in the Certificate System.
12.5. Hardware Cryptographic Accelerators
The Certificate System can use hardware cryptographic accelerators with external tokens. Many of the accelerators provide the following security features:
• Fast SSL connections. Speed is important to accommodate a high number of simultaneous enrollment or service requests.
• Hardware protection of private keys. These devices behave like smart cards by not allowing private keys to be copied or removed from the hardware token. This is important as a precaution against key theft from an active attack of an online Certificate Manager.
269
270
Chapter 13.
Certificate Profiles
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.
13.1. About Certificate Profiles
A certificate profile defines everything associated with issuing a particular type of certificate, including the authentication 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 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.
For example, a certificate profile for user certificates defines all aspects of that certificate, including the validity period of the certificate. The default validity period can be set to two years, and a constraint can be set on the profile that the validity period for certificates requested through this certificate profile cannot exceed two years. When a user requests a certificate using the input form associated with this certificate profile, the issued certificate contains the information specified in the defaults and will be valid for two years. If the user submits a preformatted request for a certificate with a validity period of four years, the request is rejected since the constraints allow a maximum of two years validity period for this type of certificate.
A set of certificate profiles have been predefined for the most common certificates issued. These certificate profiles define defaults and constraints, associate the authentication method, and define the needed inputs and outputs for the certificate profile.
The parameters of the default certificate profiles � the authentication method, the defaults, the constraints used in each profile, the values assigned to any of the parameters in a profile, the input, and the output � can be modified. It is also possible to create new certificate profiles for other types of certificates or for creating more than one certificate profile for a certificate type. There can be multiple certificate profiles for a particular type of certificate to issue the same type of certificate with a different authentication method or different definitions for the defaults and constraints. For example, there can be two certificate profiles for enrollment of SSL server certificates where one certificate profile issues certificates with a validity period of six months and another certificate profile issues certificates with a validity period of two years.
An input sets a text field in the enrollment form and what kind of information needs gathered from the end entity; this includes setting the text area for a certificate request to be pasted, which allows a request to be created outside the input form with any of the request information desired. The input values are set as values in the certificate.
An output specifies how the response page to a successful enrollment is presented. It usually displays the certificate in a user-readable format. The default output shows a printable version of the resultant certificate; other outputs set the type of information generated at the end of the enrollment, such as
PKCS #7.
Policy sets are sets of constraints and default extensions attached to every certificate processed through the profile. The extensions define certificate content such as validity periods and subject name
271
Chapter 13. Certificate Profiles requirements. A profile handles one certificate request, but a single request can contain information for multiple certificates. A PKCS#10 request contains a single public key. One CRMF request can contain multiple public keys, meaning multiple certificate requests. A profile may contain multiple sets of policies, with each set specifying how to handle one certificate request within a CRMF request.
13.2. How Certificate Profiles Work
An administrator sets up a certificate profile by associating an existing authentication plug-in, or method, with the certificate profile; enabling and configuring defaults and constraints; and defining inputs and outputs. The administrator can use the existing certificate profiles, modify the existing certificate profiles, create new certificate profiles, and delete any certificate profile that will not be used in this PKI.
Once a certificate profile is set up, it appears on the Manage Certificate Profiles page of the agent services page where an agent can approve, and thus enable, a certificate profile. Once the certificate profile is enabled, it appears on the Certificate Profile tab of the end-entities page where end entities can enroll for a certificate using the certificate profile.
The certificate profile enrollment page in the end-entities interface contains links to each certificate profile that has been enabled by the agents. When an end entity selects one of those links, an enrollment page appears containing an enrollment form specific to that certificate profile. The enrollment page is dynamically generated from the inputs defined for the profile. If an authentication plug-in is configured, additional fields may be added to authenticate the user.
When an end entity submits a certificate profile request that is associated with an agent-approved
(manual) enrollment, an enrollment where no authentication plug-in is configured, the certificate request is queued in the agent services interface. The agent can change some aspects of the enrollment, request, validate it, cancel it, reject it, update it, or approve it. The agent is able to update the request without submitting it or validate that the request adheres to the profile's defaults and constraints. This validation procedure is only for verification and does not result in the request being submitted. The agent is bound by the constraints set; they cannot change the request in such a way that a constraint is violated. The signed approval is immediately processed, and a certificate is issued.
When a certificate profile is associated with an authentication method, the request is approved immediately and generates a certificate automatically if the user successfully authenticates, all the information required is provided, and the request does not violate any of the constraints set up for the certificate profile. There are profile policies which allow user-supplied settings like subject names or validity periods. The certificate profile framework can also preserve user-defined content set in the original certificate request in the issued certificate.
The issued certificate contains the content defined in the defaults for this certificate profile, such as the extensions and validity period for the certificate. The content of the certificate is constrained by the constraints set for each default. Multiple policies (defaults and constraints) can be set for one profile, distinguishing each set by using the same value in the policy set ID. This is particularly useful for dealing with dual keys enrollment where encryption keys and signing keys are submitted to the same profile. The server evaluates each set with each request it receives. When a single certificate is issued, one set is evaluated, and any other sets are ignored. When dual-key pairs are issued, the first 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 set for issuing a single certificate or more than two sets for issuing dual-key pairs.
272
Setting up Certificate Profiles
13.3. Setting up Certificate Profiles
Certificate profiles are managed by changing the existing certificate profiles, deleting an existing certificate profile, or adding another certificate profile. Maintaining certificate profiles includes the following process:
• Deciding which certificate profiles are needed in the PKI. There should be at least one profile for each type of certificate issued. There can be more than one certificate profile for each type of certificate to set different authentication methods or different defaults and constraints for a particular type of certificate type. Any certificate profile available in the administrative interface can be approved by an agent and then used by an end entity to enroll.
• Deleting any certificate profiles that will not be used.
• Creating custom certificate profiles.
• Modifying the existing certificate profiles and any custom certificate profiles.
• Changing the defaults set up in the certificate profile, the values of the parameters set in the defaults, or the constraints that control the certificate content.
• Changing the constraints set up by changing the value of the parameters.
• Changing the authentication method.
• Changing the inputs by adding or deleting inputs in the certificate profile, which control the fields on the input page.
• Adding or deleting the output.
• Section 13.3.1, “Modifying Certificate Profiles through the CA Console”
• Section 13.3.2, “Modifying Certificate Profiles through the Command Line”
• Section 13.3.4, “Customizing the Enrollment Form”
13.3.1. Modifying 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:// host:SSLport /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.
273
Chapter 13. Certificate Profiles
Figure 13.1. Certificate Profile Instances Management Tab
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.
Figure 13.2. Certificate Profile Plugin Implementation Window
4. Fill in the profile information in the Certificate Profile Instance Editor .
274
Modifying Certificate Profiles through the CA Console
Figure 13.3. Certificate Profile Instance Editor
• Certificate Profile Instance ID . This is the ID used by the system to identify the profile.
• Certificate Profile Name . This is the user-friendly name for the profile.
• Certificate Profile Description .
• End User Certificate Profile . This sets whether the request must be made through the input form for the profile. This is usually set to true . Setting this to false allows a signed request to be processed through the Certificate Manager's certificate profile framework, rather than through the input page for the certificate profile.
• Certificate Profile Authentication . This sets the authentication method. An automated authentication is set by providing the instance ID for the authentication instance. If this field is blank, the authentication method is agent-approved enrollment; the request is submitted to the request queue of the agent services interface.
5. Click OK . The plugin editor closes, and the new profile is listed in the profiles tab.
275
Chapter 13. Certificate Profiles
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 .
Figure 13.4. Certificate Profile Policy Editor b. Choose the default from the Default field, choose the constraints associated with that policy in the Constraints field, and click OK .
276
Modifying Certificate Profiles through the CA Console
Figure 13.5. Certificate Profile Editor: Defaults Tab 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.
277
Chapter 13. Certificate Profiles
Figure 13.6. Certificate Profile Editor: Constraints Tab
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 13.7, “Defaults Reference” and Section 13.8, “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 .
278
Modifying Certificate Profiles through the CA Console
Figure 13.7. Certificate Profile Inputs b. Choose the input from the list, and click OK . See Section 13.5, “Input Reference” for complete details of the default inputs.
c. The New Certificate Profile Editor window opens. Set the input ID, and click OK .
279
Chapter 13. Certificate Profiles
Figure 13.8. Setting Inputs
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.
280
Modifying Certificate Profiles through the CA Console
Figure 13.9. Certificate Profile Outputs
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. 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.
281
Chapter 13. Certificate Profiles
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.
11. Delete any certificate profiles that will not be approved by an agent. Any certificate profile that appears in the Certificate Profile Instance Management tab also appears in the agent services interface. If a profile has already been enabled, it must be disabled by the agent before it can be deleted from the profile list.
13.3.2. Modifying 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/rhpki-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.
NOTE
Restart the server after editing the profile configuration file for the changes to take effect.
• Section 13.3.2.1, “Profile Configuration Parameters”
• Section 13.3.2.2, “Modifying Certificate Extensions through the Command Line”
• Section 13.3.2.3, “Adding Inputs through the Command Line”
13.3.2.1. Profile Configuration Parameters
The configuration files are stored in the CA profile directory, such as /var/lib/rhpki-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=userKeyDefaultImpl 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 13.1, “Profile Configuration File
Parameters” .
282
Modifying Certificate Profiles through the Command Line
Parameter desc enable auth.instance_id
name input.list
Description
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.
Sets whether the profile is enabled, and therefore accessible through the end-entities page. For example, enable=true .
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 .
Gives the name of the profile. For example, name=Agent-Authenticated Server Certificate
Enrollment .
Lists the allowed inputs for the profile by name.
For example, input.list=i1,i2 .
input.
input_id output.list
output.
policyset.list
.class_id
output_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 .
Lists the possible output formats for the profile by name. For example, output.list=o1 .
Gives the java class name for the output format named in output.list
. For example, output.o1.class_id=certOutputImpl .
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.
rule_id .list
Lists the policy sets configured for the profile by ID number. For example, policyset.serverCertSet.list=1,2,3,4,5,6,7,8 .
policyset.
rule_id.policy_number.
constraint.class_id
constraint plug-in set for the default configured in the profile rule. For example, policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl .
policyset.
rule_id.policy_number.
constraint.name
of the constraint. For example, policyset.serverCertSet.1.constraint.name=Subject
Name Constraint .
283
Chapter 13. Certificate Profiles
Parameter Description policyset.
rule_id.policy_number.
constraint.params.
attribute attribute for the constraint. The possible attributes vary depending on the type of constraint. For example, policyset.serverCertSet.1.constraint.params.pattern=CN=.* .
policyset.
rule_id.policy_number.
default.class_id
set in the profile rule. For example, policyset.serverCertSet.1.default.class_id=userSubjectNameDefaultImpl policyset.
rule_id.policy_number.
default.nameGives the user-defined name of the default. For example, policyset.serverCertSet.1.default.name=Subject
Name Default policyset.
rule_id.policy_number.
default.params.
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 13.1. Profile Configuration File Parameters
13.3.2.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
284
Populating Certificates with Directory Attributes
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.
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 13.7,
“Defaults Reference” and Section 13.8, “Constraints Reference” .
13.3.2.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 13.5, “Input Reference” .
13.3.3. Populating Certificates with Directory Attributes
It is possible to populate certificates with data retrieved from LDAP entries. This is done by setting the certificate profile to use an LDAP attribute variable set in the authentication plug-in whenever a particular extension is used. To populate certificates with LDAP attribute values, do the following:
1. Enable the user directory authentication plug-in, UidPwdDirAuth .
a. Open the CA Console.
pkiconsole https://server.example.com:9443/ca
285
Chapter 13. Certificate Profiles 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 16.3.1, “Setting up
Directory-Based Authentication” .
2. When the new authentication plug-in is added, the corresponding parameters are added to the
CA's CS.cfg
file. For example, this instance of the UidPwdDirAuth plug-in is set to populate the mail attribute:
...
auths.instance.UserDirEnrollment.dnpattern=
auths.instance.UserDirEnrollment.ldapByteAttributes= auths.instance.UserDirEnrollment.ldapStringAttributes=mail
auths.instance.UserDirEnrollment.pluginName=UidPwdDirAuth
auths.instance.UserDirEnrollment.ldap.basedn=dc=example,dc=com
auths.instance.UserDirEnrollment.ldap.maxConns=
auths.instance.UserDirEnrollment.ldap.minConns=
auths.instance.UserDirEnrollment.ldap.ldapconn.host=localhost
auths.instance.UserDirEnrollment.ldap.ldapconn.port=389
auths.instance.UserDirEnrollment.ldap.ldapconn.secureConn=false...
The ldapStringAttributes parameter instructs the authentication plug-in to read the value of the mail attribute from the user's LDAP entry and put that value in the certificate request.
When the value is in the request, the certificate profile policy can be set to insert that value for an extension value.
3. To enable the CA to insert the LDAP attribute value in the certificate extension, edit the profile's configuration file, and insert a policy set parameter for an extension. For example, to insert the mail attribute value in the Subject Alternative Name extension in the caDirUser profile, do the following: cd /var/lib/rhpki-ca/profiles vi caDirUser.cfg
policyset.setID.8.default.params.
subjAltExtPattern_0=$request.auth_token.mail[0]$
4. Restart the CA.
/etc/init.d/rhpki-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:
286
Populating Certificates with Directory Attributes
Identifier: Subject Alternative Name - 2.5.29.17
Critical: no
Value:
RFC822Name: [email protected]
There are many attributes which can be automatically inserted into certificates by being set as a token in the policy set. These are listed in Table 13.2, “Tokens Used to Populate Certificates” .
Policy Set Token
$request.requestType$
Description
This specifies the type of request, such as enrollment.
This is the base-64 certificate request.
$request.cert_request$
$request.profile$
$request.cert_request_type$
$request.auth_token.userDN$
$request.authenticatedName$
This is the type of request, such as CRMF or
PKCS #10.
This inserts the user DN of the user who requested the certificate.
This inserts the user DN of the user who requested the certificate.
$request.profileRemoteAddr$
$request.auth_token.cn[0]$
$request.auth_token.uid$
This inserts the LDAP common name ( cn ) attribute of the suer who requested the certificate.
This inserts the LDAP user ID ( uid ) attribute of the user who requested the certificate.
$request.bodyPartId$
$request.profileApprovedBy$
$request.auth_token.authMgrImplName$
$request.profileId$
This inserts the name of the Certificate System agent who approved the certificate.
This inserts the type of authentication plug-in which authenticated the user.
This inserts the name of the profile enrollment form to which the request was submitted.
$request.profileRemoteHost$
$request.requestId$
$request.requestVersion$
This inserts the request ID number.
This inserts the Certificate System version number of the CA which issued the certificate.
$request.dbStatus$
$request.auth_token.tokenCertSubject$
$request.requestStatus$
$request.auth_token.authMgrInstName$
This inserts the certificate subject name.
$request.auth_token.mail[0]$
This inserts the name of the authentication plugin instance which authenticated the user.
This inserts the value of the LDAP email
( mail ) attribute of the user who requested the certificate.
287
Chapter 13. Certificate Profiles
Policy Set Token
$request.profileSetId$
Table 13.2. Tokens Used to Populate Certificates
Description
This inserts the name of the policy set which processed the certificate request.
13.3.4. Customizing the Enrollment Form
To customize enrollment forms, create new pages with a custom design rather than editing the default enrollment form pages. All of the enrollment forms can be customized with different colors, logos, and other designs.
To create custom enrollment forms, do the following:
1. Access the default enrollment form generated by the server through the profileList page; this page lists all of the forms without the default page formatting. For example: https://server.example.com:9443/ca/ee/ca/profileList
2. Click the profile that will be customized.
3. Right-click on the form, and select Save Page as from the menu. Give a new filename for the page, such as MyServerEnrollment.html
.
4. Move the saved web page to the CA's end entities directory, instance_directory /webapps/ca/ ee/ca directory.
5. Customize the form as desired.
6. The form can be accessed by going to https://server.example.com:9443/ca/ee/ca/
MyServerEnrollment.html
.
13.4. Certificate Profile Reference
A set of certificate profiles have been predefined for the types of certificates that are usually issued by a CA. All certificate profiles are installed with a CA. The default certificate profiles include the following:
• caAgentServerCert . For server certificates which allow automatically issuing server certificates with the validation of an agent's certificate.
• caAuditCert . For a signed audit signing certificate, used by a subsystem to sign the signed audit logs.
• caCACert . For a CA signing certificate.
• caDirUserCert . For end user certificates using directory-based authentication.
• caDomainController . For enrolling Windows domain controller certificates.
• caDualCert . For enrolling dual key pairs. Two keys are generated, a signing key and an encryption key, and two certificates are issued, one for each of those keys.
• caOCSPCert . For an OCSP signing certificate.
• caServerCert . For an SSL server certificate.
288
Input Reference
• caTransportCert . For a transport signing certificate, used by the DRM.
• caUserCert . For enrolling end user certificates.
13.5. Input Reference
An input puts certain fields on the enrollment page associated with a particular certificate profile.
The inputs set for a certificate profile are used to generate the enrollment page dynamically with the appropriate fields; these input fields collect necessary information for the profile to generate the final certificate.
13.5.1. Certificate Request Input
The Certificate Request input is used for enrollments in which a certificate request is pasted into the enrollment form. It allows the request format to be set from a drop-down list and provides an input field to paste the request.
This input puts the following fields in the enrollment form:
• Certificate Request Type . This drop-down menu lets the user specify the certificate request type.
The choices are PKCS #10, CRMF, and CMC.
• Certificate Request . This is the text area in which to paste the request.
13.5.2. CMC Certificate Request Input
The CMC Certificate Request input is used for enrollments using a Certificate Message over
CMS (CMC) certificate request is submitted in the request form. The request type is preset to CMC, and the only field is the Certificate Request text area in which to paste the request.
13.5.3. Dual Key Generation Input
The Dual Key Generation input is for enrollments in which dual key pairs will be generated, and thus two certificates issued, one for signing and one for encryption.
This input puts the following fields into the enrollment form:
• Key Generation Request Type . This field is a read-only field displaying crmf as the request type.
• Key Generation Request . This field is a read-only field displaying 1024 (Encryption), 1024
(Signing) as the key generation request.
13.5.4. File-Signing Input
The File-Signing input sets the fields to sign a file to show it has not been tampered with.
This input creates the following fields:
• Key Generation Request Type . This field is a read-only field displaying crmf as the request type.
• Key Generation Request . This field is a read-only field displaying 1024 (High-grade) as the key generation request.
• URL Of File Being Signed . This gives the location of the file which is to be signed.
289
Chapter 13. Certificate Profiles
• Text Being Signed . This gives the filename.
13.5.5. Image Input
The Image input sets the field to sign an image file. The only field which this input creates is Image
URL , which gives the location of the image which is to be signed.
13.5.6. Key Generation Input
The Key Generation input is used for enrollments in which a single key pair will be generated, generally user-based certificate enrollments.
This input puts the following fields into the enrollment form:
• Key Generation Request Type . This field is a read-only field displaying crmf as the request type.
• Key Generation Request . This field is a read-only field displaying 1024 (High Grade) as the key generation request.
13.5.7. nsHcertificateRequest (Token Key) Input
The Token Key input is used to enroll keys for hardware tokens for agents to use later for certificatebased authentication.
This input puts the following fields into the enrollment form:
• Token Key CUID . This field gives the CUID (contextually unique user ID) for the token device.
• Token Key User Public Key . This field gives the path and name of the file containing the token user's public key.
13.5.8. nsNcertificateRequest (Token User Key) Input
The Token User Key input is used to enroll keys for the user of a hardware token, for agents to use the token later for certificate-based authentication.
This input puts the following fields into the enrollment form:
• Token Key User UID . This field gives the UID for the LDAP entry of the user of the token device.
• Token Key User Public Key . This field gives the path and name of the file containing the token user's public key.
13.5.9. Subject DN Input
The Subject DN input allows the user to input the DN to set as the certificate subject name.
This input puts the following fields into the enrollment form:
• Subject Name . This field sets the subject DN to use for the certificate.
13.5.10. Subject Name Input
The Subject Name input is used for enrollment when DN parameters need to be collected from the user. The parameters are used to formulate the subject name in the certificate.
290
Submitter Information Input
This input puts the following fields into the enrollment form:
• UID (the LDAP directory user ID)
• Common Name (the name of the user)
• Organizational Unit (the organizational unit ( ou ) to which the user belongs)
• Organization (the organization name)
• Country (the country where the user is located)
13.5.11. Submitter Information Input
The Submitter Information input collects the certificate requester's information such as name, email, and phone.
This input puts the following fields into the enrollment form:
• Requester Name
• Requester Email
• Requester Phone
13.6. Output Reference
An output is the response to the end user of a successful enrollment.
13.6.1. Certificate Output
This output displays the certificate in pretty-print format. This output cannot be configured or changed.
It does not display anything other than the certificate in pretty-print format.
This output needs to be specified for any automated enrollment. Once a user successfully authenticates 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 end-entities page; there is no output page associated with agent-approved enrollment.
13.6.2. PKCS #7 Output
This output returns the certificate and the certificate chain in PKCS #7 format. PKCS #7 format is the
Cryptographic Message Syntax Standard, which is used for signing. This output cannot be configured or changed.
13.6.3. CMMF Output
This output returns the certificate in Certificate Management Messages Formats (CMMF). CMMF govern communication between different parts of a PKI and is used for requesting certificates and requesting certificate revocation.
291
Chapter 13. Certificate Profiles
13.7. Defaults Reference
Defaults are used to define the contents of a certificate. This section lists and defines the predefined defaults.
13.7.1. Authority Info Access Extension Default
This default attaches the Authority Info Access extension. This extension specifies how an application validating a certificate can access information, such as online validation services and CA statements, about the CA that has issued the certificate. This extension should not be used to point directly to the CRL location maintained by a CA; the CRL Distribution Points extension, Section 13.7.4, “CRL
Distribution Points Extension Default” , provides references to CRL locations.
For general information about this extension, see Section A.3.1, “authorityInfoAccess” .
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
This default can define up to five locations, with parameters for each location. The parameters are marked with an n in the table to show with which location the parameter is associated.
Parameter
Critical
Method_ n
LocationType_ n
292
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the access method for retrieving additional information about the CA that has issued the certificate in which the extension appears. This is one of the following values:
• ocsp (1.3.6.1.5.5.7.48.1).
• caIssuers (1.3.6.1.5.5.7.48.2)
• renewal (2.16.840.1.113730.16.1)
Specifies the general name type for the location that contains additional information about the CA that has issued the certificate. This is one of the following types:
• DirectoryName
• DNSName
• EDIPartyName
• IPAddress
• OID
• RFC822Name
• URIName
Parameter
Location_ n
Authority Key Identifier Extension Default
Enable_ n
Table 13.3. Authority Info Access Extension Default Configuration Parameters
13.7.2. Authority Key Identifier Extension Default
This default attaches the Authority Key Identifier extension to the certificate. The extension identifies the public key that corresponds to the private key used by a CA to sign certificates. This default has no parameters. If used, this extension is included in the certificate with the public key information.
This default takes the following constraint:
• No Constraints; see Section 13.8.6, “No Constraint” .
For general information about this extension, see Section A.3.2, “The authorityKeyIdentifier” .
293
Description
Specifies the address or location to get additional information about the CA that has issued the certificate.
• For directoryName , the value must be a string form of
X.500 name, similar to the subject name in a certificate.
For example, cn=SubCA, ou=Research Dept, o=Example
Corporation, c=US .
• For dNSName , the value must be a valid fully-qualified domain name. For example, testCA.example.com
.
• For EDIPartyName , the value must be an IA5String. For example, Example Corporation .
• For iPAddress , the value must be a valid IP address.
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 IPv 6 address with netmask is separated by a comma.
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 .
• For OID , the value must be a unique, valid OID specified in dot-separated numeric component notation. For example,
1.2.3.4.55.6.5.99
.
• For RFC822Name , the value must be a valid Internet mail address.
• For URIName , the value must be a non-relative universal resource identifier (URI) following the URL syntax and encoding rules. The name must include both a scheme, such as http , and a fully-qualified domain name or IP address of the host. For example, http:// ocspResponder.example.com:8000 .
Specifies whether this location is enabled. Select true to enable, false to disable.
Chapter 13. Certificate Profiles
13.7.3. Basic Constraints Extension Default
This default attaches the Basic Constraint extension to the certificate. The extension identifies whether the Certificate Manager is a CA. The extension is also used during the certificate chain verification process to identify CA certificates and to apply certificate chain-path length constraints.
For general information about this extension, see Section A.3.3, “basicConstraints” .
The following constraints can be defined with this default:
• Basic Constraints Extension Constraint; see Section 13.8.1, “Basic Constraints Extension
Constraint” .
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter
Critical
IsCA
PathLen
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies whether the certificate subject is a CA. With true , the server checks the PathLen parameter and sets the specified path length in the certificate. With false , the server treats the certificate subject as a non-CA and ignores the value specified for the PathLen parameter.
Specifies the path length, the maximum number of CA certificates that may be chained below (subordinate to) the subordinate CA certificate being issued. The path length affects the number of CA certificates to be used during certificate validation. The chain starts with the end-entity certificate being validated and moves up.
The maxPathLen parameter has no effect if the extension is set in end-entity certificates.
The permissible values are 0 or n . The value should be less than the path length specified in the Basic Constraints extension of the CA signing certificate. 0 specifies that no subordinate CA certificates are allowed below the subordinate
CA certificate; only an end-entity certificate may follow in the path. n must be an integer greater than zero. It specifies the maximum number of subordinate CA certificates allowed below the subordinate CA certificate.
If the field is blank, the path length defaults to a value that is determined by the path length set in the Basic Constraints extension in the issuer's certificate. If the issuer's path length is unlimited, the path length in the subordinate CA certificate will also be unlimited. If the issuer's path length is an integer greater than zero, the path length in the subordinate CA certificate will be set to a value that's one less than the issuer's
294
CRL Distribution Points Extension Default
Parameter
Table 13.4. Basic Constraints Extension Default Configuration Parameters
13.7.4. CRL Distribution Points Extension Default
This default attaches the CRL Distribution Points extension to the certificate. This extension identifies locations from which an application that is validating the certificate can obtain the CRL information to verify the revocation status of the certificate.
For general information about this extension, see Section A.3.5, “CRLDistributionPoints” .
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
This default defines up to five locations, with parameters for each location. The parameters are marked with an n in the table to show with which location the parameter is associated.
Parameter
Critical
Type_ n
Name_ n
Reasons_ n
295
Description path length; for example, if the issuer's path length is 4, the path length in the subordinate CA certificate will be set to 3.
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the type of CRL distribution point. The permissible values are DirectoryName , URIName , or
RelativeToIssuer . The type must correspond to the value in the Name field.
Specifies the name of the CRL distribution point, the name can be in any of the following formats:
• An X.500 directory name in the RFC 2253 syntax. The name looks similar to the subject name in a certificate, like cn=CA
Central, ou=Research Dept, o=Example Corporation, c=US .
• A URIName, such as http://testCA.example.com:80 .
• An RDN which specifies a location relative to the CRL issuer. In this case, the value of the Type attribute must be
RelativeToIssuer .
Specifies revocation reasons covered by the CRL maintained at the distribution point. Provide a comma-separated list of the following constants:
• unused
• keyCompromise
• cACompromise
• affiliationChanged
Chapter 13. Certificate Profiles
Parameter
IssuerType_ n
IssuerName_ n
296
Description
• superseded
• cessationOfOperation
• certificateHold
Specifies the naming type of the issuer that has signed the
CRL maintained at the distribution point. The issuer name can be in any of the following formats:
• RFC822Name
• DirectoryName
• DNSName
• EDIPartyName
• URIName
• IPAddress
• OIDName
• OtherName
Specifies the name format of the CRL issuer that signed the
CRL. The permissible values are as follows:
• For RFC822Name , the value must be a valid Internet mail address. For example, [email protected]
.
• For DirectoryName , the value must be a string form of
X.500 name, similar to the subject name in a certificate.
For example, cn=SubCA, ou=Research Dept, o=Example
Corporation, c=US .
• For DNSName , the value must be a valid fully-qualified domain name. For example, testCA.example.com
.
• For EDIPartyName , the value must be an IA5String. For example, Example Corporation .
• For URIName , the value must be a non-relative URI following the URL syntax and encoding rules. The name must include both a scheme, such as http , and a fully qualified domain name or IP address of the host. For example, http:// testCA.example.com
.
• For IPAddress , the value must be a valid IP address.
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 IPv 6 address with netmask is separated by a comma.
For example, 0:0:0:0:0:0:13.1.68.3
, FF01::43 ,
Parameter
Extended Key Usage Extension Default
Table 13.5. CRL Distribution Points Extension Configuration Parameters
13.7.5. Extended Key Usage Extension Default
This default attaches the Extended Key Usage extension to the certificate.
For general information about this extension, see Section A.3.6, “extKeyUsage” .
The extension identifies the purposes, in addition to the basic purposes indicated in the Key Usage extension, for which the certified public key may be used. For example, if the key usage extension identifies a signing key, the Extended Key Usage extension can narrow the usage of the key for only signing OCSP responses or only Java ™ applets.
Usage
Server authentication
Client authentication
Code signing
IPsec end system
IPsec tunnel
IPsec user
Timestamping
Table 13.6. PKIX Usage Definitions for the Extended Key Usage Extension
Windows 2000 can encrypt files on the hard disk, a feature known as encrypted file system (EFS), using certificates that contain the Extended Key Usage extension with the following two OIDs:
1.3.6.1.4.1.311.10.3.4 (EFS certificate)
1.3.6.1.4.1.311.10.3.4.1 (EFS recovery certificate)
297
Description
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 .
• For OIDName , the value must be a unique, valid OID specified in dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99
.
• OtherName is used for names with any other format; this supports PrintableString , IA5String ,
UTF8String , BMPString , Any , and KerberosName .
PrintableString , IA5String , UTF8String ,
BMPString , and Any set a string to a base-64 encoded file specifying the subtree, such as /var/lib/rhpkica/othername.txt
. KerberosName has the format
Realm|NameType|NameStrings , such as realm1|0| userID1,userID2 .
The value for this parameter must correspond to the value in the issuerName field.
OID
1.3.6.1.5.5.7.3.1
1.3.6.1.5.5.7.3.2
1.3.6.1.5.5.7.3.3
1.3.6.1.5.5.7.3.4
1.3.6.1.5.5.7.3.5
1.3.6.1.5.5.7.3.6
1.3.6.1.5.5.7.3.7
1.3.6.1.5.5.7.3.8
Chapter 13. Certificate Profiles
The EFS recovery certificate is used by a recovery agent when a user loses the private key and the data encrypted with that key needs to be used. Certificate System supports these two OIDs and allows certificates to be issued containing the Extended Key Usage extension with these OIDs.
Normal user certificates should be created with only the EFS OID, not the recovery OID.
The following constraints can be defined with this default:
• Extended Key Usage Constraint; see Section 13.8.2, “Extended Key Usage Extension Constraint” .
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter
Critical
OIDs
Table 13.7. Extended Key Usage Extension Default Configuration Parameters
13.7.6. Freshest CRL Extension Default
This default attaches the Freshest CRL extension to the certificate.
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
This default defines five locations with parameters for each location. The parameters are marked with an n in the table to show with which location the parameter is associated.
Parameter
Critical
PointEnable_ n
PointType_ n
298
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the OID that identifies a key-usage purpose. The permissible values are a unique, valid OID specified in the dot-separated numeric component notation. For example,
2.16.840.1.113730.1.99
. Depending on the key-usage purposes, the OIDs can be designated by PKIX (listed in
Table 13.6, “PKIX Usage Definitions for the Extended Key
Usage Extension” ) or custom OIDs. Custom OIDs must be in the registered subtree of IDs reserved for the company's use.
Although it is possible to use custom OIDs for evaluating and testing the Certificate System, in a production environment, comply with the ISO rules for defining OIDs and for registering subtrees of IDs. See Section A.2, “Note on Object Identifiers” for information on allocating private OIDs.
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Select true to enable this point; select false to disable this point.
Specifies the type of issuing point, either DirectoryName or
URIName .
Parameter
PointName_ n
PointIssuerName_ n
Freshest CRL Extension Default
Description
• If pointType is set to directoryName , the value must be an X.500 name, similar to the subject name in a certificate.
For example, cn=CACentral,ou=Research Dept,o=Example
Corporation,c=US .
• If pointType is set to URIName , the name must be a URI, an absolute pathname that specifies the host. For example, http://testCA.example.com/get/crls/here/ .
Specifies the name of the issuer that has signed the CRL. The name can be in any of the following formats:
• For RFC822Name , the value must be a valid Internet mail address. For example, [email protected]
.
• For DirectoryName , the value must be a string form of
X.500 name, similar to the subject name in a certificate.
For example, cn=SubCA, ou=Research Dept, o=Example
Corporation, c=US .
• For DNSName , the value must be a valid fully-qualified domain name. For example, testCA.example.com
.
• For EDIPartyName , the value must be an IA5String. For example, Example Corporation .
• For URIName , the value must be a non-relative URI following the URL syntax and encoding rules. The name must include both a scheme, such as http , and a fully qualified domain name or IP address of the host. For example, http:// testCA.example.com
.
• For IPAddress , the value must be a valid IP address.
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 IPv 6 address with netmask is separated by a comma.
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 .
• For OIDName , the value must be a unique, valid OID specified in dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99
.
• OtherName is used for names with any other format; this supports PrintableString ,
IA5String , UTF8String , BMPString , Any , and
KerberosName .
PrintableString , IA5String ,
UTF8String , BMPString , and Any set a string to a base-64 encoded file specifying the subtree, such as /var/
299
Chapter 13. Certificate Profiles
Parameter
PointType_ n
Table 13.8. Freshest CRL Extension Default Configuration Parameters
13.7.7. Issuer Alternative Name Extension Default
This default attaches the Issuer Alternative Name extension to the certificate. The Issuer Alternative
Name extension is used to associate Internet-style identities with the certificate issuer.
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
This default defines five locations with parameters for each location. The parameters are marked with an n in the table to show with which location the parameter is associated.
Parameter
Critical issuerAltExtType
300
Description lib/rhpki-ca/othername.txt
. KerberosName has the format Realm|NameType|NameStrings , such as realm1|0| userID1,userID2 .
The name value must comply with the format specified in
PointType_ .
Specifies the general name type of the CRL issuer that signed the CRL. The permissible values are as follows:
• RFC822Name
• DirectoryName
• DNSName
• EDIPartyName
• URIName
• IPAddress
• OIDName
• OtherName
The value for this parameter must correspond to the value in the PointIssuerName field.
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
This sets the type of name extension to be used, which can be one of the following:
• RFC822Name
• DirectoryName
• DNSName
Key Usage Extension Default
Parameter issuerAltExtPattern
Table 13.9. Issuer Alternative Name Extension Default Configuration Parameters
13.7.8. Key Usage Extension Default
This default attaches the Key Usage extension to the certificate. The extension specifies the purposes for which the key contained in a certificate should be used, such as data signing, key encryption, or data encryption, which restricts the usage of a key pair to predetermined purposes.
For general information about this extension, see Section A.3.8, “keyUsage” .
The following constraints can be defined with this default:
• Key Usage Constraint; see Section 13.8.5, “Key Usage Extension Constraint” .
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter critical digitalSignature nonRepudiation
301
Description
• EDIPartyName
• URIName
• IPAddress
• OIDName
Specifies the request attribute value to include in the extension. The attribute value must conform to any of the supported general name types. If the server finds the attribute in the request, it sets the attribute value in the extension and adds the extension to certificates. If multiple attributes are specified and none of the attributes are present in the request, the server does not add the Issuer Alternative Name extension to certificates. The permissible value is a request attribute included in the certificate request. For example,
$request.requester_email$ .
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies whether to allow signing SSL client certificates and
S/MIME signing certificates. Select true to set.
Specifies whether to use for S/MIME signing certificates.
Select true to set.
WARNING
Using this bit is controversial. Carefully consider the legal consequences of its use before setting it for any certificate.
Chapter 13. Certificate Profiles
Parameter keyEncipherment dataEncipherment keyAgreement keyCertsign cRLSign encipherOnly decipherOnly
Table 13.10. Key Usage Extension Default Configuration Parameters
13.7.9. Name Constraints Extension Default
This default attaches a Name Constraints extension to the certificate. The extension is used in CA certificates to indicate a name space within which the subject names or subject alternative names in subsequent certificates in a certificate chain should be located.
For general information about this extension, see Section A.3.9, “nameConstraints” .
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
This default defines up to five locations for both the permitted subtree and the excluded subtree and sets parameters for each location. The parameters are marked with an n in the table to show with which location the parameter is associated.
Parameter critical
PermittedSubtrees n .min
302
Description
Specifies whether to set the extension for SSL server certificates and S/MIME encryption certificates. Select true to set.
Specifies whether to set the extension when the subject's public key is used to encipher user data as opposed to key material. Select true to set.
Specifies whether to set the extension whenever the subject's public key is used for key agreement. Select true to set.
Specifies whether to use the extension for all CA signing certificates. Select true to set.
Specifies whether to set the extension for CA signing certificates that sign CRLs. Select true to set.
Specifies whether to set the extension if the public key is only for encrypting data. If this bit is set, keyAgreement should also be set. Select true to set.
Specifies whether to set the extension if the public key is only for decrypting data. If this bit is set, keyAgreement should also be set. Select true to set.
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the minimum number of permitted subtrees.
• -1 specifies that the field should not be set in the extension.
• 0 specifies that the minimum number of subtrees is zero.
• n must be an integer that is greater than zero. It sets the minimum required number of subtrees.
Parameter
PermittedSubtreesmax_ n
PermittedSubtreeNameChoice_ n
Name Constraints Extension Default
PermittedSubtreeNameValue_ n
Description
Specifies the maximum number of permitted subtrees.
• -1 specifies that the field should not be set in the extension.
• 0 specifies that the maximum number of subtrees is zero.
• n must be an integer that is greater than zero. It sets the maximum number of subtrees allowed.
Specifies the general name type for the permitted subtree to include in the extension. The permissible values are as follows:
• RFC822Name
• DirectoryName
• DNSName
• EDIPartyName
• URIName
• IPAddress
• OIDName
• OtherName
Specifies the general name value for the permitted subtree to include in the extension.
• For RFC822Name , the value must be a valid Internet mail address. For example, [email protected]
.
• For DirectoryName , the value must be a string form of
X.500 name, similar to the subject name in a certificate.
For example, cn=SubCA, ou=Research Dept, o=Example
Corporation, c=US .
• For DNSName , the value must be a valid fully-qualified domain name. For example, testCA.example.com
.
• For EDIPartyName , the value must be an IA5String. For example, Example Corporation .
• For URIName , the value must be a non-relative URI following the URL syntax and encoding rules. The name must include both a scheme, such as http , and a fully qualified domain name or IP address of the host. For example, http:// testCA.example.com
.
• For IPAddress , the value must be a valid IP address.
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 IPv 6 address with netmask is separated by a comma.
303
Chapter 13. Certificate Profiles
Parameter
PermittedSubtreeEnable_ n
ExcludedSubtrees n .min
ExcludedSubtreeMax_ n
ExcludedSubtreeNameChoice_ n
304
Description
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 .
• For OIDName , the value must be a unique, valid OID specified in dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99
.
• OtherName is used for names with any other format; this supports PrintableString , IA5String ,
UTF8String , BMPString , Any , and KerberosName .
PrintableString , IA5String , UTF8String ,
BMPString , and Any set a string to a base-64 encoded file specifying the subtree, such as /var/lib/rhpkica/othername.txt
. KerberosName has the format
Realm|NameType|NameStrings , such as realm1|0| userID1,userID2 .
Select true to enable this permitted subtree entry.
Specifies the minimum number of excluded subtrees.
• -1 specifies that the field should not be set in the extension.
• 0 specifies that the minimum number of subtrees is zero.
• n must be an integer that is greater than zero. This sets the minimum number of required subtrees.
Specifies the maximum number of excluded subtrees.
• -1 specifies that the field should not be set in the extension.
• 0 specifies that the maximum number of subtrees is zero.
• n must be an integer that is greater than zero. This sets the maximum number of allowed subtrees.
Specifies the general name type for the excluded subtree to include in the extension. The permissible values are as follows:
• RFC822Name
• DirectoryName
• DNSName
• EDIPartyName
• URIName
• IPAddress
• OIDName
• OtherName
Parameter
ExcludedSubtreeNameValue_ n
Name Constraints Extension Default
Description
Specifies the general name value for the permitted subtree to include in the extension.
• For RFC822Name , the value must be a valid Internet mail address. For example, [email protected]
.
• For DirectoryName , the value must be an X.500 name, similar to the subject name in a certificate. For example, cn=SubCA, ou=Research Dept, o=Example Corporation, c=US .
• For DNSName , the value must be a valid fully-qualified domain name. For example, testCA.example.com
.
• For EDIPartyName , the value must be an IA5String. For example, Example Corporation .
• For URIName , the value must be a non-relative URI following the URL syntax and encoding rules. The name must include both a scheme, such as http , and a fully qualified domain name or IP address of the host. For example, http:// testCA.example.com
.
• For IPAddress , the value must be a valid IP address.
An IPv4 address must be in n.n.n.n
format, with netmask in n.n.n.n,m.m.m.m
format. For example,
128.21.39.40
, 128.21.39.40,255.255.255.00
. An IPv
6 address with netmask is separated by a comma.
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 .
• For OIDName , the value must be a unique, valid OID specified in dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99
.
• For OtherName , the values are names with any other format. This supports PrintableString , IA5String ,
UTF8String , BMPString , Any , and KerberosName .
PrintableString , IA5String , UTF8String ,
BMPString , and Any set a string which specifies the path to a file containing the base-64 encoded string of the subtree, such as /var/lib/rhpki-ca/othername.txt
.
KerberosName has the format Realm|NameType|
NameStrings , such as realm1|0|userID1,userID2 .
Select true to enable this excluded subtree entry.
ExcludedSubtreeEnable_ n
Table 13.11. Name Constraints Extension Default Configuration Parameters
305
Chapter 13. Certificate Profiles
13.7.10. Netscape Certificate Type Extension Default
WARNING
This extension is obsolete. Use the Key Usage or Extended Key Usage certificate extensions instead.
This default attaches a Netscape Certificate Type extension to the certificate. The extension identifies the certificate type, such as CA certificate, server SSL certificate, client SSL certificate, or S/MIME certificate. This restricts the usage of a certificate to predetermined purposes.
13.7.11. Netscape Comment Extension Default
WARNING
This extension is obsolete.
This default attaches a Netscape Comment extension to the certificate. The extension can be used to include textual comments in certificates. Applications that are capable of interpreting the comment display it when the certificate is used or viewed.
For general information about this extension, see Section A.6.2, “netscape-comment” .
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter critical
CommentContent
Table 13.12. Netscape Comment Extension Configuration Parameters
13.7.12. No Default Extension
This default can be used to set constraints when no defaults are being used. This default has no settings and sets no defaults but does allow all of the constraints available to be set.
13.7.13. OCSP No Check Extension Default
This default attaches an OCSP No Check extension to the certificate. The extension, which should be used in OCSP responder certificates only, indicates how OCSP-compliant applications can verify the revocation status of the certificate an authorized OCSP responder uses to sign OCSP responses.
For general information about this extension, see Section A.3.10, “OCSPNocheck” .
306
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the content of the comment to appear in the certificate.
Policy Constraints Extension Default
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter critical
Table 13.13. OCSP No Check Extension Default Configuration Parameters
13.7.14. Policy Constraints Extension Default
This default attaches a Policy Constraints extension to the certificate. The extension, which can be used in CA certificates only, constrains path validation in two ways: either to prohibit policy mapping or to require that each certificate in a path contain an acceptable policy identifier. The default can specify both, ReqExplicitPolicy and InhibitPolicyMapping . PKIX standard requires that, if present in a CA certificate, the extension must never consist of a null sequence. At least one of the two specified fields must be present.
For general information about this extension, see Section A.3.11, “policyConstraints” .
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter critical reqExplicitPolicy inhibitPolicyMapping
307
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the total number of certificates permitted in the path before an explicit policy is required. This is the number of CA certificates that can be chained below the subordinate CA certificate before an acceptable policy is required.
• -1 specifies that the field should not be set in the extension.
• 0 specifies that no subordinate CA certificates are permitted in the path before an explicit policy is required.
• n must be an integer that is greater than zero. It specifies the maximum number of subordinate CA certificates allowed in the path before an explicit policy is required.
This number affects the number of CA certificates to be used during certificate validation. The chain starts with the endentity certificate being validated and moving up the chain. The parameter has no effect if the extension is set in end-entity certificates.
Specifies the total number of certificates permitted in the path before policy mapping is no longer permitted.
Chapter 13. Certificate Profiles
Parameter
Table 13.14. Policy Constraints Extension Default Configuration Parameters
13.7.15. Policy Mappers Extension Default
This default attaches a Policy Mappings extension to the certificate. The extension lists pairs of OIDs, each pair identifying two policy statements of two CAs. The pairing indicates that the corresponding policies of one CA are equivalent to policies of another CA. The extension may be useful in the context of cross-certification. If supported, the extension is included in CA certificates only. The default maps policy statements of one CA to that of another by pairing the OIDs assigned to their policy statements
Each pair is defined by two parameters, issuerDomainPolicy and subjectDomainPolicy .
The pairing indicates that the issuing CA considers the issuerDomainPolicy equivalent to the subjectDomainPolicy of the subject CA. The issuing CA's users may accept an issuerDomainPolicy for certain applications. The policy mapping tells these users which policies associated with the subject CA are equivalent to the policy they accept.
For general information about this extension, see Section A.3.12, “policyMappings” .
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter critical
IssuerDomainPolicy_ n
SubjectDomainPolicy_ n
Table 13.15. Policy Mappings Extension Default Configuration Parameters
13.7.16. Signing Algorithm Default
This default attaches a signing algorithm in the certificate request. This default presents an agent with the possible algorithms that can be used for signing the certificate.
308
Description
• -1 specifies that the field should not be set in the extension.
• 0 specifies that no subordinate CA certificates are permitted in the path before policy mapping is no longer permitted.
• n must be an integer that is greater than zero. It specifies at the maximum number of subordinate CA certificates allowed in the path before policy mapping is no longer permitted.
For example, a value of 1 indicates that policy mapping may be processed in certificates issued by the subject of this certificate, but not in additional certificates in the path.
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the OID assigned to the policy statement of the issuing CA to map with the policy statement of another CA. For example, 1.2.3.4.5
.
Specifies the OID assigned to the policy statement of the subject CA that corresponds to the policy statement of the issuing CA. For example, 6.7.8.9.10
.
Subject Alternative Name Extension Default
The following constraints can be defined with this default:
• Signing Algorithm Constraint; see Section 13.8.8, “Signing Algorithm Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter signingAlgsAllowed signingAlg
Table 13.16. Signing Algorithm Default Configuration Parameters
13.7.17. Subject Alternative Name Extension Default
This default attaches a Subject Alternative Name extension to the certificate. The extension binds additional identities, such as an email address, a DNS name, an IP address, or a URI, to the subject of the certificate. The standard requires that if the certificate subject field contains an empty sequence, then the Subject Alternative name extension must contain the subject's alternative name and that the extension be marked critical.
For any of the directory-based authentication methods, the Certificate System can retrieve values for any string and byte attributes and set them in the certificate request. These attributes are set by entering them in the ldapStringAttributes and ldapByteAttributes fields defined in the automated enrollment modules.
If authenticated attributes need to be part of this extension, use values from the $request token.
For example, to enable the Subject Alternative Name extension in the caDirUserCert profile for the mail LDAP attribute for the user to authenticate against to obtain a certificate, use the following configuration: policyset.serverCertSet.9.constraint.name=No Constraint policyset.serverCertSet.9.default.class_id=subjectAltNameExtDefaultImpl policyset.serverCertSet.9.default.name=Subject Alternative Name Extension Default policyset.serverCertSet.9.default.params.subjAltExtGNEnable_0=true policyset.serverCertSet.9.default.params.subjAltExtGNEnable_1=true policyset.serverCertSet.9.default.params.subjAltExtGNEnable_2=true policyset.serverCertSet.9.default.params.subjAltExtGNEnable_3=false policyset.serverCertSet.9.default.params.subjAltExtGNEnable_4=false policyset.serverCertSet.9.default.params.subjAltExtPattern_0=$request.requester_email$ policyset.serverCertSet.9.default.params.subjAltExtPattern_1=$request.SAN1$ policyset.serverCertSet.9.default.params.subjAltExtPattern_2=http://www.server.example.com
policyset.serverCertSet.9.default.params.subjAltExtPattern_3= policyset.serverCertSet.9.default.params.subjAltExtPattern_4=
309
Description
Specify the signing algorithms that can be used for signing this certificate. The algorithms can be any or all of the following:
• MD2withRSA
• MD5withRSA
• SHA1withRSA
• SHA256withRSA
• SHA512withRSA
Specify the default signing algorithm to be used to create this certificate. An agent can override this value by specifying one of the values contained in the signingAlgsAllowed parameter.
Chapter 13. Certificate Profiles policyset.serverCertSet.9.default.params.subjAltExtType_0=RFC822Name policyset.serverCertSet.9.default.params.subjAltExtType_1=DNSName policyset.serverCertSet.9.default.params.subjAltExtType_2=URIName policyset.serverCertSet.9.default.params.subjAltExtType_3=RFC822Name policyset.serverCertSet.9.default.params.subjAltExtType_4=RFC822Name policyset.serverCertSet.9.default.params.subjAltNameExtCritical=false policyset.serverCertSet.9.default.params.subjAltNameNumGNs=3
Example 13.1. Default Subject Alternative Name Extension Configuration
The Subject Alternative Name extension profile checks the certificate request for the policy attributes.
If the request contains an attribute, the profile reads its value and sets it in the extension. The extension added to the certificates contain all the configured attributes.
Multiple attributes can be set for a single extension. Up to five subject alternative names can be set; the subjAltNameNumGNs parameter controls how many of the listed attributes are required to be added to the certificate. This parameter must be added to custom profiles and may need modified in default profiles to include as many attributes as required. In Example 13.1, “Default Subject Alternative
Name Extension Configuration” , the subjAltNameNumGNs is set to 3 to insert the RFC822Name ,
DNSName , and URIName names (generic names _0 , _1 , and _2 ).
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter
Critical
Pattern
Type
310
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
Specifies the request attribute value to include in the extension. The attribute value must conform to any of the supported general name types. If the server finds the attribute in the request, it sets the attribute value in the extension and adds the extension to certificates. If multiple attributes are specified and none of the attributes are present in the request, the server does not add the Subject Alternative Name extension to certificates. The permissible value is a request attribute included in the certificate request. For example,
$request.requester_email$ .
Specifies the general name type for the request attribute.
• Select RFC822Name if the request-attribute value is an email address in the local-part@domain format. For example, [email protected]
• Select DirectoryName if the request-attribute value is an X.500 directory name, similar to the subject name in a certificate. For example, cn=Jane Doe, ou=Sales Dept, o=Example Corporation, c=US .
• Select DNSName if the request-attribute value is a DNS name. For example, corpDirectory.example.com
.
Parameter
Subject Directory Attributes Extension Default
Table 13.17. Subject Alternative Name Extension Default Configuration Parameters
13.7.18. Subject Directory Attributes Extension Default
This default attaches a Subject Directory Attributes extension to the certificate. The Subject Directory
Attributes extension conveys any desired directory attribute values for the subject of the certificate.
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter
Critical
Name
Pattern
311
Description
• Select EDIPartyName if the request-attribute value is an
EDI party name. For example, Example Corporation .
• Select URIName if the request-attribute value is a nonrelative URI that includes both a scheme, such as http , and a fully qualified domain name or IP address of the host. For example, http://hr.example.com
.
• Select IPAddress if the request-attribute value is a valid
IP address specified in dot-separated numeric component notation. For example, 128.21.39.40
.
• Select OIDName if the request-attribute value is a unique, valid OID specified in the dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99
.
• Select OtherName for names with any other format.
This supports PrintableString , IA5String ,
UTF8String , BMPString , Any , and KerberosName .
PrintableString , IA5String , UTF8String ,
BMPString , and Any are a string which specifies the path to a base-64 encoded file which sets the subtree, such as / var/lib/rhpki-ca/othername.txt
. KerberosName has the format Realm|NameType|NameStrings , such as realm1|0|userID1,userID2 .
Description
Select true to mark this extension critical; select false to mark the extension noncritical.
The attribute name; this can be any LDAP directory attribute, such as cn or mail .
Specifies the request attribute value to include in the extension. The attribute value must conform to the allowed values of the attribute. If the server finds the attribute, it sets the attribute value in the extension and adds the extension to certificates. If multiple attributes are specified and none of the attributes are present in the request, the server does not add the Subject Directory Attributes extension to certificates. For example, $request.requester_email$ .
Chapter 13. Certificate Profiles
Parameter
Enable
Table 13.18. Subject Directory Attributes Extension Default Configuration Parameters
13.7.19. Subject Key Identifier Extension Default
This default attaches a Subject Key Identifier extension to the certificate. The extension identifies certificates that contain a particular public key, which identifies a certificate from among several that have the same subject name.
For general information about this extension, see Section A.3.16, “subjectKeyIdentifier” .
If enabled, the profile adds a Subject Key Identifier Extension to an enrollment request if the extension does not already exist. If the extension exists in the request, such as a CRMF request, the default replaces the extension. After an agent approves the manual enrollment request, the profile accepts any Subject Key Identifier Extension that is already there.
This default has no parameters. If used, this extension is included in the certificate with the public key information.
The following constraints can be defined with this default:
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
13.7.20. Subject Name Default
This default attaches a server-side configurable subject name to the certificate request. A static subject name is used as the subject name in the certificate.
The following constraints can be defined with this default:
• Subject Name Constraint; see Section 13.8.9, “Subject Name Constraint” .
• Unique Subject Name Constraint; see Section 13.8.10, “Unique Subject Name Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
Parameter
Name
Table 13.19. Subject Name Default Configuration Parameters
If you need to get a certificate subject name that uses the DNPATTERN value from the UidPwdDirAuth plugin, then configure the profile to use the Subject Name Default plugin and substitute the Name parameter with the "Subject Name" from the AuthToken as shown below.
policyset.userCertSet.1.default.class_id=subjectNameDefaultImpl policyset.userCertSet.1.default.name=Subject Name Default policyset.userCertSet.1.default.params.name=$request.auth_token.tokenCertSubject$
312
Description
Sets whether that attribute is able to be added to the certificate. Select true to enable the attribute.
Description
Specify the subject name for this certificate.
Token Supplied Subject Name Default
13.7.21. Token Supplied Subject Name Default
This default profile populates subject names based on the attribute values in the authentication token
(AuthToken) object.
This default plug-in works with the directory-based authentication manager. The Directory-Based User
Dual-Use Certificate Enrollment certificate profile has two input parameters, UID and password. The directory-based authentication manager checks if the given UID and password are correct.
In addition, the directory-based authentication manager formulates the subject name of the issuing certificate. It forms the subject name by using the user's DN value from AuthToken .
This default is responsible for reading the subject name from the AuthToken and placing it in the certificate request so that the final certificate contains the subject name.
The following constraints can be defined with this default:
• No Constraints; see Section 13.8.6, “No Constraint” .
13.7.22. User Supplied Extension Default
The User Supplied Extension Default class populates a certificate with any certificate extension defined by the user in the certificate request. This requires users to submit certificate requests which meet certain standards or give certain information because the profile can require specific extensions before enrolling a certificate.
The user-defined extension is validated against whatever constraint is set, so it is possible to restrict the kind of extension (through the Extension Constraint) or to set rules for the key and other basic constraints, such as whether this is a CA certificate.
NOTE
If this extension is set on a profile with a corresponding OID (Extension Constraint), then any certificate request processed through that profile must carry the specified extension or the request is rejected.
If a certificate profile was enabled with the User Supplied Extension Default before the errata RHSA 2008:0500, then this profile must be edited to support user supplied extensions in certificate requests. Apply the userExtensionDefaultImpl default, as shown in the example. The given OID is for the Basic Constraints Extension Constraint.
policyset.set1.p6.default.class_id=userExtensionDefaultImpl policyset.set1.p6.default.name=User Supplied Extension Default policyset.set1.p6.default.params.userExtOID=2.5.29.19
The CA handles an enrollment with the User Supplied Extension Default in one of three ways:
• If the OID of the extension is specified in both the certificate request and the default, then the extension is validated by the constraints and applied to the certificate.
• If an OID of an extension is given in the request but is not specified in the User Supplied Extension
Default in the profile, then the user-specified extension is ignored, and the certificate is successfully enrolled without that extension.
313
Chapter 13. Certificate Profiles
• If this extension is set on a profile with a corresponding OID (Extension Constraint), then any certificate request processed through that profile must carry the specified extension or the request is rejected.
A certificate request that contains the user-defined extensions must be submitted to the profile. The certificate enrollment forms, however, do not have any input fields for users to add user-supplied extensions. Submitting a certificate request without supplying the extension fails.
The following constraints can be defined with this default:
• Basic Constraints Extension Constraint; see Section 13.8.1, “Basic Constraints Extension
Constraint” .
• Extended Key Usage Constraint; see Section 13.8.2, “Extended Key Usage Extension Constraint” .
• Extension Constraint; see Section 13.8.3, “Extension Constraint” .
• Key Constraints; see Section 13.8.4, “Key Constraint” .
• Netscape Certificate Type Extension Constraint; see Section 13.8.7, “Netscape Certificate Type
Extension Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
This example adds the User Supplied Extension Default to a profile with the Basic Constraints
Extension Constraint. The OID specified in the userExtOID parameter is for the Basic Constraints
Extension Constraint.
policyset.set1.p5.default.params.keyUsageNonRepudiation=true policyset.set1.p6.constraint.class_id=basicConstraintsExtConstraintImpl policyset.set1.p6.constraint.name=Basic Constraint Extension Constraint policyset.set1.p6.constraint.params.basicConstraintsCritical=true policyset.set1.p6.constraint.params.basicConstraintsIsCA=false policyset.set1.p6.constraint.params.basicConstraintsMinPathLen=-1 policyset.set1.p6.constraint.params.basicConstraintsMaxPathLen=-1 policyset.set1.p6.default.class_id=userExtensionDefaultImpl policyset.set1.p6.default.name=User Supplied Extension Default policyset.set1.p6.default.params.userExtOID=2.5.29.19
Editing profiles is described in Section 13.3.2, “Modifying Certificate Profiles through the Command
Line” .
13.7.23. User Supplied Key Default
This default attaches a user-supplied key into the certificate request. This is a required default. Keys are part of the enrollment request.
The following constraints can be defined with this default:
• Key Constraint; see Section 13.8.4, “Key Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
314
User Signing Algorithm Default
13.7.24. User Signing Algorithm Default
This default implements an enrollment default profile that populates a user-supplied signing algorithm in the certificate request. If included in the certificate profile, this allows a user to choose a signing algorithm for the certificate, subject to the constraint set.
No inputs are provided to add signing algorithm choices to the enrollment form. It is also possible to submit a request that contains this information.
The following constraints can be defined with this default:
• Signing Algorithm Constraint; see Section 13.8.8, “Signing Algorithm Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
13.7.25. User Supplied Subject Name Default
This default attaches a user-supplied subject name to the certificate request. If included in the certificate profile, it allows a user to supply a subject name for the certificate, subject to the constraints set. This extension preserves the subject name that is specified in the original certificate request when the certificate is issued.
The following constraints can be defined with this default:
• Subject Name Constraint; see Section 13.8.9, “Subject Name Constraint” .
• Unique Subject Name Constraint; see Section 13.8.10, “Unique Subject Name Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
13.7.26. User Supplied Validity Default
This default attaches a user-supplied validity to the certificate request. If included in the certificate profile, it allows a user to supply the validity period, subject to the constraints set. This default profile preserves that user-defined validity in the original certificate request when the certificate is issued.
No inputs are provided to add user-supplied validity date to the enrollment form. It is also possible to submit a request that contains this information.
The following constraints can be defined with this default:
• Validity Constraint; see Section 13.8.11, “Validity Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
13.7.27. Validity Default
This default attaches a server-side configurable validity into the certificate request.
The following constraints can be defined with this default:
• Validity Constraint; see Section 13.8.11, “Validity Constraint” .
• No Constraints; see Section 13.8.6, “No Constraint” .
315
Chapter 13. Certificate Profiles
Parameter range
Table 13.20. Validity Default Configuration Parameters
13.8. Constraints Reference
Constraints are used to define the allowable contents of a certificate and the values associated with that content. This section lists the predefined constraints with complete definitions of each.
13.8.1. Basic Constraints Extension Constraint
The Basic Constraints extension constraint checks if the basic constraint in the certificate request satisfies the criteria set in this constraint.
Parameter
Critical
IsCA
PathLen
Description
Specifies the validity period for this certificate.
Description
Specifies whether the extension can be marked critical or noncritical. Select true to allow this extension to be mark critical; select false to prevent this extension from being marked critical.
Specifies whether the certificate subject is a CA. Select true to allow a value of true for this parameter; select false to disallow a value of true for this parameter; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies the maximum allowable path length, the maximum number of CA certificates that may be chained below
(subordinate to) the subordinate CA certificate being issued.
The path length affects the number of CA certificates used during certificate validation. The chain starts with the end-entity certificate being validated and moves up.
This parameter has no effect if the extension is set in endentity certificates.
The permissible values are 0 or n . The value must be less than the path length specified in the Basic Constraints extension of the CA signing certificate.
0 specifies that no subordinate CA certificates are allowed below the subordinate CA certificate being issued; only an endentity certificate may follow in the path.
n must be an integer greater than zero. This is the maximum number of subordinate CA certificates allowed below the subordinate CA certificate being used.
If the field is blank, the path length defaults to a value determined by the path length set on the Basic Constraints extension in the issuer's certificate. If the issuer's path length is unlimited, the path length in the subordinate CA certificate is also unlimited. If the issuer's path length is an integer greater than zero, the path length in the subordinate CA certificate
316
Extended Key Usage Extension Constraint
Parameter
Table 13.21. Basic Constraints Extension Constraint Configuration Parameters
13.8.2. Extended Key Usage Extension Constraint
The Extended Key Usage extension constraint checks if the Extended Key Usage extension on the certificate satisfies the criteria set in this constraint.
Parameter
Critical exKeyUsageOIDs
Table 13.22. Extended Key Usage Extension Constraint Configuration Parameters
13.8.3. Extension Constraint
This constraint implements the general extension constraint. It checks if the extension is present.
13.8.4. Key Constraint
This constraint checks the key length.
Parameter keyType keyMinLength keyMaxLength
Table 13.23. Key Constraint Configuration Parameters
13.8.5. Key Usage Extension Constraint
The Key Usage extension constraint checks if the key usage constraint in the certificate request satisfies the criteria set in this constraint.
Parameter critical digitalSignature nonRepudiation
317
Description is set to a value one less than the issuer's path length; for example, if the issuer's path length is 4, the path length in the subordinate CA certificate is set to 3.
Description
Specifies whether the extension can be marked critical or noncritical. Select true to mark the extension critical; select false to mark it noncritical.
Specifies the allowable OIDs that identifies a key-usage purpose. Multiple OIDs can be added in a comma-separated list.
Description
Gives a key type; this is set to by default and uses an RSA key system.
Specifies the minimum allowable key length.
Specifies the maximum allowable key length.
Description
Select true to mark this as critical; select false to mark it noncritical.
Specifies whether to sign SSL client certificates and S/MIME signing certificates. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether to set S/MIME signing certificates. Select true to allow this to be set; select false to keep this from
Chapter 13. Certificate Profiles
Parameter keyEncipherment dataEncipherment keyAgreement keyCertsign cRLSign encipherOnly decipherOnly
Table 13.24. Key Usage Extension Constraint Configuration Parameters
318
Description being set; select a hyphen, , to indicate no constraints are placed for this parameter.
WARNING
Using this bit is controversial. Carefully consider the legal consequences of its use before setting it for any certificate.
Specifies whether to set the extension for SSL server certificates and S/MIME encryption certificates. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether to set the extension when the subject's public key is used to encrypt user data, instead of key material.
Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether to set the extension whenever the subject's public key is used for key agreement. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether the extension applies for all CA signing certificates. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether to set the extension for CA signing certificates that are used to sign CRLs. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether to set the extension if the public key is to be used only for encrypting data. If this bit is set, keyAgreement should also be set. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
Specifies whether to set the extension if the public key is to be used only for deciphering data. If this bit is set, keyAgreement should also be set. Select true to allow this to be set; select false to keep this from being set; select a hyphen, , to indicate no constraints are placed for this parameter.
No Constraint
13.8.6. No Constraint
This constraint implements no constraint. When chosen along with a default, there are not constraints placed on that default.
13.8.7. Netscape Certificate Type Extension Constraint
WARNING
This constraint is obsolete. Instead of using the Netscape Certificate Type extension constraint, use the Key Usage extension or Extended Key Usage extension.
The Netscape Certificate Type extension constraint checks if the Netscape Certificate Type extension in the certificate request satisfies the criteria set in this constraint.
13.8.8. Signing Algorithm Constraint
The Signing Algorithm constraint checks if the signing algorithm in the certificate request satisfies the criteria set in this constraint.
Parameter signingAlgsAllowed
Table 13.25. Signing Algorithms Constraint Configuration Parameters
13.8.9. Subject Name Constraint
The Subject Name constraint checks if the subject name in the certificate request satisfies the criteria.
Parameter
Pattern
Table 13.26. Subject Name Constraint Configuration Parameters
The Subject Name constraint supports all regular-expression constructs listed in http://java.sun.com/ j2se/1.4.1/docs/api/java/util/regex/Pattern.html
. This allows wildcards such as asterisks ( * ) to search for any number of the characters and periods ( .
)to search for any type character.
For example, if the pattern of the subject name constraint is set to uid=.* , the certificate profile framework checks if the subject name in the certificate request matches the pattern. A subject name
319
Description
Sets the signing algorithms that can be specified to sign the certificate. The algorithms can be any or all of the following:
• MD2withRSA
• MD5withRSA
• SHA1withRSA
• SHA256withRSA
• SHA512withRSA
The algorithm can also be set to , which means the server picks the best available signing algorithm that is compatible with the key type (RSA).
Description
Specifies a regular expression as a string.
Chapter 13. Certificate Profiles like uid=user, o=Example, c=US satisfies the pattern uid=.* . The subject name cn=user, o=example,c=US does not satisfy the pattern. uid=.* means the subject name must begin with the uid attribute; the period-asterisk ( .* ) wildcards allow any type and number of characters to follow uid .
It is possible to require internal patterns, such as .*ou=Engineering.* , which requires the ou=Engineering attribute with any kind of string before and after it. This matches cn=jdoe,ou=internal,ou=west coast,ou=engineering,o="Example Corp",st=NC as well as uid=bjensen,ou=engineering,dc=example,dc=com .
Lastly, it is also possible to allow requests that are either one string or another by setting a pipe sign ( | ) between the options. For example, to permit subject names that contain either ou=engineering,ou=people or ou=engineering,o="Example Corp" , the pattern is
.*ou=engineering,ou=people.* | .*ou=engineering,o="Example Corp".* .
NOTE
For constructing a pattern which uses a special character, such as a period ( .
), escape the character with a back slash ( \ ). For example, to search for the string o="Example
Inc." , set the pattern to o="Example Inc\." .
13.8.10. Unique Subject Name Constraint
The Unique Subject Name constraint restricts the server from issuing multiple certificates with the same subject names. When a certificate request is submitted, the server automatically checks the nickname against other issued certificate nicknames. This constraint can be applied to certificate enrollment through the end-entities' page.
The Unique Subject Name constraint has no configuration parameters.
13.8.11. Validity Constraint
The Validity constraint checks if the validity in the certificate request satisfies the criteria.
Parameter range
Table 13.27. Validity Constraint Configuration Parameters
320
Description
The range of the validity period. This is an integer which set the number of days.
Chapter 14.
Revocation and CRLs
The Certificate System provides methods for revoking certificates and for producing lists of revoked certificates, called certificate revocation lists (CRLs). This chapter describes the methods for revoking a certificate, describes CMC revocation, and provides details about CRLs and setting up CRLs.
14.1. Revocation
Certificates can be revoked by an end user (the original owner of the certificate) or by a Certificate
Manager agent. End users can revoke certificates by using the revocation form provided in the endentities page. Agents can revoke end-entity certificates by using the appropriate form in the agent services interface. Certificate-based (SSL client authentication) is required in both cases.
An end user can revoke only certificates that contain the same subject name as the certificate presented for authentication. After successful authentication, the server lists the certificates belonging to the end user. The end user can then select the certificate to be revoked or can revoke all certificates in the list. The end user can also specify additional details, such as the date of revocation and revocation reason for each certificate or for the list as a whole.
Agents can revoke certificates based on a range of serial numbers or based on subject name components. When the revocation request is submitted, agents receive a list of certificates from which they can pick the ones to be revoked. For instructions on how agents revoke end-entity certificates, see the Certificate System Agent's Guide .
When it receives the CRL, the Certificate Manager marks the corresponding certificate records in its internal database as revoked, and, if configured to do so, removes the revoked certificates from the publishing directory and updates the CRL in the publishing directory.
14.1.1. SSL Client Authenticated Revocation
When an end user submits a certificate revocation request, the first step in the revocation process is for the Certificate Manager to identify and authenticate the end user to verify that the user is attempting to revoke his own certificate, not a certificate belonging to someone else.
In SSL client authentication, the server expects the end user to present a certificate that has the same subject name as the one to be revoked and uses that for authentication purposes. The server verifies the authenticity of a revocation request by mapping the subject name in the certificate presented for client authentication to certificates in its internal database. The server revokes the certificate only if the certificate maps successfully to one or more valid or expired certificates in its internal database.
After successful authentication, if the server detects only one valid or expired certificate matching the subject name of the one presented for client authentication, it revokes the certificate. If the server detects more than one valid or expired certificate with a matching subject name, it lists all those certificates. The user can then either select the certificate to be revoked or revoke all certificates in the list.
14.1.2. Certificate Revocation Forms
The end-entities page of the Certificate Manager includes default HTML forms for SSL client authenticated revocation. The forms are accessible from the Revocation tab. The form for SSL client authenticated-revocation is shown by clicking the User Certificate link.
321
Chapter 14. Revocation and CRLs
To change the form appearance to suit an organization's requirements, edit the
UserRevocation.html
, the form that allows SSL client authenticated revocation of client or personal certificates. The file is the in /var/lib/ instance_ID /webapps/ subsystem_type / ee/ subsystem_type directory.
14.2. CMC Revocation
CMC revocation allows users to set up a revocation client, sign the revocation request with an agent certificate, and then send the signed request to the Certificate Manager. When this method is used, the Certificate Manager automatically issues certificates when a valid certificate request signed with the agent's certificate is received and automatically revokes a certificate when a valid revocation request signed with the agent's certificate is received.
14.2.1. Setting up CMC Revocation
To use CMC to revoke certificates, do the following:
• Set up an instance of the CMCAuth Authentication plug-in module. An instance is enabled and configured by default.
• Use the agent certificate to sign revocation requests.
14.2.1.1. revoker Utility
The CMC revocation utility, revoker , is used to sign a revocation request with an agent's certificate.
This utility has the following syntax: revoker -d /instance/alias/ -n cert_nickname -i issuerName -s serialName
-m reason -c comment
-d is the directory where the cert8.db
, key3.db
, and secmod.db
databases containing the agent certificate are located. -n is the nickname of the agent's certificate. -i is the issuer name of the certificate being revoked. -s is the serial number of the certificate being revoked in decimal value. -m is the reason the certificate is being revoked, which can be any of the following:
• 0 , unspecified
• 1 , the key was compromised
• 2 , the CA key was compromised
• 3 , the employee's affiliation changed
• 4 , the certificate has been superseded
• 5 , cessation of operation
• 6 , the certificate is on hold
-c adds comments about the request.
322
Testing CMC Revoke
NOTE
Surround values that include spaces in quotation marks.
14.2.2. Testing CMC Revoke
1. Create a CMC revocation request for an existing certificate.
revoker -d /instance/alias -n nickname -i issuerName -s serialName
-m reason -c comment
For example, if the directory containing the agent certificate is /var/lib/rhpki-ca/alias , the nickname of the certificate is AgentCert , and the serial number of the certificate is 22 , the command is as shown: revoker -d "/var/lib/rhpki-ca/alias" -n "ManagerAgentCert" -i "cn=agentAuthMgr"
-s 22 -m 0 -c "test comment"
2. Open the end-entities page at https:// localhost /ca/ .
3. Select the Revocation tab.
4. Select the CMC Revoke link on the menu.
5. Paste the output from the revoker into the text area.
6. Remove -----BEGIN NEW CERTIFICATE REQUEST---- and ----END NEW CERTIFICATE
REQUEST---- from the pasted content.
7. Click Submit .
8. The returned page should confirm that correct certificate was been revoked.
14.3. About CRLs
Server and client applications that use public-key certificates as ID tokens need access to information about the validity of a certificate. Because one of the factors that determines the validity of a certificate is its revocation status, these applications need to know whether the certificate being validated has been revoked. The CA has a responsibility to do the following:
• Revoke the certificate if any of the certificate information becomes false.
• Make the revoked certificate status available to parties or applications that need to verify its validity status.
Whenever a certificate is revoked, the Certificate Manager automatically updates the status of the certificate in its internal database, it marks the copy of the certificate in its internal database as revoked and removes the revoked certificate from the publishing directory, if the Certificate Manager is configured to remove the certificate from the database.
323
Chapter 14. Revocation and CRLs
One of the standard methods for conveying the revocation status of certificates is by publishing a list of revoked certificates, known a certificate revocation list (CRL). A CRL is a publicly available list of certificates that have been revoked.
The Certificate Manager can be configured to generate CRLs. These CRLs can be created to conform to X.509 standards by enabling extension-specific modules in the CRL configuration. The server supports standard CRL extensions through its CRL issuing points framework; see Section 14.4.3,
“Setting CRL Extensions” for more information on setting up CRL extensions for issuing points. The
Certificate Manager can generate the CRL every time a certificate is revoked and at periodic intervals.
If publishing is set up, the CRLs can be published to a file, an LDAP directory, or an OCSP responder.
A CRL is issued and digitally signed by the CA that issued the certificates listed in the CRL. The CA may use a single key pair to sign both the certificates and CRLs it issues or two separate key pairs, one for signing certificates and another one for signing CRLs.
By default, the Certificate Manager uses a single key pair for signing the certificates it issues and
CRLs it generates. To create another key pair for the Certificate Manager and use it exclusively for signing CRLs, see Section 4.11, “CRL Signing Key Pair and Certificate” .
14.3.1. Reasons for Revoking a Certificate
A Certificate Manager can revoke any certificate it has issued. There are generally accepted reason codes for revoking a certificate that are often included in the CRL, such as the following:
• 0 . Unspecified; no particular reason is given.
• 1 . The private key associated with the certificate was compromised.
• 2 . The private key associated with the CA that issued the certificate was compromised.
• 3 . The owner of the certificate is no longer affiliated with the issuer of the certificate and either no longer has rights to the access gained with the certificate or no longer needs it.
• 4 . Another certificate replaces this one.
• 5 . The CA that issued the certificate has ceased to operate.
• 6 . The certificate is on hold pending further action. It is treated as revoked but may be taken off hold in the future.
A certificate can be revoked by administrators, agents, and end entities. Agents and administrators with agent privileges can revoke certificates using the forms in the agent services page. End users can revoke certificates using the forms in the Revocation tab of the end-entity interface. End users can revoke only their own certificates, whereas agents and administrators can revoke any certificates issued by the server. End users are also required to authenticate to the server in order to revoke a certificate.
Whenever a certificate is revoked, the Certificate Manager updates the status of the certificate in its internal database. The server uses the entries in the internal database to track of all revoked certificates, and, when configured, it makes the CRLs public by publishing it to a central repository to notify other users that the certificates in the list are no longer valid.
324
Publishing CRLs
14.3.2. Publishing CRLs
The Certificate Manager can publish the CRL to a file, an LDAP-compliant directory, or to an OCSP responder. Where and how frequently CRLs are published are configured in the Certificate Manager.
For information about setting up CRL publishing, see Chapter 15, Publishing .
14.3.3. CRL Issuing Points
Because CRLs can grow very large, there are several methods to minimize the overhead of retrieving and delivering large CRLs. One of these methods partitions the entire certificate space and associates a separate CRL with every partition. This partition is called a CRL issuing point , the location where a subset of all the revoked certificates is maintained. Partitioning can be based on whether the revoked certificate is a CA certificate or end-entity certificate. Each issuing point is identified by its name.
By default, the Certificate Manager generates and publishes a single CRL, the master CRL . An issuing point can be defined for user certificates, for CA signing certificates, or for all revoked certificate information, including expired certificates.
Once the issuing points have been defined, they can be included in certificates so that an application that needs to check the revocation status of a certificate can access the CRL issuing points specified in the certificate instead of the master or main CRL. Since the CRL maintained at the issuing point is smaller than the master CRL, checking the revocation status is much faster.
CRL distribution points can be associated with certificates by setting the CRLDistributionPoint extension.
14.3.4. Delta CRLs
Delta CRLs can be issued for any defined issuing point. A delta CRL contains information about any certificates revoked since the last update to the full CRL. Delta CRLs for an issuing point are created by enabling the DeltaCRLIndicator extension.
14.3.5. How CRLs Work
CRLs are generated when issuing points are defined and configured and any CRL extensions are enabled.
When CRLs are enabled, the server collects revocation information as certificates are revoked. The server attempts to match the revoked certificate against all issuing points that are set up. A given certificate can match none of the issuing points, one of the issuing points, several of the issuing points, or all of the issuing points. When a certificate that has been revoked matches an issuing point, the server stores the information about the certificate in the cache for that issuing point.
The cache is copied to the internal directory at the intervals set for copying the cache. When the interval for creating a CRL is reached, a CRL is created from the cache. If a delta CRL has been set up for this issuing point, a delta CRL is also created at this time. The full CRL contains all revoked certificate information since the Certificate Manager began collecting this information. The delta CRL contains all revoked certificate information since the last update of the full CRL.
The full CRL and the delta CRL have the same number, allowing clients to determine a match between them. This numbering is how the delta CRL references the full CRL from which it gathers information.
For example, if the full CRL is the first CRL, it may be known as CRL 1. The corresponding delta CRL would be called delta CRL 1. Therefore, delta CRL 1 refers back to CRL 1 as its full CRL.
325
Chapter 14. Revocation and CRLs
NOTE
When changes are made to the extensions for an issuing point, no delta CRL is created with the next full CRL for that issuing point. A delta CRL is created with the second full
CRL that is created, and then all subsequent full CRLs.
The internal database stores only the latest CRL and delta CRL. As each new CRL is created, the old one is overwritten.
When CRLs are published, each update to the CRL and delta CRL is published to the locations specified in the publishing set up. The method of publishing determines how many CRLs are stored.
For file publishing, each CRL that is published to a file using the number for the CRL, so no file is overwritten. For LDAP publishing, each CRL that is published replaces the old CRL in the attribute containing the CRL in the directory entry.
By default, CRLs do not contain information about revoked expired certificates. The server can include revoked expired certificates by enabling that option for the issuing point. If expired certificates are included, information about revoked certificates is not removed from the CRL when the certificate expires. If expired certificates are not included, information about revoked certificates is removed from the CRL when the certificate expires.
14.4. Issuing CRLs
Set up CRLs by doing the following:
1. The Certificate Manager uses its CA signing key to sign CRLs. To use a separate signing key pair for CRLs, set up a CRL singing key and change the Certificate Manager configuration to use this key to sign CRLs. See Section 4.11, “CRL Signing Key Pair and Certificate” for more information.
2. Set up CRL issuing points. An issuing point is already set up and enabled for a master CRL.
326
Issuing CRLs
Figure 14.1. Default CRL Issuing Point
Additional issuing points for the CRLs can be created. See Section 14.4.1, “Configuring Issuing
Points” for details.
There are four types of CRLs the issuing points can create, depending on the options set when configuring the issuing point to define what the CRL will list:
• Master CRL , which contains the list of revoked certificates from the entire CA.
• ARL , an Authority Revocation List containing only revoked CA certificates.
• CRL with expired certificates , which includes revoked certificates that have expired in the CRL.
• CRL from certificate profiles , which determines the revoked certificates to include based on the profiles used to create the certificates originally.
3. Configure the CRLs for each issuing point. See Section 14.4.2, “Configuring CRLs for Each
Issuing Point” for details.
4. Set up the CRL extensions which are configured for the issuing point. See Section 14.4.3, “Setting
CRL Extensions” for details.
5. Set up the delta CRL for an issuing point by enabling extensions for that issuing point,
DeltaCRLIndicator or CRLNumber .
6. Set up the CRLDistributionPoint extension to include information about the issuing point.
7. Set up publishing CRLs to files, an LDAP directory, or an OCSP responder. See Chapter 15,
Publishing for details about setting up publishing.
327
Chapter 14. Revocation and CRLs
14.4.1. Configuring Issuing Points
Issuing points define which certificates are included in a new CRL. A master CRL issuing point is created by default for a master CRL containing a list of all revoked certificates for the Certificate
Manager.
To create a new issuing point, do the following:
1. Open the Certificate System Console.
pkiconsole https:// hostname:SSLport /ca
2. In the Configuration tab, select Certificate Manager from the left navigation menu. Then select
CRL Issuing Points .
3. To edit an issuing point, select the issuing point, and click Edit . The only parameters which can be edited are the name of the issuing point and whether the issuing point is enabled to disabled.
To add an issuing point, click Add . The CRL Issuing Point Editor window opens.
Figure 14.2. CRL Issuing Point Editor
NOTE
If some fields do not appear large enough to read the content, expand the window by dragging one of the corners.
Fill in the following fields:
• Enable . Enables the issuing point if selected; deselect to disable.
• CRL Issuing Point name . Gives the name for the issuing point; spaces are not allowed.
• Description . Describes the issuing point.
4. Click OK .
To view and configure a new issuing point, close the CA Console, then open the Console again. The new issuing point is listed below the CRL Issuing Points entry in the navigation tree.
Configure CRLs for the new issuing point, and set up any CRL extensions that will be used with the CRL. See Section 14.4.2, “Configuring CRLs for Each Issuing Point” for details on configuring an issuing point. See Section 14.4.3, “Setting CRL Extensions” for details on setting up the CRL
328
Configuring CRLs for Each Issuing Point extensions. All the CRLs created appear on the Update Revocation List page of the agent services pages.
14.4.2. Configuring CRLs for Each Issuing Point
Information, such as the generation interval, the CRL version, CRL extensions, and the signing algorithm, can all be configured for the CRLs for the issuing point. The CRLs must be configured for each issuing point.
1. Open the CA Console.
pkiconsole https:// hostname:SSLport /ca
2. In the navigation tree, select Certificate Manager , and then select CRL Issuing Points .
3. Select the issuing point name below the Issuing Points entry.
4. Configure how and how often the CRLs are updated by supplying information in the Update tab for the issuing point. This tab has two sections, Update Schema and Update Frequency .
• The Update Schema section has the following options:
• Enable CRL generation . This checkbox sets whether CRLs are generated for that issuing point.
• Generate full CRL every # delta(s) . This field sets how frequently CRLs are created in relation to the number of changes.
• Extend next update time in full CRLs.
This adds the nextUpdate field to the published
CRLs, which indicates the date by which the next CRL will be issued.
329
Chapter 14. Revocation and CRLs
• The Update Frequency section sets the different intervals when the CRLs are generated and published to the directory.
• Every time a certificate is revoked or released from hold . This sets the Certificate
Manager to generate the CRL every time it revokes a certificate. The Certificate Manager attempts to publish the CRL to the configured directory whenever it is generated. Publishing a CRL can be time consuming if the CRL is large. Configuring the Certificate Manager to publish CRLs every time a certificate is revoked may engage the server for a considerable amount of time; during this time, the server will not be able to update the directory with any changes it receives.
This setting is not recommended for a standard installation. This option should be selected to test revocation immediately, such as testing whether the server publishes the CRL to a flat file.
• Update the CRL at . This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separate list of times, such as 01:50,04:55,06:55 .
• Update the CRL every . This checkbox enables generating and publishing CRLs at the interval set in the field. For example, to publish CRLs every day, select the checkbox, and enter 1440 in this field.
• Next update grace period . If the Certificate Manager updates the CRL at a specific frequency, the server can be configured to have a grace period to the next update time to allow time to create the CRL and publish it. For example, if the server is configured to update the CRL every 20 minutes with a grace period of 2 minutes, and if the CRL is updated at
16:00, the CRL is updated again at 16:18.
5. The Cache tab sets whether caching is enabled and the cache frequency.
330
Configuring CRLs for Each Issuing Point
Figure 14.3. CRL Cache Tab
• Enable CRL cache . This checkbox enables the cache, which is used to create delta CRLs. If the cache is disabled, delta CRLs will not be created. For more information about the cache, see
Section 14.3.5, “How CRLs Work” .
• Update cache every . This field sets how frequently the cache is written to the internal database. Set to 0 to have the cache written to the database every time a certificate is revoked.
• Enable cache recovery . This checkbox allows the cache to be restored.
6. The Format tab sets the formatting and contents of the CRLs that are created. There are two sections, CRL Format and CRL Contents .
331
Chapter 14. Revocation and CRLs
332
Figure 14.4. CRL Format Tab
• The CRL Format section has two options:
• Revocation list signing algorithm , which is a drop down list of allowed ciphers to encrypt the CRL.
• Allow extensions for CRL v2 , a checkbox which enabled CRL v2 extensions for the issuing point. If this is enabled, set the required CRL extensions described in Section 14.4.3, “Setting
CRL Extensions” .
NOTE
Extensions must be turned on to create delta CRLs.
• The CRL Contents section has three checkboxes which set what types of certificates to include in the CRL:
• Include expired certificates . This includes revoked certificates that have expired. If this is enabled, information about revoked certificates remains in the CRL after the certificate expires. If this is not enabled, information about revoked certificates is removed when the certificate expires.
• CA certificates only.
This includes only CA certificates in the CRL. Selecting this option creates an Authority Revocation List (ARL), which lists only revoked CA certificates.
• Certificates issued according to profiles . This only includes certificates that were issued according to the listed profiles; to specify multiple profiles, enter a comma-separated list.
Setting CRL Extensions
7. Click Save .
8. Extensions are allowed for this issuing point and can be configured. See Section 14.4.3, “Setting
CRL Extensions” for details.
14.4.3. Setting CRL Extensions
NOTE
Extensions only need configured for an issuing point if the Allow extensions for CRLs v2 checkbox is selected for that issuing point.
When the issuing point is created, three extensions are automatically enabled: CRLReason ,
InvalidityDate , and CRLNumber . Other extensions are available but are disabled by default.
These can be enabled and modified. For more information about the available CRL extensions, see
Section A.5, “Standard X.509 v3 CRL Extensions” .
To configure CRL extensions, do the following:
1. Open the CA Console.
pkiconsole https:// hostname:SSLport /ca
2. In the navigation tree, select Certificate Manager , and then select CRL Issuing Points .
3. Select the issuing point name below the Issuing Points entry, and select the CRL Extension entry below the issuing point.
The right pane shows the CRL Extensions Management tab, which lists configured extensions.
333
Chapter 14. Revocation and CRLs
Figure 14.5. CRL Extensions
4. To modify a rule, select it, and click Edit/View .
5. Most extensions have two options, enabling them and setting whether they are critical. Some require more information. Supply all required values. See Section A.5, “Standard X.509 v3
CRL Extensions” for complete information about each extension and the parameters for those extensions.
6. Click OK .
7. Click Refresh to see the updated status of all the rules.
14.5. Setting Full and Delta CRL Schedules
CRLs are published periodically. Setting that period is touched on in the configuration in
Section 14.4.2, “Configuring CRLs for Each Issuing Point” .
First, CRLs are issued according to a time-based schedule. CRLs can be issued every single time a certificate is revoked, at a specific time of day, or once every so-many minutes.
However, this time-based publishing schedule applies to every CRL that is generated. There are two kinds of CRLs, however. The full CRL has a record of every single revoked certificate. However, the
Certificate System also publishes a delta CRL, which contains only the certificates that have been revoked since the last CRL (delta or full) was published.
By default, full and delta CRLs are generated at the same time, and every time. However, it is possible to space out when full CRLs are published and to publish multiple interim delta CRLs. This is configured in the CRL schema , which sets the scheme for publishing delta and full CRLs.
334
Configuring Extended Updated Intervals for CRLs in the Console
A full CRL is also called an extended update . By default, every CRL publishing period has an extended update. However, this can be configured so that not every publishing period is an extended update and to set the interval of when the extended updates are published.
If the interval is set to 3, for example, then the first CRL publishing is both a full and delta CRL, then the next two publishing updates are only delta CRLs, and then the fourth interval is both a full and delta CRL again. In other words, every third publishing interval has both a full CRL and a delta CRL.
Interval 1, 2, 3, 4, 5, 6, 7 ...
Full CRL 1 4 7 ...
Delta CRL 1, 2, 3, 4, 5, 6, 7 ...
NOTE
For delta CRLs to be published independent of full CRLs, the CRL cache must be enabled.
14.5.1. Configuring Extended Updated Intervals for CRLs in the
Console
1. Open the console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, expand the Certificate Manager folder and the CRL Issuing Points subfolder.
3. Select the MasterCRL node.
4. Deselect the Extend next update time in full CRLs check box, which disables publishing a full
CRL every time a CRL is published. Then, set the new full CRL interval in the Generate full CRL every ... deltas field.
335
Chapter 14. Revocation and CRLs
5. Save the changes.
14.5.2. Configuring Extended Updated Intervals for CRLs in CS.cfg
Two parameters need to be configured for setting the full/delta CRL publishing interval in the CS.cfg
file, ca.crl.extendedNextUpdate
and ca.crl.MasterCRL.updateSchema
.
1. Stop the CA server.
/etc/init.d/rhpki-ca stop
2. Open the CA configuration directory.
cd /var/lib/ subsystem_name /conf
3. Edit the CS.cfg
file, and add two lines to set the extended updated interval: ca.crl.extendedNextUpdate=false ca.crl.MasterCRL.updateSchema=3
The default interval is 1, meaning a full CRL is published every time a CRL is published. The updateSchema interval can be set to any integer.
4. Restart the CA server.
/etc/init.d/rhpki-ca start
336
Chapter 15.
Publishing
Red Hat Certificate System includes a customizable publishing framework for the Certificate Manager, enabling certificate authorities to publish certificates, certificate revocation lists (CRLs), and other certificate-related objects to any of the supported repositories: an LDAP-compliant directory, a flat file, and an online validation authority. This chapter explains how to configure a Certificate Manager to publish certificates and CRLs to a file, to a directory, and to the Online Certificate Status Manager.
15.1. About Publishing
The Certificate System is capable of publishing certificates to a file or an LDAP directory and of publishing CRLs to a file, an LDAP directory, or to an OCSP responder.
For additional flexibility, specific types of certificates or CRLs can be published to a single format or all three. For example, CA certificates can be published only to a directory and not to a file, and user certificates can be published to both a file and a directory.
NOTE
An OCSP responder only provides information about CRLs; certificates are not published to an OCSP responder.
Different publishing locations can be set for certificates files and CRL files, as well as different publishing locations for different types of certificates files or different types of CRL files.
Similarly, different types of certificates and different types of CRLs can be published to different places in a directory. For example, certificates for users from the West Coast division of a company can be published in one branch of the directory, while certificates for users in the East Coast division can be published to another branch in the directory.
Setting up publishing involves configuring publishers, mappers, and rules.
15.1.1. About Publishers
Publishers specify the location to which certificates and CRLs are published. When publishing to a file, publishers specify the filesystem publishing directory. When publishing to an LDAP directory, publishers specify the attribute in the directory that stores the certificate or CRL; a mapper is used to determine the DN of the entry. For every DN, a different formula is set for deriving that DN. The location of the LDAP directory is specified when LDAP publishing is enabled. When publishing a CRL to an OCSP responder, publishers specify the hostname and URI of the Online Certificate Status
Manager.
15.1.2. About Mappers
Mappers are only used in LDAP publishing. Mappers construct the DN for an entry based on information from the certificate or the certificate request. The server has information from the subject name of the certificate and the certificate request and needs to know how to use this information to create a DN for that entry. The mapper provides a formula for converting the information available either to a DN or to some unique information that can be searched in the directory to obtain a DN for the entry.
337
Chapter 15. Publishing
15.1.3. About Rules
Rules for file, LDAP, and OCSP publishing tell the server whether and how a certificate or CRL is to be published. A rule first defines what is to be published, a certificate or CRL matching certain characteristics, by setting a type and predicate for the rule. A rule then specifies the publishing method and location by being associated with a publisher and, for LDAP publishing, with a mapper.
Rules can be as simple or complex as necessary for the PKI deployment and are flexibile enough to accomodate different scenarios.
15.1.4. Publishing to Files
The server can publish certificates and CRLs to flat files, which can then be imported into any repository, such as a relational database. When the server is configured to publish certificates and
CRLs to file, the files created are DER-encoded binary blobs.
• For each certificate the server issues, it creates a file that contains the certificate in its DERencoded format. Each file is named certserial_number .der
, where serial_number specifies the serial number of the certificate contained in the file. For example, the filename for a certificate with serial number 1234 is cert-1234.der
.
• Every time the server generates a CRL, it creates a file that contains the new CRL in its DERencoded format. Each file is named crlthis_update .der
, where this_update specifies the value derived from the time-dependent This Update variable of the CRL contained in the file. For example, the filename for a CRL with This Update: Friday January 28 15:36:00 PST
2009 , is crl-94.3696899.der
.
15.1.5. LDAP Publishing
In LDAP publishing , the server publishes the certificates, CRLs, and other certificate-related objects to a directory using LDAP or LDAPS. The branch of the directory to which it publishes is called the publishing directory .
• For each certificate the server issues, it creates a blob that contains the certificate in its DERencoded format in the specified attribute of the user's entry. The certificate is published as a DER encoded binary blob.
• Every time the server generates a CRL, it creates a blob that contains the new CRL in its DERencoded format in the specified attribute of the entry for the CA.
The server can publish certificates and CRLs to an LDAP-compliant directory using the LDAP protocol or LDAP over SSL (LDAPS) protocol, and applications can retrieve the certificates and CRLs over
HTTP. Support for retrieving certificates and CRLs over HTTP enables some browsers to import the latest CRL automatically from the directory that receives regular updates from the server. The browser can then use the CRL to check all certificates automatically to ensure that they have not been revoked.
For LDAP publishing to work, the user entry must be present in the LDAP directory.
If the server and publishing directory become out of sync for some reason, privileged users
(administrators and agents) can also manually initiate the publishing process. For instructions, see
Section 15.11.2, “Manually Updating the CRL in the Directory” .
338
OCSP Publishing
15.1.6. OCSP Publishing
There are two forms of Certificate System OCSP services, an internal service for the Certificate
Manager and the Online Certificate Status Manager. The internal service checks the internal database of the Certificate Manager to report on the status of a certificate. The internal service is not set for publishing; it uses the certificates stored in its internal database to determine the status of a certificate.
The Online Certificate Status Manager checks CRLs sent to it by Certificate Manager. A publisher is set for each location a CRL is sent and one rule for each type of CRL sent.
For detailed information on both OCSP services, see Chapter 6, Online Certificate Status Protocol
Responder .
15.1.7. How Publishing Works
When publishing is enabled, every time a certificate or a CRL is issued, updated, or revoked, the publishing system is invoked. The certificate or CRL is evaluated by the rules to see if it matches the type and predicate set in the rule. The type specifies if the object is a CRL, CA certificate, or any other certificate. The predicate sets more criteria for the type of object being evaluated. For example, it can specify user certificates, or it can specify West Coast user certificates. To use predicates, a value needs to be entered in the predicate field of the publishing rule, and a corresponding value (although formatted somewhat differently) needs to be contained in the certificate or certificate request to match.
The value in the certificate or certificate request may be derived from information in the certificate, such as the type of certificate, or may be derived from a hidden value that is placed in the request form. If no predicate is set, all certificates of that type are considered to match. For example, all CRLs match the rule if CRL is set as the type.
Every rule that is matched publishes the certificate or CRL according to the method and location specified in that rule. A given certificate or CRL can match no rules, one rule, more than one rule, or all rules. The publishing system attempts to match every certificate and CRL issued against all rules.
When a rule is matched, the certificate or CRL is published according to the method and location specified in the publisher associated with that rule. For example, if a rule matches all certificates issued to users, and the rule has a publisher that publishes to a file in the location /etc/CS/ certificates , the certificate is published as a file to that location. If another rule matches all certificates issued to users, and the rule has a publisher that publishes to the LDAP attribute userCertificate;binary attribute, the certificate is published to the directory specified when
LDAP publishing was enabled in this attribute in the user's entry.
For rules that specify to publish to a file, a new file is created when either a certificate or a CRL is issued in the stipulated directory.
For rules that specify to publish to an LDAP directory, the certificate or CRL is published to the entry specified in the directory, in the attribute specified. The certificate or CRL replaces any existing certificate or CRL that is already published to this attribute.
For rules that specify to publish to an Online Certificate Status Manager, a CRL is published to this manager. Certificates are not published to an Online Certificate Status Manager.
For LDAP publishing, the location of the user's entry needs to be determined. Mappers are used to determine the entry to which to publish. The mappers can contain an exact DN for the entry, some variable that associates information that can be gotten from the certificate to create the DN, or enough information to search the directory for a unique attribute or set of attributes in the entry to ascertain the correct DN for the entry.
339
Chapter 15. Publishing
When a certificate is revoked, the server uses the publishing rules to locate and delete the corresponding certificate from the LDAP directory or from the filesystem.
When a certificate expires, the server can remove that certificate from the configured directory. The server does not do this automatically; the server must be configured to run the appropriate job. For details, see Chapter 19, Automated Jobs .
15.2. Setting up Publishing
The general process to configure publishing is as follows:
1. For file publishing, create a publisher for each location to publish files.
There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or finer definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.
For details about setting up publishers, see Section 15.3.1, “Configuring Publishers for Publishing to a File” .
2. For OCSP publishing, create a publisher for each Online Certificate Status Manager to which
CRLs will be published.
There can be a single publisher or multiple publishers, depending on how many locations will be used. Rules determine which type to publish and to what location by being associated with the publisher.
For details about setting up publishers, see Section 15.3.2, “Configuring Publishers for Publishing to OCSP” .
3. For LDAP publishing, there are three steps: a. Configure the Directory Server to which certificates will be published. Refer to Section 15.10,
“Configuring the Directory for LDAP Publishing” .
b. Configure a publisher for each type of object published: CA certificates, cross-pair certificates,
CRLs, and user certificates. The publisher declares in which attribute to store the object.
The attributes set by default are the X.500 standard attributes for storing each object type.
This attribute can be changed in the publisher, but, generally, LDAP publishers do not need changed. For more information, see Section 15.3.3, “Configuring Publishers for LDAP
Publishing” .
c. Set up mappers to enable an entry's DN to be derived from the certificate's subject name.
This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.
For details about setting up mappers, see Section 15.4, “Configuring Mappers” .
4. Set rules to determine what certificates are published to the locations. Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any
340
Configuring Publishers rule which it matches is activated. The same certificate can be published to a file and to an LDAP directory by matching a file-based rule and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. There can be different rules for different kinds of certificates or different kinds of CRLs.
The rule first determines if the object meets the criteria by matching the type and predicate set in the rule. The destination of matching objects is determined by the publisher and mapper associated with the rule.
For details about setting rules, see Section 15.5.1, “Modifying Publishing Rules for Certificates and
CRLs” .
5. Configure CRLs. CRLs must be configured before they can be published. See Chapter 14,
Revocation and CRLs .
6. Enable publishing after setting up publishers, mappers, and rules. Once publishing is enabled, the server starts publishing immediately. If the publishers, mappers, and rules are not completely configured, publishing may not work correctly or at all.
For details, see Section 15.6, “Enabling Publishing” .
15.3. Configuring Publishers
Publishers specify the location where a particular object is published. There can be a single publisher to publish everything to a single location or multiple publishers for multiple destinations. When publishing to a file, a publisher sets the directory where the files are published. For OCSP publishing, a publisher specifies a particular Online Certificate Status Manager to which to publish a CRL.
For LDAP publishing, a publisher specifies a particular attribute in the LDAP entry that stores the published file.
15.3.1. Configuring Publishers for Publishing to a File
Publishers must be created and configured for each publishing location; publishers are not automatically created for publishing to a file. To publish all files to a single location, create one publisher. To publish to different locations, create a publisher for each location. A location can either contain an object type, like user certificates, or a subset of an object type, like West Coast user certificates.
To create publishers for publishing to files, do the following:
1. Log into the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select
Publishing , and then Publishers .
The Publishers Management tab, which lists configured publisher instances, opens on the right.
341
Chapter 15. Publishing
Figure 15.1. Using the Publishers Management Tab to Create Publishers
3. Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
Figure 15.2. Select Publisher Plug-in Implementation Window
4. Select the FileBasedPublisher module, then open the editor window.
This is the module that enables the Certificate Manager to publish certificates and CRLs to files.
342
Configuring Publishers for Publishing to OCSP
Figure 15.3. Publisher Editor Window
5. Set the publisher ID, an alphanumeric string with no spaces like PublishCertsToFile , and the directory, the complete path to the directory in which the Certificate Manager should create the
DER-encoded files; the path can be an absolute path or can be relative to the Certificate System instance directory. For example, /export/CS/certificates .
15.3.2. Configuring Publishers for Publishing to OCSP
A publisher must be created and configured for each publishing location; publishers are not automatically created for publishing to the OCSP responder. Create a single publisher to publish everything to s single location, or create a publisher for every location to which CRLs will be published.
Each location can contain a different kind of CRL.
To create publishers for publishing CRLs to an OCSP, do the following:
1. Log into the Certificate Manager Console.
343
Chapter 15. Publishing pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select
Publishing , and then Publishers .
The Publishers Management tab, which lists configured publisher instances, opens on the right.
Figure 15.4. Publishers Management Tab
3. Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
Figure 15.5. Select Publisher Plug-in Implementation Window
4. Select the OCSPPublisher module, then open the editor window.
344
Configuring Publishers for LDAP Publishing
This is the publisher module that enables the Certificate Manager to publish CRLs to the Online
Certificate Status Manager.
Figure 15.6. Publisher Editor Window
5. Set the publisher ID, an alphanumeric string with no spaces like PublishCertsToOCSP ; the fullyqualified domain name, such as ocspResponder.example.com
, and port number of the Online
Certificate Status Manager; and the default path, /ocsp/addCRL .
15.3.3. Configuring Publishers for LDAP Publishing
The Certificate Manager creates, configures, and enables a set of publishers that are associated with
LDAP publishing, as shown in Table 15.1, “LDAP Publishers” .
Publisher
LdapCaCertPublisher
LdapCrlPublisher
Description
Used to publish CA certificates to the LDAP directory.
Used to publish CRLs to the LDAP directory.
345
Chapter 15. Publishing
Publisher
LdapDeltaCrlPublisher
LdapUserCertPublisher
LdapCrossCertPairPublisher
Description
Used to publish Delta CRLs to the LDAP directory.
Used to publish all types of end-entity certificates to the LDAP directory.
Used to publish cross-signed certificates to the
LDAP directory.
Table 15.1. LDAP Publishers
The publishers are enabled and configured using the X.500 standard attributes for storing certificates and CRLs. The preconfigured publishers do not need modified.
15.4. Configuring Mappers
Mappers are only used with LDAP publishing. Mappers define a relationship between a certificate's subject name and the DN of the directory entry to which the certificate is published. The Certificate
Manager needs to derive the DN of the entry from the certificate or the certificate request so it can determine which entry to use. The mapper defines the relationship between the DN for the user entry and the subject name of the certificate or other input information. This relationship can derive the exact
DN of the entry or set a search for the directory to find the DN of the entry.
During installation, the Certificate Manager automatically creates a set of mappers defining the most common relationships. The default mappers are listed in Table 15.2, “Default Mappers” .
Mapper
LdapUserCertMap
LdapCrlMap
LdapCaCertMap
Description
Locates the correct attribute of user entries in the directory in order to publish user certificates.
Locates the correct attribute of the CA's entry in the directory in order to publish the CRL.
Locates the correct attribute of the CA's entry in the directory in order to publish the CA certificate.
Table 15.2. Default Mappers
To use the default mappers, configure each of the macros by specifying the DN pattern and whether to create the CA entry in the directory.
To use other mappers, create and configure an instance of the mapper. For more information see
Section 15.13.2, “Mapper Plug-in Modules ” .
Modify a mapper by doing the following:
1. Log into the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select
Publishing , and then Mappers .
The Mappers Management tab, which lists configured mappers, opens on the right.
346
Figure 15.7. Mappers Management Tab
3. In the mapper list, select a mapper to modify.
4. To edit an existing mapper, click Edit/View . The editor window opens.
Configuring Mappers
347
Chapter 15. Publishing
Figure 15.8. Mapper Editor Window
5. To create a new mapper instance, click Add . The Select Mapper Plugin Implementation window opens, which lists registered mapper modules. Select a module, and edit it. For complete information about these modules, see Section 15.13.2, “Mapper Plug-in Modules ” .
348
Figure 15.9. Selecting a New Mapper Type
6. Edit the mapper instance, and click OK .
Configuring Mappers
349
Chapter 15. Publishing
Figure 15.10. Creating a New Mapper
See Section 15.13.2, “Mapper Plug-in Modules ” for detailed information about each mapper.
15.5. Rules
Rules determine what certificate object is published in what location. Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any rule which it matches is activated. In this way, the same certificate or CRL can be published to a file, to an Online
Certificate Status Manager, and to an LDAP directory by matching a file-based rule, an OCSP rule, and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. The rules can be more detailed for different kinds of certificates or different kinds of CRLs.
The rule first determines if the object matches by matching the type and predicate set up in the rule with the object. Where matching objects are published is determined by the publisher and mapper associated with the rule.
350
Modifying Publishing Rules for Certificates and CRLs
15.5.1. Modifying Publishing Rules for Certificates and CRLs
Rules are created for each type of certificate the Certificate Manager issues.
Modify publishing rules by doing the following:
1. Log into the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select
Publishing , and then Rules .
The Rules Management tab, which lists configured rules, opens on the right.
Figure 15.11. Rules Management Tab
3. To edit an existing rule, select that rule from the list, and click Edit . This opens the Rule Editor window.
351
Chapter 15. Publishing
Figure 15.12. Using the Rule Editor Window to Edit an Existing Rule
4. To create a rule, click Add . This opens the Select Rule Plug-in Implementation window.
352
Modifying Publishing Rules for Certificates and CRLs
Figure 15.13. Select Rule Plugin Implementation Window
Select the Rule module. This is the only default module. If any custom modules have been been registered, they are also available.
5. Edit the rule.
353
Chapter 15. Publishing
354
Figure 15.14. Rule Editor Window
• type.
This is the type of certificate for which the rule applies. For a CA signing certificate, the value is cacert . For a cross-signed certificate, the value is xcert . For all other types of certificates, the value is certs . For CRLs, specify crl .
• predicate.
This sets the predicate value for the type of certificate or CRL issuing point to which this rule applies. The predicate values for CRL issuing points, delta CRLs, and certificates are listed in Table 15.3, “Predicate Expressions” .
• enable.
• mapper.
Mappers are not necessary when publishing to a file; they are only needed for LDAP publishing. If this rule is associated with a publisher that publishes to an LDAP directory, select an appropriate mapper here. Leave blank for all other forms of publishing.
• publisher.
Sets the publisher to associate with the rule.
Predicates Used in Publishing Rules
15.5.2. Predicates Used in Publishing Rules
Table 15.3, “Predicate Expressions” lists the predicates that can be used to identify CRL issuing points and delta CRLs and certificate profiles.
Predicate Type
CRL Issuing Point
Certificate Profile
Predicate issuingPointId== Issuing_Point_Instance_ID
&& isDeltaCRl==[true|false]
To publish only the master CRL, set isDeltaCRl==false . To publish only the delta
CRL, set isDeltaCRl==true . To publish both, set a rule for the master CRL and another rule for the delta CRL.
profileId== profile_name
To publish certificates based on the profile used to issue them, set profileId== to a profile name, such as caServerCert .
Table 15.3. Predicate Expressions
15.6. Enabling Publishing
Publishing can be enabled for only files, only LDAP, or both. Publishing should be enabled after setting up publishers, rules, and mappers. Once enabled, the server will attempt to begin publishing.
If publishing was not configured correctly before being enabled, publishing may exhibit undesirable behavior or may fail.
Enable publishing by doing the following:
1. Log into the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select
Publishing .
The right pane shows the details for publishing to an LDAP-compliant directory.
3. To enable publishing to a file only, select Enable Publishing .
4. To enable LDAP publishing, select both Enable Publishing and Enable Default LDAP
Connection .
355
Chapter 15. Publishing
356
Figure 15.15. Enabling Publishing
In the Destination section, set the information for the Directory Server instance.
• Host name.
If the Directory Server is configured for SSL client authenticated communication, the name must match the cn component in the subject DN of the Directory Server's SSL server certificate.
• Port number.
• Directory Manager DN.
This is the distinguished name (DN) of the directory entry that has
Directory Manager privileges. The Certificate Manager uses this DN to access the directory tree and to publish to the directory. The access control set up for this DN determines whether the
Certificate Manager can perform publishing. It is possible to create another DN that has limited read-write permissions for only those attributes that the publishing system actually needs to write.
• Password.
The Certificate Manager saves this password in its password.conf
file. For example:
CA LDAP Publishing:password
The parameter name which identifies the publishing password ( CA LDAP
Publishing ) is set in the Certificate Manager's CS.cfg
file in the ca.publish.ldappublish.ldap.ldapauth.bindPWPrompt
parameter, and it can be edited.
• Client certificate.
This sets the certificate the Certificate Manager uses for SSL client authentication to the publishing directory. By default, the Certificate Manager uses its SSL server certificate.
• LDAP version.
. Select LDAP version 3.
Publishing Cross-Pair Certificates
• Authentication.
The way the Certificate Manager authenticates to the Directory Server. The choices are Basic authentication and SSL client authentication .
If the Directory Server is configured for basic authentication or for SSL communication without client authentication, select Basic authentication and specify values for the Directory manager DN and password.
If the Directory Server is configured for SSL communication with client authentication, select
SSL client authentication and the Use SSL communication option, and identify the certificate that the Certificate Manager must use for SSL client authentication to the directory.
The server attempts to connect to the Directory Server. If the information is incorrect, the server displays an error message.
15.7. Publishing Cross-Pair Certificates
The cross-pair certificates can be published as a crossCertificatePair entry to an LDAP directory or to a file; this is enabled by default. If this has been disabled, it can be reenabled through the Certificate Manager Console by doing the following:
1. Open the CA Console pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select the Certificate Manager link in the left pane, then the Publishing link.
3. Click the Rules link under Publishing . This opens the Rules Management pane on the right.
4. If the rule exists and has been disabled, select the enable checkbox. If the rule has been deleted, then click Add and create a new rule.
a. Select xcerts from the type drop-down menu.
b. Make sure the enable checkbox is selected.
c. Select LdapCaCertMap from the mapper drop-down menu.
d. Select LdapCrossCertPairPublisher from the publisher drop-down menu.
The mapper and publisher specified in the publishing rule are both listed under Mapper and
Publisher under the Publishing link in the left navigation window of the CA Console. The mapper,
LdapCaCertMap , by default designates that the crossCertificatePair be stored to the
LdapCaSimpleMap LDAP entry. The publisher, LDAPCrossPairPublisher , by default sets the attribute to store the cross-pair certificate in the CA entry to crossCertificatePair;binary .
15.8. Testing Publishing to Files
To verify that the Certificate Manager is publishing certificates and CRLs correctly to file, do the following:
1. Open the CA's end-entities page, and request a certificate.
357
Chapter 15. Publishing
2. Approve the request through the agent services page, if required.
3. Retrieve the certificate from the end-entities page, and download the certificate into the browser.
4. Check whether the server generated the DER-encoded file containing the certificate.
Open the directory to which the binary blob of the certificate is supposed to be published. The certificate file should be named certserial_number .der
.
5. Convert the DER-encoded certificate to its base 64-encoded format using the Binary to ASCII tool.
For more information on this tool, refer to the Certificate System Command-Line Tools Guide .
BtoA input_file output_file input_file sets the path to the file that contains the DER-encoded certificate, and output_file sets the path to the file to write the base-64 encoded certificate.
6. Open the ASCII file; the base-64 encoded certificate is similar to the one shown:
-----BEGIN CERTIFICATE-----
MMIIBtgYJYIZIAYb4QgIFoIIBpzCCAZ8wggGbMIIBRaADAgEAAgEBMA0GCSqGSIb3DQEBBAUAMFcxC
AJBgNVBAYTAlVTMSwwKgYDVQQKEyNOZXRzY2FwZSBDb21tdW5pY2F0aWhfyyuougjgjjgmkgjkgmjg fjfgjjjgfyjfyj9ucyBDb3Jwb3JhdGlvbjpMEaMBgGA1UECxMRSXNzdWluZyhgdfhbfdpffjphotoo gdhkBBdXRob3JpdHkwHhcNOTYxMTA4MDkwNzM0WhcNOTgxMTA4MDkwNzMM0WjBXMQswCQYDVQQGEwJ
VUzEsMCoGA1UEChMjTmV0c2NhcGUgQ29tbXVuaWNhdGlvbnMgQ29ycG9yY2F0aW9ucyBDb3Jwb3Jhd
GlvbjpMEaMBgGA1UECxMRSXNzdWluZyBBdXRob3JpdHkwHh
-----END CERTIFICATE-----
7. Convert the base 64-encoded certificate to a readable form using the Pretty Print Certificate tool.
For more information on this tool, refer to the Certificate System Command-Line Tools Guide .
PrettyPrintCert input_file [output_file] input_file sets the path to the ASCII file that contains the base-64 encoded certificate, and output_file , optionally, sets the path to the file to write the certificate. If an output file is not set, the certificate information is written to the standard output.
8. Compare the output with the certificate issued; check the serial number in the certificate with the one used in the filename.
If everything matches, the Certificate Manager is configured correctly to publish certificates to file.
9. Revoke the certificate.
10. Check whether the server generated the DER-encoded file containing the CRL.
Open the directory to which the server is to publish the CRL as a binary blob. The CRL file should have a name in the form crlthis_update .der
. this_update specifies the value derived from the time-dependent This Update variable of the CRL.
11. Convert the DER-encoded CRL to its base 64-encoded format using the Binary to ASCII tool.
358
Viewing Certificates and CRLs Published to File
BtoA input_file output_file
12. Convert the base 64-encoded CRL to readable form using the Pretty Print CRL tool.
PrettyPrintCrl input_file [output_file]
13. Compare the output.
15.9. Viewing Certificates and CRLs Published to File
Certificates and CRLs can be published to two types of files: base-64 encoded or DER-encoded. The content of these files can be viewed by converting the files to pretty-print format using the dumpasn1 tool or the PrettyPrintCert or PrettyPrintCRL tool.
To view the content in a base-64 encoded file, do the following:
1. Convert the base-64 file to binary. For example:
AtoB /tmp/example.b64 /tmp/example.bin
2. Use the PrettyPrintCert or PrettyPrintCRL tool to convert the binary file to pretty-print format. For example:
PrettyPrintCert example.bin example.cert
Alternatively, the dumpasn1 can be used to convert a binary certificate or CRL to pretty-print format. The dumpasn1 tool can be downloaded at http://fedoraproject.org/extras/4/i386/repodata/ repoview/dumpasn1-0-20050404-1.fc4.html
.
To view the content of a DER-encoded file, simply run the dumpasn1 , PrettyPrintCert , or
PrettyPrintCRL tool with the DER-encoded file. For example:
PrettyPrintCRL example.der example.crl
15.10. Configuring the Directory for LDAP Publishing
Before certificates and CRLs can be published, the Directory Server must be configured to work with the publishing system.
• Section 15.10.1, “Schema”
• Section 15.10.2, “Entry for the CA”
• Section 15.10.3, “Bind DN”
• Section 15.10.4, “Directory Authentication Method”
359
Chapter 15. Publishing
15.10.1. Schema
For a Certificate Manager to publish certificates and CRLs to a directory, it must be configured with specific attributes and object classes. This section discusses those basic schema requirements.
15.10.1.1. Required Schema for Publishing End-Entity Certificates
The Certificate Manager publishes an end entity's certificate to the userCertificate;binary attribute within the end entity's or subject's directory object. This attribute is multi-valued; each value is a DER-encoded binary X.509 certificate. The LDAP object class named inetOrgPerson allows this attribute. The strongAuthenticationUser object class allows this attribute and can be combined with any other object class to allow certificates to be published to that object. The Certificate Manager does not automatically add this object class to the schema table of the corresponding Directory Server.
If the directory object that it finds does not allow the userCertificate;binary attribute, adding or removing the certificate fails.
15.10.1.2. Required Schema for Publishing the CA Certificate
The Certificate Manager publishes its own CA certificate in the caCertificate;binary attribute of the CA's directory object when the server is started; this is the object that corresponds to the
Certificate Manager's issuer name. This is a required attribute of the certificationAuthority object class. The Certificate Manager will add this object class to the directory entry for the CA if it can find the CA's directory entry.
15.10.1.3. Required Schema for Publishing CRLs
The Certificate Manager publishes the updated CRL to the CA's directory object under the certificateRevocationList;binary attribute. This attribute is an attribute of the certificationAuthority object class. The value of the attribute is the DER-encoded binary
X.509 CRL. The CA's entry must already contain the certificationAuthority object class.
15.10.2. Entry for the CA
The Certificate Manager automatically creates an entry for the CA in the directory. This option is set in both the CA and CRL mapper instances and enabled by default. If the directory restricts the Certificate
Manager from creating entries in the directory, turn off this option in those mapper instances, and add an entry for the CA manually in the directory.
For the Certificate Manager to publish its CA certificate and CRL, the directory must include an entry for the CA.
When adding the CA's entry to the directory, select the entry type based on the DN of the CA:
• If the CA's DN begins with the cn component, create a new person entry for the CA. Selecting a different type of entry may not allow the cn component to be specified.
• If the CA's DN begins with the ou component, create a new organizationalunit entry for the
CA.
The entry does not have to be in the certificationAuthority object class. The Certificate
Manager will convert this entry to the certificationAuthority object class automatically by publishing its CA's signing certificate.
For more information on creating directory entries, see the Red Hat Directory Server documentation.
360
Bind DN
15.10.3. Bind DN
The Certificate Manager accesses the Directory Server using a DN that has read-write permissions to the directory. To publish certificates and CRLs to the directory, the Certificate Manager needs to use a directory user entry that has write access to the directory. This enables the Certificate Manager to modify the user entries with certificate-related information and the CA entry with CA's certificate and
CRL related information.
This entry can be either of the following:
• An existing DN that has write access, such as the Directory Manager.
• A new user which is granted write access. The entry can be identified by the Certificate
Manager's DN, such as cn=testCA, ou=Research Dept, o=Example Corporation, st=California, c=US .
NOTE
Carefully consider what privileges are given to this user. This user can be restricted in what it can write to the directory by creating ACLs for the account. For instructions on giving write access to the Certificate Manager's entry, see the Directory Server documentation.
15.10.4. Directory Authentication Method
Depending on how the Certificate Manager should authenticate to the directory, set up Directory
Server for one of the following methods of communication:
• Publishing with basic authentication
• Publishing over SSL without client authentication
• Publishing over SSL with client authentication
See the Red Hat Directory Server documentation for instructions on setting up these methods of communication with the server.
15.11. Updating Certificates and CRLs in a Directory
The Certificate Manager and the publishing directory can become out of sync if certificates are issued or revoked while the Directory Server is down. Certificates that were issued or revoked need to be published or unpublished manually when the Directory Server comes back up.
To find certificates that are out of sync with the directory � valid certificates that are not in the directory and revoked or expired certificates that are still in the directory � the Certificate Manager keeps a record of whether a certificate in its internal database has been published to the directory. If the
Certificate Manager and the publishing directory become out of sync, use the Update Directory option in the Certificate Manager agent services page to synchronize the publishing directory with the internal database.
The following choices are available for synchronizing the directory with the internal database:
• Search the internal database for certificates that are out of sync and publish or unpublish.
361
Chapter 15. Publishing
• Publish certificates that were issued while the Directory Server was down. Similarly, unpublish certificates that were revoked or that expired while Directory Server was down.
• Publish or unpublish a range of certificates based on serial numbers, from serial number xx to serial number yy .
A Certificate Manager's publishing directory can be manually updated by a Certificate Manager agent only.
15.11.1. Manually Updating Certificates in the Directory
The Update Directory Server form in the Certificate Manager agent services page can be used to update the directory manually with certificate-related information. This form initiates a combination of the following operations:
• Update the directory with certificates.
• Remove expired certificates from the directory.
Removing expired certificates from the publishing directory can be automated by scheduling an automated job. For details, see Chapter 19, Automated Jobs .
• Remove revoked certificates from the directory.
Manually update the directory with changes by doing the following:
1. Open the Certificate Manager agent services page.
2. Select the Update Directory Server link.
3. Select the appropriate options, and click Update Directory .
The Certificate Manager starts updating the directory with the certificate information in its internal database. If the changes are substantial, updating the directory can take considerable time. During this period, any changes made through the Certificate Manager, including any certificates issued or any certificates revoked, may not be included in the update. If any certificates are issued or revoked while the directory is updated, update the directory again to reflect those changes.
When the directory update is complete, the Certificate Manager displays a status report. If the process is interrupted, the server logs an error message.
If the Certificate Manager is installed as a root CA, the CA signing certificate may get published using the publishing rule set up for user certificates when using the agent interface to update the directory with valid certificates. This may return an object class violation error or other errors in the mapper.
Selecting the appropriate serial number range to exclude the CA signing certificate can avoid this problem. The CA signing certificate is the first certificate a root CA issues.
• Modify the default publishing rule for user certificates by changing the value of the predicate parameter to HTTP_PARAMS.certType!=ca .
• Use the LdapCaCertPublisher publisher plug-in module to add another rule, with the predicate parameter set to HTTP_PARAMS.certType==ca , for publishing subordinate CA certificates.
362
Manually Updating the CRL in the Directory
15.11.2. Manually Updating the CRL in the Directory
The Certificate Revocation List form in the Certificate Manager agent services page manually updates the directory with CRL-related information.
Manually update the CRL information by doing the following:
1. Open the Certificate Manager agent services page.
2. Select Update Revocation List .
3. Click Update .
The Certificate Manager starts updating the directory with the CRL in its internal database. If the CRL is large, updating the directory takes considerable time. During this period, any changes made to the
CRL may not be included in the update.
When the directory is updated, the Certificate Manager displays a status report. If the process is interrupted, the server logs an error message.
15.12. Registering and Deleting Mapper and Publisher Plugin Modules
New mapper or publisher plug-in modules can be registered in a Certificate Manager's publishing framework. Unwanted mapper or publisher plug-in modules can be deleted. Before deleting a module, delete all the rules that are based on this module.
1. Log into the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select
Publishing .
3. To register or delete a mapper module, select Mappers , and then select the Mapper Plugin
Registration tab.
4. To register or delete a publisher module, select Publishers , and then select the Publisher Plugin Registration tab.
5. To delete a plug-in, select the plug-in, and click Delete . Confirm the deletion in the popup window that appears.
6. To register a plug-in, click Register .
7. Set the plug-in name and plug-in class name. The class name is, the path to the implementing
Java ™ class. If this class is part of a package, include the package name. For example, to register a class named customMapper in a package named com.customplugins
, the name is com.customplugins.customMapper
.
363
Chapter 15. Publishing
15.13. Module Reference
The following sections list and describe the publisher, mapper, and rule modules that are contained by default with the Certificate Manager.
• Section 15.13.1, “Publisher Plug-in Modules”
• Section 15.13.2, “Mapper Plug-in Modules ”
• Section 15.13.3, “Configuring Rule Instances”
15.13.1. Publisher Plug-in Modules
This section describes the publisher modules provided for the Certificate Manager. The modules are used by the Certificate Manager to enable and configure specific publisher instances.
• Section 15.13.1.1, “FileBasedPublisher”
• Section 15.13.1.2, “LdapCaCertPublisher”
• Section 15.13.1.3, “LdapUserCertPublisher”
• Section 15.13.1.4, “LdapCrlPublisher”
• Section 15.13.1.5, “LdapDeltaCrlPublisher”
• Section 15.13.1.6, “LdapCertificatePairPublisher”
• Section 15.13.1.7, “OCSPPublisher”
15.13.1.1. FileBasedPublisher
The FileBasedPublisher plug-in module configures a Certificate Manager to publish certificates and CRLs to file. This mapper can publish base-64 encoded files, DER-encoded files, or both, depending on the checkboxes selected when the publisher is configured. The certificate and CRL content can be viewed by converting the files using the PrettyPrintCert and PrettyPrintCRL tools. For details on viewing the content in base-64 and DER-encoded certificates and CRLs, see
Section 15.9, “Viewing Certificates and CRLs Published to File” .
By default, the Certificate Manager does not create an instance of the FileBasedPublisher module.
Parameter
Publisher ID
Description
Specifies a name for the publisher, an alphanumeric string with no spaces. For example, PublishCertsToFile .
directory Specifies the complete path to the directory to which the Certificate Manager creates the files; the path can be an absolute path or can be relative to the Certificate System instance directory. For example, /export/CS/ certificates .
Table 15.4. FileBasedPublisher Configuration Parameters
364
Publisher Plug-in Modules
15.13.1.2. LdapCaCertPublisher
The LdapCaCertPublisher plug-in module configures a Certificate Manager to publish or unpublish a CA certificate to the caCertificate;binary attribute of the CA's directory entry.
The module converts the object class of the CA's entry to a certificationAuthority , if it is not used already. Similarly, it also removes the certificationAuthority object class when unpublishing if the CA has no other certificates.
During installation, the Certificate Manager automatically creates an instance of the
LdapCaCertPublisher module for publishing the CA certificate to the directory.
Parameter caCertAttr
Description
Specifies the LDAP directory attribute to publish the CA certificate. This must be caCertificate;binary .
caObjectClass Specifies the object class for the CA's entry in the directory. This must be certificationAuthority .
Table 15.5. LdapCaCertPublisher Configuration Parameters
15.13.1.3. LdapUserCertPublisher
The LdapUserCertPublisher plug-in module configures a Certificate Manager to publish or unpublish a user certificate to the userCertificate;binary attribute of the user's directory entry.
This module is used to publish any end-entity certificate to an LDAP directory. Types of end-entity certificates include SSL client, S/MIME, SSL server, and OCSP responder.
During installation, the Certificate Manager automatically creates an instance of the
LdapUserCertPublisher module for publishing end-entity certificates to the directory.
Parameter Description certAttr Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the certificate. This must be userCertificate;binary .
Table 15.6. LdapUserCertPublisher Configuration Parameters
15.13.1.4. LdapCrlPublisher
The LdapCrlPublisher plug-in module configures a Certificate Manager to publish or unpublish the
CRL to the certificateRevocationList;binary attribute of a directory entry.
During installation, the Certificate Manager automatically creates an instance of the
LdapCrlPublisher module for publishing CRLs to the directory.
Parameter Description crlAttr Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the CRL. This must be certificateRevocationList;binary .
Table 15.7. LdapCrlPublisher Configuration Parameters
365
Chapter 15. Publishing
15.13.1.5. LdapDeltaCrlPublisher
The LdapDeltaCrlPublisher plug-in module configures a Certificate Manager to publish or unpublish a delta CRL to the deltaRevocationList;binary attribute of a directory entry.
During installation, the Certificate Manager automatically creates an instance of the
LdapDeltaCrlPublisher module for publishing CRLs to the directory.
Parameter Description crlAttr Specifies the directory attribute of the mapped entry to which the Certificate Manager should publish the delta CRL. This must be deltaRevocationList;binary .
Table 15.8. LdapDeltaCrlPublisher Configuration Parameters
15.13.1.6. LdapCertificatePairPublisher
The LdapCertificatePairPublisher plug-in module configures a Certificate Manager to publish or unpublish a cross-signed certificate to the crossCertPair;binary attribute of the CA's directory entry.
The module also converts the object class of the CA's entry to a certificationAuthority , if it is not used already. Similarly, it also removes the certificationAuthority object class when unpublishing if the CA has no other certificates.
During installation, the Certificate Manager automatically creates an instance of the
LdapCertificatePairPublisher module named LdapCrossCertPairPublisher for publishing the cross-signed certificates to the directory.
Parameter crossCertPairAttr
Description
Specifies the LDAP directory attribute to publish the CA certificate. This must be crossCertificatePair;binary .
caObjectClass
Table 15.9. LdapCertificatePairPublisher Parameters
Specifies the object class for the CA's entry in the directory. This must be certificationAuthority .
15.13.1.7. OCSPPublisher
The OCSPPublisher plug-in module configures a Certificate Manager to publish its CRLs to an
Online Certificate Status Manager.
The Certificate Manager does not create any instances of the OCSPPublisher module at installation.
Parameter host port
Description
Specifies the fully qualified hostname of the
Online Certificate Status Manager.
Specifies the port number on which the Online
Certificate Status Manager is listening to the
Certificate Manager. This is the Online Certificate
Status Manager's SSL port number.
366
Mapper Plug-in Modules
Parameter path
Table 15.10. OCSPPublisher Parameters
Description
Specifies the path for publishing the CRL. This must be the default path, /ocsp/addCRL .
15.13.2. Mapper Plug-in Modules
This section describes the mapper plug-in modules provided for the Certificate Manager. These modules configure a Certificate Manager to enable and configure specific mapper instances.
The available mapper plug-in modules include the following:
• Section 15.13.2.1, “LdapCaSimpleMap”
• Section 15.13.2.2, “LdapDNExactMap”
• Section 15.13.2.3, “LdapSimpleMap”
• Section 15.13.2.4, “LdapSubjAttrMap”
• Section 15.13.2.5, “LdapDNCompsMap”
15.13.2.1. LdapCaSimpleMap
The LdapCaSimpleMap plug-in module configures a Certificate Manager to create an entry for the
CA in an LDAP directory automatically and then map the CA's certificate to the directory entry by formulating the entry's DN from components specified in the certificate request, certificate subject name, certificate extension, and attribute variable assertion (AVA) constants. For more information on
AVAs, check the directory documentation.
The CA certificate mapper specifies whether to create an entry for the CA, to map the certificate to an existing entry, or to do both.
If a CA entry already exists in the publishing directory and the value assigned to the dnPattern parameter of this mapper is changed, but the uid and o attributes are the same, the mapper fails to create the second CA entry. For example, if the directory already has a CA entry for uid=CA,ou=Marketing,o=example.com
and a mapper is configured to create another CA entry with uid=CA,ou=Engineering,o=example.com
, the operation fails.
The operation may fail because the directory has the UID Uniqueness plug-in set to a specific base
DN. This setting prevents the directory from having two entries with the same UID under that base
DN. In this example, it prevents the directory from having two entries under o=example.com
with the same UID, CA .
If the mapper fails to create a second CA entry, check the base DN to which the UID Uniqueness plugin is set, and check if an entry with the same UID already exists in the directory. If necessary, adjust the mapper setting, remove the old CA entry, comment out the plug-in, or create the entry manually.
During installation, the Certificate Manager automatically creates two instances of the CA certificate mapper module. The mappers are named as follows:
• LdapCrlMap for CRLs (see Section 15.13.2.1.2, “LdapCrlMap” )
• LdapCaCertMap for CA certificates (see Section 15.13.2.1.1, “LdapCaCertMap” ).
367
Chapter 15. Publishing
Parameter createCAEntry
Description
Creates a CA's entry, if selected (default).
dnPattern
If selected, the Certificate Manager first attempts to create an entry for the CA in the directory. If the Certificate Manager succeeds in creating the entry, it then attempts to publish the CA's certificate to the entry. If this is not selected, the entry must already be present in order to publish to it.
Specifies the DN pattern the Certificate Manager should use to construct to search for the CA's entry in the publishing directory. The value of dnPattern can be a list of AVAs separated by commas. An AVA can be a variable, such as cn=$subj.cn
, that the Certificate Manager can derive from the certificate subject name or a constant, such as o=Example Corporation .
If the CA certificate does not have the cn component in its subject name, adjust the CA certificate mapping DN pattern to reflect the
DN of the entry in the directory where the CA certificate is to be published. For example, if the CA certificate subject DN is o=Example
Corporation and the CA's entry in the directory is cn=Certificate Authority, o=Example Corporation , the pattern is cn=Certificate Authority, o=$subj.o
.
• Example 1: uid=CertMgr, o=Example
Corporation
• Example 2: cn=$subj.cn,ou=
$subj.ou,o=$subj.o,c=US
• Example 3: uid=
$req.HTTP_PARAMS.uid, e=
$ext.SubjectAlternativeName.RFC822Name,ou=
$subj.ou
In the above examples, $req takes the attribute from the certificate request, $subj takes the attribute from the certificate subject name, and
$ext takes the attribute from the certificate extension.
Table 15.11. LdapCaSimpleMap Configuration Parameters
15.13.2.1.1. LdapCaCertMap
The LdapCaCertMap mapper is an instance of the LdapCaSimpleMap module. The Certificate
Manager automatically creates this mapper during installation.
368
Mapper Plug-in Modules
This mapper creates an entry for the CA in the directory and maps the CA certificate to the CA's entry in the directory.
By default, the mapper is configured to create an entry for the CA in the directory, The default DN pattern for locating the CA's entry is as follows: uid=$subj.cn,ou=people,o=$subj.o
15.13.2.1.2. LdapCrlMap
The LdapCrlMap mapper is an instance of the LdapCaSimpleMap module. The Certificate Manager automatically creates this mapper during installation.
This mapper creates an entry for the CA in the directory and maps the CRL to the CA's entry in the directory.
By default, the mapper is configured to create an entry for the CA in the directory. The default DN pattern for locating the CA's entry is as follows: uid=$subj.cn,ou=people,o=$subj.o
15.13.2.2. LdapDNExactMap
The LdapDNExactMap plug-in module configures a Certificate Manager to map a certificate to an
LDAP directory entry by searching for the LDAP entry DN that matches the certificate subject name.
To use this mapper, each certificate subject name must exactly match a DN in a directory entry. For example, if the certificate subject name is uid=jdoe, o=Example Corporation, c=US , when searching the directory for the entry, the Certificate Manager only searches for an entry with the DN uid=jdoe, o=Example Corporation, c=US .
If no matching entries are found, the server returns an error and does not publish the certificate.
This mapper does not require any values for any parameters because it obtains all values from the certificate.
15.13.2.3. LdapSimpleMap
The LdapSimpleMap plug-in module configures a Certificate Manager to map a certificate to an
LDAP directory entry by deriving the entry's DN from components specified in the certificate request, certificate's subject name, certificate extension, and attribute variable assertion (AVA) constants. For more information on AVAs, see the directory documentation.
By default, the Certificate Manager uses mapper rules that are based on the simple mapper. During installation, the Certificate Manager automatically creates an instance of the simple mapper module, named LdapUserCertMap . The default mapper maps various types of end-entity certificates to their corresponding directory entries.
15.13.2.3.1. Configuration Parameters of LdapSimpleMap
The simple mapper requires one parameter, dnPattern . The value of dnPattern can be a list of
AVAs separated by commas. An AVA can be a variable, such as uid=$subj.UID
, or a constant, such as o=Example Corporation .
369
Chapter 15. Publishing
• Example 1: uid=CertMgr, o=Example Corporation
• Example 2: cn=$subj.cn,ou=$subj.ou,o=$subj.o,c=US
• Example 3: uid= $req.HTTP_PARAMS.uid, e=
$ext.SubjectAlternativeName.RFC822Name,ou=$subj.ou
In the examples, $req takes the attribute from the certificate request, $subj takes the attribute from the certificate subject name, and $ext takes the attribute from the certificate extension.
15.13.2.4. LdapSubjAttrMap
The LdapSubjAttrMap plug-in module configures a Certificate Manager to map a certificate to an
LDAP directory entry using a configurable LDAP attribute. To use this mapper, the directory entries must include the specified LDAP attribute.
This mapper requires the exact pattern of the subject DN because the Certificate Manager searches the directory for the attribute with a value that exactly matches the entire subject DN. For example, if the specified LDAP attribute is certSubjectDN and the certificate subject name is uid=jdoe, o=Example Corporation, c=US , the Certificate Manager searches the directory for entries that have the attribute certSubjectDN=uid=jdoe, o=Example Corporation, c=US .
If no matching entries are found, the server returns an error and writes it to the log.
15.13.2.4.1. Configuration Parameters of LdapSubjAttrMap
Table 15.12, “LdapSubjAttrMap Parameters” describes these parameters.
Parameter certSubjNameAttr searchBase
Description
Specifies the name of the LDAP attribute that contains a certificate subject name as its value.
The default is certSubjectName , but this can be configured to any LDAP attribute.
Specifies the base DN for starting the attribute search. The permissible value is a valid DN of an
LDAP entry, such as o=example.com, c=US .
Table 15.12. LdapSubjAttrMap Parameters
15.13.2.5. LdapDNCompsMap
The LdapDNCompsMap plug-in module implements the DN components mapper. This mapper maps a certificate to an LDAP directory entry by constructing the entry's DN from components, such as cn , ou , o , and c , specified in the certificate subject name, and then uses it as the search DN to locate the entry in the directory. The mapper locates the following entries:
• The CA's entry in the directory for publishing the CA certificate and the CRL.
• End-entity entries in the directory for publishing end-entity certificates.
The mapper takes DN components to build the search DN. The mapper also takes an optional root search DN. The server uses the DN components to form an LDAP entry to begin a subtree search and the filter components to form a search filter for the subtree. If none of the DN components are configured, the server uses the base DN for the subtree. If the base DN is null and none of the DN
370
Mapper Plug-in Modules components match, an error is returned. If none of the DN components and filter components match, an error is returned. If the filter components are null, a base search is performed.
Both the DNComps and filterComps parameters accept valid DN components or attributes separated by commas. The parameters do not accept multiple entries of an attribute; for example, filterComps can be set to cn,ou but not to cn,ou2,ou1 . To create a filter with multiple instances of the same attribute, such as if directory entries contain multiple ou s, modify the source code for the
LdapDNCompsMap module.
The following components are commonly used in DNs:
• uid , which represents the user ID of a user in the directory.
• cn , which represents the common name of a user in the directory.
• ou , which represents an organizational unit in the directory.
• o , which represents an organization in the directory.
• l , which represents a locality (city).
• st , which represents a state.
• c , which represents a country.
For example, the following DN represents the user named Jane Doe who works for the Sales department at Example Corporation, which is located in Mountain View, California, United States: cn=Jane Doe, ou=Sales, o=Example Corporation, l=Mountain View, st=California, c=US
The Certificate Manager can use some or all of these components ( cn , ou , o , l , st , and c ) to build a DN for searching the directory. When creating a mapper rule, these components can be specified for the server to use to build a DN; that is, components to match attributes in the directory. This is set through the dnComps parameter.
For example, the components cn , ou , o , and c are set as values for the dnComps parameter. To locate Jane Doe's entry in the directory, the Certificate Manager constructs the following DN by reading the DN attribute values from the certificate, and uses the DN as the base for searching the directory: cn=Jane Doe, ou=Sales, o=Example Corporation, c=US
• A subject name does not need to have all of the components specified in the dnComps parameter.
The server ignores any components that are not part of the subject name, such as l and st in this example.
• Unspecified components are not used to build the DN. In the example, if the ou component is not included, the server uses this DN as the base for searching the directory: cn=Jane Doe, o=Example Corporation, c=US
371
Chapter 15. Publishing
For the dnComps parameter, enter those DN components that the Certificate Manager can use to form the LDAP DN exactly. In certain situations, however, the subject name in a certificate may match more than one entry in the directory. Then, the Certificate Manager might not get a single, distinct matching entry from the DN. For example, the subject name cn=Jane Doe, ou=Sales, o=Example
Corporation, c=US might match two users with the name Jane Doe in the directory. If that occurs, the Certificate Manager needs additional criteria to determine which entry corresponds to the subject of the certificate.
To specify the components the Certificate Manager must use to distinguish between different entries in the directory, use the filterComps parameter; for details, see Table 15.13, “LdapDNCompsMap
Configuration Parameters” . For example, if cn , ou , o , and c are values for the dnComps parameter, enter l for the filterComps parameter only if the l attribute can be used to distinguish between entries with identical cn , ou , o , and c values.
If the two Jane Doe entries are distinguished by the value of the uid attribute � one entry's uid is janedoe1 , and the other entry's uid is janedoe2 � the subject names of certificates can be set to include the uid component.
NOTE
The e , l , and st components are not included in the standard set of certificate request forms provided for end entities. These components can be added to the forms, or the issuing agents can be required to insert these components when editing the subject name in the certificate issuance forms.
15.13.2.5.1. Configuration Parameters of LdapDNCompsMap
With this configuration, a Certificate Manager maps its certificates with the ones in the LDAP directory by using the dnComps values to form a DN and the filterComps values to form a search filter for the subtree.
• If the formed DN is null, the server uses the baseDN value for the subtree. If both the formed DN and base DN are null, the server logs an error.
• If the filter is null, the server uses the baseDN value for the search. If both the filter and base DN are null, the server logs an error.
Table 15.13, “LdapDNCompsMap Configuration Parameters” describes these parameters.
Parameter baseDN dnComps
Description
Specifies the DN to start searching for an entry in the publishing directory. If the dnComps field is blank, the server uses the base DN value to start its search in the directory.
Specifies where in the publishing directory the
Certificate Manager should start searching for an LDAP entry that matches the CA's or the end entity's information.
For example, if dnComps uses the o and c attributes of the DN, the server starts the search from the o= org , c= country entry in the directory,
372
Configuring Rule Instances
Parameter Description where org and country are replaced with values from the DN in the certificate.
If the dnComps field is empty, the server checks the baseDN field and searches the directory tree specified by that DN for entries matching the filter specified by filterComps parameter values.
filterComps
The permissible values are valid DN components or attributes separated by commas.
Specifies components the Certificate Manager should use to filter entries from the search result.
The server uses the filterComps values to form an LDAP search filter for the subtree. The server constructs the filter by gathering values for these attributes from the certificate subject name; it uses the filter to search for and match entries in the LDAP directory.
If the server finds more than one entry in the directory that matches the information gathered from the certificate, the search is successful, and the server optionally performs a verification. For example, if filterComps is set to use the email and user ID attributes ( filterComps=e,uid ), the server searches the directory for an entry whose values for email and user ID match the information gathered from the certificate.
The permissible values are valid directory attributes in the certificate DN separated by commas. The attribute names for the filters need to be attribute names from the certificate, not from ones in the LDAP directory. For example, most certificates have an e attribute for the user's email address; LDAP calls that attribute mail .
Table 15.13. LdapDNCompsMap Configuration Parameters
15.13.3. Configuring Rule Instances
This section discusses the rule instances that have been set.
15.13.3.1. LdapCaCertRule
The LdapCaCertRule can be used to publish CA certificates to an LDAP directory.
Parameter type
Value cacert predicate enable yes
Description
Specifies the type of certificate that will be published.
Specifies a predicate for the publisher.
Enables the rule.
373
Chapter 15. Publishing
Parameter mapper
Value Description
Specifies the mapper used with the rule. See
Section 15.13.2.1.1, “LdapCaCertMap” for details on the mapper.
publisher LdapCaCertPublisher
Section 15.13.1.2, “LdapCaCertPublisher” for details on the publisher.
Table 15.14. LdapCaCert Rule Configuration Parameters
15.13.3.2. LdapXCertRule
The LdapXCertRule is used to publish cross-pair certificates to an LDAP directory.
Parameter type predicate enable mapper
Value xcert
Description
Specifies the type of certificate that will be published.
yes
Specifies a predicate for the publisher.
Enables the rule.
Specifies the mapper used with the rule. See
Section 15.13.2.1.1, “LdapCaCertMap” for details on the mapper.
publisher LdapCrossCertPairPublisher
Section 15.13.1.6, “LdapCertificatePairPublisher” for details on this publisher.
Table 15.15. LdapXCert Rule Configuration Parameters
15.13.3.3. LdapUserCertRule
The LdapUserCertRule is used to publish user certificates to an LDAP directory.
Parameter type predicate enable mapper
Value certs
Description
Specifies the type of certificate that will be published.
yes
Specifies a predicate for the publisher.
Enables the rule.
Specifies the mapper used with the rule. See
Section 15.13.2.3, “LdapSimpleMap” for details on the mapper.
publisher LdapUserCertPublisher
Section 15.13.1.3, “LdapUserCertPublisher” for details on the publisher.
Table 15.16. LdapUserCert Rule Configuration Parameters
15.13.3.4. LdapCRLRule
The LdapCRLRule is used to publish CRLs to an LDAP directory.
Parameter Value type predicate crl
Description
Specifies the type of certificate that will be published.
Specifies a predicate for the publisher.
374
Configuring Rule Instances
Parameter enable
Value yes
Description
Enables the rule.
mapper LdapCrlMap Specifies the mapper used with the rule. See
Section 15.13.2.1.2, “LdapCrlMap” for details on the mapper.
publisher LdapCrlPublisher
Section 15.13.1.4, “LdapCrlPublisher” for details on the publisher.
Table 15.17. LdapCRL Rule Configuration Parameters
375
376
Chapter 16.
Authentication for Enrolling
Certificates
This chapter covers how to enroll end entity certificates, how to create and manage server certificates, the authentication methods available in the Certificate System to use when enrolling end entity certificates, and how to set up those authentication methods.
16.1. Enrollment Overview
Enrollment is the process of issuing certificates to an end entity. The process is creating and submitting the request, authenticating the user requesting it, and then approving the request and issuing the certificate.
The method used to authenticate the end entity determines the entire enrollment process. There are three ways that the Certificate System can authenticate an entity:
• In agent-approved enrollment, end-entity requests are sent to an agent for approval. The agent approves the certificate request.
• In automatic enrollment, end-entity requests are authenticated using a plug-in, and then the certificate request is processed; an agent is not involved in the enrollment process.
• In CMC enrollment , a third party application can create a request that is signed by an agent and then automatically processed.
A Certificate Manager is initially configured for agent-approved enrollment and for CMC authentication.
Automated enrollment is enabled by configuring one of the authentication plug-in modules.
More than one authentication method can be configured in a single instance of a subsystem.
The HTML registration pages contain hidden values specifying the method used. With certificate profiles, the end-entity enrollment pages are dynamically-generated for each enabled profile. The authentication method associated with this certificate profile is specified in the dynamically-generated enrollment page.
16.1.1. The Authentication Process
An end entity submits a request for enrollment. The form used to submit the request identifies the method of authentication and enrollment. All HTML forms are dynamically-generated by the profiles, which automatically associate the appropriate authentication method with the form.
If the authentication method is an agent-approved enrollment, the request is sent to the request queue of the CA agent. If the automated notification for a request in queue is set, an email is sent to the appropriate agent that a new request has been received. The agent can modify the request as allowed for that form and the profile constraints. Once approved, the request must pass the certificate profiles set for the Certificate Manager, and then the certificate is issued. When the certificate is issued, it is stored in the internal database and can be retrieved by the end entity from the end-entities page by serial number or by request ID.
If the authentication method is automated, the end entity submits the request along with required information to authenticate the user, such as an LDAP username and password. When the user is
377
Chapter 16. Authentication for Enrolling Certificates successfully authenticated, the request is processed without being sent to an agent's queue. If the request passes the certificate profile configuration of the Certificate Manager, the certificate is issued and stored in the internal database. It is delivered to the end entity immediately through the HTML forms.
NOTE
An email can be automatically sent to an end entity when the certificate is issued for any authentication method by configuring automated notifications. See Chapter 18, Automated
Notifications for more information on notifications.
16.2. Agent-Approved Enrollment
The Certificate Manager is initially configured for agent-approved enrollment. An end entity makes a request which is sent to the agent queue for an agent's approval. An agent can modify request, change the status of the request, reject the request, or approve the request. Once the request is approved, the signed request is sent to the Certificate Manager for processing. The Certificate
Manager processes the request and issues the certificate.
The agent-approved enrollment method is not configurable. If a Certificate Manager is not configured for any other enrollment method, the server automatically sends all certificate-related requests to a queue where they await agent approval. This ensures that all requests that lack authentication credentials are sent to the request queue for agent approval.
16.2.1. Configuring Agent-Approved Enrollment
To configure agent-approved enrollment:
1. Set up the certificate profiles to use to enroll users, such as specifying agent-approved enrollment and setting policies for specific certificates in the certificate profile. See Chapter 13, Certificate
Profiles for more information about profiles.
2. Customize the HTML enrollment forms. For certificate profile-based enrollment, configure inputs that are used to generate the HTML enrollment form dynamically.
16.3. Automated Enrollment
In automated enrollment, an end-entity enrollment request is processed as soon as the user successfully authenticates by the method set in the authentication plug-in module; no agent approval is necessary. The following authentication plug-in modules are provided:
• Directory-based enrollment.
End entities are authenticated against an LDAP directory using their user ID and password or their DN and password. See Section 16.3.1, “Setting up Directory-Based
Authentication” .
• PIN-based enrollment.
End entities are authenticated against an LDAP directory using their user
ID, password, and a PIN set in their directory entry. See Section 16.3.2, “Setting up PIN-based
Enrollment” .
• CMCAuth.
Clients are created and sent agent-signed requests. Those requests are then processed, and the certificate issued. See Section 16.4, “Setting up CMC Enrollment” .
378
Setting up Directory-Based Authentication
• AgentCertAuth.
Agents who are successfully issued server certificates through an automated process are automatically authenticated when they present the agent certificate. If the certificate presented is the agent certificate stored in the database for the user ID, the request for the server certificate is automatically processed. This plug-in is enabled by default and has no parameters.
This form of automatic authentication can be associated with the certificate profile for enrolling for server certificates.
16.3.1. Setting up Directory-Based Authentication
The UidPwdDirAuth and the UdnPwdDirAuth plug-in modules implement directory-based authentication. End users enroll for a certificate by providing their user IDs or DN and password to authenticate to an LDAP directory.
Set up directory-based authentication by doing the following:
1. Create an instance of either the UidPwdDirAuth or UdnPwdDirAuth authentication plug-in module and configure the instance.
a. Open the CA Console.
pkiconsole https://server.example.com:9443/ca b. In the Configuration tab, select Authentication in the navigation tree.
The right pane shows the Authentication Instance tab, which lists the currently configured authentication instances.
NOTE
The UidPwdDirAuth plug-in is enabled by default.
c. Click Add .
The Select Authentication Plug-in Implementation window appears.
d. Select UidPwdDirAuth for user ID and password authentication, or select UdnPwdDirAuth for DN and password authentication.
e. Fill in the following fields in the Authentication Instance Editor window:
• Authentication Instance ID.
Accept the default instance name, or enter a new name.
• dnpattern.
Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.
• ldapStringAttributes.
Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes are copied from the authentication directory into the authentication token and used by the certificate profile to generate the subject name. Entering values for this parameter is optional.
379
Chapter 16. Authentication for Enrolling Certificates
• ldapByteAttributes.
Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules, such as adding additional information to users' certificates.
Entering values for this parameter is optional.
• ldap.ldapconn.host.
Specifies the fully-qualified DNS hostname of the authentication directory.
• ldap.ldapconn.port.
Specifies the TCP/IP port on which the authentication directory listens to requests; if the ldap.ldapconn.secureConn.
checkbox is selected, this should be the
SSL port number.
• ldap.ldapconn.secureConn.
Specifies the type, SSL or non-SSL, of the port on which the authentication directory listens to requests from the Certificate System. Select if this is an
SSL port.
• ldap.ldapconn.version.
Specifies the LDAP protocol version, either 2 or 3 . The default is
3 , since all Directory Servers later than version 3.x are LDAPv3.
• ldap.basedn.
Specifies the base DN for searching the authentication directory. The server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.
• ldap.minConns.
Specifies the minimum number of connections permitted to the authentication directory. The permissible values are 1 to 3 .
• ldap.maxConns.
Specifies the maximum number of connections permitted to the authentication directory. The permissible values are 3 to 10 .
f.
Click OK . The authentication instance is set up and enabled.
2. Set the certificate profiles to use to enroll users by setting policies for specific certificates.
Customize the enrollment forms by configuring the inputs in the certificate profiles, and include inputs for the information needed by the plug-in to authenticate the user. If the default inputs do not contain all of the information that needs to be collected, submit a request created with a thirdparty tool.
For information on configuring the profiles, see Section 13.3.3, “Populating Certificates with
Directory Attributes” .
16.3.2. Setting up PIN-based Enrollment
PIN-based authentication involves setting up PINs for each user in the LDAP directory, distributing those PINs to the users, and then having the users provide the PIN along with their user ID and password when filling out a certificate request. Users are then authenticated both against an LDAP directory using their user ID and password and against the PIN in their LDAP entry. When the user successfully authenticates, the request is automatically processed, and a new certificate is issued.
The Certificate System provides a tool, setpin , that adds the necessary schema for PINs to the
Directory Server and generates the PINs for each user.
The PIN tool performs the following functions:
380
Setting up PIN-based Enrollment
• Adds the necessary schema for PINs to the LDAP directory.
• Adds a PIN manager user who has read-write permissions to the PINs that are set up.
• Sets up ACIs to allow for PIN removal once the PIN has been used, giving read-write permissions for PINs to the PIN manager, and preventing users from creating or changing PINs.
• Creates PINs in each user entry.
NOTE
This tool is documented in the Certificate System Command-Line Tools Guide .
To set up PIN-based authentication:
1. Use the PIN tool to add schema needed for PINs, add PINs to the user entries, and then distribute the PINs to users.
a. Open the /usr/lib/rhpki/native-tools directory.
b. Open the setpin.conf
file in a text editor.
c. Follow the instructions outlined in the file and make the appropriate changes.
Usually, the parameters which need updated are the Directory Server's host name, Directory
Manager's bind password, and PIN manager's password.
d. Run the setpin command with its optfile option pointing to the setpin.conf
file.
setpin optfile=/usr/lib/rhpki/native-tools/setpin.conf
The tool modifies the schema with a new attribute (by default, pin ) and a new object class
(by default, pinPerson ), creates a pinmanager user, and sets the ACI to allow only the pinmanager user to modify the pin attribute.
e. To generate PINs for specific user entries or to provide user-defined PINs, add these PINs using an input file. For information on constructing an input file, see the PIN generator chapter in the Certificate System Command-Line Tools Guide .
f.
Run the setpin command to create hashed PINs in the directory.
Run the tool first without the write option to generate a list of PINs without actually changing the directory.
For example: setpin host=yourhost port=9446 length=11 input=infile output=outfile write
"binddn=cn=pinmanager,o=example.com" bindpw="password" basedn=o=example.com
"filter=(uid=u*)"
381
Chapter 16. Authentication for Enrolling Certificates g. Use the output file for delivering PINs to users after completing setting up the required authentication method.
After confirming that the PIN-based enrollment works, deliver the PINs to users so they can use them during enrollment. To protect the privacy of PINs, use a secure, out-of-band delivery method.
2. Set the policies for specific certificates in the certificate profiles to enroll users. See Chapter 13,
Certificate Profiles for information about certificate profile policies.
3. Create and configure an instance of the UidPwdPinDirAuth authentication plug-in.
a. Open the CA Console.
pkiconsole https://server.example.com:9443/ca b. In the Configuration tab, select Authentication in the navigation tree.
The right pane shows the Authentication Instance tab, which lists the currently configured authentication instances.
c. Click Add .
The Select Authentication Plug-in Implementation window appears.
d. Select the UidPwdPinDirAuth plug-in module.
e. Fill in the following fields in the Authentication Instance Editor window:
• Authentication Instance ID.
Accept the default instance name or enter a new name.
• removePin.
Sets whether to remove PINs from the authentication directory after end users successfully authenticate. Removing PINs from the directory restricts users from enrolling more than once, and thus prevents them from getting more than one certificate.
• pinAttr.
Specifies the authentication directory attribute for PINs. The PIN Generator utility sets the attribute to the value of the objectclass parameter in the setpin.conf
file; the default value for this parameter is pin .
• dnpattern.
Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.
• ldapStringAttributes.
Specifies the list of LDAP string attributes that should be considered authentic for the end entity. Entering values for this parameter is optional.
• ldapByteAttributes.
Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules, such as adding additional information to users' certificates.
Entering values for this parameter is optional.
382
Setting up PIN-based Enrollment
• ldap.ldapconn.host.
Specifies the fully-qualified DNS host name of the authentication directory.
• ldap.ldapconn.port.
Specifies the TCP/IP port on which the authentication directory listens to requests from the Certificate System.
• ldap.ldapconn.secureConn.
Specifies the type, SSL or non-SSL, of the port on which the authentication directory listens to requests. Select if this is an SSL port.
• ldap.ldapconn.version.
Specifies the LDAP protocol version, either 2 or 3 . By default, this is 3 , since all Directory Server versions later than 3.x are LDAPv3.
• ldap.ldapAuthentication.bindDN.
Specifies the user entry as whom to bind when removing PINs from the authentication directory. Specify this parameter only if the removePin checkbox is selected. It is recommended that a separate user entry that has permission to modify only the PIN attribute in the directory be created and used. For example, do not use the Directory Manager's entry because it has privileges to modify the entire directory content.
• password.
Gives the password associated with the DN specified by the ldap.ldapauthbindDN
parameter. When saving changes, the server stores the password in the single sign-on password cache and uses it for subsequent start ups. This parameter needs set only if the removePin checkbox is selected.
• ldap.ldapAuthentication.clientCertNickname.
Specifies the nickname of the certificate to use for SSL client authentication to the authentication directory to remove PINs. Make sure that the certificate is valid and has been signed by a CA that is trusted in the authentication directory's certificate database and that the authentication directory's certmap.conf
file has been configured to map the certificate correctly to a DN in the directory. This is needed for PIN removal only.
• ldap.ldapAuthentication.authtype.
Specifies the authentication type, basic authentication or SSL client authentication, required in order to remove PINs from the authentication directory.
• BasicAuth specifies basic authentication. With this option, enter the correct values for ldap.ldapAuthentication.bindDN
and password parameters; the server uses the DN from the ldap.ldapAuthentication.bindDN
attribute to bind to the directory.
• SslClientAuth specifies SSL client authentication. With this option, set the value of the ldap.ldapconn.secureConn
parameter to true and the value of the ldap.ldapAuthentication.clientCertNickname
parameter to the nickname of the certificate to use for SSL client authentication.
• ldap.basedn.
Specifies the base DN for searching the authentication directory; the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.
• ldap.minConns.
Specifies the minimum number of connections permitted to the authentication directory. The permissible values are 1 to 3 .
• ldap.maxConns.
Specifies the maximum number of connections permitted to the authentication directory. The permissible values are 3 to 10 .
383
Chapter 16. Authentication for Enrolling Certificates f.
Click OK .
4. Customize the enrollment forms by configuring the inputs in the certificate profiles. Include the information that will be needed by the plug-in to authenticate the user. If the default inputs do not contain all of the information that needs to be collected, submit a request created with a third-party tool.
16.4. Setting up CMC Enrollment
CMC enrollment sets up an enrollment client, signs the certificate request with an agent certificate, and then sends the signed request to the Certificate Manager. When this method is set up, the
Certificate Manager automatically issues certificates when a valid request signed with the agent certificate is received.
The CMCAuth authentication plug-in also activates CMC revocation. CMC revocation sets up a revocation client, signs the request with the agent certificate, and then sends the signed request to the Certificate Manager. When this method is set up, the Certificate Manager automatically revokes certificates when a valid request signed with the agent certificate is received.
To set up CMC enrollment:
1. Set up the certificate profile to use to enroll users by setting policies for specific certificates in the certificate profile. See Chapter 13, Certificate Profiles for information about profile policies.
2. If necessary, set up the CMCAuth authentication plug-in. An instance of this plug-in module is created and enabled by default. It has no configuration parameters. When the instance is enabled,
CMC enrollment and CMC revocation are both enabled for the server.
a. Open the CA Console.
pkiconsole https://server.example.com:9443/ca b. In the Configuration tab, select Authentication in the navigation tree.
The right pane shows the Authentication Instance tab listing currently configured authentication instances.
c. Click Add .
The Select Authentication Plug-in Implementation window appears.
d. Select the CMCAuth plug-in module.
e. In the Authentication Instance ID field, type a unique name for this instance that will identify it if the default name is not to be used.
There are no configuration options for this plug-in; it simply enables this functionality.
f.
Click OK . The authentication instance is now set up and enabled.
3. Use the CMCEnroll utility to sign certificate requests with the agent certificate.
This utility has the following syntax:
384
Setting up the Server for Multiple Requests in a Full CMC Request
CMCEnroll -d /certificate/directory -h password
-n cert_nickname -r certrequest.file
-p certDB_passwd [-c]
Parameter d h n r p c
Table 16.1. CMCEnroll Usage Options
Description
The location of the directory containing the cert8.db
, key3.db
, and secmod.db
files associated with the agent certificate.
Password to the database specified in the d option.
The common name of the certificate.
The filename of the certificate request.
The password to the browser certificate database.
Optional.
Includes a comment about the request.
NOTE
Surround values that include spaces in quotation marks.
16.4.1. Setting up the Server for Multiple Requests in a Full CMC
Request
CMC supports multiple CRMF or PKCS #10 requests in a single full CMC request. If the numRequests parameter in the .cfg
file is larger than 1, modify the server's certificate profile by doing the following:
1. By default, the servlet processing a full CMC request uses the caFullCMCUserCert profile. This profile only handles a single request.
2. To use the new profile instead of the default, modify the web.xml
file in the /var/lib/rhpkica/webapps/ca/WEB-INF/ directory. Locate the servlet which processes the full CMC request; by default, this is /ca/profileSubmitCMCFull . Change the value for the profileID parameter to the name of the new profiles.
For information on creating a new profile, see Chapter 13, Certificate Profiles .
3. Restart the server.
/etc/init.d/rhpki-ca restart
16.4.2. Testing CMCEnroll
1. Enable CMCEnroll.
385
Chapter 16. Authentication for Enrolling Certificates
2. Create a certificate request using the certutil tool.
3. Copy the PKCS #10 ASCII output to a text file.
4. Run the CMCEnroll utility.
For example, if the input file called request34.txt
, the agent certificate is stored in the directory /var/lib/rhpki-ca/alias , the certificate common name of the agent certificate is CertificateManagerAgentsCert , and the password for the certificate database is
1234pass , the command is as follows:
CMCEnroll -d "/var/lib/rhpki-ca/alias" -n "CertificateManagerAgentsCert"
-r /export/requests/request34.txt -p 1234pass
The output of this command is stored in a file with the same filename with .out
appended to the filename.
5. Submit the signed certificate through the end-entities page.
a. Open the end-entities page.
https://server.example.com:9443/ca/ee/ca b. Select the CMC enrollment form from the list of certificate profiles.
c. Paste the content of the output file into the Certificate Request text area of this form.
d. Remove -----BEGIN NEW CERTIFICATE REQUEST---- and ----END NEW
CERTIFICATE REQUEST---- from the pasted content.
e. Fill in the contact information, and submit the form.
6. The certificate is immediately processed and returned.
7. Use the agent page to search for the new certificate.
16.5. Certificate-Based Enrollment
NOTE
This feature is supported only in legacy enrollment. Certificate System supports certificatebased enrollment for browser certificates. End users can use preissued certificates to authenticate to the server in order to enroll for certificates.
Certificate-based enrollment is useful in two common deployment scenarios:
• A client is deployed that can generate dual key pairs. Dual certificates, one for signing and one for encrypting data, need to issued to the users. Additionally, users should be able to put their key materials only on hardware tokens.
386
Setting up Certificate-Based Enrollment
One way to achieve this is to initialize hardware tokens in bulk and preload them with dual certificates issued by the Certificate System for dual key pairs. These certificates are generated with generic common names, such as hardwaretoken1234 . This way, there is no one-to-one relation between users and the hardware tokens initially. Once the tokens are ready, they are given to the users. A user can get and use any preinitialized and certificate-loaded hardware token.
Next, all users use the randomly-picked token to enroll for a pair of certificates that have a subject name derived from their LDAP attribute values; the certificates are issued for the existing key pairs preloaded into the token, but now the key pairs are associated with the user's identity.
• Users need to use the signing certificate already in their possession to get an encryption certificate.
For example, single certificates for single key pairs have already been issued to users. A client application is deployed that is capable of generating dual key pairs. Now, users can use their signing certificates as authentication tokens to request another certificate to use for encrypting data.
16.5.1. Setting up Certificate-Based Enrollment
To set up certificate-based enrollment:
1. Customize the enrollment form to use.
2. Enable the appropriate enrollment option, such as directory-based enrollment or certificate-based enrollment. Configure the authentication module to compose the desired DN pattern.
3. Three enrollment forms are provided for the certificate-based enrollment:
• CertBasedDualEnroll.html
This form enables end users to request dual certificates, one for signing another for encryption, by submitting preissued certificates as authentication tokens; when a user enrolls for a certificate, the server verifies the CA that has issued the certificate used for authentication, uses the configured directory to formulate subject names for the new certificates, and issues the certificates.
• CertBasedEncryptionEnroll.html
This form is provided as a sample. It enables end users to request encryption certificates by submitting preissued certificates as authentication tokens; when a user enrolls for a certificate, the server verifies the CA that has issued the certificate used for authentication, uses the configured directory to formulate the subject name for the new certificate, and issues the certificate.
• CertBasedSingleEnroll.html
This form is provided as a sample. It enables end users to request signing certificates by submitting preissued certificates as authentication tokens; when a user enrolls for a certificate, the server verifies the CA that has issued the certificate used for authentication, uses the configured directory to formulate the subject name for the new certificate, and issues the certificate.
Enabling certificate-based enrollment creates one link, named Certificate , under the list of certificate profiles in the end-entities page. By default, the link points to the CertBasedDualEnroll.html
form. To use either of the other two forms,
CertBasedEncryptionEnroll.html
or CertBasedSingleEnroll.html
, associate the
Certificate link to the form or add more links to the index.html
file.
387
Chapter 16. Authentication for Enrolling Certificates
NOTE
All three enrollment forms work by default with the directory-based authentication module, UidPwdDirAuth , explained in Section 16.3.1, “Setting up Directory-Based
Authentication” . Certificate-based enrollment forms can be used with any of the authentication modules, such as directory- and PIN-based authentication modules.
In general, the following three hidden variables distinguish certificate-based enrollment forms from other enrollment forms:
• certauthEnroll This variable specifies whether certificate-based enrollment is turned on or off .
• certauthEnrollType This variable specifies one of the three certificate-based-enrollment types: dual , single , or encryption ; dual specifies that the enrollment request is for dual certificates; single specifies that the enrollment request is for a signing certificate; and encryption specifies that the enrollment request is for an encryption certificate.
NOTE
Choosing dual requires a client that is capable of generating dual key pairs.
• doSslAuth This variable specifies whether the server requests SSL client authentication.
Set the value of this parameter to on , and make sure that the port number specified in the authentication instance is an SSL port.
4. Before modifying a form, look at the default certificate-based enrollment forms.
16.6. Testing Enrollment
For information on testing enrollment through the profiles, see Chapter 13, Certificate Profiles . To test whether end users can successfully enroll for a certificate using the authentication method set:
1. Open the end-entities page.
https://server.example.com:9443/ca/ee/ca
2. In the Enrollment tab, open the customized enrollment form.
3. Fill in the values, and submit the request.
4. Enter the password to the key database when prompted.
5. When the correct password is entered, the client generates the key pair.
Do not interrupt the key-generation process. Upon completion of the key generation, the request is submitted to the server to issue the certificate. The server subjects the request to the certificate profile and issues the certificate only if the request meets all the requirements.
When the certificate is issued, install the certificate in the browser.
388
Managing Authentication Plug-ins
6. Verify that the certificate is installed in the browser's certificate database.
7. If directory- or PIN-based authentication was configured with PIN removal, re-enroll for another certificate using the same PIN. The request should be rejected.
16.7. Managing Authentication Plug-ins
Custom authentication plug-in modules can be registered through the CA Console. Authentication plug-in modules can also be deleted through the CA Console. Before deleting a module, delete instances that are based on that module.
To register or delete a module:
1. Log into the Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, click Authentication in the navigation tree
3. In the right pane, click the Authentication Plug-in Registration tab.
The tab lists modules that are already registered.
4. To delete a registered module, select that module, and click Delete .
5. To register a plug-in, click Register .
The Register Authentication Plug-in Implementation window appears.
6. Specify which module to register by filling in the two fields:
• Plugin name.
The name for the module.
• Class name.
The full name of the class for this module. This is the path to the implementing
Java ™ class. If this class is part of a package, include the package name. For example, to register a class named customAuth in a package named com.customplugins
, the class name is com.customplugins.customAuth
.
7. Click OK .
389
390
Chapter 17.
User and Group Authorization
This chapter explains how to set up authorization for access to the administrative, agent services, and end-entities pages.
17.1. About Authorization
Authorization is the process of allowing access to certain tasks associated with the Certificate System.
Access can be limited to allow certain tasks to certain areas of the subsystem for certain users or groups and different tasks to different users and groups.
Users are specific to the subsystem in which they are created. Each subsystem has its own set of users independent of any other subsystem installed. The users are placed in groups, which can be predefined or user-created. Privileges are assigned to a group through access control lists (ACLs).
There are ACLs associated with areas in the administrative console, agent services interface, and end-entities page that perform an authorization check before allowing an operation to proceed. Access control instructions (ACIs) in each of the ACLs are created that specifically allow or deny possible operations for that ACL to specified users, groups, or IP addresses.
The ACLs contain a default set of ACIs for the default groups that are created. These ACIs can be modified to change the privileges of predefined groups or to assign privileges to newly-created groups.
17.1.1. How Authorization Works
Authorization goes through the following process:
1. The users authenticate to the interface using either the Certificate System user ID and password or a certificate.
2. The server authenticates the user either by matching the user ID and password with the one stored in the database or by checking the certificate against one stored in the database. With certificate-based authentication, the server also checks that the certificate is valid and finds the group membership of the user by associating the DN of the certificate with a user and checking the user entry. With password-based authentication, the server checks the password against the user ID and then finds the group membership of the user by associating that user ID with the user
ID contained in the group.
3. When the user tries to perform an operation, the authorization mechanism compares the user ID of the user, the group in which the user belongs, or the IP address of the user to the ACLs set for that user, group or IP address. If an ACL exists that allows that operation, then the operation proceeds.
17.1.2. Default Groups
A user's privileges are determined by the group membership of the user. The default subsystem setting allows users to belong to more than one group. The following groups are created by default:
• Administrators.
This group is given full access to all of the tasks available in the administrative interface.
• Agents.
This group is given full access to all of the tasks available in the agent services interface.
391
Chapter 17. User and Group Authorization
• Auditors.
This group is given access to view the signed audit logs. This group does not have any other privileges.
• Enterprise administrators.
Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator when it is joined to a security domain during configuration. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems.
• Trusted managers.
A trusted manager is a subsystem that has a trusted relationship with another subsystem. This group is given access to connect with and submit requests to the subsystem for which it is a trusted manager.
17.1.2.1. Administrators
Administrators have permissions to perform all administrative tasks. A user is an administrator by being added to the Administrators group. Every member of this group has administrative privileges for this instance of Certificate System.
At least one administrator must be defined for each Certificate System instance, but there is no limit to the number of administrators an instance can have. The first administrator entry is created when the instance is configured.
Administrators are authenticated using their Certificate System user ID and password. It is possible to change the authentication method to SSL client authentication. See Section 3.2, “Enabling SSL Client
Authentication for the Certificate System Console” for more information.
17.1.2.2. Auditors
An auditor can view the signed audit logs and is created to audit the operation of the system. The auditor cannot administer the server in any way.
An auditor is created by adding a user to the Auditors group and storing the auditor's certificate in the user entry. The auditor's certificate is used to encrypt the private key of the key pair used to sign the audit log.
The Auditors group is set when the subsystem is configured. No auditors are assigned to this group during configuration.
Auditors are authenticated into the administrative console with their UID and password. The authentication method can be changed to SSL client authentication. See Section 3.2, “Enabling SSL
Client Authentication for the Certificate System Console” for more information. Once authenticated, auditors can only view the audit logs. They cannot edit other parts of the system.
17.1.2.3. Agents
Agents are users who have been assigned end-entity certificate and key-management privileges.
Agents can access the agent services interface. For a complete list of agent tasks, see the Certificate
System Agent's Guide .
Agents are created by assigning a user to the appropriate subsystem agent group and identifying certificates that the agents must use for SSL client authentication to the subsystem for it to service requests from the agents. Each subsystem has its own agent group:
• The Certificate Manager Agents group.
392
Default Groups
• The Data Recovery Manager Agents group.
• The Online Certificate Status Manager Agents group.
• The Token Key Service Agents group.
• The Token Processing System Agents group.
Each Certificate System subsystem has its own agents with roles defined by the subsystem. Each subsystem must have at least one agent, but there is no limit to the number of agents a subsystem can have.
Certificate System identifies and authenticates a user with agent privileges by checking the user's SSL client certificate in its internal database.
17.1.2.4. Enterprise Groups
During subsystem configuration, every subsystem instance is joined to a security domain.
Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems.
For example, this allows OCSPs to push CRL publishing publishing information to all CAs in the domain, DRMs to push KRA connector information, and CAs to approve certificates generated within the CA automatically.
Enterprise subsystem administrators are given enough privileges to perform operations on the subsystems in the domain. Each subsystem has its own security domain role:
• Enterprise CA Administrators
• Enterprise DRM Administrators
• Enterprise OCSP Administrators
• Enterprise TKS Administrators
• Enterprise TPS Administrators
Additionally, there is a Security Domain Administrators group for the CA instance which manages the security domain, access control, users, and trust relationships within the domain.
Each subsystem administrator authenticates to the other subsystems using SSL client authentication with the subsystem certificate issued during configuration by the security domain CA.
17.1.2.5. Trusted Managers
One subsystem can allow another subsystem to communicate over its agent port and perform certain functions for that subsystem by forming a trust between the two. The subsystem that is trusted is called a trusted manager .
NOTE
These trust relationships are unnecessary since all interacting subsystems are within the same security domain, and the security domain automatically creates similar relationships.
393
Chapter 17. User and Group Authorization
The trusted manager relationship is set up in the following way:
• The subsystem trusts the other subsystem as a trusted manager by creating a user ID for the subsystem, adding it to the trusted manager group, and storing its SSL client authentication certificate.
• The trusted manager sets up a connector to the subsystem by specifying the agent services port for that subsystem. All communications between the trusted manager and the subsystem go through this port.
A subsystem authenticates to the subsystem which trusts it as a trusted manager using its SSL server certificate for SSL client authentication.
17.2. Creating Users
To create an administrator, agent, or auditor, create a user in the Certificate System instance where the user will have privileges and assign the user to the appropriate group. An agent or auditor must have a certificate stored in the subsystem's internal database. If the Console is configured for SSL client authentication, all administrators must also a certificate.
To create a new user entry, do the following:
1. Log into the administrative console.
pkiconsole https:// hostname:SSLport/subsystemType
2. In the Configuration tab, select Users and Groups . Click Add .
3. Fill in the information in the Edit User Information dialog.
394
Setting up a Trusted Manager
Figure 17.1. Creating a New User
The group to which the user belongs determines what privileges the user has. Assign agents and administrators to the appropriate subsystem group.
4. Store the user's certificate.
a. Request and issue an SSL client certificate for the user if one has not already been generated.
b. Copy the base-64 encoded certificate to a local file or to the clipboard.
c. Select the new user entry, and click Certificates .
d. Click Import , and paste in the base-64 encoded certificate.
17.3. Setting up a Trusted Manager
Trusted relationships are set up automatically during subsystem configuration. All subsystems within the same security domain are automatically trusted; the security domain manager issues each member of the security domain a subsystem certificate which the subsystem use to communicate with each other. Setting up or modifying trust relationships is not necessary, except in rare situations when an administrator may want to adjust different values.
Set up a trusted manager by doing the following:
395
Chapter 17. User and Group Authorization
1. Log into the administrative console for the subsystem to which the trusted manager is being added.
pkiconsole https:// host:SSLport/subsystemType
2. In the Configuration tab, select Users and Groups . Click Add .
3. Fill in the identifying information.
The information is to help keep track of the trusted manager entry; the subsystem never uses it.
The subsystem relies solely on the trusted manager's SSL client certificate for authentication.
Figure 17.2. Creating the Trusted Manager Account
The full name must be the fully qualified host name of the Certificate Manager. The group must be set to Trusted Managers do that the CA has trusted manager privileges.
4. Store the Certificate Manager's SSL client certificate in the internal database of the subsystem.
a. In the Users tab, select the trusted manager entry, and click Certificates .
b. Click Import .
396
Setting up a Trusted Manager c. In the text area of the dialog, paste the Certificate Manager's certificate in base-64 encoded form. Include the -----BEGIN CERTIFICATE---- and -----END CERTIFICATE----marker lines.
d. To view the certificate, select it, and click View .
Next, configure the connector settings of the Certificate Manager. This enables the Certificate
Manager to utilize the agent port to communicate with the subsystem.
1. Log into the administrative console for the Certificate Manager.
2. In the navigation tree, select Certificate Manager .
3. Select the Connectors tab.
Figure 17.3. The Connector Tab
4. Select the connector from the list, and click Edit .
5. Select the Enable checkbox to enable the connector configuration, and enter the appropriate information.
397
Chapter 17. User and Group Authorization
Figure 17.4. Setting Connector Information
17.4. Modifying Certificate System User Entries
This section describes how to change a user entry, delete the user, or change the certificate associated with the user.
17.4.1. Changing a Certificate System User's Login Information
Change a Certificate System user's login information by doing the following:
1. Log into the administrative console.
398
Changing a Certificate System User's Certificate pkiconsole https:// host:SSLport/subsystemType
2. Select Users and Groups .
3. Select the user to edit from the list of user IDs, and click Edit .
4. Make the appropriate modifications.
17.4.2. Changing a Certificate System User's Certificate
To change a user's certificate, do the following:
1. Log into the administrative console.
2. Select Users and Groups .
3. Select the user to edit from the list of user IDs, and click Certificates .
• To view a certificate, select the certificate, and click View .
• To delete a certificate, select the certificate, and click Delete .
• To add a new certificate, click Import . In the Import Certificate window, paste the new certificate in the text area. Include the -----BEGIN CERTIFICATE---- and -----END
CERTIFICATE---- marker lines.
17.4.3. Changing Members in a Group
Members can be added or deleted from all groups. The group for administrators must have at least one user entry.
To change a group's members, do the following:
1. Log into the administrative console.
2. Select Users and Groups from the navigation tree on the left.
3. Click the Groups tab.
4. Select the group from the list of names, and click Edit .
5. Make the appropriate changes.
• To change the group description, type a new description in the Group description field.
• To remove a user from the group, select the user, and click Delete .
• To add users, click Add User . Select the users to add from the dialog box, and click OK .
17.4.4. Deleting a Certificate System User
Users can be deleted from the internal database. Deleting a user from the internal database deletes that user from all groups to which the user belongs. To remove the user from specific groups, modify the group membership.
399
Chapter 17. User and Group Authorization
Delete a privileged user from the internal database by doing the following:
1. Log into the administrative console.
2. Select Users and Groups from the navigation menu on the left.
3. Select the user from the list of user IDs, and click Delete .
4. Confirm the delete when prompted.
17.5. Creating a New Group
Create a new group by doing the following:
1. Log into the administrative console.
2. Select Users and Groups from the navigation menu on the left.
3. Select the Groups tab.
4. Click Edit , and fill in the group information.
Figure 17.5. Creating a New Group
It is only possible to add users who already exist in the internal database.
5. Edit the ACLs to grant the group privileges. See Section 17.6.5, “Editing ACLs” for more information. If no ACIs are added to the ACLs for the group, the group will have no access permissions to any part of Certificate System.
400
Authorization for Certificate System Users
17.6. Authorization for Certificate System Users
Authorization is the mechanism that checks whether a user is allowed to perform an operation.
Authorization points are defined in certain groups of operations that require an authorization check.
17.6.1. Access Control Lists (ACLs)
Access control lists (ACLs) are the mechanisms that specify the authorization to server operations. An
ACL exists for each set of operations where an authorization check occurs. Additional operations can be added to a ACL.
17.6.2. Access Control Instructions (ACIs)
The ACL contains access control instructions (ACIs) which specifically allow or deny operations, such as read or modify. The ACI also contains an evaluator expression. The default implementation of ACLs specifies users, groups, and IP addresses as possible evaluator types. Each ACI in an ACL specifies whether access is allowed or denied, what the specific operator is being allowed or denied, and which users, groups, or IP addresses is being allowed or denied to perform the operation.
17.6.3. Changing Privileges
The privileges of Certificate System users are changed by changing the access control lists (ACL) that are associated with the group in which the user is a member, for the users themselves, or for the IP address of the user. New groups are assigned access control by adding that group to the access control lists. For example, a new group for administrators who are only authorized to view logs,
LogAdmins , can be added to the ACLs relevant to logs to allow read or modify access to this group. If this group is not added to any other ACLs, members of this group only have access to the logs.
17.6.4. How ACIs Are Formed
The access for a user, group, or IP address is changed by editing the ACI entries in the ACLs. In the ACL interface, each ACI is shown on a line of its own. In this interface window, the ACI has the following syntax: allow|deny (operator) user|group|IP="name"
For example, the following is an ACI that allows administrators to perform read operations: allow (read) group="Administrators"
An ACI can have more than one operator. The operators are separated with a comma with no space on either side. For example: allow (read,modify) group="Administrators"
An ACI can have more than one group, user, or IP address by separating them with two pipe symbols
( || ) with a space on either side. For example:
401
Chapter 17. User and Group Authorization allow (read) group="Administrators" || group="Auditors"
The administrative console can create or modify ACIs. The interface sets whether to allow or deny the operation in the Allow and Deny field, sets which operations are possible in the Operations field, and then lists the groups, users, or IP addresses being granted or denied access in the Syntax field.
17.6.4.1. Allow and Deny
An ACI can either allow or deny an operation for the specified group, user ID, or IP address. Generally,
ACIs do not need created to deny access. If there are no allow ACIs that include a user ID, group, or
IP address, the group, user ID, or IP address is denied access.
If a user is not allowed access to any of the operations for a resource, then this user is considered denied; he does not specifically need to be denied access. For example, user JohnB is a member of the Administrators group. If an ACL has only the following ACI, JohnB would be denied any access since he does not match any of the allow ACIs:
Allow (read,modify) group="Auditors" || user="BrianC"
There usually is not a need to include a deny statement. Some situations can arise, however, when it is useful to specify one. For example, JohnB , a member of the Administrators group, has just been fired. It may be necessary to deny access specifically to JohnB if the user cannot be deleted immediately. Another situation is that a user, BrianC , is an administrator, but he should not have the ability to change some resource. Since the Administrators group must access this resource,
BrianC can be specifically denied access by creating an ACI that denies this user access.
17.6.4.2. Allowable Rights
The allowed rights are the operations which the ACI is controlling, either by allowing or denying permission to perform the operation. The actions that can be set for an ACL vary depending on the
ACL and subsystem. Two common operations that can be defined are read and modify.
17.6.4.3. Syntax
The syntax field of the ACI editor sets the evaluator for the expression. The evaluator can specify group, name, and IP address. These are specified along with the name of the entity set as equals ( = ) or does not equal ( != ).
17.6.4.3.1. Group Syntax
The syntax to include a group in the ACL is group="groupname" . The syntax to exclude a group is group!="groupname" , which allows any group except for the group named. For example: group="Administrators" group!="Auditors"
It is also possible to use regular expressions to specify the group, such as using wildcard characters like an asterisk ( * ). For example: group="* Managers"
402
How ACIs Are Formed
For more information on supported regular expression patterns, see http://java.sun.com/j2se/1.4.2/ docs/api/java/util/regex/Pattern.html#sum .
17.6.4.3.2. User Syntax
The syntax to include a user in the ACL is user="userID" . The syntax to exclude the user is user!
="userID" , which allows any user ID except for the user ID named. For example: user="BobC" user!="JaneK"
To specify all users, provide the value anybody . For example: user="anybody"
It is also possible to use regular expressions to specify the user names, such as using wildcard characters like an asterisk ( * ). For example: user="*johnson"
For more information on supported regular expression patterns, see http://java.sun.com/j2se/1.4.2/ docs/api/java/util/regex/Pattern.html#sum .
17.6.4.3.3. IP Address Syntax
The syntax to include an IP address in the ACL is ipaddress="ipaddress" . The syntax to exclude an ID address from the ACL is ipaddress!="ipaddress" . An IP address is specified using its numeric value, DNS values are not permitted. For example: ipaddress="12.33.45.99" ipaddress!="23.99.09.88"
It is also possible to use regular expressions to specify the IP address, such as using wildcard characters like an asterisk ( * ). For example: ipaddress="12.33.45.*"
For more information on supported regular expression patterns, see http://java.sun.com/j2se/1.4.2/ docs/api/java/util/regex/Pattern.html#sum .
17.6.4.4. Stringing Values
It is possible to create a string with more than one value by separating each value with two pipe characters (||) with a space on either side. For example: user="BobC" || group="Auditors" || group="Administrators"
403
Chapter 17. User and Group Authorization
17.6.5. Editing ACLs
ACLs are stored in the internal database and can only be modified in the administrative console.
To edit the existing ACLs, do the following:
1. Log into the administrative console.
2. Select Access Control List in the left navigation menu.
Figure 17.6. Default ACL List
3. Select the ACL to edit from the list, and click Edit . See Section 17.7, “ACL Reference” for information about each ACL.
The ACL opens in the Access Control Editor window.
404
Editing ACLs
Figure 17.7. The ACL Editor Window
4. To add an ACI, click Add , and supply the ACI information.
To edit an ACI, select the ACI from the list in the ACI entries text area of the ACL Editor window.
Click Edit .
405
Chapter 17. User and Group Authorization
Figure 17.8. Creating and Editing ACIs a. Select the allow or deny radio button from the Access field to allow or deny the operation to the groups, users, or IP addresses specified. For more information about allowing or denying access, see Section 17.6.4.1, “Allow and Deny” .
b. Set the rights for the access control. The options are read and modify . To set both, use the
Ctrl or Shift buttons.
c. Specify the user, group, or IP address that will be granted or denied access in the Syntax field. See Section 17.6.4.3, “Syntax” for details on syntax.
17.7. ACL Reference
This section lists all ACL resources defined for all subsystems, describes what each resource controls, lists the possible operations describing the outcome of those operations, and provides the default ACIs for each ACL resource defined. Each subsystem contains only those ACLs that are relevant to that subsystem.
17.7.1. certServer.acl.configuration
Controls operations to the ACL configuration.
406
certServer.admin.certificate
17.7.1.1. Operations
Operations read modify
17.7.1.2. Default ACIs allow (read) group="Administrators" || group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group=Auditors allow (modify) group="Administrators"
Agents, administrators, and auditors can read ACL configuration; only administrators can modify ACL configuration.
17.7.2. certServer.admin.certificate
This entry is associated with the CA administration interface and is only available during the configuration of the target of evaluation (TOE); it is unavailable after the CA is running.
17.7.2.1. Operations
Operations import
17.7.2.2. Default ACIs allow (import) user="anybody"
Anyone can import a certificate.
17.7.3. certServer.admin.request.enrollment
This entry is associated with the CA administration interface and is only available during the configuration of the target of evaluation (TOE); it is unavailable after the CA is running. Allow or deny submit, read, or execute operations for an administrator enrollment request.
17.7.3.1. Operations
Operations submit read
407
Description
View ACL resources and list ACL resources, ACL listing evaluators, and ACL evaluator types.
Add, delete, and update ACL evaluators.
Description
Import a CA administrator certificate.
Description
Submit a CA administrator certificate enrollment request.
View a CA administrator certificate enrollment request.
Chapter 17. User and Group Authorization
Operations execute
17.7.3.2. Default ACIs allow (submit) user="anybody" allow (read,execute) group="Certificate Manager Agents"
Anyone can submit an enrollment request; only Certificate Manager agents may read or execute request.
17.7.4. certServer.auth.configuration
Controls operations on the authentication configuration.
17.7.4.1. Operations
Operations read modify
17.7.4.2. Default ACIs allow (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group="Auditors" allow (modify) group="Administrators"
Administrators, agents, and auditors are allowed to read authentication configuration; administrators are allowed to modify authentication configuration.
17.7.5. certServer.ca.certificate
Controls import, unrevoke, revoke, and read operations for certificates in the agents services interface.
17.7.5.1. Operations
Operations import
408
Description
Execute a CA administrator certificate enrollment request.
Description
View authentication plug-ins, authentication type, configured authentication manager plug-ins, and authentication instances.
List authentication manager plug-ins and authentication manager instances.
Add or delete authentication plug-ins and authentication instances. Modify authentication instances.
Description
Retrieve a certificate by serial number.
certServer.ca.certificates
Operations unrevoke revoke read
17.7.5.2. Default ACIs allow (import,unrevoke,revoke,read) group="Certificate Manager Agents"
Certificate Manager agents can import, unrevoke, revoke, and read a certificate.
17.7.6. certServer.ca.certificates
Controls revoke or list operations for certificates in the agent services interface.
17.7.6.1. Operations
Operations revoke list
17.7.6.2. Default ACIs allow (revoke,list) group="Certificate Manager Agents"
Only Certificate Manager agents can revoke or list certificates.
17.7.7. certServer.ca.configuration
Controls operations on the general configuration for a Certificate Manager.
17.7.7.1. Operations
Operations read modify
409
Description
Change the status of a certificate from revoked.
Revoke certificates, or approve certificate revocation requests.
Retrieve certificates based on the request ID, and display certificate details based on the request ID.
Description
Revoke certificates, or approve certificate revocation requests.
List certificates based on a search. Retrieve details about a range of certificates based on a range of serial numbers.
Description
View CRL plug-in information, general CA configuration, CA connector configuration, CRL issuing points configuration, CRL configuration, request notification configuration, revocation notification configuration, request in queue notification configuration, and CRL extensions configuration. List CRL extensions configuration and CRL issuing points configuration.
Add and delete CRL issuing points. Modify general CA settings, CA connector configuration, CRL issuing points configuration, CRL configuration, request notification
Chapter 17. User and Group Authorization
Operations
17.7.7.2. Default ACIs allow (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group="Auditors" allow (modify) group="Administrators"
Administrators, auditors, and agents are allowed to read CA configuration; only administrators are allowed to modify CA configuration.
17.7.8. certServer.ca.connector
Controls submit operations for a connection to the CA.
17.7.8.1. Operations
Operations submit
17.7.8.2. Default ACIs allow (submit) group="Trusted Managers"
A trusted manager can submit requests to this interface.
17.7.9. certServer.ca.clone
Controls submit operations for a connection to the CA by a cloned CA.
17.7.9.1. Operations
Operations submit
17.7.9.2. Default ACIs
410
Description configuration, revocation notification configuration, request in queue notification configuration, and CRL extensions configuration.
Description
Submit requests from remote trusted managers.
Description
Submit information about a revoked certificate from a cloned
CA.
allow (submit) group="Certificate Manager Agents"
A trusted manager can submit requests through the subsystem interface.
17.7.10. certServer.ca.crl
Controls read or update operations for CRLs in the agent services interface.
17.7.10.1. Operations
Operations read update
17.7.10.2. Default ACIs allow (read,update) group="Certificate Manager Agents"
Certificate Manager agents can read or update CRLs.
17.7.11. certServer.ca.directory
Controls update operations to the directory.
17.7.11.1. Operations
Operations update
17.7.11.2. Default ACIs allow (update) group="Certificate Manager Agents"
Certificate Manager agents can update the directory.
17.7.12. certServer.ca.group
Controls operations to add a group.
17.7.12.1. Operations
Operations add certServer.ca.crl
411
Description
Display CRLs.
Update CRLs.
Description
Publish CA certificates and user certificates to the LDAP directory.
Description
Add groups.
Chapter 17. User and Group Authorization
17.7.12.2. Default ACIs allow (add) group="Administrators"
Only administrators are allowed to add groups.
17.7.13. certServer.ca.ocsp
Controls read operations for OCSP information in the agent services interface.
17.7.13.1. Operations
Operations read
17.7.13.2. Default ACIs allow (read) group="Certificate Manager Agents"
Only Certificate Manager agents can read OCSP usage statistics.
17.7.14. certServer.ca.profiles
Controls list operations for certificate profiles in the agent services interface.
17.7.14.1. Operations
Operations list
17.7.14.2. Default ACIs allow (list) group="Certificate Manager Agents"
Certificate Manager agents can list certificate profiles.
17.7.15. certServer.ca.profile
Controls operations for certificate profiles in the agent services interface.
17.7.15.1. Operations
Operations read
412
Description
Retrieve OCSP usage statistics.
Description
List certificate profiles.
Description
View the details of the certificate profiles.
certServer.ca.requests
Operations approve
17.7.15.2. Default ACIs allow (read,approve) group="Certificate Manager Agents"
Certificate Manager agents can view and approve certificate profiles.
17.7.16. certServer.ca.requests
Controls list operations for requests in the agents services interface.
17.7.16.1. Operations
Operations list
17.7.16.2. Default ACIs allow (list) group="Certificate Manager Agents"
Only Certificate Manager agents can list requests.
17.7.17. certServer.ca.request.enrollment
Controls submit, read, execute, assign, and unassign operations for enrollment requests.
17.7.17.1. Operations
Operations submit read execute assign unassign
17.7.17.2. Default ACIs allow (submit) user="anybody" allow (read,execute,assign,unassign) group="Certificate Manager Agents"
413
Description
Approve and enable certificate profiles.
Description
Retrieve details on a range of requests.
Description
Submit an enrollment request.
View an enrollment request.
Modify the approval state of a request.
Assign a request to a Certificate Manager agent.
Change the assignment of a request.
Chapter 17. User and Group Authorization
Anyone can submit an enrollment request; only Certificate Manager agents can read or execute enrollment requests.
17.7.18. certServer.ca.request.profile
Controls approve or read operations for certificate profile-based requests.
17.7.18.1. Operations
Operations approve read
17.7.18.2. Default ACIs allow (approve,read) group="Certificate Manager Agents"
Only Certificate Manager agents can view or modify the approval state of certificate profile-based requests.
17.7.19. certServer.ca.systemstatus
Controls approve or read operations for viewing statistics.
17.7.19.1. Operations
Operations read
17.7.19.2. Default ACIs allow (read) group="Certificate Manager Agents"
Only Certificate Manager agents may view statistics.
17.7.20. certServer.ee.certificate
Controls revoke, read, or import operations through the end-entities page.
17.7.20.1. Operations
Operations revoke
Description
Submit a revocation for a user certificate.
414
Description
Modify the approval state of a certificate profile-based certificate request.
View a certificate profile-based certificate request.
Description
View statistics.
certServer.ee.certificates
Operations read import
17.7.20.2. Default ACIs
Description
Retrieve and view certificates based on the certificate serial number or request ID.
Import a certificate into a client.
allow (revoke,read,import) user="anybody"
Anyone can request a revocation and import and read a certificate.
17.7.21. certServer.ee.certificates
Controls revoke or list operations in the end-entities page.
17.7.21.1. Operations
Operations revoke list
17.7.21.2. Default ACIs allow (revoke,list) user="anybody"
Anyone can revoke and list certificates.
17.7.22. certServer.ee.certchain
Controls download or read operations for the CA's certificate chain in the end-entities page.
17.7.22.1. Operations
Operations download read
17.7.22.2. Default ACIs allow (download,read) user="anybody"
Anyone can read or download a CA certificate chain.
415
Description
Submit a list of certificates to revoke.
Search for certificates matching specified criteria.
Description
Download the CA's certificate chain.
View the CA's certificate chain.
Chapter 17. User and Group Authorization
17.7.23. certServer.ee.crl
Controls read and add operations for CRLs in the end-entities page.
17.7.23.1. Operations
Operations read add
17.7.23.2. Default ACIs allow (read,add) user="anybody"
Anyone can add or read a CRL.
17.7.24. certServer.ee.profile
Controls submit and read operations for certificate profiles in the end-entities page.
17.7.24.1. Operations
Operations submit read
17.7.24.2. Default ACIs allow (submit,read) user="anybody"
Anyone can read and submit requests through certificate profiles.
17.7.25. certServer.ee.profiles
Controls list operations for certificate profiles in the end-entities page.
17.7.25.1. Operations
Operations list
17.7.25.2. Default ACIs allow (list) user="anybody"
416
Description
Retrieve and view the certificate revocation list.
Add CRLs to the OCSP server.
Description
Submit a certificate request through a certificate profile.
Displaying details of a certificate profile.
Description
List certificate profiles.
certServer.ee.facetofaceenrollment
Anyone can list certificate profiles.
17.7.26. certServer.ee.facetofaceenrollment
Controls list operations for certificate profiles to read face-to-face enrollment pages.
17.7.26.1. Operations
Operations read
17.7.26.2. Default ACIs allow (read) user="anybody"
Anyone can read the face-to-face enrollment page.
17.7.27. certServer.ee.request.enrollment
Controls submit operations for certificate enrollment in the end-entities page.
17.7.27.1. Operations
Operations submit
17.7.27.2. Default ACIs allow (submit) user="anybody"
Anyone can submit an enrollment request.
17.7.28. certServer.ee.request.facetofaceenrollment
Controls submitting face-to-face enrollments.
17.7.28.1. Operations
Operations submit
17.7.28.2. Default ACIs allow (submit) user="anybody"
417
Description
Read the face-to-face enrollment page.
Description
Submit a request for a new certificate.
Description
Submit face-to-face enrollment.
Chapter 17. User and Group Authorization
Anyone can submit face-to-face enrollment.
17.7.29. certServer.ee.request.ocsp
Controls submitting OCSP requests.
17.7.29.1. Operations
Operations submit
17.7.29.2. Default ACIs allow (submit) user="anybody"
Any clients can submit OCSP requests.
17.7.30. certServer.ee.request.revocation
Controls submit operations for certificate revocation requests in the end-entities page.
17.7.30.1. Operations
Operations submit
17.7.30.2. Default ACIs allow (submit) user="anybody"
Anyone can submit a revocation request.
17.7.31. certServer.ee.requestStatus
Controls read operations for the request status available from the end-entities page.
17.7.31.1. Operations
Operations read
17.7.31.2. Default ACIs
418
Description
Submit OCSP requests.
Description
Submit a request to revoke a certificate.
Description
Retrieve the status of a request and serial numbers of any certificates that have been issued against that request.
allow (read) user="anybody"
Anyone can read a request status.
17.7.32. certServer.general.configuration
Controls operations on the general configuration of the subsystem.
17.7.32.1. Operations
Operations read modify certServer.general.configuration
17.7.32.2. Default ACIs allow (read) group="Administrators"
|| group="Auditors"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents" allow (modify) group="Administrators"
Administrators, auditors, and agents are allowed to read Certificate System general configuration; only administrators are allowed to modify Certificate System general configuration.
17.7.33. certServer.job.configuration
Controls operations on the jobs configuration.
17.7.33.1. Operations
Operations read modify
419
Description
View the operating environment, LDAP configuration, SMTP configuration, server statistics, encryption, token names, subject name of certificates, certificate nicknames, CA certificates, and all certificates for management.
Modify LDAP database configuration, SMTP configuration, and encryption. Import certificates, trust and untrust CA certificates, import cross-pair certificates, install certificates, and delete certificates. Log all tokens and check token status. Run selftests on demand. Get certificate information. Process the certificate subject name. Validate the certificate subject name, certificate key length, and certificate extension.
Description
View basic job settings, job instance settings, and job plug-in settings. List job plug-ins and job instances.
Add and delete job plug-ins and job instances. Modify job plugins and job instances.
Chapter 17. User and Group Authorization
17.7.33.2. Default ACIs allow (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group="Auditors" allow (modify) group="Administrators"
Administrators, agents, and auditors are allowed to read job configuration; only administrators are allowed to modify job configuration.
17.7.34. certServer.kra.certificate.transport
Controls actions to display the key transport certificate.
17.7.34.1. Operations
Operations read
17.7.34.2. Default ACIs allow (read) user="anybody"
Anyone can view the key transport certificate.
17.7.35. certServer.kra.configuration
Controls operations on the DRM configuration.
17.7.35.1. Operations
Operations read modify
17.7.35.2. Default ACIs allow (read) group="Administrators"
|| group="Auditors"
420
Description
Display the key transport certificate.
Description
View automatic key recovery automatic configuration, key recovery archive configuration, and notification request in queue configuration.
Modify automatic key recovery archive configuration, agent passwords, and notification requests in queue configuration.
certServer.kra.connector
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents" allow (modify) group="Administrators"
Administrators, auditors, and agents are allowed to read DRM general configuration; only administrators are allowed to modify DRM configuration.
17.7.36. certServer.kra.connector
Controls request submissions.
17.7.36.1. Operations
Operations submit
17.7.36.2. Default ACIs allow (submit) group="Trusted Managers"
Only trusted managers can submit requests.
17.7.37. certServer.kra.key
Controls read, recover, and download operations for the DRM.
17.7.37.1. Operations
Operations read recover download
17.7.37.2. Default ACIs allow (read,recover,download) group="Data Recovery Manager Agents"
Only DRM agents can read, recover, or retrieve key information.
17.7.38. certServer.kra.keys
Controls list operations for the DRM.
421
Description
Submit requests.
Description
Display a key recovery request.
Indicate that a DRM has approved the key recovery. Finalize a key recovery operation.
Download a PKCS#12 file containing a private key.
Chapter 17. User and Group Authorization
17.7.38.1. Operations
Operations list
17.7.38.2. Default ACIs allow (list) group="Data Recovery Manager Agents"
Only DRM agents can list keys.
17.7.39. certServer.kra.request
Controls read operation for a DRM request.
17.7.39.1. Operations
Operations read
17.7.39.2. Default ACIs allow (read) group="Data Recovery Manager Agents"
DRM agents can read requests.
17.7.40. certServer.kra.requests
Controls list operations for a DRM request.
17.7.40.1. Operations
Operations list
17.7.40.2. Default ACIs allow (list) group="Data Recovery Manager Agents"
Only DRM agents can list key archival requests.
17.7.41. certServer.kra.request.status
Controls read operations for a DRM request.
422
Description
Search for keys to be recovered using various search filters.
Retrieve a list of key archival records matching search criteria.
Description
Assign a request to a DRM agent.
Description
Retrieve a range of key archival requests.
17.7.41.1. Operations
Operations read
17.7.41.2. Default ACIs allow (read) group="Data Recovery Manager Agents"
Only DRM agents can get the status of key archival requests.
17.7.42. certServer.kra.systemstatus
Controls read operations to display the system status of a DRM.
17.7.42.1. Operations
Operations read
17.7.42.2. Default ACIs allow (read) group="Data Recovery Manager Agents"
Only DRM agents can read system status.
17.7.43. certServer.log.configuration
Controls operations on the log configuration.
17.7.43.1. Operations
Operations read modify
17.7.43.2. Default ACIs allow (read) group="Administrators"
|| group="Auditors"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents" certServer.kra.systemstatus
423
Description
Get the status of a completed key recovery request.
Description
Displaying system statistics for a DRM.
Description
View log plug-in information, log plug-in configuration, and log instance configuration. List log plug-ins and log instances.
Add and delete log plug-ins and log instances. Modify log instances.
Chapter 17. User and Group Authorization
|| group="Online Certificate Status Manager Agents" allow (modify) group="Administrators"
Administrators, agents, and auditors are allowed to read the log configuration; only administrators are allowed to modify the log configuration.
17.7.44. certServer.log.configuration.SignedAudit.expirationTime
Controls operations on the expirationTime parameter of a log instance.
17.7.44.1. Operations
Operations read modify
17.7.44.2. Default ACIs allow (read) group="Administrators"
|| group="Auditors"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents" deny (modify) user=anybody
Administrators, auditors, and agents can read the value of the expirationTime parameter; no one is allowed to modify the value of the expirationTime parameter for the signed audit log.
17.7.45. certServer.log.configuration.fileName
Controls operations on the fileName parameter of a log instance.
17.7.45.1. Operations
Operations read modify
17.7.45.2. Default ACIs allow (read) group="Administrators"
|| group="Auditors"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
424
Description
View the value of the expirationTime parameter.
Modify the value of the expirationTime parameter.
Description
View the value of the fileName parameter for a log instance.
Modify the value of the fileName parameter for a log instance.
certServer.log.content.SignedAudit
deny (modify) user=anybody
Administrators, agents, and auditors can view the value of the fileName parameter; no one is allowed to modify the fileName parameter.
17.7.46. certServer.log.content.SignedAudit
Controls read operations to the signed audit log.
17.7.46.1. Operations
Operations read
17.7.46.2. Default ACIs deny (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
Only an auditor is allowed to view the audit log.
NOTE
All other groups need to be specifically denied access to this log since they are given access to all logs in the certServer.log.content
ACL.
17.7.47. certServer.log.content
Controls read operations to all logs.
17.7.47.1. Operations
Operations read
17.7.47.2. Default ACIs
Description
View log content. List all logs.
allow (read) group="Administrators"
|| group="Auditors"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
Administrators, agents, and auditors can read all logs.
425
Description
View log content. List logs.
Chapter 17. User and Group Authorization
17.7.48. certServer.ocsp.ca
Controls add operations for adding a CA to an Online Certificate Status Manager.
17.7.48.1. Operations
Operations add
17.7.48.2. Default ACIs allow (add) group="Online Certificate Status Manager Agents"
Only Online Certificate Status Manager agents can add CAs.
17.7.49. certServer.ocsp.cas
Controls list operations for listing the CAs that publish to an Online Certificate Status Manager.
17.7.49.1. Operations
Operations list
17.7.49.2. Default ACIs allow (list) group="Online Certificate Status Manager Agents"
Only Online Certificate Status Manager agents can list CAs.
17.7.50. certServer.ocsp.certificate
Controls validate operation for checking certificate revocation information.
17.7.50.1. Operations
Operations validate
17.7.50.2. Default ACIs
426
Description
Instruct the OCSP responder to respond to OCSP requests for a new CA.
Description
List the CAs for which the OCSP responder maintains revocation status information.
Description
Check if the OCSP responder has data that a certificate is revoked.
certServer.ocsp.configuration
allow (validate) group="Online Certificate Status Manager Agents"
Only Online Certificate Status Manager agents can validate certificate status.
17.7.51. certServer.ocsp.configuration
Controls operations on the OCSP configuration.
17.7.51.1. Operations
Operations read modify
17.7.51.2. Default ACIs allow (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group="Auditors" allow (modify) group="Administrators"
Administrators, agents, and auditors are allowed to read OCSP configuration; only administrators are allowed to modify OCSP configuration.
17.7.52. certServer.ocsp.crl
Controls add operations for posting CRLs to an OCSP.
17.7.52.1. Operations
Operations add
17.7.52.2. Default ACIs allow (add) group="Online Certificate Status Manager Agents"
Only Online Certificate Status Manager agents can add CRLs.
17.7.53. certServer.profile.configuration
Controls operations on the certificate profile configuration.
427
Description
View OCSP plug-in information, OCSP configuration, and
OCSP stores configuration. List OCSP stores configuration.
Modify the OCSP configuration, OCSP stores configuration, and default OCSP store.
Description
Submit a CRL with new revocation status information.
Chapter 17. User and Group Authorization
17.7.53.1. Operations
Operations read modify
17.7.53.2. Default ACIs allow (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group="Auditors" allow (modify) group="Administrators"
Administrators, agents, and auditors are allowed to read certificate profile configuration; only administrators are allowed to modify certificate profile configuration.
17.7.54. certServer.publisher.configuration
Controls read and modify operation for the publishing configuration.
17.7.54.1. Operations
Operations read modify
17.7.54.2. Default ACIs allow (read) group="Administrators"
|| group="Auditors"
428
Description
View certificate profile defaults and constraints, input, output, input configuration, output configuration, default configuration, policy constraints configuration, and certificate profile instance configuration. List certificate profile plug-ins and certificate profile instances.
Add, modify, and delete certificate profile defaults and constraints, input, output, and certificate profile instances. Add and modify policy constraints configuration.
Description
View LDAP server destination information, publisher plug-in configuration, publisher instance configuration, mapper plugin configuration, mapper instance configuration, rules plug-in configuration, and rules instance configuration. List publisher plug-ins and instances, rules plug-ins and instances, and mapper plug-ins and instances.
Add and delete publisher plug-ins, publisher instances, mapper plug-ins, mapper instances, rules plug-ins, and rules instances.
Modify publisher instances, mapper instances, rules instances, and LDAP server destination information.
certServer.registry.configuration
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents" allow (modify) group="Administrators"
Administrators, auditors, and agents are allowed to read publisher configuration; only administrators are allowed to modify publisher configuration.
17.7.55. certServer.registry.configuration
Controls operations on the administration registry, the file that is used to register plug-in modules.
Currently, this is only used to register certificate profile plug-ins.
17.7.55.1. Operations
Operations read modify
17.7.55.2. Default ACIs allow (read) group="Administrators"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents"
|| group="Auditors" allow (modify) group="Administrators"
Administrators, auditors, and agents are allowed to view the administration registry; only administrators are allowed to modify the administration registry.
17.7.56. certServer.usrgrp.administration
Controls operations on the user and group configuration.
17.7.56.1. Operations
Operations read modify
17.7.56.2. Default ACIs
429
Description
View the administration registry.
Modify the administration registry.
Description
View users, groups, and user's certificates. Find users and groups.
Add, modify, and delete groups, and users. Add and modify a user certificate attribute.
Chapter 17. User and Group Authorization allow (read) group="Administrators"
|| group="Auditors"
|| group="Certificate Manager Agents"
|| group="Data Recovery Manager Agents"
|| group="Online Certificate Status Manager Agents" allow (modify) group="Administrators"
Administrators, auditors, and agents are allowed to read user and group configuration; only administrators are allowed to modify user and group configuration.
430
Chapter 18.
Automated Notifications
The Certificate System can be configured to send automatic email notifications to end users when certificates are issued and revoked or to an agent when a new request has arrived in the agent request queue. This chapter describes automated notifications and details how to enable, configure, and customize the notification email messages that are sent.
NOTE
Because of the types of notifications that can be sent, only Certificate Managers have the ability to be configured for notifications; this option is not available on the other subsystems.
18.1. About Automated Notifications
Automated notifications are email messages sent when a specified event occurs. The system uses listeners that monitor the system to determine when a particular event has occurred; when the event happens, then the system is triggered to send an email to the configured recipient. Each type of notification uses a template, either in plain text or HTML, to construct the notification message. The template contains text and tokens that are expanded to fill in the correct information for a particular event. The messages can be customized by changing the text and tokens contained in the templates.
The HTML templates can also be customized for different appearances and formatting.
18.1.1. Types of Automated Notifications
There are three types of automated notifications:
• Certificate Issued .
A notification message is automatically sent to users who have been issued certificates. A rejection message is sent to a user if the user's certificate request is rejected.
• Certificate Revocation .
A notification message is automatically sent to users when the user certificate is revoked.
• Request in Queue .
A notification message is automatically sent to one or more agents when a request enters the agent request queue, using the email addresses set for the agent. There is also a job that sends a notification to agents about the status of the queue, which includes a summary of the certificate status at certain intervals. This notification sends an email every time a message enters the queue. For more information about the request in queue job, see Section 19.1.2.1,
“requestInQueueNotifier” .
18.1.2. Determining End-Entity Email Addresses
The notification system determines the email address of an end entity by checking first the certificate request or revocation request, then the subject name of the certificate, and last the Subject Alternative
Name extension of the certificate, if the certificate contains this extension. If an email address cannot be found, the notification is sent to the email address specified in the Sender's Email Address field of the Notification panel.
431
Chapter 18. Automated Notifications
18.2. Setting Up Automated Notifications
To configure a Certificate Manager to send automated notifications, do the following:
1. Open the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. Open the Configuration tab.
3. Open the Certificate Manager heading in the navigation tree on the left. Then select Notification .
The Notification tabs appear in the right side of the window.
Figure 18.1. Notification Tabs
4. To enable issued certificate notifications, go to the Certificate Issued tab, select the enable checkbox, and specify information in the following fields:
• Enable Certificate Issued notification . Select this checkbox to enable notifications when a certificate is issued or rejected.
• Sender's E-mail Address . Type the sender's full email address of the user who is notified of any delivery problems.
• Subject . Type the subject title for the notification.
• Content template path . Type the path, including the filename, to the directory that contains the template to use to construct the message content.
432
Configuring Specific Notifications by Editing the Configuration File
5. To enable certificate revocation notifications, go to the Certificate Revoked tab, select the enable checkbox, and specify information in the following fields:
• Enable Certificate Revoked notification . Select this checkbox to enable certificate revoked notifications.
• Sender's E-mail Address . Type the sender's full email address of the user who is notified of any delivery problems.
• Subject . Type the subject title for the notification.
• Content template path . Type the path, including the filename, to the directory that contains the template to use to construct the message content.
6. To enable notifications for new requests in the agent queue, go to the Request in Queue tab, select the enable checkbox, and specify information in the following fields:
• Enable Request in Queue notification . Select this checkbox to enable request in queue notifications.
• Sender's E-Mail Address . Type the sender's full email address of the user who is notified of any delivery problems.
• Subject . Type the subject title for the notification.
• Recipient's E-Mail Address . Type the recipient's full email address; these are the email addresses of the agents who will check the queue. To list more than one recipient, separate the email addresses with commas.
• Content Template path . Type the path, including the filename, to the directory that contains the template to use to construct the message content.
7. Click Save .
NOTE
Make sure the mail server is set up correctly. See Section 3.5, “Mail Server” .
8. Customize the notification message templates. See Section 18.3, “Customizing Notification
Messages” for more information.
9. Test the configuration. See Section 18.2.2, “Testing Configuration” .
18.2.1. Configuring Specific Notifications by Editing the
Configuration File
1. Stop the CA subsystem.
/etc/init.d/rhpki-ca stop
2. Open the CS.cfg
file for that instance. This file is in the instance's conf/ directory.
433
Chapter 18. Automated Notifications
3. Edit all of the configuration parameters for the notification type being enabled.
For certificate issuing notifications, there are four parameters: ca.notification.certIssued.emailSubject
ca.notification.certIssued.emailTemplate
ca.notification.certIssued.enabled
ca.notification.certIssued.senderEmail
For certificate revocation notifications, there are four parameters: ca.notification.certRevoked.emailSubject
ca.notification.certRevoked.emailTemplate
ca.notification.certRevoked.enabled
ca.notification.certRevoked.senderEmail
For certificate request notifications, there are five parameters: ca.notification.requestInQ.emailSubject
ca.notification.requestInQ.emailTemplate
ca.notification.requestInQ.enabled
ca.notification.requestInQ.recipientEmail
ca.notification.requestInQ.senderEmail
The parameters for the notification messages are explained in Section 18.2, “Setting Up
Automated Notifications” .
4. Save the file.
5. Restart the CA instance.
/etc/init.d/rhpki-ca start
6. If a job has been created to send automated messages, check that the mail server is correctly configured. See Section 3.5, “Mail Server” .
7. The messages that are sent automatically can be customized; see Section 18.3, “Customizing
Notification Messages” for more information.
18.2.2. Testing Configuration
To test whether the subsystem sends email notifications as configured, do the following:
1. Change the email address in the notification configuration for the request in queue notification to an accessible agent or administrator email address.
2. Open the end-entities page, and request a certificate using the agent-approved enrollment form.
When the request gets queued for agent approval, a request-in-queue email notification should be sent. Check the message to see if it contains the configured information.
3. Log into the agent interface, and approve the request.
434
Customizing Notification Messages
When the server issues a certificate, the user receive a certificate-issued email notification to the address listed in the request. Check the message to see if it has the correct information.
4. Log into the agent interface, and revoke the certificate.
The user email account should contain an email message reading that the certificate has been revoked. Check the message to see if it has the correct information.
18.3. Customizing Notification Messages
The email notifications are constructed using a template for each type of message. Each type of message has an HTML template and a plain text template associated with it. Messages are constructed from text, tokens, and, for the HTML templates, HTML markup. Tokens are variables, identified by a dollar sign ( $ ), in the message that are replaced by the current value when the message is constructed. See Table 18.3, “Notification Tokens” for a list of available tokens.
The contents of any message type can be modified by changing the text and tokens in the message template. The appearance of the HTML messages can be changed by modifying the HTML commands in the HTML message template.
The default text version of the certificate-issuance-notification message is as follows:
Your certificate request has been processed successfully.
SubjectDN= $SubjectDN
IssuerDN= $IssuerDN notAfter= $NotAfter notBefore= $NotBefore
Serial Number= 0x$HexSerialNumber
To get your certificate, please follow this URL: https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&
serialNumber=$SerialNumber
Please contact your admin if there is any problem.
And, of course, this is just a \$SAMPLE\$ email notification form.
This template can be customized as desired, by rearranging, adding, or removing tokens and text, as shown:
THE EXAMPLE COMPANY CERTIFICATE ISSUANCE CENTER
Your certificate has been issued!
You can pick up your new certificate at the following website: https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&
serialNumber=$SerialNumber
This certificate has been issued with the following information:
Serial Number= 0x$HexSerialNumber
Name of Certificate Holder = $SubjectDN
Name of Issuer = $IssuerDN
Certificate Expiration Date = $NotAfter
Certificate Validity Date = $NotBefore
Contact IT by calling X1234, or going to the IT website http://IT
if you have any problems.
18.3.1. Notification Message Templates
Notification message templates are located in the CA_instance_ID/ emails directory.
435
Chapter 18. Automated Notifications
The name and location of these messages can be changed; make the appropriate changes when configuring the notification. All template names can be changed except for the certificate rejected templates; these names must remain the same. The templates associated with certificate issuance and certificate rejection must be located in the same directory and must use the same extension.
Table 18.1, “Notification Templates” lists the default template files provided for creating notification messages. Table 18.2, “Job Notification Email Templates” lists the default template files provided for creating job summary messages.
Filename certIssued_CA certIssued_CA.html
certRequestRejected.html
certRequestRevoked_CA certRequestRevoked_CA.html
reqInQueue_CA reqInQueue_CA.html
Description
Template for plain text notification emails to end entities when certificates are issued.
Template for HTML-based notification emails to end entities when certificates are issued.
Template for HTML-based notification emails to end entities when certificate requests are rejected.
Template for plain text notification emails to end entities when a certificate is revoked.
Template for HTML-based notification emails to end entities when a certificate is revoked.
Template for plain text notification emails to agents when a request enters the queue.
Template for HTML-based notification emails to agents when a request enters the queue.
Table 18.1. Notification Templates
Filename rnJob1.txt
rnJob1Summary.txt
rnJob1Item.txt
riq1Item.html
riq1Summary.html
publishCerts
Description
Template for formulating the message content sent to end entities to inform them that their certificates are about to expire and that the certificates should be replaced before they expire.
Template for constructing the summary report to be sent to agents and administrators. Uses the rnJob1Item.txt
template to format items in the message.
Template for formatting the items included in the summary report.
Template for formatting the items included in the summary table, which is constructed using the riq1Summary.html
template.
Template for formulating the report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager.
Template for the report or table that summarizes the certificates to be published to the directory.
436
Token Definitions
Filename publishCertsItem.html
ExpiredUnpublishJob
Description
Uses the publishCertsItem.html
template to format the items in the table.
Template for formatting the items included in the summary table.
Template for the report or table that summarizes removal of expired certificates from the directory.
Uses the ExpiredUnpublishJobItem template to format the items in the table.
Template for formatting the items included in the summary table.
ExpiredUnpublishJobItem
Table 18.2. Job Notification Email Templates
18.3.2. Token Definitions
Table 18.3, “Notification Tokens” lists and defines the tokens that can be used in the notification message templates.
Token
$CertType
$ExecutionTime
$HexSerialNumber
$HttpHost
$HttpPort
$InstanceID
$IssuerDN
$NotAfter
$NotBefore
$RecipientEmail
$RequestId
$RequestorEmail
$RequestType
Description
Specifies the type of certificate; these can be any of the following:
• SSL client ( client )
• SSL server ( server )
• CA signing certificate ( ca )
• other ( other ).
Gives the time the job was run.
Gives the serial number of the certificate that was issued in hexadecimal format.
Gives the fully qualified host name of the
Certificate Manager to which end entities should connect to retrieve their certificates.
Gives the Certificate Manager's end-entities
(non-SSL) port number.
Gives the ID of the subsystem that sent the notification.
Gives the DN of the CA that issued the certificate.
Gives the end date of the validity period.
Gives the beginning date of the validity period.
Gives the email address of the recipient.
Gives the request ID.
Gives the email address of the requester.
Gives the type of request that was made.
437
Chapter 18. Automated Notifications
Token
$RevocationDate
$SenderEmail
$SerialNumber
$Status
$SubjectDN
$SummaryItemList
$SummaryTotalFailure
$SummaryTotalNum
$SummaryTotalSuccess
Table 18.3. Notification Tokens
Description
Gives the date the certificate was revoked.
Gives the email address of the sender; this is the same as the one specifified in the
Sender's E-mail Address field in the notification configuration.
Gives the serial number of the certificate that has been issued; the serial number is displayed as a hexadecimal value in the resulting message.
Gives the request status.
Gives the DN of the certificate subject.
Lists the items in the summary notification. Each item corresponds to a certificate the job detects for removal from the publishing directory.
Gives the total number of items in the summary report that failed.
Gives the total number of certificate requests that are pending in the queue or the total number of certificates to be removed from the directory in the summary report.
Shows how many of the total number of items in the summary report succeeded.
438
Chapter 19.
Automated Jobs
The Certificate System provides a customizable Job Scheduler that supports various mechanisms for scheduling cron jobs. This chapter explains how to configure Certificate System to use specific job plug-in modules for accomplishing jobs.
19.1. About Automated Jobs
The Certificate Manager Console includes a Job Scheduler option that can execute specific jobs at specified times. The Job Scheduler is similar to a traditional Unix cron daemon; it takes registered cron jobs and executes them at a preconfigured date and time. If configured, the scheduler checks at specified intervals for jobs waiting to be executed; if the specified execution time has arrived, the scheduler initiates the job automatically.
Jobs are implemented as Java ™ classes, which are then registered with Certificate System as plugin modules. One implementation of a job module can be used to configure multiple instances of the job. Each instance must have a unique name (an alphanumeric string with no spaces) and can contain different input parameter values to apply to different jobs.
19.1.1. Setting up Automated Jobs
The automated jobs feature is set up by doing the following:
• Enabling and configuring the Job Scheduler; see Section 19.2, “Setting up the Job Scheduler” for more information.
• Enabling and configuring the job modules and setting preferences for those job modules; see
Section 19.3, “Setting up Specific Jobs” for more information.
• Customizing the email notification messages sent with these jobs by changing the templates associated with the types of notification. The message contents are composed of both plain text messages and HTML messages; the appearance is modified by changing the HTML templates. See
Section 18.3.1, “Notification Message Templates” for more information.
19.1.2. Types of Automated Jobs
The types of automated jobs are requestInQueueNotifier , publishCerts , and unpublishExpiredCerts .
19.1.2.1. requestInQueueNotifier
The requestInQueueNotifier module checks the status of the request queue at preconfigured time intervals. If any deferred enrollment requests are waiting in the queue, the job constructs an email message summarizing its findings and sends it to the specified agents.
19.1.2.2. publishCerts
The publishCerts module checks for any new certificates that have been added to the publishing directory. When these new certificates are added, they are automatically published to an LDAP directory or file.
439
Chapter 19. Automated Jobs
19.1.2.3. unpublishExpiredCerts
Expired certificates are not automatically removed from the publishing directory. If a Certificate
Manager is configured to publish certificates to an LDAP directory, over time the directory will contain expired certificates.
The unpublishExpiredCerts job checks for certificates that have expired and are still marked as published in the internal database at the configured time interval. The job connects to the publishing directory and deletes those certificates; it then marks those certificates as unpublished in the internal database. The job collects a summary of expired certificates that it deleted and mails the summary to the agents or administrators specified by the configuration.
NOTE
This job automates removing expired certificates from the directory. Expired certificates can also be removed manually; for more information on this, see Section 15.11, “Updating
Certificates and CRLs in a Directory” .
19.2. Setting up the Job Scheduler
The Certificate Manager can execute a job only if the Job Scheduler is enabled. The job settings, such as enabling the job schedule, setting the frequency, and enabling the job modules, can be done through the Certificate System CA Console or through editing the CS.cfg
file.
19.2.1. Enabling and Configuring the Job Scheduler
To turn the Job Scheduler on, do the following:
1. Open the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab navigation tree, click Job Scheduler .
This opens the General Settings tab, which shows whether the Job Scheduler is currently enabled.
440
Setting up Specific Jobs
Figure 19.1. General Settings Tab
3. Click the Enable Jobs Schedule checkbox to enable or disable the Job Scheduler.
Disabling the Job Scheduler turns off all the jobs.
4. Set the frequency which the scheduler checks for jobs in the Check Frequency field.
The frequency is how often the Job Scheduler daemon thread wakes up and calls the configured jobs that meet the cron specification. By default, it is set to one minute.
NOTE
The window for entering this information may be too small to see the input. Drag the corners of the Certificate Manager Console to enlarge the entire window.
5. Click Save .
19.3. Setting up Specific Jobs
Automated jobs can be configured through the Certificate Manager Console or by editing the configuration file directory. It is recommended that these changes be made through the Certificate
Manager Console.
441
Chapter 19. Automated Jobs
19.3.1. Configuring Specific Jobs Using the Certificate Manager
Console
To enable and configure an automated job using the Certificate Manager Console, do the following:
1. Open the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. Confirm that the Jobs Scheduler is enabled. See Section 19.2, “Setting up the Job Scheduler” for more information.
3. In the Configuration tab, select Job Scheduler from the navigation tree. Then select Jobs .
4. This opens the Job Instance tab.
442
Figure 19.2. Job Instance Tab
Select the job instance from the list, and click Edit/View .
The Job Instance Editor opens, showing the current job configuration.
Configuring Specific Jobs Using the Certificate Manager Console
Figure 19.3. Job Configuration
5. Select Enable to turn on the job.
6. Set the configuration settings by specifying them in the fields for this dialog.
• For requestInQueueNotifier , see Section 19.3.3, “Configuration Parameters of requestInQueueNotifier” .
• For publishCerts , see Section 19.3.4, “Configuration Parameters of publishCerts” .
• For unpublishExpiredCerts , see Section 19.3.5, “Configuration Parameters of unpublishExpiredCerts” .
• For more information about setting the cron time frequencies, see Section 19.3.6, “Frequency
Settings for Automated Jobs” .
443
Chapter 19. Automated Jobs
7. Click OK .
8. Click Refresh to view any changes in the main window.
9. If the job is configured to send automatic messages, check that a mail server is set up correctly.
See Section 3.5, “Mail Server” .
10. Customize the email message text and appearance.
19.3.2. Configuring Jobs by Editing the Configuration File
1. Ensure that the Jobs Scheduler is enabled and configured; see Section 19.2, “Setting up the Job
Scheduler” .
2. Stop the CA subsystem instance.
/etc/init.d/rhpki-ca stop
3. Open the CS.cfg
file for that server instance in a text editor.
4. Edit all of the configuration parameters for the job module being configured.
• To configure the requestInQueueNotifier job, edit all parameters that begin with jobsScheduler.job.requestInQueueNotifier
; see Section 19.3.3, “Configuration
Parameters of requestInQueueNotifier” .
• To configure the publishCerts job, edit all parameters that begin with jobsScheduler.job.publishCerts
; see Section 19.3.4, “Configuration Parameters of publishCerts” .
• To configure the unpublishExpiredCerts job, edit all parameters that begin with jobsScheduler.job.unpublishExpiredCerts
; see Section 19.3.5, “Configuration
Parameters of unpublishExpiredCerts” .
5. Save the file.
6. Restart the server instance.
/etc/init.d/rhpki-ca start
7. If the job will send automated messages, check that the mail server is set up correctly. See
Section 3.5, “Mail Server” .
8. Customize the automatic job messages.
19.3.3. Configuration Parameters of requestInQueueNotifier
Table 19.1, “requestInQueueNotifier Parameters” gives details for each of these parameters that can be configured for the requestInQueueNotifier job, either in the CS.cfg
file or in the Certificate
Manager Console.
444
Configuration Parameters of publishCerts
Parameter enabled cron
Description
Sets whether the job is enabled ( true ) or disabled ( false ).
Sets the time schedule for when the job should run. This is the time at which the Job
Scheduler daemon thread checks the queue for pending requests. This setting must follow the conventions in Section 19.3.6, “Frequency
Settings for Automated Jobs” . For example: subsystemid summary.enabled
summary.emailSubject
summary.emailTemplate
summary.senderEmail
summary.recipientEmail
00**0
Specifies the subsystem which is running the job.
The only possible value is ca , for the Certificate
Manager.
Specifies whether a summary of the job accomplished should be compiled and sent. The value true enables the summary reports; false disables them. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
Sets the subject line of the summary message.
Specifies the path, including the filename, to the directory containing the template to use to create the summary report.
Specifies the sender of the notification message, who will be notified of any delivery problems.
Specifies the recipients of the summary message. These can be agents who need to process pending requests or other users. More than one recipient can be listed by separating each email address with a comma.
Table 19.1. requestInQueueNotifier Parameters
19.3.4. Configuration Parameters of publishCerts
Table 19.2, “publishCerts Parameters” gives details for each of these parameters that can be configured for the publishCerts job, either in the CS.cfg
file or in the Certificate Manager Console.
Parameter enabled cron
Description
Sets whether the job is enabled. The value true is enabled; false is disabled.
Sets the time schedule for when the job runs.
This is the time the Job Scheduler daemon thread checks the certificates to removing expired certificates from the publishing directory.
This setting must follow the conventions
445
Chapter 19. Automated Jobs
Parameter Description in Section 19.3.6, “Frequency Settings for
Automated Jobs” . For example: summary.enabled
summary.emailSubject
summary.emailTemplate
summary.itemTemplate
summary.senderEmail
summary.recipientEmail
00**6
Specifies whether a summary of the certificates removed by the job should be compiled and sent.
The value true enables the summaries; false disables them. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
Gives the subject line of the summary message.
Specifies the path, including the filename, to the directory containing the template to use to create the summary report.
Specifies the path, including the filename, to the directory containing the template to use to create the content and format of each item collected for the summary report.
Specifies the sender of the summary message, who will be notified of any delivery problems.
Specifies the recipients of the summary message. These can be agents who need to know the status of user certificates or other users. More than one recipient can be set by separating each email address with a comma.
Table 19.2. publishCerts Parameters
19.3.5. Configuration Parameters of unpublishExpiredCerts
Table 19.3, “unpublishExpiredCerts Parameters” gives details for each of these parameters that can be configured for the unpublishedExpiresCerts job, either in the CS.cfg
file or in the Certificate
Manager Console.
Parameter enabled cron
Description
Sets whether the job is enabled. The value true is enabled; false is disabled.
Sets the time schedule for when the job runs.
This is the time the Job Scheduler daemon thread checks the certificates to removing expired certificates from the publishing directory.
This setting must follow the conventions in Section 19.3.6, “Frequency Settings for
Automated Jobs” . For example:
00**6
446
Frequency Settings for Automated Jobs
Parameter summary.enabled
summary.emailSubject
summary.emailTemplate
summary.itemTemplate
summary.senderEmail
summary.recipientEmail
Description
Specifies whether a summary of the certificates removed by the job should be compiled and sent.
The value true enables the summaries; false disables them. If enabled, set the remaining summary parameters; these are required by the server to send the summary report.
Gives the subject line of the summary message.
Specifies the path, including the filename, to the directory containing the template to use to create the summary report.
Specifies the path, including the filename, to the directory containing the template to use to create the content and format of each item collected for the summary report.
Specifies the sender of the summary message, who will be notified of any delivery problems.
Specifies the recipients of the summary message. These can be agents who need to know the status of user certificates or other users. More than one recipient can be set by separating each email address with a comma.
Table 19.3. unpublishExpiredCerts Parameters
19.3.6. Frequency Settings for Automated Jobs
The Job Scheduler uses a variation of the Unix crontab entry format to specify dates and times for checking the job queue and executing jobs. As shown in Table 19.4, “Time Values for Scheduling
Jobs” and Figure 19.3, “Job Configuration” , the time entry format consists of five fields. (The sixth field specified for the Unix crontab is not used by the Job Scheduler.) Values are separated by spaces or tabs.
Each field can contain either a single integer or a pair of integers separated by a hyphen ( ) to indicate an inclusive range. To specify all legal values, a field can contain an asterisk rather than an integer.
Day fields can contain a comma-separated list of values. The syntax of this expression is
(Minute) (Hour) (Day of month) (Month of year) (Day of week)
Field
Minute
Hour
Day of month
Month of year
Day of week
Table 19.4. Time Values for Scheduling Jobs
Value
0-59
0-23
1-31
1-12
0-6 (where 0=Sunday)
For example, the following time entry specifies every hour at 15 minutes (1:15, 2:15, 3:15, and so on):
447
Chapter 19. Automated Jobs
15 * * * *
The following example sets a job to run at noon on April 12:
0 12 12 4 *
The day-of-month and day-of-week options can contain a comma-separated list of values to specify more than one day. If both day fields are specified, the specification is inclusive; that is, the day of the month is not required to fall on the day of the week to be valid. For example, the following entry specifies a job execution time of midnight on the first and fifteenth of every month and on every
Monday:
0 0 1,15 * 1
To specify one day type without the other, use an asterisk in the other day field. For example, the following entry runs the job at 3:15 a.m. every weekday morning:
15 3 * * 1-5
19.4. Managing Job Plug-ins
This section explains how to register new job plug-ins and delete existing plug-ins.
19.4.1. Registering or Deleting a Job Module
Custom job plug-ins can be registered through the Certificate Manager Console. Registering a new module involves specifying the name of the module and the full name of the Java ™ class that implements the module.
It is also possible to delete job modules, but this is not recommended.
To register or delete a job module in the Certificate System framework, do the following:
1. Log into the Certificate Manager Console.
pkiconsole https://server.example.com:9443/ca
2. In the Configuration tab, select Job Scheduler in the left navigation tree. Select Jobs .
The Job Instance tab opens, which lists any currently configured jobs. Select the Job Plugin
Registration tab.
3. To delete a module, select the module to delete, and click Delete .
When prompted, confirm the delete action.
4. To register a module, click Register .
The Register Job Scheduler Plugin Implementation window appears.
448
Registering or Deleting a Job Module
Supply the following information:
• Plugin name.
Type a name for the plug-in module.
• Class name.
Type the full name of the class for this module; this is the path to the implementing
Java
™
class. If this class is part of a package, include the package name. For example, to register a class named customJob that is in a package named com.customplugins
, type com.customplugins.customJob
.
5. Click OK .
449
450
Chapter 20.
Configuring the Certificate System for
High Availability
This chapter explains how to create and configure the Red Hat Certificate System for high availability.
Certificate System subsystems can be cloned, or duplicated, and run on different machines. This provides failover support by ensuring that Certificate System services continue even if the master instance was goes offline.
20.1. High Availability Overview
High availability systems reduce unplanned outages and other problems by making one or more subsystem clones available. When a host machine goes down, high availability systems can handle requests and perform services from an alternate system seamlessly and uninterrupted.
High availability configurations also allow systems to be taken offline for repair, troubleshooting, or other administrative tasks without interrupting the services of the system.
Typically, master and cloned instances are installed on different machines, and those machines are placed behind a load balancer . The load balancer accepts HTTP and HTTPS requests made to the
Certificate System system and directs those requests appropriately between the two machines. In the event that one machine fails, the load balancer will transparently redirect all requests to the machine that is still running until the other machine is brought back online. Cloning is scalable by assigning the same task, such as handling certificate requests, to separate instances on different machines.
The following subsystems can be cloned and run on different hosts:
• Certificate Manager (CA)
• Data Recovery Manager (DRM)
• Online Certificate Status Manager (OCSP)
• Token Key Service (TKS)
NOTE
The Token Processing System (TPS) does not support cloning.
20.1.1. Architecture of a Failover System
The diagram in Figure 20.1, “Certificate System Example” shows one way to set up a cloned
Certificate System subsystem. In this example, a separate OCSP subsystem is handling certificate verification by taking advantage of CRL publishing.
451
Chapter 20. Configuring the Certificate System for High Availability
Figure 20.1. Certificate System Example
As this diagram indicates, only one of the CAs can generate the CRLs. See Section 20.4, “Clone-
Master Conversion” for more information about configuring a clone for CRL generation during cloning.
20.1.2. Load Balancing
The load balancer in front of a Certificate System system is what provides the actual failover support in a high availability system. A load balancer can also provide the following advantages as part of a
Certificate System system:
• DNS round-robin, a feature for managing network congestion that distributes load across several different servers.
• Sticky SSL, which makes it possible for a user returning to the system to be routed the same host used previously.
Consult the documentation for the load balancer for more information about the features, advantages, and configuration of a load balancer.
20.2. Cloning Preparation
Cloning a subsystem creates two server processes performing the same functions: another, new instance of the subsystem is created and configured to use the same keys and certificates to perform
452
Diagnostics its operations. Before installing and configuring the clone, the master subsystem must be installed, fully configured, and running.
A cloned subsystem is configured through standard configuration wizard. Before going through the setup process, some manual preparation is required. To prepare for cloning, do the following:
• If the keys and certificates are stored in the Internal Key Storage Token (software token).
When configuring the master instance, select yes in the Export Keys and Certificates panel to back up the keys and certificates, and enter the password to protect the PKCS #12 file. Then restart the master instance when configuration is complete.
If the keys and certificates were not backed up when the master instance was configured, they can be backed up using the pk12util tool.
When configuring the clone instance, enter the location and the password for the PKCS #12 file in the Restore Keys and Certificates screen. Then restart the clone instance when configuration is complete.
• If the keys and certificates are stored on a hardware token.
• Duplicate all the required keys and certificates, except the SSL server key and certificate to the clone instance. Keep the nicknames for those certificates the same. Additionally, copy all the necessary trusted root from the master instance to the clone instance.
• If the token is network-based, then the keys and certificates simply need to be available to the token; the keys and certificates do not need to be copied.
• When using a network-based hardware token, make sure the high-availability feature is enabled on the hardware token to avoid single point of failure.
20.2.1. Diagnostics
Use the certutil tool to list all the certificates in the clone instance to make sure that all the required certificates are in place.
20.3. Testing the Cloned Configuration
To test the CA clone, do the following:
1. Request a certificate from the cloned CA.
2. Approve the request.
3. Download the certificate to the browser.
4. Revoke the certificate.
5. Check master CA's CRL for the revoked certificate. In the master Certificate Manager's agent services page, click Update Certificate Revocation List . Find the CRL in the list.
The CRL should show the certificate revoked by the cloned Certificate Manager. If that certificate is not listed, check logs to resolve the problem.
To test the OCSP clone, do the following:
453
Chapter 20. Configuring the Certificate System for High Availability
1. Set up OCSP publishing in the master CA so that the CRL is published to the master OCSP.
2. Once the CRL is successfully published, check both the master and cloned OCSP's List
Certificate Authorities link in the agent pages. The list should be identical.
3. Use the OCSPClient tool to submit OCSP requests to the master and the cloned Online
Certificate Status Manager. The tool should receive identical OCSP responses from both managers.
To test the DRM clone, do the following:
1. Go to the DRM agent's page.
2. Click List Requests .
3. Select Show all requests for the request type and status.
4. Click Submit .
5. Compare the results from the cloned DRM and the master DRM.
The results ought to be identical.
20.4. Clone-Master Conversion
At times, an existing cloned subsystem may need converted into a new master subsystem, such as after catastrophic failure of the existing master. First convert the existing offline master subsystem into a clone, then convert one of the current existing online cloned subsystems into the new online master subsystem. The differences between the master and the clone of the different subsystems is illustrated in Table 20.1, “Differences Between Masters and Clones”
Subsystem
Certificate Manager
Differences
• Master CAs control the database maintenance thread (this is disabled in cloned CAs)
• Master CAs monitor database replication changes
• Master CAs maintain the CRL cache
• Master CAs generate the CRL
• Cloned CAs redirect CRL generation requests
Note
Clones should never be configured to generate CRLs. Clones can revoke, display, import, and download CRLs previously generated by master CAs, but having them generate new CRLs may cause synchronization problems. The rule is that only a
454
Converting a Master CA into a Cloned CA
Subsystem Differences single CA should generate CRLs, and this task is always left to the master CA.
OCSP
DRM
Clones have a unique configuration parameter,
OCSP.Responder.store.defStore.refreshInSec
.
There are no configurable differences between a master and a clone.
TKS There are no configurable differences between a master and a clone.
Table 20.1. Differences Between Masters and Clones
20.4.1. Converting a Master CA into a Cloned CA
Since only one master CA can exist for a Certificate System installation, the offline master must first be converted into a cloned CA, and one of the cloned CAs become the new master CA.
1. Stop the master CA if it is still running.
2. Open the existing master CA configuration directory: cd /var/lib/ master_ID /conf
3. Edit the CS.cfg
file, and change the following:
• Disable control of the database maintenance thread by changing the value of the following line to 0 ; add the line if it does not already exist: ca.certStatusUpdateInterval=0
• Disable monitoring database replication changes by changing the value of the following line to false ; add the line if it does not already exist: ca.listenToCloneModifications=false
• Disable maintenance of the CRL cache by changing all of the enableCRLCache lines from true to false ; add each line if it does not already exist: ca.crl.
IssuingPointId .enableCRLCache=false
• Disable CRL generation by changing all of the enableCRLUpdates lines from true to false ; add each line if it does not already exist: ca.crl.
IssuingPointId .enableCRLUpdates=false
455
Chapter 20. Configuring the Certificate System for High Availability
• Enable CRL generation requests redirection by adding the following two lines: master.ca.agent.host= hostname master.ca.agent.port= port number
20.4.2. Converting a Cloned CA into a Master CA
After converting the existing offline master CA into an offline cloned CA, one of the online cloned CAs must be converted into the new online master CA.
1. Stop the online cloned CA server.
/etc/init.d/ instance_ID stop
2. Open the cloned CA's configuration directory.
cd /var/lib/ clone_ID /conf
3. Edit the CS.cfg
file.
a. Delete each line which begins with the ca.crl.
prefix: b. Copy each line beginning with the ca.crl.
prefix from the former master CA CS.cfg
file into the cloned CA's CS.cfg
file.
c. Enable control of the database maintenance thread by changing the value of the following line to 600 ; 600 is the default value for the master Certificate System. This value can be changed to any other non-zero number: ca.certStatusUpdateInterval=600 d. Enable monitoring database replication changes by changing the value of this line to true : ca.listenToCloneModifications=true e. Enable maintenance of the CRL cache by changing all of the enableCRLCache lines to true : ca.crl.
IssuingPointId .enableCRLCache=true f.
Enable CRL generation by changing all of the enableCRLUpdates lines to true : ca.crl.
IssuingPointId .enableCRLUpdates=true
456
Converting a Master OCSP into a Cloned OCSP g. Disable CRL generation requests redirection by removing the following two lines: master.ca.agent.host= hostname master.ca.agent.port= port number
4. Start the new master CA server.
/etc/init.d/ instance_ID start
20.4.3. Converting a Master OCSP into a Cloned OCSP
Since only one master OCSP Responder can exist for a Certificate System installation, the offline master must first be converted into a cloned OCSP Responder before one of the cloned OCSPs becomes the new master OCSP.
1. Stop the OCSP master, if it is still running.
2. Open the existing master OCSP configuration directory.
cd /var/lib/ master_ID /conf
3. Edit the CS.cfg
, and add the following line; 21600 is the default value for a cloned OCSP. This value can be changed to any other non-zero number.
OCSP.Responder.store.defStore.refreshInSec=21600
20.4.4. Converting a Cloned OCSP into a Master OCSP
After converting the existing offline master OCSP responder into an offline cloned OCSP, one of the online cloned OCSP responders must be converted into the new online master OCSP responder.
1. Stop the online cloned OCSP server.
/etc/init.d/ instance_ID stop
2. Open the cloned OCSP responder's configuration directory.
cd /var/lib/ instance_ID /conf
3. Open the CS.cfg
file, and delete the following line. 21600 is the default value for a cloned OCSP
Responder. This value can be equal to any other non-zero number.
OCSP.Responder.store.defStore.refreshInSec=21600
457
Chapter 20. Configuring the Certificate System for High Availability
4. Start the new master OCSP responder server.
/etc/init.d/ instance_ID start
458
Appendix A. Certificate and CRL
Extensions
This appendix explains both the standard certificate extensions defined by X.509 v3 and the extensions defined by Netscape that were used in versions of products released before X.509 v3 was finalized. It provides recommendations for extensions to use with specific kinds of certificates, including PKIX Part 1 recommendations.
This appendix contains the following sections:
• Section A.1, “Introduction to Certificate Extensions”
• Section A.2, “Note on Object Identifiers”
• Section A.3, “Standard X.509 v3 Certificate Extensions”
• Section A.4, “Introduction to CRL Extensions”
• Section A.5, “Standard X.509 v3 CRL Extensions”
A.1. Introduction to Certificate Extensions
An X.509 v3 certificate contains an extension field that permits any number of additional fields to be added to the certificate. Certificate extensions provide a way of adding information such as alternative subject names and usage restrictions to certificates. Older Netscape servers, such as Red Hat
Directory Server and Red Hat Certificate System, that were developed before PKIX part 1 standards were defined require Netscape-specific extensions.
The X.509 v1 certificate specification was originally designed to bind public keys to names in an X.500
directory. As certificates began to be used on the Internet and extranets and directory lookups could not always be performed, problem areas emerged that were not covered by the original specification.
• Trust . The X.500 specification establishes trust by means of a strict directory hierarchy. By contrast,
Internet and extranet deployments frequently involve distributed trust models that do not conform to the hierarchical X.500 approach.
• Certificate use . Some organizations restrict how certificates are used. For example, some certificates may be restricted to client authentication only.
• Multiple certificates . It is not uncommon for certificate users to possess multiple certificates with identical subject names but different key material. In this case, it is necessary to identify which key and certificate should be used for what purpose.
• Alternate names . For some purposes, it is useful to have alternative subject names that are also bound to the public key in the certificate.
• Additional attributes . Some organizations store additional information in certificates, such as when it is not possible to look up information in a directory.
• Relationship with CA . When certificate chaining involves intermediate CAs, it is useful to have information about the relationships among CAs embedded in their certificates.
459
Appendix A. Certificate and CRL Extensions
• CRL checking . Since it is not always possible to check a certificate's revocation status against a directory or with the original certificate authority, it is useful for certificates to include information about where to check CRLs.
The X.509 v3 specification addressed these issues by altering the certificate format to include additional information within a certificate by defining a general format for certificate extensions and specifying extensions that can be included in the certificate. The extensions defined for X.509 v3 certificates enable additional attributes to be associated with users or public keys and manage the certification hierarchy. The Internet X.509 Public Key Infrastructure Certificate and CRL Profile recommends a set of extensions to use for Internet certificates and standard locations for certificate or
CA information. These extensions are called standard extensions .
NOTE
For more information on standard extensions, see http://www.ietf.org/rfc/rfc2459.txt
, http://www.ietf.org/rfc/rfc3280.txt
, and http://www.ietf.org/rfc/rfc3279.txt
for the RFCs that describe extensions.
The X.509 v3 standard for certificates allows organizations to define custom extensions and include them in certificates. These extensions are called private , proprietary , or custom extensions, and they carry information unique to an organization or business. Applications may not able to validate certificates that contain private critical extensions, so it not recommended that these be used in widespread situations.
Before the X.509 v3 standard was finalized, Netscape and other companies had to address some of the most pressing issues with their own extension definitions. For example, applications such as
Netscape Navigator and Enterprise Server supported an extension known as the Netscape Certificate
Type Extension that specifies the type of certificate issued, such as client, server, or email. To maintain compatibility with older versions of browsers that were released before the X.509 v3 specification was finalized, certain kinds of certificates should include some of these Netscape extensions.
The X.500 and X.509 specifications are controlled by the International Telecommunication Union
(ITU), an international organization that primarily serves large telecommunication companies, government organizations, and other entities concerned with the international telecommunications network. The Internet Engineering Task Force (IETF), which controls many of the standards that underlie the Internet, is currently developing public-key infrastructure X.509 (PKIX) standards. These proposed standards further refine the X.509 v3 approach to extensions for use on the Internet. The recommendations for certificates and CRLs have reached proposed standard status and are in a document referred to as PKIX Part 1 .
Two other standards, Abstract Syntax Notation One (ASN.1) and Distinguished Encoding Rules
(DER), are used with Certificate System and certificates in general. These are specified in the CCITT
Recommendations X.208 and X.209. For a quick summary of ASN.1 and DER, see A Layman's
Guide to a Subset of ASN.1, BER, and DER , which is available at RSA Laboratories' web site, http:// www.rsa.com
.
A.1.1. Structure of Certificate Extensions
In RFC 3280, an X.509 certificate extension is defined as follows:
Extension ::= SEQUENCE { extnID OBJECT IDENTIFIER,
460
Sample Certificate Extensions critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING }
The means a certificate extension consists of the following:
• The object identifier (OID) for the extension. This identifier uniquely identifies the extension. It also determines the ASN.1 type of value in the value field and how the value is interpreted. When an extension appears in a certificate, the OID appears as the extension ID field ( extnID ) and the corresponding ASN.1 encoded structure appears as the value of the octet string ( extnValue ); examples of this are in Section A.1.2, “Sample Certificate Extensions” .
• A flag or boolean field called critical .
The value, which can be either true or false , assigned to this field indicates whether the extension is critical or noncritical to the certificate.
• If the extension is critical and the certificate is sent to an application that does not understand the extension based on the extension's ID, the application must reject the certificate.
• If the extension is not critical and the certificate is sent to an application that does not understand the extension based on the extension's ID, the application can ignore the extension and accept the certificate.
• An octet string containing the DER encoding of the value of the extension.
Typically, the application receiving the certificate checks the extension ID to determine if it can recognize the ID. If it can, it uses the extension ID to determine the type of value used.
Some of the standard extensions defined in the X.509 v3 standard include the following:
• Authority Key Identifier extension, which identifies the CA's public key, the key used to sign the certificate.
• Subject Key Identifier extension, which identifies the subject's public key, the key being certified.
NOTE
Not all applications support certificates with version 3 extensions. Applications that do support these extensions may not be able to interpret some or all of these specific extensions.
A.1.2. Sample Certificate Extensions
The following is an example of the section of a certificate containing X.509 v3 extensions. The
Certificate System can display certificates in readable pretty-print format, as shown here. As in this example, certificate extensions appear in sequence and only one instance of a particular extension may appear per certificate; for example, a certificate may contain only one subject key identifier extension. Certificates that support these extensions have the version 0x2 (which corresponds to version 3).
Data:
Version: v3
Serial Number: 0x1
461
Appendix A. Certificate and CRL Extensions
Signature Algorithm: SHA1withRSA - 1.2.840.113549.1.1.5
Issuer: CN=Certificate Manager,OU=netscape,O=aol,L=MV,ST=CA,C=US
Validity:
Not Before: Friday, February 21, 2005 12:00:00 AM PST America/Los_Angeles
Not After: Monday, February 21, 2007 12:00:00 AM PST America/Los_Angeles
Subject: CN=Certificate Manager,OU=netscape,O=aol,L=MV,ST=CA,C=US
Subject Public Key Info:
Algorithm: RSA - 1.2.840.113549.1.1.1
Public Key:
Exponent: 65537
Public Key Modulus: (1024 bits) :
E4:71:2A:CE:E4:24:DC:C4:AB:DF:A3:2E:80:42:0B:D9:
CF:90:BE:88:4A:5C:C5:B3:73:BF:49:4D:77:31:8A:88:
15:A7:56:5F:E4:93:68:83:00:BB:4F:C0:47:03:67:F1:
30:79:43:08:1C:28:A8:97:70:40:CA:64:FA:9E:42:DF:
35:3D:0E:75:C6:B9:F2:47:0B:D5:CE:24:DD:0A:F7:84:
4E:FA:16:29:3B:91:D3:EE:24:E9:AF:F6:A1:49:E1:96:
70:DE:6F:B2:BE:3A:07:1A:0B:FD:FE:2F:75:FD:F9:FC:
63:69:36:B6:5B:09:C6:84:92:17:9C:3E:64:C3:C4:C9
Extensions:
Identifier: Netscape Certificate Type - 2.16.840.1.113730.1.1
Critical: no
Certificate Usage:
SSL CA
Secure Email CA
ObjectSigning CA
Identifier: Basic Constraints - 2.5.29.19
Critical: yes
Is CA: yes
Path Length Constraint: UNLIMITED
Identifier: Subject Key Identifier - 2.5.29.14
Critical: no
Key Identifier:
3B:46:83:85:27:BC:F5:9D:8E:63:E3:BE:79:EF:AF:79:
9C:37:85:84
Identifier: Authority Key Identifier - 2.5.29.35
Critical: no
Key Identifier:
3B:46:83:85:27:BC:F5:9D:8E:63:E3:BE:79:EF:AF:79:
9C:37:85:84
Identifier: Key Usage: - 2.5.29.15
Critical: yes
Key Usage:
Digital Signature
Key CertSign
Crl Sign
Signature:
Algorithm: SHA1withRSA - 1.2.840.113549.1.1.5
Signature:
AA:96:65:3D:10:FA:C7:0B:74:38:2D:93:54:32:C0:5B:
2F:18:93:E9:7C:32:E6:A4:4F:4E:38:93:61:83:3A:6A:
A2:11:91:C2:D2:A3:48:07:6C:07:54:A8:B8:42:0E:B4:
E4:AE:42:B4:B5:36:24:46:4F:83:61:64:13:69:03:DF:
41:88:0B:CB:39:57:8C:6B:9F:52:7E:26:F9:24:5E:E7:
BC:FB:FD:93:13:AF:24:3A:8F:DB:E3:DC:C9:F9:1F:67:
A8:BD:0B:95:84:9D:EB:FC:02:95:A0:49:2C:05:D4:B0:
35:EA:A6:80:30:20:FF:B1:85:C8:4B:74:D9:DC:BB:50
A.2. Note on Object Identifiers
An object identifier (OID) is a string of numbers identifying a unique object, such as a certificate extension or a company's certificate practice statement. The Certificate System comes with a set of
462
Standard X.509 v3 Certificate Extensions extension-specific profile plug-in modules which enable X.509 certificate extensions to be added to the certificates the server issues. Some of the extensions contain fields for specifying OIDs.
The PKIX standard recommends that all objects, such as extensions and profile statements, that are used in certificates be included in the form of an OID. This promotes interoperability between organizations on a shared network. If certificates will be issued that will be used on shared networks, register the OID prefixes with the appropriate registration authority.
OIDs are controlled by the International Standards Organization (ISO) registration authority. In some cases, this authority is delegated by ISO to regional registration authorities. In the United States, the
American National Standards Institute (ANSI) manages this registration.
Using an OID registered to another organization or failing to register an OID may carry legal consequences, depending the situation. Registration may be subject to fees. For more information, contact the appropriate registration authority.
To define or assign OIDs for custom objects, know the company's arc , an OID for a private enterprise.
If the company does not have an arc, it needs to get one. The following site has more information on registering and using OIDs: http://www.alvestrand.no/objectid/
For example, this site contains information on the Netscape-defined OID for an extension named
Netscape Certificate Comment . The OID assigned to this extension is hierarchical and includes the former Netscape company arc, 2.16.840.1
.
http://www.alvestrand.no/objectid/2.16.840.1.113730.1.13.html
If an OID extension exists in a certificate and is marked critical, the application validating the certificate must be able to interpret the extension, including any optional qualifiers, or it must reject the certificate.
Since it is unlikely that all applications will be able to interpret a company's custom extensions embedded in the form of OIDs, the PKIX standard recommends that the extension be always marked noncritical.
A.3. Standard X.509 v3 Certificate Extensions
This section summarizes the extension types defined as part of the Internet X.509 version 3 standard and indicates which types are recommended by the PKIX working group.
This section summarizes important information about each certificate. For complete details, see both the X.509 v3 standard, available from the ITU, and Internet X.509 Public Key Infrastructure
- Certificate and CRL Profile (RFC 3280) , available at http://www.ietf.org/rfc/rfc3280.txt
. The descriptions of extensions reference the RFC and section number of the standard draft that discusses the extension; the object identifier (OID) for each extension is also provided.
Each extension in a certificate can be designated as critical or noncritical. A certificate-using system, such as a web browser, must reject the certificate if it encounters a critical extension it does not recognize; however, a noncritical extension can be ignored if it is not recognized.
463
Appendix A. Certificate and CRL Extensions
A.3.1. authorityInfoAccess
A.3.1.1. OID
1.3.6.1.5.5.7.1.1
A.3.1.2. Criticality
This extension must be noncritical.
A.3.1.3. Discussion
The Authority Information Access extension indicates how and where to access information about the issuer of the certificate. The extension contains an accessMethod and an accessLocation field. accessMethod specifies by OID the type and format of information about the issuer named in accessLocation .
PKIX Part 1 defines one accessMethod ( id-ad-caIssuers ) to get a list of CAs that have issued certificates higher in the CA chain than the issuer of the certificate using the extension. The accessLocation field then typically contains a URL indicating the location and protocol (LDAP,
HTTP, or FTP) used to retrieve the list.
The Online Certificate Status Protocol (RFC 2560), available at http://www.ietf.org/rfc/rfc2560.txt
, defines an accessMethod ( id-ad-ocsp ) for using OCSP to verify certificates. The accessLocation field then contains a URL indicating the location and protocol used to access an OCSP responder that can validate the certificate.
A.3.2. The authorityKeyIdentifier
A.3.2.1. OID
2.5.29.35
A.3.2.2. Criticality
This extension is always noncritical and is always evaluated.
A.3.2.3. Discussion
The Authority Key Identifier extension identifies the public key corresponding to the private key used to sign a certificate. This extension is useful when an issuer has multiple signing keys.
The extension consists of one or both of the following:
• An explicit key identifier, set in the keyIdentifier field
• An issuer, set in the authorityCertIssuer field, and serial number, set in the authorityCertSerialNumber field, identifying a certificate
If the keyIdentifier field exists, it is used to select the certificate with a matching subjectKeyIdentifier extension. If the authorityCertIssuer and authorityCertSerialNumber fields are present, then they are used to identify the correct certificate by issuer and serialNumber .
464
basicConstraints
If this extension is not present, then the issuer name alone is used to identify the issuer certificate.
PKIX Part 1 requires this extension for all certificates except self-signed root CA certificates. Where a key identifier has not been established, PKIX recommends that the authorityCertIssuer and authorityCertSerialNumber fields be specified. These fields permit construction of a complete certificate chain by matching the SubjectName and CertificateSerialNumber fields in the issuer's certificate against the authortiyCertIssuer and authorityCertSerialNumber in the
Authority Key Identifier extension of the subject certificate.
A.3.3. basicConstraints
A.3.3.1. OID
2.5.29.19
A.3.3.2. Criticality
PKIX Part 1 requires that this extension be marked critical. This extension is evaluated regardless of its criticality.
A.3.3.3. Discussion
This extension is used during the certificate chain verification process to identify CA certificates and to apply certificate chain path length constraints. The cA component should be set to true for all CA certificates. PKIX recommends that this extension should not appear in end-entity certificates.
If the pathLenConstraint component is present, its value must be greater than the number of CA certificates that have been processed so far, starting with the end-entity certificate and moving up the chain. If pathLenConstraint is omitted, then all of the higher level CA certificates in the chain must not include this component when the extension is present.
A.3.4. certificatePolicies
A.3.4.1. OID
2.5.29.32
A.3.4.2. Criticality
This extension may be critical or noncritical.
A.3.4.3. Discussion
The Certificate Policies extension defines one or more policies, each of which consists of an OID and optional qualifiers. The extension can include a URI to the issuer's Certificate Practice Statement or can embed issuer information, such as a user notice in text form. This information can be used by certificate-enabled applications.
If this extension is present, PKIX Part 1 recommends that policies be identified with an OID only, or, if necessary, only certain recommended qualifiers.
465
Appendix A. Certificate and CRL Extensions
A.3.5. CRLDistributionPoints
A.3.5.1. OID
2.5.29.31
A.3.5.2. Criticality
PKIX recommends that this extension be marked noncritical and that it be supported for all certificates.
A.3.5.3. Discussion
This extension defines how CRL information is obtained. It should be used if the system is configured to use CRL issuing points.
If the extension contains a DistributionPointName with a type set to URI, the URI is assumed to be a pointer to the current CRL for the specified revocation reasons and will be issued by the named cRLIssuer . The expected values for the URI are those defined for the Subject Alternative Name extension. If the distributionPoint omits reasons, the CRL must include revocations for all reasons. If the distributionPoint omits cRLIssuer , the CRL must be issued by the CA that issued the certificate.
PKIX recommends that this extension be supported by CAs and applications.
A.3.6. extKeyUsage
A.3.6.1. OID
2.5.29.37
A.3.6.2. Criticality
If this extension is marked critical, the certificate must be used for one of the indicated purposes only.
If it is not marked critical, it is treated as an advisory field that may be used to identify keys but does not restrict the use of the certificate to the indicated purposes.
A.3.6.3. Discussion
The Extended Key Usage extension indicates the purposes for which the certified public key may be used. These purposes may be in addition to or in place of the basic purposes indicated in the Key
Usage extension.
The Extended Key Usage extension must include OCSP Signing in an OCSP responder's certificate unless the CA signing key that signed the certificates validated by the responder is also the OCSP signing key. The OCSP responder's certificate must be issued directly by the CA that signs certificates the responder will validate.
The Key Usage, Extended Key Usage, and Basic Constraints extensions act together to define the purposes for which the certificate is intended to be used. Applications can use these extensions to disallow the use of a certificate in inappropriate contexts.
466
issuerAltName Extension
Table A.1, “PKIX Extended Key Usage Extension Uses” lists the uses defined by PKIX for this extension, and Table A.2, “Private Extended Key Usage Extension Uses” lists uses privately defined by Netscape.
Use
Server authentication
Client authentication
Code signing
Timestamping
OCSP Signing
OCSP Signing is not defined in PKIX Part 1, but in RFC 2560, X.509 Internet Public Key Infrastructure Online Certificate Status
Protocol - OCSP .
Table A.1. PKIX Extended Key Usage Extension Uses
Use
Certificate trust list signing
Microsoft Server Gated Crypto (SGC)
Microsoft Encrypted File System
Netscape SGC
Table A.2. Private Extended Key Usage Extension Uses
A.3.7. issuerAltName Extension
A.3.7.1. OID
2.5.29.18
A.3.7.2. Criticality
PKIX Part 1 recommends that this extension be marked noncritical.
A.3.7.3. Discussion
The Issuer Alternative Name extension is used to associate Internet-style identities with the certificate issuer. Names must use the forms defined for the Subject Alternative Name extension.
A.3.8. keyUsage
A.3.8.1. OID
2.5.29.15
A.3.8.2. Criticality
This extension may be critical or noncritical. PKIX Part 1 recommends that it should be marked critical if it is used.
467
OID
1.3.6.1.5.5.7.3.1
1.3.6.1.5.5.7.3.2
1.3.6.1.5.5.7.3.3
1.3.6.1.5.5.7.3.4
1.3.6.1.5.5.7.3.8
1.3.6.1.5.5.7.3.9
1
OID
1.3.6.1.4.1.311.10.3.1
1.3.6.1.4.1.311.10.3.3
1.3.6.1.4.1.311.10.3.4
2.16.840.1.113730.4.1
Appendix A. Certificate and CRL Extensions
A.3.8.3. Discussion
The Key Usage extension defines the purpose of the key contained in the certificate. The Key Usage,
Extended Key Usage, and Basic Constraints extensions act together to specify the purposes for which a certificate can be used.
If this extension is included at all, set the bits as follows:
• digitalSignature ( 0 ) for SSL client certificates, S/MIME signing certificates, and object-signing certificates.
• nonRepudiation ( 1 ) for some S/MIME signing certificates and object-signing certificates.
WARNING
Use of this bit is controversial. Carefully consider the legal consequences of its use before setting it for any certificate.
• keyEncipherment ( 2 ) for SSL server certificates and S/MIME encryption certificates.
• dataEncipherment ( 3 ) when the subject's public key is used to encrypt user data instead of key material.
• keyAgreement ( 4 ) when the subject's public key is used for key agreement.
• keyCertSign ( 5 ) for all CA signing certificates.
• cRLSign ( 6 ) for CA signing certificates that are used to sign CRLs.
• encipherOnly ( 7 ) if the public key is used only for enciphering data. If this bit is set, keyAgreement should also be set.
• decipherOnly ( 8 ) if the public key is used only for deciphering data. If this bit is set, keyAgreement should also be set.
Table A.3, “Certificate Uses and Corresponding Key Usage Bits” summarizes the guidelines for typical certificate uses.
Purpose of Certificate
CA Signing
SSL Client
SSL Server
S/MIME Signing
S/MIME Encryption
Certificate Signing
Table A.3. Certificate Uses and Corresponding Key Usage Bits
If the keyUsage extension is present and marked critical, then it is used to enforce the usage of the certificate and key. The extension is used to limit the usage of a key; if the extension is not present or not critical, all types of usage are allowed.
468
Required Key Usage Bit
• keyCertSign
• cRLSign digitalSignature keyEncipherment digitalSignature keyEncipherment keyCertSign
nameConstraints
If the keyUsage extension is present, critical or not, it is used to select from multiple certificates for a given operation. For example, it is used to distinguish separate signing and encryption certificates for users who have separate certificates and key pairs for operations.
A.3.9. nameConstraints
A.3.9.1. OID
2.5.29.30
A.3.9.2. Criticality
PKIX Part 1 requires that this extension be marked critical.
A.3.9.3. Discussion
This extension, which can used in CA certificates only, defines a name space within which all subject names in subsequent certificates in a certification path must be located.
A.3.10. OCSPNocheck
A.3.10.1. OID
1.3.6.1.5.5.7.48.4
A.3.10.2. Criticality
This extension should be noncritical.
A.3.10.3. Discussion
The extension is meant to be included in an OCSP signing certificate. The extension tells an OCSP client that the signing certificate can be trusted without querying the OCSP responder (since the reply would again be signed by the OCSP responder, and the client would again request the validity status of the signing certificate). This extension is null-valued; its meaning is determined by its presence or absence.
Since the presence of this extension in a certificate will cause OCSP clients to trust responses signed with that certificate, use of this extension should be managed carefully. If the OCSP signing key is compromised, the entire process of validating certificates in the PKI will be compromised for the duration of the validity period of the certificate. Therefore, certificates using OCSPNocheck should be issued with short lifetimes and be replaced frequently.
A.3.11. policyConstraints
A.3.11.1. OID
2.5.29.36
469
Appendix A. Certificate and CRL Extensions
A.3.11.2. Criticality
This extension may be critical or noncritical.
A.3.11.3. Discussion
This extension, which is for CA certificates only, constrains path validation in two ways. It can be used to prohibit policy mapping or to require that each certificate in a path contain an acceptable policy identifier.
PKIX requires that, if present, this extension must never consist of a null sequence. At least one of the two available fields must be present.
A.3.12. policyMappings
A.3.12.1. OID
2.5.29.33
A.3.12.2. Criticality
This extension must be noncritical.
A.3.12.3. Discussion
The Policy Mappings extension is used in CA certificates only. It lists one or more pairs of OIDs used to indicate that the corresponding policies of one CA are equivalent to policies of another CA. It may be useful in the context of cross-pair certificates.
This extension may be supported by CAs and applications.
A.3.13. privateKeyUsagePeriod
A.3.13.1. OID
2.5.29.16
A.3.13.2. Discussion
The Private Key Usage Period extension allows the certificate issuer to specify a different validity period for the private key than for the certificate itself. This extension is intended for use with digital signature keys.
NOTE
PKIX Part 1 recommends against the use of this extension. CAs conforming to PKIX Part
1 must not generate certificates with this extension.
470
subjectAltName
A.3.14. subjectAltName
A.3.14.1. OID
2.5.29.17
A.3.14.2. Criticality
If the certificate's subject field is empty, this extension must be marked critical.
A.3.14.3. Discussion
The Subject Alternative Name extension includes one or more alternative (non-X.500) names for the identity bound by the CA to the certified public key. It may be used in addition to the certificate's subject name or as a replacement for it. Defined name forms include Internet electronic mail address
(SMTP, as defined in RFC-822), DNS name, IP address, and uniform resource identifier (URI).
PKIX requires this extension for entities identified by name forms other than the X.500 distinguished name (DN) used in the subject field. PKIX Part 1 describes additional rules for the relationship between this extension and the subject field.
Email addresses may be provided in the Subject Alternative Name extension, the certificate subject name field, or both. If the email address is part of the subject name, it must be in the form of the
EmailAddress attribute defined by PKCS #9. Software that supports S/MIME must be able to read an email address from either the Subject Alternative Name extension or from the subject name field.
A.3.15. subjectDirectoryAttributes
A.3.15.1. OID
2.5.29.9
A.3.15.2. Criticality
PKIX Part 1 requires that this extension be marked noncritical.
A.3.15.3. Discussion
The Subject Directory Attributes extension conveys any desired directory attribute values for the subject of the certificate. It is not recommended as an essential part of the proposed PKIX standard but may be used in local environments.
A.3.16. subjectKeyIdentifier
A.3.16.1. OID
2.5.29.14
A.3.16.2. Criticality
This extension is always noncritical.
471
Appendix A. Certificate and CRL Extensions
A.3.16.3. Discussion
The Subject Key Identifier extension identifies the public key certified by this certificate. This extension provides a way of distinguishing public keys if more than one is available for a given subject name.
The value of this extension should be calculated by performing a SHA-1 hash of the certificate's DERencoded subjectPublicKey , as recommended by PKIX. The Subject Key Identifier extension is used in conjunction with the Authority Key Identifier extension for CA certificates. If the CA certificate has a Subject Key Identifier extension, the key identifier in the Authority Key Identifier extension of the certificate being verified should match the key identifier of the CA's Subject Key Identifier extension. It is not necessary for the verifier to recompute the key identifier in this case.
PKIX Part 1 requires this extension for all CA certificates and recommends it for all other certificates.
A.4. Introduction to CRL Extensions
Since its initial publication, the X.509 standard for CRL formats has been amended to include additional information within a CRL. This information is added through CRL extensions.
The extensions defined by ANSI X9 and ISO/IEC/ITU for X.509 CRLs [X.509] [X9.55] allow additional attributes to be associated with CRLs. The Internet X.509 Public Key Infrastructure Certificate and
CRL Profile , available at http://www.ietf.org/rfc/rfc3280.txt
, recommends a set of extensions to be used in CRLs. These extensions are called standard CRL extensions .
The standard also allows custom extensions to be created and included in CRLs. These extensions are called private , proprietary , or custom CRL extensions and carry information unique to an organization or business. Applications may not able to validate CRLs that contain private critical extensions, so it is not recommended that custom extensions be used in a general context.
NOTE
Abstract Syntax Notation One (ASN.1) and Distinguished Encoding Rules (DER) standards are specified in the CCITT Recommendations X.208 and X.209. For a quick summary of ASN.1 and DER, see A Layman's Guide to a Subset of ASN.1, BER, and
DER , which is available at RSA Laboratories' web site, http://www.rsa.com
.
A.4.1. Structure of CRL Extensions
A CRL extension consists of the following parts:
• The object identifier (OID) for the extension. This identifier uniquely identifies the extension. It also determines the ASN.1 type of value in the value field and how the value is interpreted. When an extension appears in a CRL, the OID appears as the extension ID field ( extnID ) and the corresponding ASN.1 encoded structure appears as the value of the octet string ( extnValue ); examples are shown in Section A.1.2, “Sample Certificate Extensions” .
• A flag or boolean field called critical .
The true or false value assigned to this field indicates whether the extension is critical or noncritical to the CRL.
• If the extension is critical and the CRL is sent to an application that does not understand the extension based on the extension's ID, the application must reject the CRL.
472
Sample CRL and CRL Entry Extensions
• If the extension is not critical and the CRL is sent to an application that does not understand the extension based on the extension's ID, the application can ignore the extension and accept the
CRL.
• An octet string containing the DER encoding of the value of the extension.
The application receiving the CRL checks the extension ID to determine if it can recognize the ID. If it can, it uses the extension ID to determine the type of value used.
A.4.2. Sample CRL and CRL Entry Extensions
The following is an example of the section of a CRL containing X.509 v2 extensions. The Certificate
System can display CRLs in readable pretty-print format, as shown here. As shown in the example,
CRL extensions appear in sequence and only one instance of a particular extension may appear per
CRL; for example, a CRL may contain only one Authority Key Identifier extension. However, CRL-entry extensions appear in appropriate entries in the CRL.
Certificate Revocation List:
Data:
Version: v2
...
Extensions:
Identifier: Authority Key Identifier
Critical: no
Key Identifier:
2c:22:c6:ae:4e:4b:91:c7:fb:4c:cc:ae:84:e8:aa:5b:46:6a:a0:ad
Revoked Certificates:
Serial Number: 0x12
Revocation Date: Tuesday, December 15, 1998 5:20:42 AM
Extensions:
Identifier: Revocation Reason - 2.5.29.21
Critical: no
Reason: Key_Compromise
Serial Number: 0x11
Revocation Date: Wednesday, December 16, 1998 4:51:54 AM
Extensions:
Identifier: Revocation Reason - 2.5.29.21
Critical: no
Reason: CA_Compromise
Serial Number: 0x10
Revocation Date: Thursday, December 17, 1998 2:37:24 AM
Extensions:
Identifier: Revocation Reason - 2.5.29.21
Critical: no
Reason: Key_Compromise
Serial Number: 0xA
Revocation Date: Wednesday, November 25, 1998 5:11:18 AM
Extensions:
Identifier: Revocation Reason - 2.5.29.21
Critical: no
Reason: Affiliation_Changed
...
473
Appendix A. Certificate and CRL Extensions
A.5. Standard X.509 v3 CRL Extensions
In addition to certificate extensions, the X.509 proposed standard defines extensions to CRLs, which provide methods for associating additional attributes with Internet CRLs. These are one of two kinds: extensions to the CRL itself and extensions to individual certificate entries in the CRL.
• Section A.5.1, “Extensions for CRLs”
• Section A.5.2, “CRL Entry Extensions”
A.5.1. Extensions for CRLs
The following CRL descriptions are defined as part of the Internet X.509 v3 Public Key Infrastructure proposed standard.
• Section A.5.1.1, “authorityKeyIdentifier”
• Section A.5.1.2, “CRLNumber”
• Section A.5.1.3, “deltaCRLIndicator”
• Section A.5.1.5, “issuerAltName”
• Section A.5.1.6, “issuingDistributionPoint”
A.5.1.1. authorityKeyIdentifier
A.5.1.1.1. OID
2.5.29.35
A.5.1.1.2. Discussion
The Authority Key Identifier extension for a CRL identifies the public key corresponding to the private key used to sign the CRL. For details, see the discussion under certificate extensions at Section A.3.2,
“The authorityKeyIdentifier” .
The PKIX standard recommends that the CA must include this extension in all CRLs it issues because a CA's public key can change, for example, when the key gets updated, or the CA may have multiple signing keys because of multiple concurrent key pairs or key changeover. In these cases, the CA ends up with more than one key pair. When verifying a signature on a certificate, other applications need to know which key was used in the signature.
A.5.1.1.3. Parameters
Parameter enable critical
Table A.4. AuthorityKeyIdentifierExt Configuration Parameters
474
Description
Specifies whether the rule is enabled or disabled. The default is to have this extension disabled.
Sets whether the extension is marked as critical; the default is noncritical.
Extensions for CRLs
A.5.1.2. CRLNumber
A.5.1.2.1. OID
2.5.29.20
A.5.1.2.2. Criticality
This extension must not be critical.
A.5.1.2.3. Discussion
The CRLNumber extension specifies a sequential number for each CRL issued by a CA. It allows users to easily determine when a particular CRL supersedes another CRL. PKIX requires that all
CRLs have this extension.
A.5.1.2.4. Parameters
Parameter enable critical
Table A.5. CRLNumber Configuration Parameters
A.5.1.3. deltaCRLIndicator
A.5.1.3.1. OID
2.5.29.27
A.5.1.3.2. Criticality
PKIX requires that this extension be critical if it exists.
A.5.1.3.3. Discussion
The deltaCRLIndicator extension generates a delta CRL, a list only of certificates that have been revoked since the last CRL; it also includes a reference to the base URL. This updates the local database while ignoring unchanged information already in the local database. This can significantly improve processing time for applications that store revocation information in a format other than the
CRL structure.
A.5.1.3.4. Parameters
Parameter enable
475
Description
Specifies whether the rule is enabled, which is the default.
Sets whether the extension is marked as critical; the default is noncritical.
Description
Sets whether the rule is enabled. By default, it is disabled.
Appendix A. Certificate and CRL Extensions
Parameter critical
Table A.6. DeltaCRL Configuration Parameters
A.5.1.4. FreshestCRL
A.5.1.4.1. OID
2.5.29.27
A.5.1.4.2. Criticality
PKIX requires that this extension must be noncritical.
A.5.1.4.3. Discussion
The freshestCRL extension identifies how delta CRL information is obtained. The freshestCRL extension is placed in the full CRL to indicate where to find the latest delta CRL.
A.5.1.4.4. Parameters
Parameter enable critical numPoints pointType n pointName n
Description
Sets whether the extension rule is enabled. By default, this is disabled.
Marks the extension as critical or noncritical. The default is noncritical.
Indicates the number of issuing points for the delta CRL, from 0 to any positive integer; the default is 0 . When setting this to an integer other than 0, set the number, and then click OK to close the window. Re-open the edit window for the rule, and the fields to set these points will be present.
Specifies the type of issuing point for the n issuing point. For each number specified in numPoints , there is an equal number of pointType parameters. The options are either
DirectoryName or URIName .
If pointType is set to directoryName , the value must be a string in the form of an X.500
name, similar to the subject name in a certificate.
For example, CN=CACentral,OU=Research
Dept,O=Example Corporation,C=US .
If pointType is set to URIName , the name must be a URI; the URI must be an absolute pathname and must specify the host. For
476
Description
Sets whether the extension is critical or noncritical. By default, this is critical.
Extensions for CRLs
Parameter
Table A.7. FreshestCRL Configuration Parameters
Description example, http://testCA.example.com/ get/crls/here/ .
A.5.1.5. issuerAltName
A.5.1.5.1. OID
2.5.29.18
A.5.1.5.2. Discussion
The Issuer Alternative Name extension allows additional identities to be associated with the issuer of the CRL, like binding attributes such as a mail address, a DNS name, an IP address, and a uniform resource indicator (URI), with the issuer of the CRL. For details, see the discussion under certificate extensions at Section A.3.7, “issuerAltName Extension” .
A.5.1.5.3. Parameters
Parameter enable critical numNames nameType n
477
Description
Sets whether the extension rule is enabled; by default, this is disabled.
Sets whether the extension is critical; by default, this is noncritical.
Sets the total number of alternative names or identities permitted in the extension. Each name has a set of configuration parameters, nameType and name , which must have appropriate values or the rule returns an error. Change the total number of identities by changing the value specified in this field; there is no limit on the total number of identities that can be included in the extension. Each set of configuration parameters is distinguished by an integer derived from the value of this field. For example, if the numNames parameter is set to 2 , the derived integers are 0 and 1 .
Specifies the general-name type; this can be any of the following:
• rfc822Name if the name is an Internet mail address.
• directoryName if the name is an X.500 directory name.
• dNSName if the name is a DNS name.
• ediPartyName if the name is a EDI party name.
• URL if the name is a URI (default).
• iPAddress if the name is an IP address.
• OID if the name is an object identifier.
Appendix A. Certificate and CRL Extensions
Parameter name n
Table A.8. IssuerAlternativeName Configuration Parameters
478
Description
• otherName if the name is in any other name form; this supports PrintableString , IA5String , UTF8String ,
BMPString , Any , and KerberosName .
Specifies the general-name value; the allowed values depend on the name type specified in the nameType field.
• For rfc822Name , the value must be a valid Internet mail address in the local-part@domain format.
• For directoryName , the value must be a string X.500
name, similar to the subject name in a certificate.
For example, CN=CACentral,OU=Research
Dept,O=Example Corporation,C=US .
• For dNSName , the value must be a valid domain name in the
DNS format. For example, testCA.example.com
.
• For ediPartyName , the name must be an IA5String. For example, Example Corporation .
• For URL , the value must be a non-relative URI. For example, http://testCA.example.com
.
• For iPAddress , the value must be a valid IP address specified in dot-separated numeric component notation.
It can be the IP address or the IP address including the netmask.
• For OID , the value must be a unique, valid OID specified in the dot-separated numeric component notation. For example, 1.2.3.4.55.6.5.99
. Although custom OIDs can be used to evaluate and test the server, in a production environment, comply with the ISO rules for defining OIDs and for registering subtrees of IDs. See Section A.2, “Note on Object Identifiers” for information on allocating private
OIDs.
• For otherName , the names can be any other format; this supports PrintableString , IA5String ,
UTF8String , BMPString , Any , and KerberosName .
PrintableString , IA5String , UTF8String ,
BMPString , and Any set a string to a base-64 encoded file specifying the subtree, such as /var/lib/rhpkica/othername.txt
. KerberosName has the format
Realm|NameType|NameStrings , such as realm1|0| userID1,userID2 .the name must be the absolute path to the file that contains the general name in its base-64 encoded format. For example, /var/lib/rhpki-ca/ extn/ian/othername.txt
.
Extensions for CRLs
A.5.1.6. issuingDistributionPoint
A.5.1.6.1. OID
2.5.29.28
A.5.1.6.2. Criticality
PKIX requires that this extension be critical if it exists.
A.5.1.6.3. Discussion
The Issuing Distribution Point CRL extension identifies the CRL distribution point for a particular CRL and indicates what kinds of revocation it covers, such as revocation of end-entity certificates only, CA certificates only, or revoked certificates that have a limited set of reason codes.
PKIX Part I does not require this extension.
A.5.1.6.4. Parameters
Parameter enable critical pointType pointName onlySomeReasons
479
Description
Sets whether the extension is enabled; the default is disabled.
Marks the extension as critical, the default, or noncritical.
Specifies the type of the issuing distribution point from the following:
• directoryName specifies that the type is an X.500
directory name.
• URIName specifies that the type is a uniform resource indicator.
Gives the name of the issuing distribution point. The name of the distribution point depends on the value specified for the pointType parameter.
• For directoryName , the name must be an X.500
name. For example, cn=CRLCentral,ou=Research
Dept,o=Example Corporation,c=US
• For URIName , the name must be a URI that is an absolute pathname and specifies the host. For example, http:// testCA.example.com/get/crls/here/ .
NOTE
The CRL may be stored in the directory entry corresponding to the CRL issuing point, which may be different than the directory entry of the CA.
Specifies the reason codes associated with the distribution point.
Appendix A. Certificate and CRL Extensions
Parameter onlyContainsCACerts indirectCRL
Table A.9. IssuingDistributionPoint Configuration Parameters
A.5.2. CRL Entry Extensions
The sections that follow lists the CRL entry extension types that are defined as part of the Internet
X.509 v3 Public Key Infrastructure proposed standard. All of these extensions are noncritical.
A.5.2.1. certificateIssuer
A.5.2.1.1. OID
2.5.29.29
A.5.2.1.2. Discussion
The Certificate Issuer extension identifies the certificate issuer associated with an entry in an indirect
CRL.
This extension is used only with indirect CRLs, which are not supported by the Certificate System.
A.5.2.2. holdInstructionCode
A.5.2.2.1. OID
2.5.29.23
A.5.2.2.2. Discussion
The Hold Instruction Code extension indicates the action to be taken after encountering a certificate that has been placed on hold.
A.5.2.2.3. Parameters
Parameter enable
480
Description
Permissible values are a combination of reason codes ( unspecified , keyCompromise , cACompromise , affiliationChanged , superseded , cessationOfOperation , certificateHold , and removeFromCRL ) separated by commas. Leave the field blank if the distribution point contains revoked certificates with all reason codes (default).
Specifies that the distribution point contains user certificates only if set. By default, this is not set, which means the distribution point contains all types of certificates.
Specifies that the distribution point contains an indirect CRL; by default, this is not selected.
Description
Sets whether the rule is enabled; by default, this is disabled.
CRL Entry Extensions
Parameter critical instruction
Table A.10. HoldInstruction Configuration Parameters
A.5.2.3. invalidityDate
A.5.2.3.1. OID
2.5.29.24
A.5.2.3.2. Discussion
The Invalidity Date extension provides the date on which the private key was compromised or that the certificate otherwise became invalid.
A.5.2.3.3. Parameters
Parameter enable critical
Table A.11. InvalidityDate Configuration Parameters
A.5.2.4. CRLReason
A.5.2.4.1. OID
2.5.29.21
A.5.2.4.2. Discussion
The Reason Code extension identifies the reason for certificate revocation.
481
Description
Marks the extension as critical; by default, this is marked noncritical.
Sets the action a validating application must take when it encounters a certificate that has been put on hold; these can be none , callissuer , or reject .
none specifies that the validating application should not do anything; the PKIX standard says that this is semantically equivalent to disabling holdInstructionCode .
callissuer specifies that the validating application must call the CA that has issued the certificate or reject the certificate.
reject specifies that the validating application must reject the certificate on hold.
Description
Sets whether the extension rule is enabled or disabled. By default, this is enabled.
Marks the extension as critical or noncritical; by default, this is noncritical.
Appendix A. Certificate and CRL Extensions
A.5.2.4.3. Parameters
Parameter enable critical
Table A.12. CRLReason Configuration Parameters
A.6. Netscape-Defined Certificate Extensions
Netscape defined certain certificate extensions for its products. Some of the extensions are now obsolete, and others have been superseded by the extensions defined in the X.509 proposed standard. All Netscape extensions should be tagged as noncritical, so that their presence in a certificate does not make that certificate incompatible with other clients.
A.6.1. netscape-cert-type
A.6.1.1. OID
2.16.840.1.113730.1
A.6.1.2. Discussion
The Netscape Certificate Type extension can be used to limit the purposes for which a certificate can be used. It has been replaced by the X.509 v3 extensions Section A.3.6, “extKeyUsage” and
Section A.3.3, “basicConstraints” .
If the extension exists in a certificate, it limits the certificate to the uses specified in it. If the extension is not present, the certificate can be used for all applications.
The value is a bit-string, where the individual bit positions, when set, certify the certificate for particular uses as follows:
• bit 0: SSL Client certificate
• bit 1: SSL Server certificate
• bit 2: S/MIME certificate
• bit 5: SSL CA certificate
• bit 6: S/MIME CA certificate
A.6.2. netscape-comment
A.6.2.1. OID
2.16.840.1.113730.13
482
Description
Sets whether the extension rule is enabled or disabled. By default, this is enabled.
Marks the extension as critical or noncritical. By default, this is noncritical.
netscape-comment
A.6.2.2. Discussion
The value of this extension is an IA5String. It is a comment that can be displayed to the user when the certificate is viewed.
483
484
Appendix B. Introduction to Public-Key
Cryptography
Public-key cryptography and related standards underlie the security features of many products such as signed and encrypted email, single sign-on, and Secure Sockets Layer (SSL) communications. This chapter covers the basic concepts of public-key cryptography.
• Section B.1, “Internet Security Issues”
• Section B.2, “Encryption and Decryption”
• Section B.3, “Digital Signatures”
• Section B.4, “Certificates and Authentication”
• Section B.5, “Managing Certificates”
B.1. Internet Security Issues
All communication over the Internet uses the Transmission Control Protocol/Internet Protocol
(TCP/IP). TCP/IP allows information to be sent from one computer to another through intermediate computers and separate networks before reaching its destination.
The great flexibility of TCP/IP has led to its worldwide acceptance as the basic Internet and intranet communications protocol. However, since TCP/IP allows information to pass through intermediate computers, it is possible for a third party to interfere with communications in the following ways:
• Eavesdropping.
Information remains intact, but its privacy is compromised. For example, someone could gather credit card numbers, record a sensitive conversation, or intercept classified information.
• Tampering.
Information in transit is changed or replaced and then sent to the recipient. For example, someone could alter an order for goods or change a person's resume.
• Impersonation.
Information passes to a person who poses as the intended recipient. Impersonation can take two forms:
• Spoofing.
A person can pretend to be someone else. For example, a person can pretend to have the email address [email protected]
or a computer can falsely identify itself as a site called www.example.net
.
• Misrepresentation.
A person or organization can misrepresent itself. For example, a site called www.example.net
can purport to be an on-line furniture store when it really receives credit-card payments but never sends any goods.
Normally, the network traffic is not monitored by the cooperating computers or networks which compose the Internet. However, many sensitive personal and business communications over the
Internet require precautions that address potential security threats. Well-established standards and practices known as public- key cryptography make it relatively easy to take such precautions.
Public-key cryptography facilitates the following tasks:
485
Appendix B. Introduction to Public-Key Cryptography
• Encryption and decryption allow two communicating parties to disguise information they send to each other. The sender encrypts, or scrambles, information before sending it. The receiver decrypts, or unscrambles, the information after receiving it. While in transit, the encrypted information is unintelligible to an intruder.
• Tamper detection allows the recipient of information to verify that it has not been modified in transit.
Any attempts to modify or substitute data are detected.
• Authentication allows the recipient of information to determine its origin by confirming the sender's identity.
• Nonrepudiation prevents the sender of information from claiming at a later date that the information was never sent.
B.2. Encryption and Decryption
Encryption is the process of transforming information so it is unintelligible to anyone but the intended recipient. Decryption is the process of decoding encrypted information. A cryptographic algorithm, also called a cipher , is a mathematical function used for encryption or decryption. Usually, two related functions are used, one for encryption and the other for decryption.
With most modern cryptography, the ability to keep encrypted information secret is based not on the cryptographic algorithm, which is widely known, but on a number called a key that must be used with the algorithm to produce an encrypted result or to decrypt previously encrypted information.
Decryption with the correct key is simple. Decryption without the correct key is very difficult, if not impossible.
The following sections cover using keys for encryption and decryption:
• Section B.2.1, “Symmetric-Key Encryption”
• Section B.2.2, “Public-Key Encryption”
• Section B.2.3, “Key Length and Encryption Strength”
B.2.1. Symmetric-Key Encryption
With symmetric-key encryption, the encryption key can be calculated from the decryption key and vice versa. With most symmetric algorithms, the same key is used for both encryption and decryption, as shown in Figure B.1, “Symmetric-Key Encryption” .
Figure B.1. Symmetric-Key Encryption
Implementations of symmetric-key encryption can be highly efficient, so that users do not experience any significant time delay as a result of the encryption and decryption. Symmetric-key encryption also
486
Public-Key Encryption provides a degree of authentication, since information encrypted with one symmetric key cannot be decrypted with any other symmetric key. Thus, as long as the symmetric key is kept secret by the two parties using it to encrypt communications, each party can be sure that it is communicating with the other as long as the decrypted messages continue to make sense.
Symmetric-key encryption is effective only if the symmetric key is kept secret by the two parties involved. If anyone else discovers the key, it affects both confidentiality and authentication. A person with an unauthorized symmetric key not only can decrypt messages sent with that key, but can encrypt new messages and send them as if they came from one of the legitimate parties using the key.
Symmetric-key encryption plays an important role in SSL communication, which is widely used for authentication, tamper detection, and encryption over TCP/IP networks. SSL also uses techniques of public-key encryption, which is described in the next section.
B.2.2. Public-Key Encryption
NOTE
The most common implementations of public-key encryption are based on algorithms patented by RSA Data Security. Therefore, this section describes the RSA approach to public-key encryption.
Public-key encryption (also called asymmetric encryption) involves a pair of keys, a public key and a private key, associated with an entity. Each public key is published, and the corresponding private key is kept secret. (For more information about the way public keys are published, see Section B.4,
“Certificates and Authentication” .) Data encrypted with a public key can be decrypted only with the corresponding private key. Figure B.2, “Public-Key Encryption” shows a simplified view of the way public-key encryption works.
Figure B.2. Public-Key Encryption
The scheme shown in Figure B.2, “Public-Key Encryption” allows public keys to be freely distributed, while only authorized people are able to read data encrypted using this key. In general, to send encrypted data, the data is encrypted with that person's public key, and the person receiving the encrypted data decrypts it with the corresponding private key.
Compared with symmetric-key encryption, public-key encryption requires more processing and may not be feasible for encrypting and decrypting large amounts of data. However, it is possible to use public-key encryption to send a symmetric key, which can then be used to encrypt additional data. This is the approach used by the SSL/TLS protocols.
The reverse of the scheme shown in Figure B.2, “Public-Key Encryption” also works: data encrypted with a private key can be decrypted only with the corresponding public key. This is not
487
Appendix B. Introduction to Public-Key Cryptography a recommended practice to encrypt sensitive data, however, because it means that anyone with the public key, which is by definition published, could decrypt the data. Nevertheless, private-key encryption is useful because it means the private key can be used to sign data with a digital signature, an important requirement for electronic commerce and other commercial applications of cryptography.
Client software such as Mozilla Firefox can then use the public key to confirm that the message was signed with the appropriate private key and that it has not been tampered with since being signed.
Section B.3, “Digital Signatures” illustrates how this confirmation process works.
B.2.3. Key Length and Encryption Strength
The strength of encryption is related to the difficulty of discovering the key, which depends on the cipher used and the length of the key. For example, the difficulty of discovering the key for the RSA cipher depends on the difficulty of factoring large numbers, a well-known mathematical problem.
Encryption strength is often described in terms of the size of the keys used to perform the encryption: longer keys provide stronger encryption. Key length is measured in bits. For example, 128-bit keys with the RC4 symmetric-key cipher supported by SSL provide significantly better cryptographic protection than 40-bit keys used with the same cipher. The 128-bit RC4 encryption is 3 x 10^26 times stronger than 40-bit RC4 encryption. For more information about RC4 and other ciphers used with
SSL, see Section 1.4.10, “SSL/TLS and Supported Cipher Suites” .
Different ciphers may require different key lengths to achieve the same level of encryption strength.
The RSA cipher can use only a subset of all possible values for a key of a given length, due to the nature of the mathematical problem on which it is based. Other ciphers, such as those used for symmetric-key encryption, can use all possible values for a key of a given length. Thus, a 128-bit key with a symmetric-key encryption cipher provides stronger encryption than a 128-bit key with the RSA public-key encryption cipher. This difference explains why the RSA public-key encryption cipher must use a 512-bit key or longer to be considered cryptographically strong, when symmetric-key ciphers can achieve the same level of strength with a 64-bit key.
B.3. Digital Signatures
Encryption and decryption address the problem of eavesdropping, but encryption and decryption, by themselves, do not address the two other problems: tampering and impersonation.
Tamper detection relies on a mathematical function called a one-way hash (also called a message digest ). A one-way hash is a number of fixed length with the following characteristics:
• The value of the hash is unique for the hashed data. Any change in the data, even deleting or altering a single character, results in a different value.
• The content of the hashed data cannot be deduced from the hash.
As mentioned in Section B.2.2, “Public-Key Encryption” , it is possible to use a private key for encryption and the corresponding public key for decryption. Although not recommended when encrypting sensitive information, it is a crucial part of digitally signing any data. Instead of encrypting the data itself, the signing software creates a one-way hash of the data, then uses the private key to encrypt the hash. The encrypted hash, along with other information such as the hashing algorithm, is known as a digital signature.
Figure B.3, “Using a Digital Signature to Validate Data Integrity” illustrates the way a digital signature can be used to validate the integrity of signed data.
488
Certificates and Authentication
Figure B.3. Using a Digital Signature to Validate Data Integrity
Figure B.3, “Using a Digital Signature to Validate Data Integrity” shows two items transferred to the recipient of some signed data: the original data and the digital signature, which is a one-way hash of the original data encrypted with the signer's private key. To validate the integrity of the data, the receiving software first uses the public key to decrypt the hash. It then uses the same hashing algorithm that generated the original hash to generate a new one-way hash of the same data.
(Information about the hashing algorithm used is sent with the digital signature.) Finally, the receiving software compares the new hash against the original hash. If the two hashes match, the data has not changed since it was signed. If they do not match, the data may have been tampered with since it was signed, or the signature may have been created with a private key that does not correspond to the public key presented by the signer.
If the two hashes match, the recipient can be certain that the public key used to decrypt the digital signature corresponds to the private key used to create the digital signature. Confirming the identity of the signer also requires some way of confirming that the public key belongs to a particular entity. For more information on authenticating users, see Section B.4, “Certificates and Authentication” .
A digital signature is similar to a handwritten signature. Once data have been signed, it is difficult to deny doing so later, assuming the private key has not been compromised. This quality of digital signatures provides a high degree of nonrepudiation; digital signatures make it difficult for the signer to deny having signed the data. In some situations, a digital signature is as legally binding as a handwritten signature.
B.4. Certificates and Authentication
• Section B.4.1, “A Certificate Identifies Someone or Something”
• Section B.4.2, “Authentication Confirms an Identity”
• Section B.4.3, “How Certificates Are Used”
• Section B.4.5, “Contents of a Certificate”
• Section B.4.6, “How CA Certificates Establish Trust”
B.4.1. A Certificate Identifies Someone or Something
A certificate is an electronic document used to identify an individual, a server, a company, or other entity and to associate that identity with a public key. Like a driver's license or passport, a certificate
489
Appendix B. Introduction to Public-Key Cryptography provides generally recognized proof of a person's identity. Public-key cryptography uses certificates to address the problem of impersonation.
To get personal ID such as a driver's license, a person has to present some other form of identification which confirms that the person is who he claims to be. Certificates work much the same way.
Certificate authorities (CAs) validate identities and issue certificates. CAs can be either independent third parties or organizations running their own certificate-issuing server software, such as Certificate
System. The methods used to validate an identity vary depending on the policies of a given CA for the type of certificate being requested. Before issuing a certificate, a CA must confirm the user's identity with its standard verification procedures.
The certificate issued by the CA binds a particular public key to the name of the entity the certificate identifies, such as the name of an employee or a server. Certificates help prevent the use of fake public keys for impersonation. Only the public key certified by the certificate will work with the corresponding private key possessed by the entity identified by the certificate.
In addition to a public key, a certificate always includes the name of the entity it identifies, an expiration date, the name of the CA that issued the certificate, and a serial number. Most importantly, a certificate always includes the digital signature of the issuing CA. The CA's digital signature allows the certificate to serve as a valid credential for users who know and trust the CA but do not know the entity identified by the certificate.
For more information about the role of CAs, see Section B.4.6, “How CA Certificates Establish Trust” .
B.4.2. Authentication Confirms an Identity
Authentication is the process of confirming an identity. For network interactions, authentication involves the identification of one party by another party. There are many ways to use authentication over networks. Certificates are one of those way.
Network interactions typically take place between a client, such as a web browser, and a server. Client authentication refers to the identification of a client (the person assumed to be using the software) by a server. Server authentication refers to the identification of a server (the organization assumed to be running the server at the network address) by a client.
Client and server authentication are not the only forms of authentication that certificates support. For example, the digital signature on an email message, combined with the certificate that identifies the sender, can authenticate the sender of the message. Similarly, a digital signature on an HTML form, combined with a certificate that identifies the signer, can provide evidence that the person identified by that certificate agreed to the contents of the form. In addition to authentication, the digital signature in both cases ensures a degree of nonrepudiation; a digital signature makes it difficult for the signer to claim later not to have sent the email or the form.
Client authentication is an essential element of network security within most intranets or extranets.
There are two main forms of client authentication:
• Password-based authentication . Almost all server software permits client authentication by requiring a recognized name and password before granting access to the server.
• Certificate-based authentication . Client authentication based on certificates is part of the SSL protocol. The client digitally signs a randomly generated piece of data and sends both the certificate
490
Authentication Confirms an Identity and the signed data across the network. The server validates the signature and confirms the validity of the certificate.
B.4.2.1. Password-Based Authentication
Figure B.4, “Using a Password to Authenticate a Client to a Server” shows the process of authenticating a user using a username and password. This example assumes the following:
• The user has already trusted the server, either without authentication or on the basis of server authentication over SSL.
• The user has requested a resource controlled by the server.
• The server requires client authentication before permitting access to the requested resource.
Figure B.4. Using a Password to Authenticate a Client to a Server
These are the steps in this authentication process:
1. When the server requests authentication from the client, the client displays a dialog box requesting the username and password for that server.
2. The client sends the name and password across the network, either in plain text or over an encrypted SSL connection.
3. The server looks up the name and password in its local password database and, if they match, accepts them as evidence authenticating the user's identity.
4. The server determines whether the identified user is permitted to access the requested resource and, if so, allows the client to access it.
With this arrangement, the user must supply a new password for each server accessed, and the administrator must keep track of the name and password for each user.
B.4.2.2. Certificate-Based Authentication
One of the advantages of certificate-based authentication is that it can be used to replace the first three steps in authentication with a mechanism that allows the user to supply one password, which is
491
Appendix B. Introduction to Public-Key Cryptography not sent across the network, and allows the administrator to control user authentication centrally. This is called single sign-on .
Figure B.5, “Using a Certificate to Authenticate a Client to a Server” shows how client authentication works using certificates and SSL. To authenticate a user to a server, a client digitally signs a randomly generated piece of data and sends both the certificate and the signed data across the network. The server authenticates the user's identity based on the data in the certificate and signed data.
Like Figure B.4, “Using a Password to Authenticate a Client to a Server” , Figure B.5, “Using a
Certificate to Authenticate a Client to a Server” assumes that the user has already trusted the server and requested a resource and that the server has requested client authentication before granting access to the requested resource.
Figure B.5. Using a Certificate to Authenticate a Client to a Server
Unlike the authentication process in Figure B.4, “Using a Password to Authenticate a Client to a
Server” , the authentication process in Figure B.5, “Using a Certificate to Authenticate a Client to a Server” requires SSL. Figure B.5, “Using a Certificate to Authenticate a Client to a Server” also assumes that the client has a valid certificate that can be used to identify the client to the server.
Certificate-based authentication is preferred to password-based authentication because it is based on the user both possessing the private key and knowing the password. However, these two assumptions are true only if unauthorized personnel have not gained access to the user's machine or password, the password for the client software's private key database has been set, and the software is set up to request the password at reasonably frequent intervals.
NOTE
Neither password-based authentication nor certificate-based authentication address security issues related to physical access to individual machines or passwords. Publickey cryptography can only verify that a private key used to sign some data corresponds to the public key in a certificate. It is the user's responsibility to protect a machine's physical security and to keep the private-key password secret.
492
How Certificates Are Used
These are the authentication steps shown in Figure B.5, “Using a Certificate to Authenticate a Client to a Server” :
1. The client software maintains a database of the private keys that correspond to the public keys published in any certificates issued for that client. The client asks for the password to this database the first time the client needs to access it during a given session, such as the first time the user attempts to access an SSL-enabled server that requires certificate-based client authentication.
After entering this password once, the user does not need to enter it again for the rest of the session, even when accessing other SSL-enabled servers.
2. The client unlocks the private-key database, retrieves the private key for the user's certificate, and uses that private key to sign data randomly-generated from input from both the client and the server. This data and the digital signature are evidence of the private key's validity. The digital signature can be created only with that private key and can be validated with the corresponding public key against the signed data, which is unique to the SSL session.
3. The client sends both the user's certificate and the randomly-generated data across the network.
4. The server uses the certificate and the signed data to authenticate the user's identity.
5. The server may perform other authentication tasks, such as checking that the certificate presented by the client is stored in the user's entry in an LDAP directory. The server then evaluates whether the identified user is permitted to access the requested resource. This evaluation process can employ a variety of standard authorization mechanisms, potentially using additional information in an LDAP directory or company databases. If the result of the evaluation is positive, the server allows the client to access the requested resource.
Certificates replace the authentication portion of the interaction between the client and the server.
Instead of requiring a user to send passwords across the network continually, single sign-on requires the user to enter the private-key database password once, without sending it across the network. For the rest of the session, the client presents the user's certificate to authenticate the user to each new server it encounters. Existing authorization mechanisms based on the authenticated user identity are not affected.
B.4.3. How Certificates Are Used
The following sections cover common certificate types and when these certificates are commonly used.
• Section B.4.3.1, “Types of Certificates”
• Section B.4.3.2, “SSL”
• Section B.4.3.3, “Signed and Encrypted Email”
• Section B.4.4, “Single Sign-on”
B.4.3.1. Types of Certificates
Five kinds of certificates are commonly used:
493
Appendix B. Introduction to Public-Key Cryptography
Certificate Type
Client SSL certificates
Server SSL certificates
S/MIME certificates
CA certificates
Use
Used for client authentication to servers over SSL. Typically, the identity of the client is assumed to be the same as the identity of a person, such as an employee.
See Section B.4.2.2, “Certificate-Based
Authentication” for a description of the way
SSL client certificates are used for client authentication. Client SSL certificates can also be used as part of single sign-on.
Used for server authentication to clients over SSL. Server authentication may be used without client authentication. Server authentication is required for an encrypted
SSL session. For more information, see
Section B.4.3.2, “SSL” .
Used for signed and encrypted email. As with SSL client certificates, the identity of the client is assumed to be the same as the identity of a person, such as an employee.
A single certificate may be used as both an
S/MIME certificate and an SSL certificate; see Section B.4.3.3, “Signed and Encrypted
Email” . S/MIME certificates can also be used as part of single sign-on.
Used to identify CAs. Client and server software use CA certificates to determine what other certificates can be trusted. For more information, see Section B.4.6, “How CA
Certificates Establish Trust” .
Example
A bank gives a customer an SSL client certificate that allows the bank's servers to identify that customer and authorize access to the customer's accounts.
A company gives a new employee an SSL client certificate that allows the company's servers to identify that employee and authorize access to the company's servers.
Internet sites that engage in electronic commerce usually support certificate-based server authentication to establish an encrypted SSL session and to assure customers that they are dealing with the web site identified with the company. The encrypted SSL session ensures that personal information sent over the network, such as credit card numbers, cannot easily be intercepted.
A company deploys combined S/MIME and SSL certificates solely to authenticate employee identities, thus permitting signed email and SSL client authentication but not encrypted email. Another company issues
S/MIME certificates solely to sign and encrypt email that deals with sensitive financial or legal matters.
The CA certificates stored in Mozilla Firefox determine what other certificates can be authenticated. An administrator can implement corporate security policies by controlling the CA certificates stored in each user's copy of Firefox.
Table B.1. Common Certificates
B.4.3.2. 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.
For an overview of client authentication over SSL and how it differs from password-based authentication, see Section B.4.2, “Authentication Confirms an Identity” .
494
Single Sign-on
B.4.3.3. Signed and Encrypted Email
Some email programs support digitally signed and encrypted email using a widely accepted protocol known as Secure Multipurpose Internet Mail Extension (S/MIME). Using S/MIME to sign or encrypt email messages requires the sender of the message to have an S/MIME certificate.
An email message that includes a digital signature provides some assurance that it was sent by the person whose name appears in the message header, thus authenticating the sender. If the digital signature cannot be validated by the email software, the user is alerted.
The digital signature is unique to the message it accompanies. If the message received differs in any way from the message that was sent, even by adding or deleting a single character, the digital signature cannot be validated. Therefore, signed email also provides assurance that the email has not been tampered with. This kind of assurance is known as nonrepudiation, which makes it difficult for the sender to deny having sent the message. This is important for business communication. For information about the way digital signatures work, see Section B.3, “Digital Signatures” .
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.
B.4.4. Single Sign-on
Network users are frequently required to remember multiple passwords for the different services they use, like logging onto the network, collecting email, using directory services, using the corporate calendar program, and accessing servers. Users have difficulty keeping track of different passwords, tend to choose poor ones, and tend to write them down in obvious places, and 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, both of which make using multiple passwords problematic.
The solution to this problem is single sign-on , which allows a user to log in once with a single password and get authenticated access to all network resources that user is authorized to use, without sending any passwords over the network. Both SSL client certificates and S/MIME certificates can play a significant role in a comprehensive single sign-on solution; SSL client authentication allows a user to log into the local client's private-key database and get authenticated access to all SSLenabled servers that user is authorized to use. This approach simplifies access for users because they do not need to enter passwords for each new server. It also simplifies network management since administrators can control access by controlling lists of CAs rather than much longer lists of users and passwords.
In addition to using certificates, a complete single-sign on solution must address interoperability with enterprise systems, such as the operating system, that rely on passwords or other forms of authentication.
B.4.5. Contents of a Certificate
The contents of certificates are organized according to the X.509 v3 certificate specification, which has been recommended by the International Telecommunications Union (ITU), an international standards body.
495
Appendix B. Introduction to Public-Key Cryptography
Users do not usually need to be concerned about the exact contents of a certificate. However, system administrators working with certificates may need some familiarity with the information contained in them.
B.4.5.1. Distinguished Names
An X.509 v3 certificate binds a distinguished name (DN) to a public key. A DN is a series of namevalue pairs, such as uid=doe , that uniquely identify an entity. This is also called the certificate subject name .
This is an example DN of an employee for Example Corp.: uid=doe, cn=John Doe,o=Example Corp.,c=US
In this DN, uid is the username, cn is the user's common name, o is the organization or company name, and c is the country.
DNs may include a variety of other name-value pairs. They are used to identify both certificate subjects and entries in directories that support the Lightweight Directory Access Protocol (LDAP).
The rules governing the construction of DNs can be complex; for comprehensive information about
DNs, see A String Representation of Distinguished Names at http://www.ietf.org/rfc/rfc1485.txt
.
B.4.5.2. A Typical Certificate
Every X.509 certificate consists of two sections:
• The data section includes the following information:
• The version number of the X.509 standard supported by the certificate.
• The certificate's serial number. Every certificate issued by a CA has a serial number that is unique among the certificates issued by that CA.
• Information about the user's public key, including the algorithm used and a representation of the key itself.
• The DN of the CA that issued the certificate.
• The period during which the certificate is valid; for example, between 1:00 p.m. on November 15,
2004, and 1:00 p.m. November 15, 2009.
• The DN of the certificate subject, which is also called the subject name; for example, in an SSL client certificate, this is the user's DN.
• Optional certificate extensions , which may provide additional data used by the client or server. For example, the Netscape Certificate Type extension indicates the type of certificate, such as an SSL client certificate, an SSL server certificate, or a certificate for signing email. Certificate extensions can also be used for other purposes.
• The signature section includes the following information:
• The cryptographic algorithm, or cipher, used by the issuing CA to create its own digital signature.
For more information about ciphers, see Section 1.4.10, “SSL/TLS and Supported Cipher Suites” .
496
Contents of a Certificate
• The CA's digital signature, obtained by hashing all of the data in the certificate together and encrypting it with the CA's private key.
Here are the data and signature sections of a certificate shown in the readable pretty-print format:
Certificate:
Data:
Version: v3 (0x2)
Serial Number: 3 (0x3)
Signature Algorithm: PKCS #1 MD5 With RSA Encryption
Issuer: OU=Ace Certificate Authority, O=Ace Industry, C=US
Validity:
Not Before: Fri Oct 17 18:36:25 1997
Not After: Sun Oct 17 18:36:25 1999
Subject: CN=Jane Doe, OU=Finance, O=Ace Industry, C=US
Subject Public Key Info:
Algorithm: PKCS #1 RSA Encryption
Public Key:
Modulus:
00:ca:fa:79:98:8f:19:f8:d7:de:e4:49:80:48:e6:2a:2a:86:
ed:27:40:4d:86:b3:05:c0:01:bb:50:15:c9:de:dc:85:19:22:
43:7d:45:6d:71:4e:17:3d:f0:36:4b:5b:7f:a8:51:a3:a1:00:
98:ce:7f:47:50:2c:93:36:7c:01:6e:cb:89:06:41:72:b5:e9:
73:49:38:76:ef:b6:8f:ac:49:bb:63:0f:9b:ff:16:2a:e3:0e:
9d:3b:af:ce:9a:3e:48:65:de:96:61:d5:0a:11:2a:a2:80:b0:
7d:d8:99:cb:0c:99:34:c9:ab:25:06:a8:31:ad:8c:4b:aa:54:
91:f4:15
Public Exponent: 65537 (0x10001)
Extensions:
Identifier: Certificate Type
Critical: no
Certified Usage:
SSL Client
Identifier: Authority Key Identifier
Critical: no
Key Identifier:
f2:f2:06:59:90:18:47:51:f5:89:33:5a:31:7a:e6:5c:fb:36:
26:c9
Signature:
Algorithm: PKCS #1 MD5 With RSA Encryption
Signature:
6d:23:af:f3:d3:b6:7a:df:90:df:cd:7e:18:6c:01:69:8e:54:65:fc:06:
30:43:34:d1:63:1f:06:7d:c3:40:a8:2a:82:c1:a4:83:2a:fb:2e:8f:fb:
f0:6d:ff:75:a3:78:f7:52:47:46:62:97:1d:d9:c6:11:0a:02:a2:e0:cc:
2a:75:6c:8b:b6:9b:87:00:7d:7c:84:76:79:ba:f8:b4:d2:62:58:c3:c5:
b6:c1:43:ac:63:44:42:fd:af:c8:0f:2f:38:85:6d:d6:59:e8:41:42:a5:
4a:e5:26:38:ff:32:78:a1:38:f1:ed:dc:0d:31:d1:b0:6d:67:e9:46:a8:
d:c4
Here is the same certificate in the base-64 encoded format:
-----BEGIN CERTIFICATE-----
MIICKzCCAZSgAwIBAgIBAzANBgkqhkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzER
MA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEw
MTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBgNVBAYTAlVTMREwDwYDVQQK
EwhOZXRzY2FwZTENMAsGA1UECxMEUHViczEXMBUGA1UEAxMOU3Vwcml5YSBTaGV0 dHkwgZ8wDQYJKoZIhvcNAQEFBQADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG
7SdATYazBcABu1AVyd7chRkiQ31FbXFOGD3wNktbf6hRo6EAmM5/R1AskzZ8AW7L iQZBcrXpc0k4du+2Q6xJu2MPm/8WKuMOnTuvzpo+SGXelmHVChEqooCwfdiZywyZ
NMmrJgaoMa2MS6pUkfQVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgDAfBgNV
497
Appendix B. Introduction to Public-Key Cryptography
HSMEGDAWgBTy8gZZkBhHUfWJM1oxeuZc+zYmyTANBgkqhkiG9w0BAQQFAAOBgQBt
I6/z07Z635DfzX4XbAFpjlRl/AYwQzTSYx8GfcNAqCqCwaSMKvsuj/vwbf91o3j3
UkdGYpcd2cYRCgKi4MwqdWyLtpuHAH18hHZ5uvi00mJYw8W2wUOsY0RC/a/IDy84 hW3WWehBUqVK5SY4/zJ4oTjx7dwNMdGwbWfpRqjd1A==
-----END CERTIFICATE-----
B.4.6. How CA Certificates Establish Trust
CAs validate identities and issue certificates. They can be either independent third parties or organizations running their own certificate-issuing server software, such as the Certificate System.
Any client or server software that supports certificates maintains a collection of trusted CA certificates.
These CA certificates determine which issuers of certificates the software can trust, or validate. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It is also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy.
The sections that follow explains how certificate hierarchies and certificate chains determine what certificates software can trust.
• Section B.4.6.1, “CA Hierarchies”
• Section B.4.6.2, “Certificate Chains”
• Section B.4.6.3, “Verifying a Certificate Chain”
B.4.6.1. CA Hierarchies
In large organizations, responsibility for issuing certificates can be delegated to several different CAs.
For example, the number of certificates required may be too large for a single CA to maintain; different organizational units may have different profile requirements; or a CA may need to be physically located in the same geographic area as the people to whom it is issuing certificates.
These certificate-issuing responsibilities can be divided among subordinate CAs. The X.509 standard includes a model for setting up a hierarchy of CAs, shown in Figure B.6, “Example of a Hierarchy of
Certificate Authorities” .
498
How CA Certificates Establish Trust
Figure B.6. Example of a Hierarchy of Certificate Authorities
The root CA is at the top of the hierarchy. The root CA's certificate is a self-signed certificate ; that is, the certificate is digitally signed by the same entity that the certificate identifies. The CAs that are directly subordinate to the root CA have CA certificates signed by the root CA. CAs under the subordinate CAs in the hierarchy have their CA certificates signed by the higher-level subordinate
CAs.
Organizations have a great deal of flexibility in how CA hierarchies are set up; Figure B.6, “Example of a Hierarchy of Certificate Authorities” shows just one example.
B.4.6.2. Certificate Chains
CA hierarchies are reflected in certificate chains. A certificate chain is series of certificates issued by successive CAs. Figure B.7, “Example of a Certificate Chain” shows a certificate chain leading from a certificate that identifies an entity through two subordinate CA certificates to the CA certificate for the root CA, based on the CA hierarchy shown in Figure B.6, “Example of a Hierarchy of Certificate
Authorities” .
499
Appendix B. Introduction to Public-Key Cryptography
Figure B.7. Example of a Certificate Chain
A certificate chain traces a path of certificates from a branch in the hierarchy to the root of the hierarchy. In a certificate chain, the following occur:
• Each certificate is followed by the certificate of its issuer.
• Each certificate contains the name (DN) of that certificate's issuer, which is the same as the subject name of the next certificate in the chain.
In Figure B.7, “Example of a Certificate Chain” , the Engineering CA certificate contains the DN of the CA, USA CA , that issued that certificate. USA CA 's DN is also the subject name of the next certificate in the chain.
• Each certificate is signed with the private key of its issuer. The signature can be verified with the public key in the issuer's certificate, which is the next certificate in the chain.
In Figure B.7, “Example of a Certificate Chain” , the public key in the certificate for the USA CA can be used to verify the USA CA 's digital signature on the certificate for the Engineering CA .
B.4.6.3. Verifying a Certificate Chain
Certificate chain verification makes sure a given certificate chain is well-formed, valid, properly signed, and trustworthy. The following procedure is used to form and verify a certificate chain, starting with the certificate being presented for authentication:
500
How CA Certificates Establish Trust
1. The certificate validity period is checked against the current time provided by the verifier's system clock.
2. The issuer's certificate is located. The source can be either the verifier's local certificate database on that client or server or the certificate chain provided by the subject, as with an SSL connection.
3. The certificate signature is verified using the public key in the issuer's certificate.
4. If the issuer's certificate is trusted by the verifier in the verifier's certificate database, verification stops successfully here. Otherwise, the issuer's certificate is checked to make sure it contains the appropriate subordinate CA indication in the certificate type extension, and chain verification starts over with this new certificate. Figure B.8, “Verifying a Certificate Chain to the Root CA” presents an example of this process.
Figure B.8. Verifying a Certificate Chain to the Root CA
Figure B.8, “Verifying a Certificate Chain to the Root CA” illustrates what happens when only the root
CA is included in the verifier's local database. If a certificate for one of the intermediate CAs, such as
Engineering CA , is found in the verifier's local database, verification stops with that certificate, as shown in Figure B.9, “Verifying a Certificate Chain to an Intermediate CA” .
501
Appendix B. Introduction to Public-Key Cryptography
Figure B.9. Verifying a Certificate Chain to an Intermediate CA
Expired validity dates, an invalid signature, or the absence of a certificate for the issuing CA at any point in the certificate chain causes authentication to fail. Figure B.10, “A Certificate Chain That cannot
Be Verified” shows how verification fails if neither the root CA certificate nor any of the intermediate CA certificates are included in the verifier's local database.
502
Managing Certificates
Figure B.10. A Certificate Chain That cannot Be Verified
B.5. Managing Certificates
The standards and services that facilitate using public-key cryptography and X.509 v3 certificates in a network environment is called the public-key infrastructure (PKI). The sections that follow introduce some specific certificate management issues involved in managing the PKI.
• Section B.5.1, “Issuing Certificates”
• Section B.5.2, “Certificates and the LDAP Directory”
• Section B.5.3, “Key Management”
• Section B.5.4, “Revoking Certificates”
B.5.1. Issuing Certificates
The process for issuing a certificate depends on the CA that issues it and the purpose for which it will be used. Issuing nondigital forms of identification varies in similar ways. The requirements to get a library card are different than the ones to get a driver's license. Similarly, different CAs have different
503
Appendix B. Introduction to Public-Key Cryptography procedures for issuing different kinds of certificates. Requirements for receiving a certificate can be as simple as an email address or username and password to notarized documents, a background check, and a personal interview.
Depending on an organization's policies, the process of issuing certificates can range from being completely transparent for the user to requiring significant user participation and complex procedures.
In general, processes for issuing certificates should be flexible, so organizations can tailor them to their changing needs.
The Certificate System allows an organization to set up its own CA and issue certificates.
B.5.2. Certificates and the LDAP Directory
The Lightweight Directory Access Protocol (LDAP) for directory services offers flexibility in managing certificates within an organization. System administrators can store much of the information required to manage certificates in an LDAP-compliant directory. For example, a CA can use information in a directory to prepopulate a certificate with a new employee's legal name and other information. The CA can leverage directory information in other ways to issue certificates one at a time or in bulk, using a range of different identification techniques depending on the security policies of a given organization.
Other routine management tasks, such as key management and revoking certificates, can be partially or fully automated with the aid of the directory.
Information stored in the directory can also be used with certificates to control access to network resources by different users or groups. Issuing certificates and other certificate management tasks can be an integral part of user and group management.
High-performance directory services are an essential ingredient of any certificate management strategy. For the Certificate System to function, there must be a Red Hat Directory Server installed to support the LDAP directory services.
B.5.3. Key Management
Before a certificate can be issued, the public key it contains and the corresponding private key must be generated. Sometimes it may be useful to issue a single person one certificate and key pair for signing operations and another certificate and key pair for encryption operations. Separate signing and encryption certificates keep the private signing key only on the local machine, providing maximum nonrepudiation. This also aids in backing up the private encryption key in some central location where it can be retrieved in case the user loses the original key or leaves the company.
Keys can be generated by client software or generated centrally by the CA and distributed to users through an LDAP directory. There are costs associated with either method. Local key generation provides maximum nonrepudiation but may involve more participation by the user in the issuing process. Flexible key management capabilities are essential for most organizations.
Key recovery , or the ability to retrieve backups of encryption keys under carefully defined conditions, can be a crucial part of certificate management, depending on how an organization uses certificates.
In some PKI setups, several authorized personnel must agree before an encryption key can be recovered to ensure that the key is only recovered to the legitimate owner in authorized circumstance.
It can be necessary to recover a key when information is encrypted and can only be decrypted by the lost key.
504
Revoking Certificates
B.5.4. Revoking Certificates
Like a driver's license, a certificate specifies a period of time during which it is valid. Attempts to use a certificate for authentication before or after its validity period will fail. Managing certificate expirations is an essential part of the certificate management strategy. For example, an administrator may wish to be notified automatically when a certificate is about to expire so that an appropriate replacement process can be completed without disrupting the system operation.
Additionally, it may be necessary to revoke a certificate before it has expired, such as when an employee leaves a company or moves to a new job in a different unit within the company.
Certificate revocation can be handled in several different ways. Servers can be configured so that the authentication process checks the directory for the presence of the certificate being presented. When an administrator revokes a certificate, the certificate can be automatically removed from the directory, and subsequent authentication attempts with that certificate will fail, even though the certificate remains valid in every other respect. Alternatively, a list of revoked certificates, a certificate revocation list (CRL), can be published to the directory at regular intervals. The CRL can be checked as part of the authentication process. The issuing CA can also be checked directly each time a certificate is presented for authentication. This procedure is sometimes called real-time status checking.
505
506
Appendix C. Enrolling a Certificate in a
Cisco Router
IOS version
Not all versions of IOS have the relevant 'crypto' features. You must install a firmware image with the
"Certification Authority Interoperability" feature.
SCEP support for CS was tested on a Cisco 2611 router running the following version of IOS:
IOS (tm) C2600 Software (C2600-JK9S-M), Version 12.2(40), RELEASE SOFTWARE (fc1)
C.1. Preparation
Your router must be configured with an IP address, DNS server, and routing information. The router's date/time must be correct. Also, the router's hostname and dnsname must be configured. Please see
"Cisco Router Configuration" to describe how to accomplish all this.
C.2. Configuration
The router's hostname is scep. Log into the router's console, you'll see the following prompt: scep>
Now run the following commands in sequence:
Enable Privileged Commands: scep> enable
Enter Configuration Mode: scep# conf t
Set up a CA identity: scep(config)# crypto ca identity CA scep(ca-identity)# enrollment url http://water.sfbay.redhat.com:9080/ca/cgi-bin scep(ca-identity)# crl optional scep(ca-identity)# exit
Get the CA's certificate: scep(config)# crypto ca authenticate CA
Certificate has the following attributes:
Fingerprint: 145E3825 31998BA7 F001EA9A B4001F57
% Do you accept this certificate? [yes/no]: yes
507
Appendix C. Enrolling a Certificate in a Cisco Router
Generate rsa key pair: scep(config)# crypto key generate rsa
The name for the keys will be: scep.dsdev.sjc.redhat.com
Choose the size of the key modulus in the range of 360 to 2048 for your
General Purpose Keys. Choosing a key modulus greater than 512 may take a few minutes.
How many bits in the modulus [512]:
Generating RSA keys ...
[OK]
Enroll: scep(config)# crypto ca enroll CA
%
% Start certificate enrollment ..
% Create a challenge password. You will need to verbally provide this
password to the CA Administrator in order to revoke your certificate.
For security reasons your password will not be saved in the configuration.
Please make a note of it.
Password: 12345
Re-enter password: 12345
% The subject name in the certificate will be: scep.dsdev.sjc.redhat.com
% Include the router serial number in the subject name? [yes/no]: yes
% The serial number in the certificate will be: 57DE391C
% Include an IP address in the subject name? [yes/no]: yes
% Interface: Ethernet0/0
% Request certificate from CA? [yes/no]: yes
% Certificate request sent to Certificate Authority
% The certificate request fingerprint will be displayed.
% The 'show crypto ca certificate' command will also show the fingerprint.
% Fingerprint: D89DB555 E64CC2F7 123725B4 3DBDF263
Jan 12 13:41:17.348: %CRYPTO-6-CERTRET: Certificate received from Certificate
Exit from conf mode scep(config)# exit
Show certificates: scep# show crypto ca certificates
Certificate
Status: Available
Certificate Serial Number: 0C
Key Usage: General Purpose
Issuer:
CN = Certificate Authority
O = Sfbay Red hat Domain 20070111d12
Subject Name Contains:
Name: scep.dsdev.sjc.redhat.com
IP Address: 10.14.1.94
Serial Number: 57DE391C
508
Working with chained (subordinate) CAs
Validity Date:
start date: 21:42:40 UTC Jan 12 2007
end date: 21:49:50 UTC Dec 31 2008
Associated Identity: CA
CA Certificate
Status: Available
Certificate Serial Number: 01
Key Usage: Signature
Issuer:
CN = Certificate Authority
O = Sfbay Red hat Domain 20070111d12
Subject:
CN = Certificate Authority
O = Sfbay Red hat Domain 20070111d12
Validity Date:
start date: 21:49:50 UTC Jan 11 2007
end date: 21:49:50 UTC Dec 31 2008
Associated Identity: CA
CLEANUP: Zeroize keys (necessary to re-enroll) scep(config)# crypto key zeroize rsa
% Keys to be removed are named scep.dsdev.sjc.redhat.com.
Do you really want to remove these keys? [yes/no]: yes
CLEANUP: Removing a CA identity: scep(config)# no crypto ca identity CA
% Removing an identity will destroy all certificates received from the related Certificate Authority.
Are you sure you want to do this? [yes/no]: yes
% Be sure to ask the CA administrator to revoke your certificates.
No enrollment sessions are currently active.
C.2.1. Working with chained (subordinate) CAs
Before running the 'crypto ca authenticate' command above, you must import all certificates in the chain, starting with the root. In conf mode (Note: the following example has only two CAs in the chain, therefore the root starts at 1, and the subordinate CA is 0),
Note
The following url's in the example are for enrollment via an RA. If you want to bypass RA and directly talk to CA or subordinate CA, you need to change the url's to point to them: e.g.
root CEP http://paw.sfbay.redhat.com:9280/ca/cgi-bin enrollment url http://paw.sfbay.redhat.com:9280/ca/cgi-bin
Example to enroll via an RA to a subordinate CA:
509
Appendix C. Enrolling a Certificate in a Cisco Router scep(config)# crypto ca trusted-root 1 scep(ca-root)# root CEP http://paw.sfbay.redhat.com:12888/ee/scep/pkiclient.cgi
scep(ca-root)# crl optional scep(ca-root)# exit scep(config)# cry ca authenticate 1 scep(config)# crypto ca trusted-root 0 scep(ca-root)# root CEP http://paw.sfbay.redhat.com:12888/ee/scep/pkiclient.cgi
scep(ca-root)# crl optional scep(ca-root)# exit scep(config)# cry ca authenticate 0
In the above example, if your CA certs do not have CRL distribution point extension in them, you must turn off the CRL requirement: scep(ca-root)# crl optional
Set up a CA identity: scep(config)# crypto ca identity CA scep(ca-identity)# enrollment url http://paw.sfbay.redhat.com:12888/ee/scep/pkiclient.cgi
scep(ca-identity)# crl optional scep(ca-identity)# exit
Submit enrollment request to subordinate CA in this example: scep(config)# crypto ca authenticate CA scep(config)# crypto ca enroll CA
C.2.2. DEBUGGING:
The router will provide additional debugging during SCEP operations if you execute the following debug statements.
scep# debug crypto pki callbacks
Crypto PKI callbacks debugging is on scep# debug crypto pki messages
Crypto PKI Msg debugging is on scep# debug crypto pki transactions
Crypto PKI Trans debugging is on scep# debug crypto verbose verbose debug output debugging is on
510
Glossary
A access control access control instructions
(ACI) access control list (ACL) administrator agent agent-approved enrollment agent services attribute value assertion
(AVA) audit log auditor authentication
The process of controlling what particular users are allowed to do. For example, access control to servers is typically based on an identity, established by a password or a certificate, and on rules regarding what that entity can do. See also access control list (ACL) .
An access rule that specifies how subjects requesting access are to be identified or what rights are allowed or denied for a particular subject. See access control list (ACL) .
A collection of access control entries that define a hierarchy of access rules to be evaluated when a server receives a request for access to a particular resource. See access control instructions (ACI) .
The person who installs and configures one or more Certificate
System managers and sets up privileged users, or agents, for them.
See also agent .
A user who belongs to a group authorized to manage agent services for a Certificate System manager. See also Certificate Manager agent , Data Recovery Manager agent .
An enrollment that requires an agent to approve the request before the certificate is issued.
1. Services that can be administered by a Certificate System agent through HTML pages served by the Certificate System subsystem for which the agent has been assigned the necessary privileges.
2. The HTML pages for administering such services.
An assertion of the form attribute = value , where attribute is a tag, such as o (organization) or uid (user ID), and value is a value such as "Red Hat, Inc." or a login name. AVAs are used to form the distinguished name (DN) that identifies the subject of a certificate, called the subject name of the certificate.
A log that records various system events. This log can be signed, providing proof that it was not tampered with, and can only be read by an auditor user.
A privileged user who can view the signed audit logs.
Confident identification; assurance that a party to some computerized transaction is not an impostor. Authentication typically involves the use of a password, certificate, PIN, or other information to validate identity over a computer network. See also password-based authentication , certificate-based authentication , client authentication , server authentication .
511
Glossary authentication module authorization automated enrollment
A set of rules (implemented as a Java ™ class) for authenticating an end entity, agent, administrator, or any other entity that needs to interact with a Certificate System subsystem. In the case of typical end-user enrollment, after the user has supplied the information requested by the enrollment form, the enrollment servlet uses an authentication module associated with that form to validate the information and authenticate the user's identity. See servlet .
Permission to access a resource controlled by a server. Authorization typically takes place after the ACLs associated with a resource have been evaluated by a server. See access control list (ACL) .
A way of configuring a Certificate System subsystem that allows automatic authentication for end-entity enrollment, without human intervention. With this form of authentication, a certificate request that completes authentication module processing successfully is automatically approved for profile processing and certificate issuance.
B bind DN
C
CA certificate
CA hierarchy
CA server key
CA signing key certificate certificate authority (CA)
A user ID, in the form of a distinguished name (DN), used with a password to authenticate to Red Hat Directory Server.
A certificate that identifies a certificate authority. See also certificate authority (CA) , subordinate CA , root CA .
A hierarchy of CAs in which a root CA delegates the authority to issue certificates to subordinate CAs. Subordinate CAs can also expand the hierarchy by delegating issuing status to other CAs. See also certificate authority (CA) , subordinate CA , root CA .
The SSL server key of the server providing a CA service.
The private key that corresponds to the public key in the CA certificate. A CA uses its signing key to sign certificates and CRLs.
Digital data, formatted according to the X.509 standard, that specifies the name of an individual, company, or other entity (the subject name of the certificate) and certifies that a public key , which is also included in the certificate, belongs to that entity. A certificate is issued and digitally signed by a certificate authority (CA) . A certificate's validity can be verified by checking the CA's digital signature through public-key cryptography techniques. To be trusted within a public-key infrastructure (PKI) , a certificate must be issued and signed by a CA that is trusted by other entities enrolled in the PKI.
A trusted entity that issues a certificate after verifying the identity of the person or entity the certificate is intended to identify. A CA also renews and revokes certificates and generates CRLs. The
512
certificate-based authentication certificate chain certificate extensions certificate fingerprint
Certificate Management
Messages over
Cryptographic Message
Syntax (CMC)
Certificate Management
Message Formats (CMMF)
Certificate Manager
Certificate Manager agent entity named in the issuer field of a certificate is always a CA.
Certificate authorities can be independent third parties or a person or organization using certificate-issuing server software, such as Red
Hat Certificate System.
Authentication based on certificates and public-key cryptography. See also password-based authentication .
A hierarchical series of certificates signed by successive certificate authorities. A CA certificate identifies a certificate authority (CA) and is used to sign certificates issued by that authority. A CA certificate can in turn be signed by the CA certificate of a parent CA, and so on up to a root CA . Certificate System allows any end entity to retrieve all the certificates in a certificate chain.
An X.509 v3 certificate contains an extensions field that permits any number of additional fields to be added to the certificate. Certificate extensions provide a way of adding information such as alternative subject names and usage restrictions to certificates. A number of standard extensions have been defined by the PKIX working group.
A one-way hash associated with a certificate. The number is not part of the certificate itself, but is produced by applying a hash function to the contents of the certificate. If the contents of the certificate changes, even by a single character, the same function produces a different number. Certificate fingerprints can therefore be used to verify that certificates have not been tampered with.
Message format used to convey a request for a certificate to a Certificate Manager. A proposed standard from the Internet
Engineering Task Force (IETF) PKIX working group. For detailed information, see http://www.ietf.org/internet-drafts/draft-ietf-pkixcmc-02.txt
.
Message formats used to convey certificate requests and revocation requests from end entities to a Certificate Manager and to send a variety of information to end entities. A proposed standard from the
Internet Engineering Task Force (IETF) PKIX working group. CMMF is subsumed by another proposed standard, Certificate Management
Messages over Cryptographic Message Syntax (CMC) . For detailed information, see http://www.ietf.org/internet-drafts/draft-ietf-pkixcmmf-02.txt
.
An independent Certificate System subsystem that acts as a certificate authority. A Certificate Manager instance issues, renews, and revokes certificates, which it can publish along with CRLs to an
LDAP directory. It accepts requests from end entities. See certificate authority (CA) .
A user who belongs to a group authorized to manage agent services for a Certificate Manager. These services include the ability to access and modify (approve and reject) certificate requests and issue certificates.
513
Glossary certificate profile
Certificate Request
Message Format (CRMF) certificate revocation list
(CRL) chain of trust chained CA cipher client authentication client SSL certificate
CMC
CMC Enrollment
CMMF
Certificate System
Certificate System instance
Certificate System subsystem
Certificate System console
CRL cross-pair certificate
A set of configuration settings that defines a certain type of enrollment. The certificate profile sets policies for a particular type of enrollment along with an authentication method in a certificate profile.
Format used for messages related to management of X.509
certificates. This format is a subset of CMMF. See also Certificate
Management Message Formats (CMMF) . For detailed information, see ftp://ftp.isi.edu/in-notes/rfc2511.txt
.
As defined by the X.509 standard, a list of revoked certificates by serial number, generated and signed by a certificate authority (CA) .
See certificate chain .
See linked CA .
See cryptographic algorithm .
The process of identifying a client to a server, such as with a name and password or with a certificate and some digitally signed data.
See certificate-based authentication , password-based authentication , server authentication .
A certificate used to identify a client to a server using the SSL protocol. See Secure Sockets Layer (SSL) .
See Certificate Management Messages over Cryptographic Message
Syntax (CMC) .
Features that allow either signed enrollment or signed revocation requests to be sent to a Certificate Manager using an agent's signing certificate. These requests are then automatically processed by the
Certificate Manager.
See Certificate Management Message Formats (CMMF) .
See Red Hat Certificate System , Cryptographic Message Syntax
(CS) .
An instance of a Certificate System subsystem , comprising both code and data and treated as a discrete entity.
One of the five Certificate System managers: Certificate Manager ,
Online Certificate Status Manager, Data Recovery Manager , Token
Key Service, or Token Processing System.
A console that can be opened for any single Certificate System instance. A Certificate System console allows the Certificate System administrator to control configuration settings for the corresponding
Certificate System instance.
See certificate revocation list (CRL) .
A certificate issued by one CA to another CA which is then stored by both CAs to form a circle of trust. The two CAs issue certificates to each other, and then store both cross-pair certificates as a certificate pair.
514
CRMF cross-certification cryptographic algorithm
Cryptographic Message
Syntax (CS) cryptographic module cryptographic service provider (CSP)
See Certificate Request Message Format (CRMF) .
The exchange of certificates by two CAs in different certification hierarchies, or chains. Cross-certification extends the chain of trust so that it encompasses both hierarchies. See also certificate authority
(CA) .
A set of rules or directions used to perform cryptographic operations such as encryption and decryption .
The syntax used to digitally sign, digest, authenticate, or encrypt arbitrary messages, such as CMMF.
See PKCS #11 module .
A cryptographic module that performs cryptographic services, such as key generation, key storage, and encryption, on behalf of software that uses a standard interface such as that defined by PKCS #11 to request such services.
See cryptographic service provider (CSP) .
CSP
D
Data Recovery Manager
Data Recovery Manager agent
Data Recovery Manager recovery agent
Data Recovery Manager storage key
Data Recovery Manager transport certificate decryption
An optional, independent Certificate System subsystem that manages the long-term archival and recovery of RSA encryption keys for end entities. A Certificate Manager can be configured to archive end entities' encryption keys with a Data Recovery Manager before issuing new certificates. The Data Recovery Manager is useful only if end entities are encrypting data, such as sensitive email, that the organization may need to recover someday. It can be used only with end entities that support dual key pairs: two separate key pairs, one for encryption and one for digital signatures.
A user who belongs to a group authorized to manage agent services for a Data Recovery Manager, including managing the request queue and authorizing recovery operation using HTML-based administration pages.
One of the m of n people who own portions of the storage key for the
Data Recovery Manager .
Special key used by the Data Recovery Manager to encrypt the end entity's encryption key after it has been decrypted with the Data
Recovery Manager's private transport key. The storage key never leaves the Data Recovery Manager.
Certifies the public key used by an end entity to encrypt the entity's encryption key for transport to the Data Recovery Manager. The Data
Recovery Manager uses the private key corresponding to the certified public key to decrypt the end entity's key before encrypting it with the storage key.
Unscrambling data that has been encrypted. See encryption .
515
Glossary
Data Encryption Standard
(DES) delta CRL digital ID digital signature distribution points distinguished name (DN) dual key pair
A FIPS-approved cryptographic algorithm required by FIPS 140-1 and specified by FIPS PUBS 46-2. DES, which uses 56-bit keys, is a standard encryption and decryption algorithm that has been used successfully throughout the world for more than 20 years.
See also FIPS PUBS 140-1 . For detailed information, see http:// www.itl.nist.gov/div897/pubs/fip46-2.htm
A CRL containing a list of those certificates that have been revoked since the last full CRL was issued.
See certificate .
To create a digital signature, the signing software first creates a one-way hash from the data to be signed, such as a newly issued certificate. The one-way hash is then encrypted with the private key of the signer. The resulting digital signature is unique for each piece of data signed. Even a single comma added to a message changes the digital signature for that message. Successful decryption of the digital signature with the signer's public key and comparison with another hash of the same data provides tamper detection . Verification of the certificate chain for the certificate containing the public key provides authentication of the signer. See also nonrepudiation , encryption .
Used for CRLs to define a set of certificates. Each distribution point is defined by a set of certificates that are issued. A CRL can be created for a particular distribution point.
A series of AVAs that identify the subject of a certificate. See attribute value assertion (AVA) .
Two public-private key pairs, four keys altogether, corresponding to two separate certificates. The private key of one pair is used for signing operations, and the public and private keys of the other pair are used for encryption and decryption operations. Each pair corresponds to a separate certificate . See also encryption key , publickey cryptography , signing key .
E eavesdropping encryption encryption key enrollment end entity
Surreptitious interception of information sent over a network by an entity for which the information is not intended.
Scrambling information in a way that disguises its meaning. See decryption .
A private key used for encryption only. An encryption key and its equivalent public key, plus a signing key and its equivalent public key, constitute a dual key pair .
The process of requesting and receiving an X.509 certificate for use in a public-key infrastructure (PKI) . Also known as registration .
In a public-key infrastructure (PKI) , a person, router, server, or other entity that uses a certificate to identify itself.
516
extensions field
F fingerprint
FIPS PUBS 140-1 firewall
See certificate extensions .
See certificate fingerprint .
Federal Information Standards Publications (FIPS PUBS) 140-1 is a US government standard for implementations of cryptographic modules, hardware or software that encrypts and decrypts data or performs other cryptographic operations, such as creating or verifying digital signatures. Many products sold to the US government must comply with one or more of the FIPS standards. See http:// www.itl.nist.gov/div897/pubs/fip140-1.htm
.
A system or combination of systems that enforces a boundary between two or more networks.
I impersonation input intermediate CA
The act of posing as the intended recipient of information sent over a network. Impersonation can take two forms: spoofing and misrepresentation .
In the context of the certificate profile feature, it defines the enrollment form for a particular certificate profile. Each input is set, which then dynamically creates the enrollment form from all inputs configured for this enrollment.
A CA whose certificate is located between the root CA and the issued certificate in a certificate chain .
The forgery of client IP addresses.
IP spoofing
J
JAR file A digital envelope for a compressed collection of files organized according to the Java
™
archive (JAR) format .
Java ™ archive (JAR) format A set of conventions for associating digital signatures, installer scripts, and other information with files in a directory.
Java ™ Cryptography
Architecture (JCA)
Java
(JDK)
Java
(JNI)
™
™
Development Kit
Native Interface
The API specification and reference developed by Sun Microsystems for cryptographic services. See http://java.sun.com/products/jdk/1.2/ docs/guide/security/CryptoSpec.Introduction
.
Software development kit provided by Sun Microsystems for developing applications and applets using the Java ™ programming language.
A standard programming interface that provides binary compatibility across different implementations of the Java ™ Virtual Machine (JVM) on a given platform, allowing existing code written in a language
517
Glossary
Java
™
Security Services
(JSS)
K
KEA key key exchange
Key Exchange Algorithm
(KEA)
L
Lightweight Directory
Access Protocol (LDAP) such as C or C++ for a single platform to bind to Java ™ . See http:// java.sun.com/products/jdk/1.2/docs/guide/jni/index.html
.
A Java
™
interface for controlling security operations performed by
Netscape Security Services (NSS).
See Key Exchange Algorithm (KEA) .
A large number used by a cryptographic algorithm to encrypt or decrypt data. A person's public key , for example, allows other people to encrypt messages intended for that person. The messages must then be decrypted by using the corresponding private key .
A procedure followed by a client and server to determine the symmetric keys they will both use during an SSL session.
An algorithm used for key exchange by the US Government.
linked CA
A directory service protocol designed to run over TCP/IP and across multiple platforms. LDAP is a simplified version of Directory Access
Protocol (DAP), used to access X.500 directories. LDAP is under
IETF change control and has evolved to meet Internet requirements.
An internally deployed certificate authority (CA) whose certificate is signed by a public, third-party CA. The internal CA acts as the root
CA for certificates it issues, and the third- party CA acts as the root
CA for certificates issued by other CAs that are linked to the same third-party root CA. Also known as "chained CA" and by other terms used by different public CAs.
M manual authentication
MD5 message digest misrepresentation
A way of configuring a Certificate System subsystem that requires human approval of each certificate request. With this form of authentication, a servlet forwards a certificate request to a request queue after successful authentication module processing. An agent with appropriate privileges must then approve each request individually before profile processing and certificate issuance can proceed.
A message digest algorithm that was developed by Ronald Rivest.
See also one-way hash .
See one-way hash .
The presentation of an entity as a person or organization that it is not.
For example, a website might pretend to be a furniture store when it
518
is really a site that takes credit-card payments but never sends any goods. Misrepresentation is one form of impersonation . See also spoofing .
N
Netscape Security Services
(NSS) nonrepudiation
O object signing
A set of libraries designed to support cross-platform development of security-enabled communications applications. Applications built using the NSS libraries support the Secure Sockets Layer (SSL) protocol for authentication, tamper detection, and encryption, and the
PKCS #11 protocol for cryptographic token interfaces. NSS is also available separately as a software development kit.
The inability by the sender of a message to deny having sent the message. A digital signature provides one form of nonrepudiation.
object-signing certificate
OCSP one-way hash operation output
A technology that allows software developers to sign Java ™ code,
JavaScript scripts, or any kind of file and allows users to identify the signers and control access by signed code to local system resources.
A certificate that's associated private key is used to sign objects using the technology known as object signing .
Online Certificate Status Protocol.
1. A number of fixed-length generated from data of arbitrary length with the aid of a hashing algorithm. The number, also called a message digest, is unique to the hashed data. Any change in the data, even deleting or altering a single character, results in a different value.
2. The content of the hashed data cannot be deduced from the hash.
The specific operation, such as read or write, that is being allowed or denied in an access control instruction.
In the context of the certificate profile feature, it defines the resulting form from a successful certificate enrollment for a particular certificate profile. Each output is set, which then dynamically creates the form from all outputs configured for this enrollment.
P password-based authentication
PKCS #7
PKCS #10
Confident identification by means of a name and password. See also authentication , certificate-based authentication .
The public-key cryptography standard that governs signing and encryption.
The public-key cryptography standard that governs certificate requests.
519
Glossary
PKCS #11
PKCS #11 module
PCKS #12 private key proof-of-archival (POA) public key public-key cryptography public-key infrastructure
(PKI)
R
RC2, RC4
Red Hat Certificate System
The public-key cryptography standard that governs cryptographic tokens such as smart cards.
A driver for a cryptographic device that provides cryptographic services, such as encryption and decryption, through the PKCS
#11 interface. A PKCS #11 module, also called a cryptographic module or cryptographic service provider , can be implemented in either hardware or software. A PKCS #11 module always has one or more slots, which may be implemented as physical hardware slots in some form of physical reader, such as for smart cards, or as conceptual slots in software. Each slot for a PKCS #11 module can in turn contain a token, which is the hardware or software device that actually provides cryptographic services and optionally stores certificates and keys. Red Hat provides a built-in PKCS #11 module with Certificate System.
The public-key cryptography standard that governs key portability.
One of a pair of keys used in public-key cryptography. The private key is kept secret and is used to decrypt data encrypted with the corresponding public key .
Data signed with the private Data Recovery Manager transport key that contains information about an archived end-entity key, including key serial number, name of the Data Recovery Manager, subject name of the corresponding certificate, and date of archival. The signed proof-of-archival data are the response returned by the Data
Recovery Manager to the Certificate Manager after a successful key archival operation. See also Data Recovery Manager transport certificate .
One of a pair of keys used in public-key cryptography. The public key is distributed freely and published as part of a certificate . It is typically used to encrypt data sent to the public key's owner, who then decrypts the data with the corresponding private key .
A set of well-established techniques and standards that allow an entity to verify its identity electronically or to sign and encrypt electronic data. Two keys are involved, a public key and a private key.
A public key is published as part of a certificate, which associates that key with a particular identity. The corresponding private key is kept secret. Data encrypted with the public key can be decrypted only with the private key.
The standards and services that facilitate the use of public-key cryptography and X.509 v3 certificates in a networked environment.
Cryptographic algorithms developed for RSA Data Security by Rivest.
See also cryptographic algorithm .
A highly configurable set of software components and tools for creating, deploying, and managing certificates. Certificate System is
520
registration root CA
RSA algorithm
RSA key exchange
S sandbox
Secure Sockets Layer
(SSL) self tests server authentication server SSL certificate servlet
SHA-1 signature algorithm signed audit log signing certificate signing key comprised of five major subsystems that can be installed in different
Certificate System instances in different physical locations: Certificate
Manager , Online Certificate Status Manager, Data Recovery
Manager , Token Key Service, and Token Processing System.
See enrollment .
The certificate authority (CA) with a self-signed certificate at the top of a certificate chain. See also CA certificate , subordinate CA .
Short for Rivest-Shamir-Adleman, a public-key algorithm for both encryption and authentication. It was developed by Ronald Rivest, Adi
Shamir, and Leonard Adleman and introduced in 1978.
A key-exchange algorithm for SSL based on the RSA algorithm.
A Java ™ term for the carefully defined limits within which Java ™ code must operate.
A protocol that allows mutual authentication between a client and server and the establishment of an authenticated and encrypted connection. SSL runs above TCP/IP and below HTTP, LDAP, IMAP,
NNTP, and other high-level network protocols.
A feature that tests a Certificate System instance both when the instance starts up and on-demand.
The process of identifying a server to a client. See also client authentication .
A certificate used to identify a server to a client using the Secure
Sockets Layer (SSL) protocol.
Java
™
code that handles a particular kind of interaction with end entities on behalf of a Certificate System sudsystem. For example, certificate enrollment, revocation, and key recovery requests are each handled by separate servlets.
Secure Hash Algorithm, a hash function used by the US government.
A cryptographic algorithm used to create digital signatures. Certificate
System supports the MD5 and SHA-1 signing algorithms. See also cryptographic algorithm , digital signature .
See audit log .
A certificate that's public key corresponds to a private key used to create digital signatures. For example, a Certificate Manager must have a signing certificate that's public key corresponds to the private key it uses to sign the certificates it issues.
A private key used for signing only. A signing key and its equivalent public key, plus an encryption key and its equivalent public key, constitute a dual key pair .
521
Glossary single sign-on slot smart card spoofing
SSL subject subject name subordinate CA symmetric encryption
T tamper detection token tree hierarchy
522
1. In Certificate System, a password that simplifies the way to sign on to Red Hat Certificate System by storing the passwords for the internal database and tokens. Each time a user logs on, he is required to enter this single password.
2. The ability for a user to log in once to a single computer and be authenticated automatically by a variety of servers within a network.
Partial single sign-on solutions can take many forms, including mechanisms for automatically tracking passwords used with different servers. Certificates support single sign-on within a public-key infrastructure (PKI) . A user can log in once to a local client's privatekey database and, as long as the client software is running, rely on certificate-based authentication to access each server within an organization that the user is allowed to access.
The portion of a PKCS #11 module , implemented in either hardware or software, that contains a token .
A small device that contains a microprocessor and stores cryptographic information, such as keys and certificates, and performs cryptographic operations. Smart cards implement some or all of the PKCS #11 interface.
Pretending to be someone else. For example, a person can pretend to have the email address [email protected]
, or a computer can identify itself as a site called www.redhat.com
when it is not.
Spoofing is one form of impersonation . See also misrepresentation .
See Secure Sockets Layer (SSL) .
The entity identified by a certificate . In particular, the subject field of a certificate contains a subject name that uniquely describes the certified entity.
A distinguished name (DN) that uniquely describes the subject of a certificate .
A certificate authority that's certificate is signed by another subordinate CA or by the root CA. See CA certificate , root CA .
An encryption method that uses the same cryptographic key to encrypt and decrypt a given message.
A mechanism ensuring that data received in electronic form entirely corresponds with the original version of the same data.
A hardware or software device that is associated with a slot in a
PKCS #11 module . It provides cryptographic services and optionally stores certificates and keys.
The hierarchical structure of an LDAP directory.
trust Confident reliance on a person or other entity. In a public-key infrastructure (PKI) , trust refers to the relationship between the user of a certificate and the certificate authority (CA) that issued the certificate. If a CA is trusted, then valid certificates issued by that CA can be trusted.
V virtual private network
(VPN)
A way of connecting geographically distant divisions of an enterprise.
The VPN allows the divisions to communicate over an encrypted channel, allowing authenticated, confidential transactions that would normally be restricted to a private network.
523
524
Index
A accelerators, 269 active logs default file location, 76 message categories, 79 adding extensions to CRLs, 333 adding new directory attributes, 129 administrators creating, 124, 161, 181, 220, 394 deleting, 400 modifying group membership, 399 storing certificates, 252 tools provided
Certificate System console, 61 agent certificate, 227 requesting, 231
Agent services interface
URL for, 95 agents authorizing key recovery, 177 creating, 124, 161, 181, 220, 394 deleting, 400 enrolling users in person, 322, 386 modifying group membership, 399 port used for operations, 95 role defined, 392
See also Agent Services interface, 392 storing certificates, 252 algorithm cryptographic, 486 archiving rotated log files, 82 users' private encryption keys, 173
Audit log defined, 76 auditors creating, 124, 161, 181, 220, 394 authentication certificate-based, 491, 493 client and server, 490 during certificate revocation, 321 managing through the Console, 379, 382, 384 password-based, 491, 491
See also client authentication, 491
See also server authentication, 491 authentication modules agent initiated user enrollment, 322, 386 deleting, 389 registering new ones, 389 authorityKeyIdentifier, 123, 464, 474
B backing up the Certificate System, 107 backups, 107 base-64 encoded file viewing content, 359 basicConstraints, 122, 465 buffered logging, 81
C
CA certificate, 494 defined, 490 hierarchies and root, 498 trusted, 498
CA certificate mapper, 367
CA certificate publisher, 365, 366
CA chaining, 8
CA decisions for deployment distinguished name, 112 root versus subordinate, 25, 114 signing certificate, 113 signing key, 113
CA hierarchy, 7 root CA, 7 subordinate CA, 7
CA scalability, 8
CA signing certificate, 111, 113, 226 changing trust settings of, 261 deleting, 260 getting a new one, 229 nickname, 111 requesting, 233 viewing details of, 258 certificate viewing content, 359 certificate chains installing in the certificate database, 255 why install, 257 certificate database how to manage, 254 what it contains, 254 where it is maintained, 254 certificate issuance to servers, 231
525
Index
Certificate Manager, 15 administrators creating, 124, 394 agents creating, 124, 394 as root CA, 7 as subordinate CA, 7
CA hierarchy, 7
CA signing certificate, 226 chaining to third-party CAs, 8 clone CA, 14 cloning, 8 configuring
SMTP settings for notifications, 67
DRM and, 13, 15 installed by itself, 13 key pairs and certificates
CA signing certificate, 111
OCSP signing certificate, 112
SSL server certificate, 112 wTLS CA signing certificate, 112 manual updates to publishing directory, 362 master CA, 14 serial number range, 121 what to do when exhausts all serial numbers,
122 certificate revocation authentication during, 321 reasons for, 324 who can revoke certificates, 324
Certificate Setup Wizard, 229, 233 using to install certificate chains, 255 using to install certificates, 255
Certificate System backing up, 107 restoring, 107
SELinux, 22 standards supported by, 21, 22
Certificate System architecture high availability, 451
Certificate System console
Configuration tab, 61 introduction, 61 managing logs, 85
Status tab, 62
Certificate System Console configuring authentication, 379, 382, 384
Certificate System data where it is stored, 103 certificate-based authentication defined, 491 certificate-based enrollment, 386 forms for, 387 what you need, 387 when to use, 387 certificateIssuer, 480 certificatePolicies, 465 certificates and LDAP Directory, 504 authentication using, 491
CA certificate, 494 chains, 500 contents of, 495 extensions for, 123, 459 how to revoke, 324 installing, 254 issuing of, 503 management formats and protocols, 21 publishing to files, 338 publishing to LDAP directory required schema, 360 revocation reasons, 324 revoking, 505
S/MIME, 494 self-signed, 499 serial numbers what to do when a CA exhausts all, 122 storing user's, 252 verifying a certificate chain, 501
X.509 specification, 22 certutil requesting certificates, 244 changing
DER-encoding order of DirectoryString, 130 group members, 399 trust settings in certificates, 261 why would you change, 261 ciphers defined, 486 client authentication
SSL client certificates defined, 494 clone CA, 14 cloning, 8 setting up server for multiple requests, 385
CMC, 21
CMMF, 21 command-line utilities for adding extensions to Certificate System certificates, 241 configuration file, 68 comments and other ignored text, 69 copying from one instance to another, 70
526
format, 68 format for localizable values, 69 guidelines for editing, 68 name, 68 when created, 68
Configuration tab, 61 configuring for high availability, 451
CRL viewing content, 359
CRL Distribution Point extension, 325
CRL extension modules
CRLReason, 298
CRL publisher, 365
CRL signing certificate, 226, 324 requesting, 233 cRLDistributionPoints, 466
CRLNumber, 475
CRLReason, 481
CRLs
Certificate Manager support for, 5 defined, 324 entering multiple update times, 330 entering update period, 330 extension-specific modules, 472 extensions for, 474 issuing or distribution points, 325 publishing of, 323 publishing to files, 338 publishing to LDAP directory, 325, 338 required schema, 360 publishing to online validation authority, 157 supported extensions, 324 when automated updates take place, 324 when generated, 324 who generates it, 324
CRMF, 21
Cryptographic Message Syntax (CMS), 21
D
Data Recovery Manager administrators creating, 181, 394 agents creating, 181, 394 key pairs and certificates list of, 173 storage key pair, 174 transport certificate, 174 setting up key archival, 178 key recovery, 179 deleting authentication modules, 389 log modules, 87 mapper modules, 363 privileged users, 400 publisher modules, 363 deltaCRLIndicator, 475 deployment planning
CA decisions
CA reissuance, 120 distinguished name, 112 root versus subordinate, 25, 114 signing certificate, 113 signing key, 113 token management, 15 topology decisions, 15
DER-encoded file viewing content, 359
DER-encoding order of DirectoryString, 130 digital signatures defined, 488 directory removing expired certificates from, 440 directory attributes adding new, 129 supported in CS, 128 distinguished name (DN) extending attribute support, 129 for CA, 112
DN components mapper, 370 downloading certificates, 254
DRM, 15
Certificate Manager and, 13, 15
DRM transport certificate requesting, 233
E email, signed and encrypted, 495 encrypted file system (EFS), 297 encryption defined, 486 public-key, 487 symmetric-key, 486 end entities port used for operations, 95 end-entity certificate publisher, 365 enrollment agent initiated, 322, 386
Enterprise Security Client, 223, 223
Error log defined, 78
527
Index expired certificates removing from the directory, 440
Extended Key Usage extension
OIDs for encrypted file system, 297 extending directory-attribute support in CS, 129 extensions, 123, 459 an example, 461 authorityKeyIdentifier, 123, 464, 474 basicConstraints, 122, 465
CA certificates and, 122, 123 certificateIssuer, 480 certificatePolicies, 465 cRLDistributionPoints, 466
CRLNumber, 475
CRLReason, 481 deltaCRLIndicator, 475 extKeyUsage, 466 holdInstructionCode, 480 invalidityDate, 481 issuerAltName, 467, 477 issuingDistributionPoint, 479 keyUsage, 467 nameConstraints, 469 netscape-cert-type, 482
Netscape-defined, 482 policyConstraints, 469 policyMappings, 470 privateKeyUsagePeriod, 470 structure of, 460 subjectAltName, 471 subjectDirectoryAttributes, 471 tool for joining, 241 tools for generating, 241
X.509 certificate, summarized, 463
X.509 CRL, summarized, 474 external tokens defined, 265 installing, 267 extKeyUsage, 466
F failover, 451 failover and load balancing, 452 failover architecture, 451 file-based publisher, 364
FIPS PUBS 140-1, 22 flush interval for logs, 81
G groups changing members, 399
H hardware accelerators, 269 hardware tokens
See external tokens, 265, 265 high availability, 451 holdInstructionCode, 480 host name for mail server used for notifications, 67 how to revoke certificates, 324 how to search for keys, 175
I installation, 23 installing certificates, 254 installing external hardware tokens, 267 internal database default hostname, 104 precaution for changing the hostname, 104 defined, 103 how to distinguish from other Directory Server instances, 106 name format, 106 schema, 104 what is it used for, 103 when installed, 104 internal tokens, 265 invalidityDate, 481 issuerAltName, 467, 477 issuing certificates to servers, 231 issuingDistributionPoint, 479
J job modules registering new ones, 448 jobs built-in modules unpublishExpiredCerts, 440 compared to plug-in implementation, 439 configuring job notification messages, 436, 439 setting frequency, 440 specifying schedule for, 447 turning on scheduler, 440
K key archival, 175 how it works, 175 how keys are stored, 175 how to set up, 178
PKI setup required, 173 reasons to archive, 175
528
where keys are stored, 175 key length, 113 key recovery, 177 designated agents
See key recovery agents, 177 how to set up, 179 key recovery agents passwords, 177 significance, 177 responsibilities, 177 role defined, 177
KEYGEN tag, 22 keys defined, 486 management and recovery, 504 keyUsage, 467
L
LDAP, 22
LDAP publishing defined, 338 manual updates, 362 when to do, 362 who can do this, 362 linked CA, 8 load balancing, 452 location of active log files, 76 log modules deleting, 87 registering new ones, 87 logging buffered vs. unbuffered, 81 log files archiving rotated files, 82 default location, 76 signing rotated files, 86 timing of rotation, 81 log levels, 80, 80 default selection, 81 how they relate to message categories, 80 significance of choosing the right level, 81 what it means, 80 managing from Certificate System console, 85 services that are logged, 79 types of logs, 76
Audit, 76
Error, 78
M mail server used for notifications, 67 managing certificate database, 254 mapper modules deleting, 363 registering new ones, 363 mappers created during installation, 346, 367, 369 mappers that use
CA certificate, 367
DN components, 370 master CA, 14 modifying privileged user's group membership, 399
N
Name extension modules
Issuer Alternative Name, 300 nameConstraints, 469 naming convention for internal database instances, 106 netscape-cert-type, 482 nickname for CA signing certificate, 111 for OCSP signing certificate, 112 for signing certificate, 159 for SSL server certificate, 112, 159 for wTLS signing certificate, 112 notifications configuring the mail server hostname, 67 port, 67 to agents about unpublishing certificates, 440
O
OCSP, 12
OCSP publisher, 366
OCSP responder, 157 defined, 12
OCSP server, 157
OCSP signing certificate, 112, 226 nickname, 112 requesting, 233
Online Certificate Status Manager administrators creating, 161, 394 agents creating, 161, 394 introduced, 12 key pairs and certificates signing certificate, 159
SSL server certificate, 159
529
Index online certificate validation authority defined, 12
P password using for authentication, 490 password-based authentication, defined, 491,
491 password-quality checker, 66
PIN Generator tool delivering PINs to users, 382
PKCS #10, 22
PKCS #11, 22
PKCS #11 support, 265
PKCS #7, 22
PKIX , 21 plug-in modules for CRL extensions
CRLReason, 298 for publishing
FileBasedPublisher, 364
LdapCaCertPublisher, 365, 366
LdapCaSimpleMap, 367
LdapCrlPublisher, 365
LdapDNCompsMap, 370
LdapUserCertPublisher, 365
OCSPPublisher, 366 for scheduling jobs unpublishExpiredCerts, 440
Issuer Alternative Name, 300 policyConstraints, 469 policyMappings, 470 port separation, 96 ports, 94 changing, 96 for agent operations, 95 for end-entity operations, 95 for the mail server used for notifications, 67 how to choose numbers, 94 port separation, 96 private key, defined, 487 privateKeyUsagePeriod, 470 privileged users deleting, 400 modifying privileges group membership, 399 types agents, 392 public key cryptography, 485 defined, 487 infrastructure, 503 management, 504 publisher modules deleting, 363 registering new ones, 363 publishers created during installation, 345, 365, 365, 366 publishers that can publish to
CA's entry in the directory, 365, 365, 366 files, 364
OCSP responder, 366 users' entries in the directory, 365 publishing of certificates to files, 338 of CRLs, 323 to files, 338 to LDAP directory, 325, 338 to online validation authority, 157 viewing content, 359 publishing directory defined, 338
R reasons for revoking certificates, 324 recovering users' private keys, 177 registering authentication modules, 389 custom OIDs, 463 job modules, 448 log modules, 87 mapper modules, 363 publisher modules, 363 requesting certificates agent certificate, 231
CA signing certificate, 233
CRL signing certificate, 233
DRM transport certificate, 233
OCSP signing certificate, 233
SSL client certificate, 233
SSL server certificate, 233 through the Console, 233 through the end-entities page, 231 user certificate, 231 using certutil, 244 restarting subsystem instance, 66 restore, 107 restoring the Certificate System, 107 revocation-status checking for agent certificates,
126
530
revoking certificates reasons, 324 who can revoke certificates, 324 roles agent, 392 key recovery agents, 177 root CA, 7 root versus subordinate CA, 25, 114 rotating log files archiving files, 82 how to set the time, 81 signing files, 86
RSA, 113
S
S/MIME certificate, 494 self-signed certificate, 499
SELinux, 22 servlet
XML parameter, 75 setting CRL extensions, 333 setting up key archival, 178 key recovery, 179 signing rotated log files, 86 signing certificate, 159
CA, 113 changing trust settings of, 261 deleting, 260 getting a new one, 229 nickname, 159 viewing details of, 258 signing key, for CA, 113 single sign-on, 495
SMTP settings, 67
SSL, 22 client certificates, 494
SSL client certificate, 227 requesting, 233
SSL server certificate, 112, 159, 227 changing trust settings of, 261 deleting, 260 getting a new one, 229 nickname, 112, 159 requesting, 233 viewing details of, 258 starting subsystem instance, 66
Status tab, 62 stopping subsystem instance, 66 storage key pair, 174 storing user's certificates, 252 subjectAltName, 471 subjectDirectoryAttributes, 471 subjectKeyIdentifier subjectKeyIdentifier, 471 subordinate CA, 7
T
TCP/IP, defined, 485 templates for notifications, 436 timing log rotation, 81
Token Key Service, 15, 217 administrators creating, 220, 394 agents creating, 220, 394
Token Processing System and, 15
Token Key Service (TKS), 217
Token Management System
Enterprise Security Client, 223
TKS, 217
Token Processing System, 15
Token Key Service and, 15 tokens changing password of, 268 defined, 265 external, 265 internal, 265 managing, 268 viewing which tokens are installed, 268 topology decisions, for deployment, 15, 15 transport certificate, 174 changing trust settings of, 261 deleting, 260 getting a new one, 229 viewing details of, 258 when used, 176 trusted CA, defined, 498 trusted managers certificate for SSL client authentication, 394 deleting, 400 modifying group membership, 399
U unbuffered logging, 81 user certificate, 227 requesting, 231
531
Index users creating, 124, 161, 181, 220, 394 storing certificates, 252
W why to revoke certificates, 324 wTLS CA signing certificate, 112 nickname, 112
X
X.509 certificates, 22
532
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Installation and Configuration of Certificate System
Management of Certificate System subsystems
User Management (adding/removing)
Requesting and Revoking Certificates
Publishing Certificate Revocation Lists (CRLs)
Smart Card Management
Frequently asked questions
The Certificate System provides a secure infrastructure for authentication, encryption, and digital signatures.
This guide is intended for Certificate System administrators.
This guide covers installing, configuring, and managing Certificate System subsystems, as well as management tasks such as adding users, requesting and revoking certificates, publishing CRLs, and managing smart cards.
