Chapter 9. Using Certificate System
Chapter 9. Using Certificate System
Using any Certificate System has basic tasks such as editing the configuration file, starting and stopping the server instance and Console, opening web services, and locating logs. This is explained in more detail in the Certificate System Administrator's Guide.
9.1. Starting the Certificate System Console
The CA, DRM, OCSP, and TKS subsystems have a Java interface which can be accessed to perform administrative functions. For the DRM, OCSP, and TKS, this includes very basic tasks like configuring logging and managing users and groups. For the CA, this includes other configuration settings such as creating certificate profiles and configuring publishing.
The Console is opened by connecting to the subsystem instance over its SSL port using the
pkiconsole command. This command has the format: pkiconsole https://server.example.com:admin_port/subsystem_type
The subsystem_type can be ca, kra, ocsp, or tks. For example, this opens the DRM console: pkiconsole https://server.example.com:10445/kra
If DNS is properly configured, then an IPv4 or IPv6 address can be used to connect to the console. For example: https://1.2.3.4:9445/ca https://[00:00:00:00:123:456:789:00:]:9445/ca
9.2. Starting, Stopping, and Restarting an Instance
The Certificate System subsystem instances can be stopped and started using system tools on Red
Hat Enterprise Linux. For example: service instance-name {start|stop|restart}
The instance name for default subsystem instances is usually pki-instance-id, such as pki-ca.
9.3. Starting the Subsystem Automatically
Red Hat Enterprise Linux 5.3 has a tool called chkconfig which manages the automatic startup and shutdown settings for each process on the server. This means that when a system reboots, some services can be automatically restarted. chkconfig also defines startup settings for different run levels of the server. chkconfig is explained more in the Red Hat Enterprise Linux documentation, such as the Deployment Guide .
Certificate System subsystems can be managed by chkconfig, so this tool can set whether to restart subsystems automatically. By default, every Certificate System subsystem instance is turned off at every run level in the system, meaning instances must be started and stopped manually. This can be changed by resetting the configuration in chkconfig to on. For example, this automatically restarts Red Hat
Directory Server, Administration Server, and the CA:
103
Red Hat Certificate System 8.0 Install Guide
/sbin/chkconfig --level 2345 dirsrv-admin on
/sbin/chkconfig --level 2345 dirsrv on
/sbin/chkconfig --level 2345 pki-ca on
Make sure the subsystem is listed with the other services.
chkconfig --list | grep subsystem_name
To remove the subsystem from the start list, simply turn the level to off: chkconfig --level 35 subsystem_name off
Red Hat Enterprise Linux also has a GUI console that can manage chkconfig settings.
Figure 9.1. chkconfig Settings
The start order of services is extremely important, or the subsystems will not function. The Directory
Server and Administration Server instances used by the subsystems must be running before the subsystems can be started, and their web services (Tomcat or Apache) must be running before the subsystems are started or their web services will not function.
The default Certificate System chkconfig settings set a start and stop priority for all of the subsystems and their dependent services so that they start and stop in the proper order, as listed in
Table 9.1, “Certificate System Processes and Their chkconfig Start Priority”
. Processes with a low number for their start priority are started first, so Directory Server, Administration Server, and Tomcat are started before any of the subsystem instances. Likewise, processes with a low number for their shutdown priority are shut down first, so the subsystem processes are stopped before the processes they depend on are stopped.
104
Chapter 9. Using Certificate System
Table 9.1. Certificate System Processes and Their chkconfig Start Priority
Server
Administration Server
Directory Server
Tomcat Server
CA
DRM
OCSP
TKS
Apache
RA
TPS
Process Name dirsrv-admin dirsrv tomcat5 pki-ca pki-kra pki-ocsp pki-tks httpd
86 pki-tps
Start Priority
84
85
14
87
21
21
80
81
82
83
Shutdown Priority
16
15
13
79
79
20
19
18
17
9.4. Finding the Subsystem Web Services Pages
The CA, RA, DRM, OCSP, TKS, and TPS subsystems have web services pages for agents, as well as potentially regular users and administrators. These web services can be accessed by opening the URL to the subsystem host over the subsystem's secure end user's port. For example, for the CA: https://server.example.com:9444/ca/services
TIP
To get a complete list of all of the interfaces, URLs, and ports for a subsystem, check the service's status: service instance-name status
The main web services page for each subsystem has a list of available services pages; these are
summarized in Table 9.2, “Default Web Services Pages”
. To access any service specifically, access the appropriate port and append the appropriate directory to the URL. For example, to access the CA's end entities (regular users) web services: https://server.example.com:9444/ca/ee/ca/
If DNS is properly configured, then an IPv4 or IPv6 address can be used to connect to the services pages. For example: https://1.2.3.4:9444/ca/services https://[00:00:00:00:123:456:789:00:]:9444/ca/services
105
Red Hat Certificate System 8.0 Install Guide
NOTE
Anyone can access the end user pages for a subsystem, but accessing agent or admin web services pages requires that an agent or administrator certificate be issued and installed in the web browser, or authentication to the web services fails.
106
12890
12890
Data Recovery
Manager
10180
10444
10443
10445
Yes
Yes
No
Yes
Yes
Yes
Chapter 9. Using Certificate System
Table 9.2. Default Web Services Pages
Port Used for SSL Used for Client
Authentication [a
]
Web Services
Certificate
Manager
9180
9444
9443
9445
No
Yes
Yes
Yes
No
Yes
End Entities
End Entities
Agents
Configuration
9445
9445
Registration
Manager
12888
12889
12889
12890
10445
10445
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Online
Certificate
Status Manager
11180
11444
11443
11445
No
Yes
Yes
Yes
No
No
Yes
Yes
No
Yes
No
No
No
Yes
Services
Console
End Entities
Agents
Admin
Configuration
End Entities
Services
End Entities
[b ]
End Entities
[b ]
Agents
Configuration
Services
Console
End Entities
[c]
End Entities
[c]
Agents
Configuration
Web Service
Location ca/ee/ca/ ca/ee/ca ca/agent/ca ca/admin/console/ config/login?
pin=pin ca/services pkiconsole https://host:port/ca ee/index.cgi
agent/index.cgi
admin/index.cgi
ra/admin/console/ config/login?
pin=pin ee/index.cgi
index.cgi
kra/ee/kra/ kra/ee/kra kra/agent/kra kra/admin/console
/config/login?
pin=pin kra/services pkiconsole https://host:port/kr a ocsp/ee/ocsp ocsp/ee/ocsp ocsp/agent/ocsp ocsp/admin/conso le/config/login?
107
7889
7889
7889
7890
7890
108
11445
11445
Token Key
Service
13180
13444
13443
13445
13445
13445
Token
Processing
System
7888
7890
7888
Red Hat Certificate System 8.0 Install Guide
No
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
No
No
No
No
Yes
No
No
7890
7889
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Services
Console
End Entities
[b ]
End Entities
[b ]
Agents
Configuration
Services
Console pin=pin ocsp/services pkiconsole https://host:port/oc sp tks/ee/tks tks/ee/tks tks/agent/tks tks/admin/console
/config/login?
pin=pin tks/services pkiconsole https://host:port/tk s
Enterprise
Security Client
Phone Home
Enterprise
Security Client
Phone Home
Enterprise
Security Client
Security Officer
Enrollment
Enterprise
Security Client
Security Officer
Enrollment
Enterprise
Security Client
Security Officer
Workstation
Agents
[d ]
Admin [d ]
Operator [d ]
Configuration
Services cgibin/home/index.cgi
cgibin/home/index.cgi
cgibin/so/enroll.cgi
cgibin/so/enroll.cgi
cgibin/sow/welcome.c
gi tus tus?
op=index_admin tus?
r op=index_operato tps/admin/console
/config/login?
pin=pin index.cgi
Chapter 9. Using Certificate System
9445 Yes No Console pkiconsole https://host:port/ca
[a]
Services with a client authenticatio n value o f No can b e reco nfig ured to req uire client authenticatio n. Services which d o no t have either a Yes o r No value canno t b e co nfig ured to use client authenticatio n.
[b ]
Altho ug h this sub system typ e d o es have end entities p o rts and interfaces, these end -entity services are no t accessib le thro ug h a web b ro wser, as o ther end -entity services are.
[c]
Altho ug h the O CSP d o es have end entities p o rts and interfaces, these end -entity services are no t accessib le thro ug h a web b ro wser, as o ther end -entity services are. End user O CSP services are accessed b y a client send ing an O CSP req uest.
[d ]
The ag ent, ad min, and o p erato r services are all accessed thro ug h the same web services p ag e. Each ro le has a d ifferent tab o n that p ag e. The ro le-sp ecific tab is visib le to every user who is a memb er o f that ro le.
9.5. Default File and Directory Locations for Certificate System
Certificate System servers consist of subsystems and instances.
Server subsystems are servers for a specific type of PKI function and are installed by the Certificate
System RPMs. This general subsystem information is contained in non-relocatable, RPM-defined shared libraries, Java archive files, binaries, and templates. These are stored in a fixed location.
NOTE
There is an environment variable, DONT_RUN_PKICREATE, which stops the pkicreate script from running automatically after the subsystems are installed. This allows the default instances to be installed in user-defined installation directories, instead of the default locations in var/lib.
To use custom directory locations, install the subsystems through the ISO image with this environment variable set to block the pkicreate script.
Server instances are somewhat relocatable and have user-specific default and customized forms and data.
When the Certificate System is first installed, one instance for each subsystem type is also installed.
The default information such as the port numbers, instance name, and configuration file location for each subsystem (after being installed and going through the setup process) is listed in the following sections.
9.5.1. Default CA Instance Information
The default CA configuration is listed in Table 9.3, “Default CA Instance Information”
. Most of these values are unique to the default instance; the default certificates and some other settings are true for every CA instance.
109
Red Hat Certificate System 8.0 Install Guide
Table 9.3. Default CA Instance Information
Setting
Standard Port
Agents Port
End Users Port
End-Entites Client Authentication Port
Admin Port
Tomcat Port
Instance Name
Main Directory
Configuration Directory
Configuration File
Value
9180
9443
9444
9446
9445
9701 pki-ca
/var/lib/pki-ca
/etc/pki-ca
/etc/pki-ca/CS.cfg
/etc/pki-ca/password.conf
Subsystem Certificates
CA signing certificate
OCSP signing certificate (for the CA's internal
OCSP service)
SSL server certificate
Audit log signing certificate
Security Databases
Log Files
Install Logs
Process File
Profile Files
Email Notification Templates
Web Services Files
Subsystem certificate [a]
/var/lib/pki-ca/alias
/var/log/pki-ca
/var/log/pki-ca-install.log
/var/run/pki-ca.pid
/var/lib/pki-ca/profiles/ca
/var/lib/pki-ca/emails
/var/lib/pki-ca/webapps - Agent services
/var/lib/pki-ca/webapps.admin - Admin services
/var/lib/pki-ca/webapps.ee - End user services
[a]
The sub system certificate is always issued b y the security d o main so that d o main-level o p eratio ns that req uire client authenticatio n are b ased o n this sub system certificate.
9.5.2. Default RA Instance Information
The default RA configuration is listed in Table 9.4, “Default RA Instance Information”
. Most of these values are unique to the default instance; the default certificates and some other settings are true for every RA instance.
110
Chapter 9. Using Certificate System
Table 9.4 . Default RA Instance Information
Setting
Standard Port (for End Users)
SSL Port (for Agents and Administrators)
SSL Port (for End Users)
Instance Name
Main Directory
Configuration Directory
Configuration File
Value
12888
12889
12890 pki-ra
/var/lib/pki-ra
/etc/pki-ra
/etc/pki-ra/CS.cfg
/etc/pki-ra/nss.conf
/etc/pki-ra/password.conf
Subsystem Certificates
SSL server certificate
Security Databases
Log Files
Install Logs
Web Services Files
Subsystem certificate [a]
/var/lib/pki-ra/alias
/var/log/pki-ra
/var/log/pki-ra-install.log
/var/lib/pki-ra/docroot
/var/lib/pki-ra/lib
[a]
The sub system certificate is always issued b y the security d o main so that d o main-level o p eratio ns that req uire client authenticatio n are b ased o n this sub system certificate.
9.5.3. Default DRM Instance Information
The default DRM configuration is listed in Table 9.5, “Default KRA Instance Information”
. Most of these values are unique to the default instance; the default certificates and some other settings are true for every DRM instance.
111
Red Hat Certificate System 8.0 Install Guide
Table 9.5. Default KRA Instance Information
Setting
Standard Port
End Users Secure Port
Agents Port
Admin Port
Tomcat Port
Instance Name
Main Directory
Configuration Directory
Configuration File
Value
10180
10444
10443
10445
10701 pki-kra
/var/lib/pki-kra
/etc/pki-kra
/etc/pki-kra/CS.cfg
/etc/pki-kra/password.conf
Subsystem Certificates
Transport certificate
Storage certificate
SSL server certificate
Audit log signing certificate
Security Databases
Log Files
Install Logs
Process File
Web Services Files
Subsystem certificate [a]
/var/lib/pki-kra/alias
/var/log/pki-kra
/var/log/pki-kra-install.log
/var/run/pki-kra.pid
/var/lib/pki-kra/webapps - Agent services
/var/lib/pki-kra/webapps.admin - Admin services
[a]
The sub system certificate is always issued b y the security d o main so that d o main-level o p eratio ns that req uire client authenticatio n are b ased o n this sub system certificate.
9.5.4. Default OCSP Instance Information
The default OCSP configuration is listed in Table 9.6, “Default OCSP Instance Information”
. Most of these values are unique to the default instance; the default certificates and some other settings are true for every OCSP instance.
112
Chapter 9. Using Certificate System
Table 9.6. Default OCSP Instance Information
Setting
Standard Port
End Users Secure Port
Agents Port
Admin Port
Tomcat Port
Instance Name
Main Directory
Configuration Directory
Configuration File
Value
11180
11444
11443
11445
11701 pki-ocsp
/var/lib/pki-ocsp
/etc/pki-ocsp
/etc/pki-ocsp/CS.cfg
/etc/pki-ocsp/password.conf
Subsystem Certificates
OCSP signing certificate
SSL server certificate
Audit log signing certificate
Security Databases
Log Files
Install Logs
Process File
Web Services Files
Subsystem certificate [a]
/var/lib/pki-ocsp/alias
/var/log/pki-ocsp
/var/log/pki-ocsp-install.log
/var/run/pki-ocspocsp.pid
/var/lib/pki-ocsp/webapps - Agent services
/var/lib/pki-ocsp/webapps.admin - Admin services
[a]
The sub system certificate is always issued b y the security d o main so that d o main-level o p eratio ns that req uire client authenticatio n are b ased o n this sub system certificate.
9.5.5. Default TKS Instance Information
The default TKS configuration is listed in Table 9.7, “Default TKS Instance Information”
. Most of these values are unique to the default instance; the default certificates and some other settings are true for every TKS instance.
113
Red Hat Certificate System 8.0 Install Guide
Table 9.7. Default TKS Instance Information
Setting
Standard Port
End Users Secure Port
Agents Port
Admin Port
Tomcat Port
Instance Name
Main Directory
Configuration Directory
Configuration File
Value
13180
13444
13443
13445
13701 pki-tks
/var/lib/pki-tks
/etc/pki-tks
/etc/pki-tks/CS.cfg
/etc/pki-tks/password.conf
Subsystem Certificates
SSL server certificate
Audit log signing certificate
Subsystem certificate [a]
Security Databases
Log Files
/var/lib/pki-tks/alias
/var/log/pki-tks
Install Logs /var/log/pki-tks-install.log
Process File /var/run/pki-tks.pid
[a]
The sub system certificate is always issued b y the security d o main so that d o main-level o p eratio ns that req uire client authenticatio n are b ased o n this sub system certificate.
9.5.6. Default TPS Instance Information
The default TPS configuration is listed in Table 9.8, “Default TPS Instance Information”
. Most of these values are unique to the default instance; the default certificates and some other settings are true for every TPS instance.
114
Chapter 9. Using Certificate System
Table 9.8. Default TPS Instance Information
Setting
Standard Port (for End Users)
SSL Port (for Agents and Administrators)
SSL Port (for End Users)
Instance Name
Main Directory
Configuration Directory
Configuration File
Subsystem Certificates
Security Databases
Log Files
Install Logs
Web Services Files
Value
7888
7889
7890 pki-tps
/var/lib/pki-tps
/etc/pki-tps
/etc/pki-tps/CS.cfg
/etc/pki-tps/nss.conf
/etc/pki-tps/password.conf
SSL server certificate
Subsystem certificate
/var/lib/pki-tps/alias
/var/log/pki-tps
/var/log/pki-tps-install.log
/var/lib/pki-tps/docroot
/var/lib/pki-tps/cgi-bin
/var/lib/pki-tps/lib
9.5.7. Shared Certificate System Subsystem File Locations
There are some directories used by or common to all Certificate System subsystem instances for
general server operations, listed in Table 9.9, “Subsystem File Locations”
.
115
Red Hat Certificate System 8.0 Install Guide
Table 9.9. Subsystem File Locations
Directory Location
/var/lib/instance_name
/usr/share/java/pki
/usr/share/pki
/usr/bin
/var/lib/tomcat5/common/lib
/var/lib/tomcat5/server/lib
/usr/lib/httpd/modules
/usr/lib64/httpd/modules
116
Contents
Contains the main instance directory, which is the location for user-specific default and customized configuration files, profiles, certificate databases, web files, and other files for the subsystem instance.
Contains Java archive files shared by the
Certificate System subsystems. Along with shared files for all subsystems, there are subsystem-specific files in subfolders: pki/ca/ (CA) pki/kra/ (DRM) pki/ocsp/ (OCSP) pki/tks/ (TKS)
Not used by the RA or TPS subsystems.
Contains common files and templates used to create Certificate System instances. Along with shared files for all subsystems, there are subsystem-specific files in subfolders: pki/ca/ (CA) pki/kra/ (DRM) pki/ocsp/ (OCSP) pki/ra/ (RA) pki/tks/ (TKS) pki/tps (TPS)
Contains the pkicreate and pkiremove instance configuration scripts and tools (Java, native, and security) shared by the Certificate
System subsystems.
Contains Java archive files shared by local
Tomcat web applications and shared by the
Certificate System subsystems. Not used by the
TPS or RA subsystems.
Contains Java archive files used by the local
Tomcat web server and shared by the Certificate
System subsystems. Not used by the TPS or RA subsystems.
Contains Apache modules shared by TPS and
RA subsystems. Not used by the CA, DRM,
OCSP, or TKS subsystems.
