Planning, Installation, and Deployment Guide (Common Criteria Edition)
Updated for Red Hat Certificate System 9.4 Common Criteria Certification
Edition 9.4-1
Red Hat
Abstract
Part I. Introduction to Red Hat Certificate System and Deployment Planning
Chapter 1. About This Guidance Document
Note
pkispawn
Utility”. Afterwards, follow the required post-installation steps in Section 7.4, “Post-installation Tasks” to ensure the complete installation is compliant. This last section links you to relevant parts of the guide which explains the steps to perform for full compliance.
Important
pkispawn
phase (discussed in Section 7.3, “Installing Using the pkispawn
Utility”), it is suggested to check your configuration carefully for mistakes and refer to the error logs. Prior to re-running the pkispawn
utility to retry the installation, it is necessary to fully remove the old instance. Refer to Chapter 16, Removing a Subsystem for information about removing subsystems.
Chapter 2. Introduction to Red Hat Certificate System
Note
2.1. A Review of Certificate System Subsystems
- A certificate authority called Certificate Manager. The CA is the core of the PKI; it issues and revokes all certificates. The Certificate Manager is also the core of the Certificate System. By establishing a security domain of trusted subsystems, it establishes and manages relationships between the other subsystems.
- A key recovery authority (KRA). Certificates are created based on a specific and unique key pair. If a private key is ever lost, then the data which that key was used to access (such as encrypted emails) is also lost because it is inaccessible. The KRA stores key pairs, so that a new, identical certificate can be generated based on recovered keys, and all of the encrypted data can be accessed even after a private key is lost or damaged.
Note
In previous versions of Certificate System, KRA was also referred to as the data recovery manager (DRM). Some code, configuration file entries, web panels, and other resources might still use the term DRM instead of KRA. - An online certificate status protocol (OCSP) responder. The OCSP verifies whether a certificate is valid and not expired. This function can also be done by the CA, which has an internal OCSP service, but using an external OCSP responder lowers the load of the issuing CA.
- A token key service (TKS). The TKS derives keys based on the token CCID, private information, and a defined algorithm. These derived keys are used by the TPS to format tokens and enroll certificates on the token.
- A token processing system (TPS). The TPS interacts directly with external tokens, like smart cards, and manages the keys and certificates on those tokens through a local client, the Enterprise Security Client (ESC). The ESC contacts the TPS when there is a token operation, and the TPS interacts with the CA, KRA, or TKS, as required, then send the information back to the token by way of the Enterprise Security Client.
- A token management system or TMS environment, which manages smart cards. This requires a CA, TKS, and TPS, with an optional KRA for server-side key generation.
- A traditional non token management system or non-TMS environment, which manages certificates used in an environment other than smart cards, usually in software databases. At a minimum, a non-TMS requires only a CA, but a non-TMS environment can use OCSP responders and KRA instances as well.
2.2. Overview of Certificate System Subsystems
2.2.1. Separate versus Shared Instances
- Separate PKI instances run as a single Java-based Apache Tomcat instance.
- Separate PKI instances contain a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS).
- Separate PKI instances must utilize unique ports if co-located on the same physical machine or virtual machine (VM).
- Shared PKI instances also run as a single Java-based Apache Tomcat instance.
- Shared PKI instances that contain a single PKI subsystem are identical to a separate PKI instance.
- Shared PKI instances may contain any combination of up to one of each type of PKI subsystem:
- CA only
- TKS only
- CA and KRA
- CA and OCSP
- TKS and TPS
- CA, KRA, TKS, and TPS
- CA, KRA, OCSP, TKS, and TPS
- etc.
- Shared PKI instances allow all of their subsystems contained within that instance to share the same ports.
- Shared PKI instances must utilize unique ports if more than one is co-located on the same physical machine or VM.
2.2.2. Instance Installation Prerequisites
2.2.2.1. Directory Server Instance Availability
2.2.2.2. PKI Packages
- The following base packages form the core of Certificate System, and are available in base Red Hat Enterprise Linux repositories:
- pki-core.el7
- pki-base
- pki-base-java
- pki-ca
- pki-javadoc
- pki-kra
- pki-server
- pki-symkey
- pki-tools
- The packages listed below are not available in the base Red Hat Enterprise Linux subscription channel. To install these packages, you must first use Subscription Manager to attach the Red Hat Certificate System subscription pool, and enable the RHCS9 repository. See the Subscription Manager chapter of the Red Hat Enterprise Linux 7 System Administrator's Guide for instructions.
- pki-console.el7pki
- pki-console
- pki-core.el7pki
- pki-ocsp
- pki-tks
- pki-tps
- redhat-pki.el7pki
- redhat-pki
- redhat-pki-theme.el7pki
- redhat-pki-console-theme
- redhat-pki-server-theme
#
yum install redhat-pki
Note
2.2.2.3. Instance Installation and Configuration
pkispawn
command line tool is used to install and configure a new PKI instance. It eliminates the need for separate installation and configuration steps, and should be run as a batch process. The utility does not provide a way to install or configure the browser-based graphical interface.
pkispawn --help
command.
pkispawn
command:
- Reads in its default
name=value
pairs from a plain text configuration file (/etc/pki/default.cfg
). - Automatically overrides any pairs as specified and stores the final result as a Python dictionary.
- Executes an ordered series of scriptlets to perform subsystem and instance installation.
- The configuration scriptlet packages the Python dictionary as a JavaScript Object Notation (JSON) data object, which is then passed to the Java-based configuration servlet.
- The configuration servlet utilizes this data to configure a new PKI subsystem, and then passes control back to the
pkispawn
executable, which finalizes the PKI setup. A copy of the final deployment file is stored in/var/lib/pki/instance_name/<subsystem>/registry/<subsystem>/deployment.cfg
pkispawn
man page for additional information.
/etc/pki/default.cfg
, is a plain text file containing the default installation and configuration values which are read at the beginning of the process described above. It consists of name=value
pairs divided into [DEFAULT]
, [Tomcat]
, [CA]
, [KRA]
, [OCSP]
, [TKS]
, and [TPS]
sections.
-s
option with pkispawn
and specify a subsystem name, then only the section for that subsystem will be read.
name=value
pair specified in a subsystem section will override the pair in the [Tomcat]
section, which in turn override the pair in the [DEFAULT]
section. Default pairs can further be overridden by pairs in a specified PKI instance configuration file.
Note
pkispawn
configuration files are used to override default name=value
pairs, they may be stored in any location and specified at any time. These files are referred to as myconfig.txt
in the pkispawn
man pages, but they are also often referred to as .ini
files, or more generally as PKI instance configuration override files.
pki_default.cfg
man page for more information.
/usr/share/java/pki/pki-certsrv.jar
as com/netscape/certsrv/system/ConfigurationRequest.class
. The servlet processes data passed in as a JSON object from the configuration scriptlet using pkispawn
, and then returns to pkispawn
using Java bytecode served in the same file as com/netscape/certsrv/system/ConfigurationResponse.class
.
pkispawn
command on a command line as root
:
#
pkispawn
Important
#
mkdir -p /root/pki
- Use a text editor such as vim to create a configuration file named
/root/pki/ca.cfg
with the following contents:[DEFAULT] pki_admin_password=<password> pki_client_pkcs12_password=<password> pki_ds_password=<password>
#
pkispawn -s CA -f /root/pki/ca.cfg
pkispawn
man page for various configuration examples.
2.2.2.4. Instance Removal
pkidestroy
command. It can be run interactively or as a batch process. Use pkidestroy -h
to display detailed usage inforamtion on the command line.
pkidestroy
command reads in a PKI subsystem deployment configuration file which was stored when the subsystem was created (/var/lib/pki/instance_name/<subsystem>/registry/<subsystem>/deployment.cfg
), uses the read-in file in order to remove the PKI subsystem, and then removes the PKI instance if it contains no additional subsystems. See the pkidestroy
man page for more information.
pkidestroy
may look similar to the following:
#
pkidestroy
Subsystem (CA/KRA/OCSP/TKS/TPS) [CA]: Instance [pki-tomcat]: Begin uninstallation (Yes/No/Quit)? Yes Log file: /var/log/pki/pki-ca-destroy.20150928183547.log Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg. Uninstalling CA from /var/lib/pki/pki-tomcat. rm '/etc/systemd/system/multi-user.target.wants/pki-tomcatd.target' Uninstallation complete.
#
pkidestroy -s CA -i pki-tomcat
Log file: /var/log/pki/pki-ca-destroy.20150928183159.log Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg. Uninstalling CA from /var/lib/pki/pki-tomcat. rm '/etc/systemd/system/multi-user.target.wants/pki-tomcatd.target' Uninstallation complete.
2.2.3. Execution Management (systemctl)
2.2.3.1. Starting, Stopping, Restarting, and Obtaining Status
systemctl
execution management system tool on Red Hat Enterprise Linux 7:
#
systemctl start <unit-file>@instance_name.service
#
systemctl status <unit-file>@instance_name.service
#
systemctl stop <unit-file>@instance_name.service
#
systemctl restart <unit-file>@instance_name.service
pki-tomcatd
Withwatchdog
disabledpki-tomcatd-nuxwdog
Withwatchdog
enabled
watchdog
service, refer Section 2.3.11, “Passwords and Watchdog (nuxwdog)” and Section 9.3.2, “Using the Certificate System Watchdog Service”.
2.2.3.2. Starting the Instance Automatically
systemctl
utility in Red Hat Enterprise Linux 7 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. System unit files control service startup to ensure that services are started in the correct order. The systemd
service and systemctl
utility are described in the Red Hat Enterprise Linux System Administrator's Guide
systemctl
, so this utility can set whether to restart instances automatically. After a Certificate System instance is created, it is enabled on boot. This can be changed by using systemctl
:
#
systemctl disable pki-tomcatd@instance_name.service
#
systemctl enable pki-tomcatd@instance_name.service
Note
systemctl enable
and systemctl disable
commands do not immediately start or stop Certificate System.
2.2.4. Process Management (pki-server and pkidaemon)
2.2.4.1. The pki-server Command Line Tool
pki-server
. Use the pki-server --help
command and see the pki-server
man page for usage information.
pki-server
command-line interface (CLI) manages local server instances (for example server configuration or system certificates). Invoke the CLI as follows:
$
pki-server [CLI options] <command> [command parameters]
$
pki-server
$
pki-server ca
$
pki-server ca-audit
--help
option:
$
pki-server
--help
$
pki-server ca-audit-event-find
--help
2.2.4.2. Enabling and Disabling an Installed Subsystem Using pki-server
pki-server
utility.
#
pki-server subsystem-disable -i instance_id subsystem_id
#
pki-server subsystem-enable -i instance_id subsystem_id
ca
, kra
, tks
, ocsp
, or tps
.
Note
pki-tomcat
:
#
pki-server subsystem-disable -i pki-tomcat ocsp
#
pki-server subsystem-find -i instance_id
#
pki-server subsystem-find -i instance_id subsystem_id
2.2.4.3. The pkidaemon Command Line Tool
pkidaemon
tool:
pkidaemon {start|status} instance-type [instance_name]
pkidaemon status tomcat
- Provides status information such as on/off, ports, URLs of each PKI subsystem of all PKI instances on the system.pkidaemon status tomcat instance_name
- Provides status information such as on/off, ports, URLs of each PKI subsystem of a specific instance.pkidaemon start tomcat instance_name.service
- Used internally usingsystemctl
.
pkidaemon
man page for additional information.
2.2.4.4. Finding the Subsystem Web Services URLs
https://server.example.com:8443/ca/services
Note
pkidaemon status instance_name
https://server.example.com:8443/ca/ee/ca
https://192.0.2.1:8443/ca/services https://[2001:DB8::1111]:8443/ca/services
Note
Table 2.1. Default Web Services Pages
Port | Used for TLS | Used for Client Authentication[a] | Web Services | Web Service Location |
---|---|---|---|---|
Certificate Manager | ||||
8080 | No | End Entities | ca/ee/ca | |
8443 | Yes | No | End Entities | ca/ee/ca |
8443 | Yes | Yes | Agents | ca/agent/ca |
8443 | Yes | No | Services | ca/services |
8443 | Yes | No | Console | pkiconsole https://host:port/ca |
Key Recovery Authority | ||||
8080 | No | End Entities[b] | kra/ee/kra | |
8443 | Yes | No | End Entities[b] | kra/ee/kra |
8443 | Yes | Yes | Agents | kra/agent/kra |
8443 | Yes | No | Services | kra/services |
8443 | Yes | No | Console | pkiconsole https://host:port/kra |
Online Certificate Status Manager | ||||
8080 | No | End Entities[c] | ocsp/ee/ocsp | |
8443 | Yes | No | End Entities[c] | ocsp/ee/ocsp |
8443 | Yes | Yes | Agents | ocsp/agent/ocsp |
8443 | Yes | No | Services | ocsp/services |
8443 | Yes | No | Console | pkiconsole https://host:port/ocsp |
Token Key Service | ||||
8080 | No | End Entities[b] | tks/ee/tks | |
8443 | Yes | No | End Entities[b] | tks/ee/tks |
8443 | Yes | Yes | Agents | tks/agent/tks |
8443 | Yes | No | Services | tks/services |
8443 | Yes | No | Console | pkiconsole https://host:port/tks |
Token Processing System | ||||
8080 | No | Unsecure Services | tps/tps | |
8443 | Yes | Secure Services | tps/tps | |
8080 | No | Enterprise Security Client Phone Home | tps/phoneHome | |
8443 | Yes | Enterprise Security Client Phone Home | tps/phoneHome | |
8443 | Yes | Yes | Admin, Agent, and Operator Services [d] | tps/ui |
[a]
Services with a client authentication value of No can be reconfigured to require client authentication. Services which do not have either a Yes or No value cannot be configured to use client authentication.
[b]
Although this subsystem type does have end entities ports and interfaces, these end-entity services are not accessible through a web browser, as other end-entity services are.
[c]
Although the OCSP does have end entities ports and interfaces, these end-entity services are not accessible through a web browser, as other end-entity services are. End user OCSP services are accessed by a client sending an OCSP request.
[d]
The agent, admin, and operator services are all accessed through the same web services page. Each role can only access specific sections which are only visible to the members of that role.
|
2.2.4.5. Starting the Certificate System Console
pkiconsole
utility. This utility uses the format:
pkiconsole https://server.example.com:admin_port/subsystem_type
ca
, kra
, ocsp
, or tks
. For example, this opens the KRA console:
pkiconsole https://server.example.com:8443/kra
https://192.0.2.1:8443/ca https://[2001:DB8::1111]:8443/ca
2.3. Certificate System Architecture Overview
2.3.1. Java Application Server
server.xml
. The following link provides more information about Tomcat configuration: https://tomcat.apache.org/tomcat-8.0-doc/config/.
web.xml
file, which is defined in Java Servlet 3.1 specification. See https://www.jcp.org/en/jsr/detail?id=340 for details.
CS.cfg
.
2.3.2. Java Security Manager
pki_security_manager=false
option under its own Tomcat section.
# systemctl stop pki-tomcatd@instance_name.service
or# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
(if using thenuxwdog
watchdog)- Open the
/etc/sysconfig/instance_name
file, and setSECURITY_MANAGER="false"
# systemctl start pki-tomcatd@instance_name.service
or# systemctl start pki-tomcatd-nuxwdog@instance_name.service
(if using thenuxwdog
watchdog)
pkidaemon
from the following files:
/usr/share/pki/server/conf/catalina.policy /usr/share/tomcat/conf/catalina.policy /var/lib/pki/$PKI_INSTANCE_NAME/conf/pki.policy /var/lib/pki/$PKI_INSTANCE_NAME/conf/custom.policy
/var/lib/pki/instance_name/conf/catalina.policy
.
2.3.2.1. Running Subsystems under a Java Security Manager
2.3.2.1.1. About the Security Manager Policy Files
- The
catalina.policy
file from the default Tomcat policy located in the/usr/share/tomcat/conf
directory; this is updated whenever the general Tomcat files are updated. - A
pki.policy
file, in the/var/lib/pki/instance_name/conf
directory, that is supplied with the subsystem instance. - A
custom.policy
file, in the/var/lib/pki/instance_name/conf
directory, that contains user-defined security policies.
catalina.policy
file, also in the /var/lib/pki/instance_name/conf
directory, which is used for the instance.
pki.policy
file contains permissions that grant unrestricted access to the Tomcat, LDAP, and symkey services used by the PKI subsystems. For example:
// These permissions apply to Tomcat java as utilized by PKI instances grant codeBase "file:/usr/share/java/tomcat/-" { permission java.security.AllPermission; };
custom.policy
file is empty by default; administrators can write policies in that file which will be used in addition to the given PKI policies and Tomcat policies.
2.3.2.1.2. Starting a Subsystem Instance without the Java Security Manager
pki_security_manager=true
under the [Tomcat] section in the /etc/pki/default.cfg
file). However, it is possible to start or restart an instance and run it without starting the Java Security Manager, as shown below.
Procedure 2.1. Starting an Instance Without the Java Security Manager
- Stop the instance.
# systemctl stop pki-tomcatd@instance_name.service
OR# systemctl stop pki-tomcatd-nuxwdog@instance_name.service (if using the
nuxwdog watchdog
) - Edit the
/etc/sysconfig/instance_name
file and turn off the security manager:SECURITY_MANAGER="false"
- Start the instance.
# systemctl start pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using the
nuxwdog watchdog
)
2.3.3. Interfaces
2.3.3.1. Servlet Interface
web.xml
file, that is, /usr/share/pki/ca/webapps/ca/WEB-INF/web.xml
. The same file also defines the URL of each servlet and the security requirements to access the servlets. See Section 2.3.1, “Java Application Server” for more information.
2.3.3.2. Administrative Interface
2.3.3.3. End-Entity Interface
2.3.3.4. Operator Interface
2.3.4. REST Interface
web.xml
of the corresponding subsystem. More information about RESTEasy can be found at http://resteasy.jboss.org/.
- CA certificate service:
http://<host_name>:<port>/ca/rest/certs/
- KRA key service:
http://<host_name>:<port>/kra/rest/agent/keys/
- TKS user service:
http://<host_name>:<port>/tks/rest/admin/users/
- TPS group service:
http://<host_name>:<port>/tps/rest/admin/groups/
{ "id":"admin", "UserID":"admin", "FullName":"Administrator", "Email":"admin@example.com", ... }
- user name and password
- client certificate
/usr/share/pki/ca/conf/auth-method.properties
.
/usr/share/pki/<subsystem>/conf/acl.properties
.
2.3.5. NSS
2.3.6. JSS
2.3.7. Tomcatjss
tomcatjss
as a bridge between the Tomcat Server HTTP engine and JSS, the Java interface for security operations performed by NSS. Tomcatjss is a Java Secure Socket Extension (JSSE) implementation using Java Security Services (JSS) for Tomcat.
- The server is started.
- Tomcat gets to the point where it needs to create the listening sockets for the Certificate System installation.
- The
server.xml
file is processed. Configuration in this file tells the system to use a socket factory implemented by Tomcatjss. - For each requested socket, Tomcajss reads and processes the included attributes when it creates the socket. The resulting socket will behave as it has been asked to by those parameters.
- Once the server is running, we have the required set of listening sockets waiting for incoming connections to the Tomcat-based Certificate System.
server.xml
file, see Section 9.4, “Configuration Files for the Tomcat Engine and Web Services”.
2.3.8. PKCS #11
2.3.8.1. NSS Soft Token (internal token)
Note
/var/lib/pki/instance_name/alias/
directory.
- 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"), which handles all communication with the certificate and key database files that store certificates and keys.
- The FIPS 140 module. This module complies with the FIPS 140 government standard for cryptographic module implementations. The FIPS 140 module includes a single, built-in FIPS 140 certificate database token, which handles both cryptographic operations and communication with the certificate and key database files.
2.3.8.2. Hardware Security Module (HSM, external token)
Note
secmod.db
database for the subsystem. The modutil
utility is used to modify this file when there are changes to the system, such as installing a hardware accelerator to use for signing operations. For more information on modutil
, see Network Security Services (NSS) at Mozilla Developer webpage.
2.3.9. Certificate System Serial Number Management
2.3.9.1. Serial Number Ranges
- Current serial number management is based on assigning ranges of sequential serial numbers.
- Instances request new ranges when crossing below a defined threshold.
- Instances store information about a newly acquired range once it is assigned to the instance.
- Instances continue using old ranges until all numbers are exhausted from it, and then it moves to the new range.
- Cloned subsystems synchronize their range assignment through replication conflicts.
- Part of the current range of the master is transferred to a new clone in the process of cloning.
- New clones may request a new range if the transferred range is below the defined threshold.
[CA]
section to the PKI instance override configuration file, and adding the following name=value
pairs under that section as needed. Default values which already exist in /etc/pki/default.cfg
are shown in the following example:
[CA] pki_serial_number_range_start=1 pki_serial_number_range_end=10000000 pki_request_number_range_start=1 pki_request_number_range_end=10000000 pki_replica_number_range_start=1 pki_replica_number_range_end=100
2.3.9.2. Random Serial Number Management
[CA]
section to the PKI instance override file and adding the following name=value
pair under that section:
[CA] pki_random_serial_numbers_enable=True
2.3.10. Security Domain
2.3.11. Passwords and Watchdog (nuxwdog)
<instance_dir>/conf/password.conf
. At the same time, an identifying string is stored in the main configuration file CS.cfg
as part of the parameter cms.passwordlist
.
CS.cfg
, is protected by Red Hat Enterprise Linux, and only accessible by the PKI administrators. No passwords are stored in CS.cfg
.
password.conf
.
password.conf
. LDAP publishing is one example where the newly configured Directory Manager password for the publishing directory is entered into password.conf
.
Note
password.conf
file altogether. On restart, the nuxwdog watchdog program will prompt the administrator for the required passwords, using the parameter cms.passwordlist
(and cms.tokenList
if an HSM is used) as a list of passwords for which to prompt. The passwords are then cached by nuxwdog in the kernel keyring to allow automated recovery from a server crash. This automated recovery (automatic subsystem restart) happens in case of uncontrolled shutdown (crash). In case of a controlled shutdown by the administrator, administrators are prompted for passwords again.
2.3.12. Internal LDAP Database
pkispawn
options will also be needed for installing such Certificate System instance.
2.3.13. Security-Enhanced Linux (SELinux)
Figure 2.1. CA SELinux Port Policy
- Files and directories for each subsystem instance are labeled with a specific SELinux context.
- The ports for each subsystem instance are labeled with a specific SELinux context.
- All Certificate System processes are constrained within a subsystem-specific domain.
- Each domain has specific rules that define what actions that are authorized for the domain.
- Any access not specified in the SELinux policy is denied to the Certificate System instance.
pkispawn
is run to configure a Certificate System subsystem, files and ports associated with that subsystem are labeled with the required SELinux contexts. These contexts are removed when the particular subsystems are removed using pkidestroy
.
pki_tomcat_t
domain. Certificate System instances are Tomcat servers, and the pki_tomcat_t
domain extends the policies for a standard tomcat_t
Tomcat domain. All Certificate System instances on a server share the same domain.
unconfined_t
) and then transitions into the pki_tomcat_t
domain. This process then has certain access permissions, such as write access to log files labeled pki_tomcat_log_t
, read and write access to configuration files labeled pki_tomcat_etc_rw_t
, or the ability to open and write to http_port_t
ports.
2.3.14. Self-tests
#
pki-server subsystem-enable <subsystem>
2.3.15. Logs
pki_subsystem_log_path
when the instance was created with pkispawn
. Regular audit logs are located in the log directory with other types of logs, while signed audit logs are written to /var/log/pki/instance_name/subsystem_name/signedAudit
. The default location for logs can be changed by modifying the configuration.
2.3.15.1. Audit Log
Note
2.3.15.2. System 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 (both IPv4 and IPv6) 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:
id_number processor - [date:time] [number_of_operations] [result] servlet: message
Example 2.1. TKS System Log
10439.http-13443-Processor25 - [19/May/2021:14:16:51 CDT] [11] [3] UGSubsystem: Get User Error User not found
2.3.15.3. Transactions Log
transactions
, records any kind of operation performed or submitted to the subsystem.
id_number.processor - [date:time] [number_of_operations] [result] servlet: message
Example 2.2. Transactions Log
11438.http-8443-Processor25 - [27/May/2021:07:56:18 CDT] [1] [1] archival reqID 4 fromAgent agentID: CA-server.example.com-8443 authenticated by noAuthManager is completed DN requested: UID=recoverykey,E=recoverykey@email.com,CN=recover key serial number: 0x3
2.3.15.4. Debug Logs
[date:time] [processor]: servlet: message
[10/Jun/2021:05:14:51][main]: Established LDAP connection using basic authentication to host localhost port 389 as cn=Directory Manager
main
, and the message is the message from the server about the LDAP connection, and there is no servlet.
[06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443
Example 2.3. CA Certificate Request Log Messages
[06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.profileapprovedby$ value=admin [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.cert_request$ value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOB... [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.profile$ value=true [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.cert_request_type$ value=crmf [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestversion$ value=1.0.0 [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.req_locale$ value=en [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443 [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.dbstatus$ value=NOT_UPDATED [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.subject$ value=uid=jsmith, e=jsmith@example.com [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requeststatus$ value=begin [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.user$ value=uid=KRA-server.example.com-8443,ou=People,dc=example,dc=com [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.req_key$ value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M HTmlOqm4HwFxzy0RRQIDAQAB [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.authmgrinstname$ value=raCertAuth [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.uid$ value=KRA-server.example.com-8443 [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.userid$ value=KRA-server.example.com-8443 [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestor_name$ value= [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.profileid$ value=caUserCert [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.userdn$ value=uid=KRA-server.example.com-4747,ou=People,dc=example,dc=com [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestid$ value=20 [06/Jun/2021:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.authtime$ value=1212782378071 [06/Jun/2021:14:59:38][http-8443;-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=
[07/Jul/2021:06:25:40][http-11180-Processor25]: OCSPServlet: OCSP Request: [07/Jul/2021:06:25:40][http-11180-Processor25]: OCSPServlet: MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU
2.3.15.5. Installation Logs
pkispawn
, 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 /var/log/pki/
directory for the instance with a name in the form pki-subsystem_name-spawn.timestamp.log
.
Example 2.4. CA Install Log
... 2015-07-22 20:43:13 pkispawn : INFO ... finalizing 'pki.server.deployment.scriptlets.finalization' 2015-07-22 20:43:13 pkispawn : INFO ....... cp -p /etc/sysconfig/pki/tomcat/pki-tomcat/ca/deployment.cfg /var/log/pki/pki-tomcat/ca/archive/spawn_deployment.cfg.20150722204136 2015-07-22 20:43:13 pkispawn : DEBUG ........... chmod 660 /var/log/pki/pki-tomcat/ca/archive/spawn_deployment.cfg.20150722204136 2015-07-22 20:43:13 pkispawn : DEBUG ........... chown 26445:26445 /var/log/pki/pki-tomcat/ca/archive/spawn_deployment.cfg.20150722204136 2015-07-22 20:43:13 pkispawn : INFO ....... generating manifest file called '/etc/sysconfig/pki/tomcat/pki-tomcat/ca/manifest' 2015-07-22 20:43:13 pkispawn : INFO ....... cp -p /etc/sysconfig/pki/tomcat/pki-tomcat/ca/manifest /var/log/pki/pki-tomcat/ca/archive/spawn_manifest.20150722204136 2015-07-22 20:43:13 pkispawn : DEBUG ........... chmod 660 /var/log/pki/pki-tomcat/ca/archive/spawn_manifest.20150722204136 2015-07-22 20:43:13 pkispawn : DEBUG ........... chown 26445:26445 /var/log/pki/pki-tomcat/ca/archive/spawn_manifest.20150722204136 2015-07-22 20:43:13 pkispawn : INFO ....... executing 'systemctl enable pki-tomcatd.target' 2015-07-22 20:43:13 pkispawn : INFO ....... executing 'systemctl daemon-reload' 2015-07-22 20:43:13 pkispawn : INFO ....... executing 'systemctl restart pki-tomcatd@pki-tomcat.service' 2015-07-22 20:43:14 pkispawn : INFO END spawning subsystem 'CA' of instance 'pki-tomcat' 2015-07-22 20:43:14 pkispawn : DEBUG
2.3.15.6. Tomcat Error and Access Logs
- admin.timestamp
- catalina.timestamp
- catalina.out
- host-manager.timestamp
- localhost.timestamp
- localhost_access_log.timestamp
- manager.timestamp
2.3.15.7. Self-Tests Log
CS.cfg
file. The information about logs in this section does not pertain to this log. See Section 2.6.5, “Self-Tests” for more information about self-tests.
2.3.15.8. journalctl
Logs
systemd
and exposed via the journalctl
utility.
# journalctl -u pki-tomcatd@instance_name.service
nuxwdog
service:
# journalctl -u pki-tomcatd-nuxwdog@instance_name.service
# journalctl -f -u pki-tomcatd@instance_name.service
nuxwdog
service:
# journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service
2.3.16. Instance Layout
/etc/pki/instance_name/server.xml
, which is instance-specific, but the CA servlets are defined in /usr/share/pki/ca/webapps/ca/WEB-INF/web.xml
, which is shared by all server instances on the system.
2.3.16.1. File and Directory Locations for Certificate System
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
Table 2.2. Tomcat Instance Information
Setting | Value |
---|---|
Main Directory | /var/lib/pki/pki-tomcat |
Configuration Directory | /etc/pki/pki-tomcat |
Configuration File |
/etc/pki/pki-tomcat/server.xml
/etc/pki/pki-tomcat/password.conf
|
Security Databases | /var/lib/pki/pki-tomcat/alias |
Subsystem Certificates |
TLS server certificate
Subsystem certificate [a]
|
Log Files | /var/log/pki/pki-tomcat |
Web Services Files |
/usr/share/pki/server/webapps/ROOT - Main page
/usr/share/pki/server/webapps/pki/admin - Admin templates
/usr/share/pki/server/webapps/pki/js - JavaScript libraries
|
[a]
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.
|
Note
/var/lib/pki/instance_name/conf/
directory is a symbolic link to the /etc/pki/instance_name/
directory.
2.3.16.2. CA Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
Table 2.3. CA Subsystem Information
Setting | Value |
---|---|
Main Directory | /var/lib/pki/pki-tomcat/ca |
Configuration Directory | /etc/pki/pki-tomcat/ca |
Configuration File | /etc/pki/pki-tomcat/ca/CS.cfg |
Subsystem Certificates |
CA signing certificate
OCSP signing certificate (for the CA's internal OCSP service)
Audit log signing certificate
|
Log Files | /var/log/pki/pki-tomcat/ca |
Install Logs | /var/log/pki/pki-ca-spawn.YYYYMMDDhhmmss.log |
Profile Files | /var/lib/pki/pki-tomcat/ca/profiles/ca |
Email Notification Templates | /var/lib/pki/pki-tomcat/ca/emails |
Web Services Files |
/usr/share/pki/ca/webapps/ca/agent - Agent services
/usr/share/pki/ca/webapps/ca/admin - Admin services
/usr/share/pki/ca/webapps/ca/ee - End user services
|
2.3.16.3. KRA Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
Table 2.4. KRA Subsystem Information
Setting | Value |
---|---|
Main Directory | /var/lib/pki/pki-tomcat/kra |
Configuration Directory | /etc/pki/pki-tomcat/kra |
Configuration File | /etc/pki/pki-tomcat/kra/CS.cfg |
Subsystem Certificates |
Transport certificate
Storage certificate
Audit log signing certificate
|
Log Files | /var/log/pki/pki-tomcat/kra |
Install Logs | /var/log/pki/pki-kra-spawn.YYYYMMDDhhmmss.log |
Web Services Files |
/usr/share/pki/kra/webapps/kra/agent - Agent services
/usr/share/pki/kra/webapps/kra/admin - Admin services
|
2.3.16.4. OCSP Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
Table 2.5. OCSP Subsystem Information
Setting | Value |
---|---|
Main Directory | /var/lib/pki/pki-tomcat/ocsp |
Configuration Directory | /etc/pki/pki-tomcat/ocsp |
Configuration File | /etc/pki/pki-tomcat/ocsp/CS.cfg |
Subsystem Certificates |
OCSP signing certificate
Audit log signing certificate
|
Log Files | /var/log/pki/pki-tomcat/ocsp |
Install Logs | /var/log/pki/pki-ocsp-spawn.YYYYMMDDhhmmss.log |
Web Services Files |
/usr/share/pki/ocsp/webapps/ocsp/agent - Agent services
/usr/share/pki/ocsp/webapps/ocsp/admin - Admin services
|
2.3.16.5. TKS Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
Table 2.6. TKS Subsystem Information
Setting | Value |
---|---|
Main Directory | /var/lib/pki/pki-tomcat/tks |
Configuration Directory | /etc/pki/pki-tomcat/tks |
Configuration File | /etc/pki/pki-tomcat/tks/CS.cfg |
Subsystem Certificates | Audit log signing certificate |
Log Files | /var/log/pki/pki-tomcat/tks |
Install Logs | /var/log/pki/pki-tomcat/pki-tks-spawn.YYYYMMDDhhmmss.log |
2.3.16.6. TPS Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
Table 2.7. TPS Subsystem Information
Setting | Value |
---|---|
Main Directory | /var/lib/pki/pki-tomcat/tps |
Configuration Directory | /etc/pki/pki-tomcat/tps |
Configuration File | /etc/pki/pki-tomcat/tps/CS.cfg |
Subsystem Certificates | Audit log signing certificate |
Log Files | /var/log/pki/pki-tomcat/tps |
Install Logs | /var/log/pki/pki-tps-spawn.YYYYMMDDhhhmmss.log |
Web Services Files | /usr/share/pki/tps/webapps/tps - TPS services |
2.3.16.7. Shared Certificate System Subsystem File Locations
Table 2.8. Subsystem File Locations
Directory Location | Contents |
---|---|
/usr/share/pki | 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:
|
/usr/bin | Contains the pkispawn and pkidestroy instance configuration scripts and tools (Java, native, and security) shared by the Certificate System subsystems. |
/usr/share/java/pki | Contains Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. |
2.4. PKI with Certificate System
Note
2.4.1. Issuing Certificates
2.4.1.1. Enrollment Using the Command Line
2.4.1.1.1. Enrolling with CMC
- Generate a PKCS #10 or CRMF certificate signing request (CSR) using a utility, such as
certutil
,openssl
,PKCS10Client
, orCRMFPopClient
. For details, see the Creating Certificate Signing Requests section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Note
If key archival is enabled in the Key Recovery Agent (KRA), use theCRMFPopClient
utility with the KRA's transport certificate in Privacy Enhanced Mail (PEM) format set in thekra.transport
file. - Use the
CMCRequest
utility to convert the CSR into a CMC request. TheCMCRequest
utility uses a configuration file as input. This file contains, for example, the path to the CSR and the CSR's format.For further details and examples, see the CMCRequest(1) man page. - Use the
HttpClient
utility to send the CMC request to the CA.HttpClient
uses a configuration file with settings, such as the path to the CMC request file and the servlet.If theHttpClient
command succeeds, the utility receives a PKCS #7 chain with CMC status controls in a CMC response from the CA.For details about what parameters the utility provides, enter theHttpClient
command without any parameters. - Use the
CMCResponse
utility to check the issuance result of the CMC response file generated byHttpClient
. If the request is successful,CMCResponse
displays the certificate chain in a readable format along with status information.For further details, see the CMCResponse(1) man page. - Import the new certificate into the application. For details, follow the instructions of the application to which you want to import the certificate.
Note
The certificate retrieved byHttpClient
is in CMC response format that contains PKCS #7. If the application supports only Base64-encoded certificates, use theBtoA
utility to convert the certificate.Additionally, certain applications require a header and footer for certificates in Privacy Enhanced Mail (PEM) format. If these are required, add them manually to the PEM file after you converted the certificate.
2.4.1.1.2. CMC Enrollment without POP
HttpClient
utility receives an EncryptedPOP
CMC status, which is displayed by the CMCResponse
command. In this case, enter the CMCRequest
command again with different parameters in the configuration file.
2.4.1.1.3. Signed CMC Requests
- If an agent signs the request, set the authentication method in the profile to
CMCAuth
. - If a user signs the request, set the authentication method in the profile to
CMCUserSignedAuth
.
2.4.1.1.4. Unsigned CMC Requests
CMCUserSignedAuth
authentication plug-in is configured in the profile, you must use an unsigned CMC request in combination with the Shared Secret authentication mechanism.
Note
self-signed CMC requests
.
2.4.1.1.5. The Shared Secret Workflow
CMCSharedToken
command. The issuance protection certificate works similar to the KRA transport certificate. For further details, see the CMCSharedToken(1) man page and the The CMC Shared Secret Feature section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
Shared Secret Create by the End Entity User (Preferred)
- The end entity user obtains the issuance protection certificate from the CA administrator.
- The end entity user uses the
CMCSharedToken
utility to generate a shared secret token.Note
The-p
option sets the passphrase that is shared between the CA and the user, not the password of the token. - The end entity user sends the encrypted shared token generated by the
CMCSharedToken
utility to the administrator. - The administrator adds the shared token into the
shrTok
attribute in the user's LDAP entry. - The end entity user uses the passphrase to set the
witness.sharedSecret
parameter in the configuration file passed to theCMCRequest
utility.
Shared Secret Created by the CA Administrator
- The administrator uses the
CMCSharedToken
utility to generate a shared secret token for the user.Note
The-p
option sets the passphrase that is shared between the CA and the user, not the password of the token. - The administrator adds the shared token into the
shrTok
attribute in the user's LDAP entry. - The administrator shares the passphrase with the user.
- The end entity user uses the passphrase to set the
witness.sharedSecret
parameter in the configuration file passed to theCMCRequest
utility.
2.4.1.1.6. Simple CMC Requests
HttpClient
utility's configuration file:
servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert
2.4.1.2. Certificate Profiles
- 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
<instance directory>/ca/profiles/ca
with names in the format of <profile id>.cfg
. LDAP-based profiles are possible with proper pkispawn
configuration parameters.
2.4.1.3. Authentication for Certificate Enrollment
2.4.1.4. Cross-Pair Certificates
2.4.2. Renewing Certificates
2.4.3. Publishing Certificates and CRLs
2.4.4. Revoking Certificates and Checking Status
2.4.4.1. Revoking Certificates
CMCRequest
utility on the command line. For details, see the Performing a CMC Revocation section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
2.4.4.2. Certificate Status
2.4.4.2.1. CRLs
2.4.4.2.2. OCSP Services
- 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.
- The CA periodically publishes CRLs to an OCSP responder.
- The OCSP responder maintains the CRL it receives from the CA.
- 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.
- 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.
2.4.4.2.2.1. OCSP Response Signing
- The CA that issued the certificate whose 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.
2.4.4.2.2.2. OCSP Responses
- 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.
Note
2.4.4.2.2.3. OCSP Services
- The OCSP built into the Certificate Manager
- The Online Certificate Status Manager subsystem
Note
2.4.5. Archiving, Recovering, and Rotating Keys
- Clients that can generate keys and CSRs in CRMF format. For details, see the Creating Certificate Signing Requests section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
- Clients that can transform the CRMF request into CMC, such as the
CMCRequest
utility. - Clients that can submit the CMC request with embedded CRMF request to the CA through a specified enrollment profile.
- An installed and configured KRA.
2.4.5.1. Archiving 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.
- 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.
- A transport key pair and corresponding certificate.
- A storage key pair.
Figure 2.2. How the Key Archival Process Works
- The client generates a CRMF request and submits it through the CA’s enrollment portal.For more information on this procedure, see Example on Obtaining an Encryption-only certificate with Key Archival procedure in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
- After approving the certificate request and issuing the certificate, the Certificate Manager sends it to the KRA for storage, along with the public key. The Certificate Manager waits for verification from the KRA that the private key has been received and stored and that it corresponds to the public encryption key.
- The KRA decrypts it with the private key. After confirming that the private encryption key corresponds to the public encryption key, the KRA encrypts it again with its public key pair of the storage key before storing it in its internal database.
- The Certificate Manager issues two certificates for the signing and encryption key pairs and returns them to the end entity.
2.4.5.2. Recovering Keys
Figure 2.3. Asynchronous Recovery
Warning
Important
pki
utility to replicate this behavior. For more information, see the pki(1) and pki-key(1) man pages.
pki
utility supports options that enable storing and retrieving these other types of secrets.
2.4.5.3. KRA Transport Key Rotation
- Generate a new KRA transport key and certificate
- Transfer the new transport key and certificate to KRA clones
- Update the CA configuration with the new KRA transport certificate
- Update the KRA configuration to use only the new transport key and certificate
- Generating the new KRA transport key and certificate
- Request the KRA transport certificate.
- Stop the KRA:
systemctl stop pki-tomcatd@pki-kra.service
ORsystemctl stop pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
) - Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
- Create a subdirectory and save all the NSS database files into it. For example:
mkdir nss_db_backup cp *.db nss_db_backup
- Create a new request by using the
PKCS10Client
utility. For example:PKCS10Client -p password -d '.' -o 'req.txt' -n 'CN=KRA Transport 2 Certificate,O=example.com Security Domain'
Alternatively, use thecertutil
utility. For example:certutil -d . -R -k rsa -g 2048 -s 'CN=KRA Transport 2 Certificate,O=example.com Security Domain' -f password-file -a -o transport-certificate-request-file
- Submit the transport certificate request on the Manual Data Recovery Manager Transport Certificate Enrollment page of the CA End-Entity page.
- Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
- Approve the KRA transport certificate through the CA Agent Services interface.
- Retrieve the KRA transport certificate.
- Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
- Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
- Once the new KRA transport certificate is available, paste its Base64-encoded value into a text file, for example a file named
cert-serial_number.txt
. Do not include the header (-----BEGIN CERTIFICATE-----
) or the footer (-----END CERTIFICATE-----
).
- Import the KRA transport certificate.
- Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
- Import the transport certificate into the KRA NSS database:
certutil -d . -A -n 'transportCert-serial_number cert-pki-kra KRA' -t 'u,u,u' -a -i cert-serial_number.txt
- Update the KRA transport certificate configuration.
- Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
- Verify that the new KRA transport certificate is imported:
certutil -d . -L certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file and add the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Propagating the new transport key and certificate to KRA clones
- Start the KRA:
systemctl start pki-tomcatd@pki-kra.service
ORsystemctl start pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
) - Extract the new transport key and certificate for propagation to clones.
- Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
- Stop the KRA:
systemctl stop pki-tomcatd@pki-kra.service
ORsystemctl stop pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
) - Verify that the new KRA transport certificate is present:
certutil -d . -L certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Export the KRA new transport key and certificate:
pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'
- Verify the exported KRA transport key and certificate:
pk12util -l transport.p12
- Perform these steps on each KRA clone:
- Copy the
transport.p12
file, including the transport key and certificate, to the KRA clone location. - Go to the clone NSS database directory:
cd /etc/pki/pki-kra/alias
- Stop the KRA clone:
systemctl stop pki-tomcatd@pki-kra.service
ORsystemctl stop pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
) - Check the content of the clone NSS database:
certutil -d . -L
- Import the new transport key and certificate of the clone:
pk12util -i transport.p12 -d .
- Add the following line to the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file on the clone:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Start the KRA clone:
systemctl start pki-tomcatd@pki-kra.service
ORsystemctl start pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
)
- Updating the CA configuration with the new KRA transport certificate
- Format the new KRA transport certificate for inclusion in the CA.
- Obtain the
cert-serial_number.txt
KRA transport certificate file created when retrieving the KRA transport certificate in the previous procedure. - Convert the Base64-encoded certificate included in
cert-serial_number.txt
to a single-line file:tr -d '\n' < cert-serial_number.txt > cert-one-line-serial_number.txt
- Do the following for the CA and all its clones corresponding to the KRA above:
- Stop the CA:
systemctl stop pki-tomcatd@pki-ca.service
ORsystemctl stop pki-tomcatd-nuxwdog@pki-ca.service (if using the
nuxwdog watchdog
) - In the
/var/lib/pki/pki-ca/ca/conf/CS.cfg
file, locate the certificate included in the following line:ca.connector.KRA.transportCert=certificate
Replace that certificate with the one contained incert-one-line-serial_number.txt
. - Start the CA:
systemctl start pki-tomcatd@pki-ca.service
ORsystemctl start pki-tomcatd-nuxwdog@pki-ca.service (if using the
nuxwdog watchdog
)
Note
While the CA and all its clones are being updated with the new KRA transport certificate, the CA instances that have completed the transition use the new KRA transport certificate, and the CA instances that have not yet been updated continue to use the old KRA transport certificate. Because the corresponding KRA and its clones have already been updated to use both transport certificates, no downtime occurs.- Updating the KRA configuration to use only the new transport key and certificate
- For the KRA and each of its clones, do the following:
- Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
- Stop the KRA:
systemctl stop pki-tomcatd@pki-kra.service
ORsystemctl stop pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
) - Verify that the new KRA transport certificate is imported:
certutil -d . -L certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file, and look for thenickName
value included in the following line:kra.transportUnit.nickName=transportCert cert-pki-kra KRA
Replace thenickName
value with thenewNickName
value included in the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
As a result, theCS.cfg
file includes this line:kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRA
- Remove the following line from
/var/lib/pki/pki-kra/kra/conf/CS.cfg
:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Start the KRA:
systemctl start pki-tomcatd@pki-kra.service
ORsystemctl start pki-tomcatd-nuxwdog@pki-kra.service (if using the
nuxwdog watchdog
)
2.5. Smart Card Token Management with Certificate System
Figure 2.4. How the TMS Manages Smart Cards
2.5.1. Token Key Service (TKS)
Note
2.5.1.1. Master Keys and Key Sets
CS.cfg
). Each TPS profile contains a configuration to direct its enrollment to the proper TKS keySet for the matching key derivation process that would essentially be responsible for establishing the Secure Channel secured by a set of session-specific keys between TMS and the smart card token.
2.5.1.2. Key Ceremony (Shared Key Transport)
tkstool
to manage the secure key transportation.
2.5.1.3. Key Update (Key Changeover)
Important
2.5.1.4. APDUs and Secure Channels
- Command APDUs, sent by the TPS to smart cards
- Response APDUs, sent by smart cards to the TPS as response to command APDUs
2.5.2. Token Processing System (TPS)
2.5.2.1. Coolkey Applet
2.5.2.2. Token Operations
- Token Format - The format operation is responsible for installing the proper Coolkey applet onto the token. The applet provides a platform where subsequent cryptographic keys and certificates can be later placed.
- Token Enrollment - The enrollment operation results in a smart card populated with required cryptographic keys and cryptographic certificates. This material allows the user of the smart card to participate in operations such as secure web site access and secure mail. Two types of enrollments are supported, which is configured globally:
- Internal Registration - Enrollment by TPS profiles determined by the profile Mapping Resolver.
- External Registration - Enrollment by TPS profiles determined by the entries in the user's LDAP record.
- Token PIN Reset - The token PIN reset operation allows the user of the token to specify a new PIN that is used to log into the token, making it available for performing cryptographic operations.
- Key Generation - Each PKI certificate is comprised of a public/private key pair. In Red Hat Certificate System, the generation of the keys can be done in two ways, depending on the TPS profile configuration:
- Token Side Key Generation - The PKI key pairs are generated on the smart card token. Generating the key pairs on the token side does not allow for key archival.
- Server Side Key Generation - The PKI key pairs are generated on the TMS server side. The key pairs are then sent back to the token using Secure Channel. Generating the key pairs on the server side allows for key archival.
- Certificate Renewal - This operation allows a previously enrolled token to have the certificates currently on the token reissued while reusing the same keys. This is useful in situations where the old certificates are due to expire and you want to create new ones but maintain the original key material.
- Certificate Revocation - Certificate revocation can be triggered based on TPS profile configuration or based on token state.Normally, only the CA which issued a certificate can revoke it, which could mean that retiring a CA would make it impossible to revoke certain certificates. However, it is possible to route revocation requests for tokens to the retired CA while still routing all other requests such as enrollment to a new, active CA. This mechanism is called Revocation Routing.
- Token Key Changeover - The key changeover operation, triggered by a format operation, results in the ability to change the internal keys of the token from the default developer key set to a new key set controlled by the deployer of the Token Processing System. This is usually done in any real deployment scenario since the developer key set is better suited to testing situations.
- Applet Update - During the course of a TMS deployment, the Coolkey smart card applet can be updated or downgraded if required.
2.5.2.3. TPS Profiles
- The steps taken to Format or Enroll a token.
- The attributes contained within the finished token after the operation has been successfully completed.
- How does the TPS connect to the user's authentication LDAP database?
- Will user authentication be required for this token operation? If so, what authentication manager will be used?
- How does the TPS connect to a Certificate System CA from which it will obtain certificates?
- How are the private and public keys generated on this token? Are they generated on the token side or on the server side?
- What key size (in bits) is to be used when generating private and public keys?
- Which certificate enrollment profile (provisioned by the CA) is to be used to generate the certificates on this token?
Note
This setting will determine the final structure of the certificates to be written to the token. Different certificates can be created for different uses, based on extensions included in the certificate. For example, one certificate can specialize in data encryption, and another one can be used for signature operations. - What version of the Coolkey applet will be required on the token?
- How many certificates will be placed on this token for an enrollment operation?
- Internal Registration - In this case, the TPS profile (
tokenType
) is determined by the profile Mapping Resolver. This filter-based resolver can be configured to take any of the data provided by the token into account and determine the target profile. - External Registration - When using external registration, the profile (in name only - actual profiles are still defined in the TPS in the same fashion as those used by the internal registration) is specified in each user's LDAP record, which is obtained during authentication. This allows the TPS to obtain key enrollment and recovery information from an external registration Directory Server where user information is stored. This gives you the control to override the enrollment, revocation, and recovery policies that are inherent to the TPS internal registration mechanism. The user LDAP record attribute names relevant to external registration are configurable.External registration can be useful when the concept of a "group certificate" is required. In that case, all users within a group can have a special record configured in their LDAP profiles for downloading a shared certificate and keys.
2.5.2.4. Token Database
2.5.2.4.1. Token States and Transitions
2.5.2.4.1.1. Token States
Table 2.9. Possible Token States
Name | Code | Label |
---|---|---|
FORMATTED | 0 | Formatted (uninitialized) |
DAMAGED | 1 | Physically damaged |
PERM_LOST | 2 | Permanently lost |
SUSPENDED | 3 | Suspended (temporarily lost) |
ACTIVE | 4 | Active |
TERMINATED | 6 | Terminated |
UNFORMATTED | 7 | Unformatted |
Note
5
, which previously belonged to a state that was removed.
2.5.2.4.1.2. Token State Transitions Done Using the Graphical or Command Line Interface
FORMATTED
to ACTIVE
or DAMAGED
, but it can never transition from FORMATTED
to UNFORMATTED
.
tokendb.allowedTransitions
property, and the tps.operations.allowedTransitions
property controls allowed transitions triggered by token operations.
/usr/share/pki/tps/conf/CS.cfg
configuration file.
2.5.2.4.1.2.1. Token State Transitions Using the Command Line or Graphical Interface
tokendb.allowedTransitions
property:
tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7
<current code>:<new code>
. The codes are described in Table 2.9, “Possible Token States”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg
.
Table 2.10. Possible Manual Token State Transitions
Transition | Current State | Next State | Description |
---|---|---|---|
0:1 | FORMATTED | DAMAGED | This token has been physically damaged. |
0:2 | FORMATTED | PERM_LOST | This token has been permanently lost. |
0:3 | FORMATTED | SUSPENDED | This token has been suspended (temporarily lost). |
0:6 | FORMATTED | TERMINATED | This token has been terminated. |
3:2 | SUSPENDED | PERM_LOST | This suspended token has been permanently lost. |
3:6 | SUSPENDED | TERMINATED | This suspended token has been terminated. |
4:1 | ACTIVE | DAMAGED | This token has been physically damaged. |
4:2 | ACTIVE | PERM_LOST | This token has been permanently lost. |
4:3 | ACTIVE | SUSPENDED | This token has been suspended (temporarily lost). |
4:6 | ACTIVE | TERMINATED | This token has been terminated. |
6:7 | TERMINATED | UNFORMATTED | Reuse this token. |
FORMATTED
and then became SUSPENDED
, it can only return to the FORMATTED
state. If a token was originally ACTIVE
and then became SUSPENDED
, it can only return to the ACTIVE
state.
Table 2.11. Token State Transitions Triggered Automatically
Transition | Current State | Next State | Description |
---|---|---|---|
3:0 | SUSPENDED | FORMATTED | This suspended (temporarily lost) token has been found. |
3:4 | SUSPENDED | ACTIVE | This suspended (temporarily lost) token has been found. |
2.5.2.4.1.3. Token State Transitions using Token Operations
tokendb.allowedTransitions
property:
tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0
<current code>:<new code>
. The codes are described in Table 2.9, “Possible Token States”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg
.
Table 2.12. Possible Token State Transitions using Token Operations
Transition | Current State | Next State | Description |
---|---|---|---|
0:0 | FORMATTED | FORMATTED | This allows reformatting a token or upgrading applet/key in a token. |
0:4 | FORMATTED | ACTIVE | This allows enrolling a token. |
4:4 | ACTIVE | ACTIVE | This allows re-enrolling an active token. May be useful for external registration. |
4:0 | ACTIVE | FORMATTED | This allows formatting an active token. |
7:0 | UNFORMATTED | FORMATTED | This allows formatting a blank or previously used token. |
2.5.2.4.1.4. Token State and Transition Labels
/usr/share/pki/tps/conf/token-states.properties
configuration file. By default, the file has the following contents:
# Token states UNFORMATTED = Unformatted FORMATTED = Formatted (uninitialized) ACTIVE = Active SUSPENDED = Suspended (temporarily lost) PERM_LOST = Permanently lost DAMAGED = Physically damaged TEMP_LOST_PERM_LOST = Temporarily lost then permanently lost TERMINATED = Terminated # Token state transitions FORMATTED.DAMAGED = This token has been physically damaged. FORMATTED.PERM_LOST = This token has been permanently lost. FORMATTED.SUSPENDED = This token has been suspended (temporarily lost). FORMATTED.TERMINATED = This token has been terminated. SUSPENDED.ACTIVE = This suspended (temporarily lost) token has been found. SUSPENDED.PERM_LOST = This suspended (temporarily lost) token has become permanently lost. SUSPENDED.TERMINATED = This suspended (temporarily lost) token has been terminated. SUSPENDED.FORMATTED = This suspended (temporarily lost) token has been found. ACTIVE.DAMAGED = This token has been physically damaged. ACTIVE.PERM_LOST = This token has been permanently lost. ACTIVE.SUSPENDED = This token has been suspended (temporarily lost). ACTIVE.TERMINATED = This token has been terminated. TERMINATED.UNFORMATTED = Reuse this token.
2.5.2.4.1.5. Customizing Allowed Token State Transitions
/var/lib/pki/instance_name/tps/conf/CS.cfg
:
tokendb.allowedTransitions
to customize the list of allowed transitions performed using the command line or graphical interfacetps.operations.allowedTransitions
to customize the list of allowed transitions using token operations
/usr/share/pki/tps/conf/CS.cfg
.
2.5.2.4.1.6. Customizing Token State and Transition Labels
/usr/share/pki/tps/conf/token-states.properties
into your instance folder (/var/lib/pki/instance_name/tps/conf/CS.cfg
), and change the labels listed inside as needed.
token-states.properties
file from your instance folder.
2.5.2.4.1.7. Token Activity Log
Table 2.13. TPS Activity Log Events
Activity | Description |
---|---|
add | A token was added. |
format | A token was formatted. |
enrollment | A token was enrolled. |
recovery | A token was recovered. |
renewal | A token was renewed. |
pin_reset | A token PIN was reset. |
token_status_change | A token status was changed using the command line or graphical interface. |
token_modify | A token was modified. |
delete | A token was deleted. |
cert_revocation | A token certificate was revoked. |
cert_unrevocation | A token certificate was unrevoked. |
2.5.2.4.2. Token Policies
RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES
2.5.2.5. Mapping Resolver
Note
FilterMappingResolver
is the only mapping resolver implementation provided with the TPS by default. It allows you to define a set of mappings and a target result for each mapping. Each mapping contains a set of filters, where:
- If the input filter parameters pass all filters within a mapping, the
target
value is assigned. - If the input parameters fail a filter, that mapping is skipped and the next one in order is tried.
- If a filter has no specified value, it always passes.
- If a filter does have a specified value, then the input parameters must match exactly.
- The order in which mappings are defined is important. The first mapping which passes is considered resolved and is returned to the caller.
FilterMappingResolver
according to the above rules. The following input filter parameters are supported by FilterMappingResolver
:
appletMajorVersion
- The major version of the Coolkey applet on the token.appletMinorVersion
- The minor version of the Coolkey applet on the token.keySet
ortokenType
keySet
- can be set as an extension in the client request. Must match the value in the filter if the extension is specified. The keySet mapping resolver is meant for determining keySet value when using external registration. The Key Set Mapping Resolver is necessary in the external registration environment when multiple key sets are supported (for example, different smart card token vendors). The keySet value is needed for identifying the master key on TKS, which is crucial for establishing Secure Channel. When a user's LDAP record is populated with a set tokenType (TPS profile), it does not know which card will end up doing the enrollment, and therefore keySet cannot be predetermined. ThekeySetMappingResolver
helps solve the issue by allowing the keySet to be resolved before authentication.tokenType
- okenType can be set as an extension in the client request. It must match the value in the filter if the extension is specified. tokenType (also referred to as TPS Profile) is determined at this time for the internal registration environment.
tokenATR
- The token's Answer to Reset (ATR).tokenCUID
- "start" and "end" define the range the Card Unique IDs (CUID) of the token must fall in to pass this filter.
2.5.2.6. TPS Roles
- TPS Administrator - this role is allowed to:
- Manage TPS tokens
- View TPS certificates and activities
- Manage TPS users and groups
- Change general TPS configuration
- Manage TPS authenticators and connectors
- Configure TPS profiles and profile mappings
- Configure TPS audit logging
- TPS Agent - this role is allowed to:
- Configure TPS tokens
- View TPS certificates and activities
- Change the status of TPS profiles
- TPS Operator - this role is allowed to:
- View TPS tokens, certificates, and activities
2.5.3. TKS/TPS Shared Secret
Note
tkstool
to transfer the key to the HSM.
2.5.4. Enterprise Security Client (ESC)
2.6. Red Hat Certificate System Services
2.6.1. Notifications
2.6.2. Jobs
2.6.3. Logging
2.6.4. Auditing
2.6.5. Self-Tests
2.6.6. Users, Authorization, and Access Controls
2.6.6.1. Default Administrative Roles
Note
- Administrators, who can perform any administrative or configuration task for a subsystem.
- Agents, who perform PKI management tasks, like approving certificate requests, managing token enrollments, or recovering keys.
- Auditors, who can view and configure audit logs.
Note
pkispawn
utility. This bootstrap administrator uses the caadmin
user name by default but can be overridden by the pki_admin_uid
parameter in the configuration file passed to the pkispawn
command. The purpose of the bootstrap administrator is to create the first administrator and agent user. This operation requires the administrator privilege to mange user and groups, and the agent privilege to issue certificates.
2.6.6.2. Built-in Subsystem Trust Roles
Chapter 3. Allowed Standards and Protocols
3.1. Allowed TLS Cipher Suites
ECC
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
RSA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
3.2. Allowed Key Algorithms and Their Sizes
- Allowed RSA key sizes:
- 2048 bits or greater
- Allowed EC curves or equivalent as defined in the FIPS PUB 186-4 standard:
- nistp256
- nistp384
- nistp521
3.3. Allowed Hash Functions
- SHA-256
- SHA-384
- SHA-512
- SHA-256
- SHA-384
- SHA-512
3.4. Allowed PKIX Formats and Protocols
Table 3.1. PKIX Standards Allowed in Certificate System 9
Format or Protocol | RFC or Draft | Description |
---|---|---|
X.509 version 3 | Digital certificate formats recommended by the International Telecommunications Union (ITU). | |
Certificate Request Message Format (CRMF) | RFC 4211 | A message format to send a certificate request to a CA. |
Certificate Management Messages over CS (CMC) | RFC 5272 | Certificate Management protocol using the Cryptographic Message Syntax (CMS). CMC incorporates CRMF and PKCS #10. |
Cryptographic Message Syntax (CMS) | RFC 2630 | A superset of PKCS #7 syntax used for digital signatures and encryption. |
PKIX Certificate and CRL Profile | RFC 5280 | A standard developed by the IETF for a public-key infrastructure for the Internet. It specifies profiles for certificates and CRLs. |
Online Certificate Status Protocol (OCSP) | RFC 6960 | A protocol useful in determining the current status of a digital certificate without requiring CRLs. |
Chapter 4. Supported Platforms
4.1. Server Support
Note
4.2. Supported Web Browsers
Table 4.1. Supported Web Browsers by Platform
Platform | Agent Services | End User Pages |
---|---|---|
Red Hat Enterprise Linux | Firefox 60 and later [a] | Firefox 60 and later [a] |
Windows 7 | Firefox 60 and later [a] |
Firefox 60 and later
Internet Explorer 10 [b]
|
[a]
This Firefox version no longer supports the crypto web object used to generate and archive keys from the browser. As a result, expect limited functionality in this area.
[b]
Internet Explorer 11 is currently not supported by Red Hat Certificate System 9 because the enrollment code for this web browser depends upon Visual Basic Script, which has been deprecated in Internet Explorer 11.
|
Note
4.3. Supported Hardware Security Modules
HSM | Firmware | Appliance Software | Client Software |
---|---|---|---|
nCipher nCipher nShield Connect 6000 | 2.61.2 | CipherTools-linux64-dev-12.30.00 | CipherTools-linux64-dev-12.30.00 |
Gemalto SafeNet Luna SA 1700 / 7000 (limited)
(Limited support )
| 6.24.0 | 6.2.0-15 | libcryptoki-6.2.x86_64 |
Chapter 5. Planning the Certificate System
5.1. Deciding on the Required Subsystems
- It is requested and issued.
- It is valid.
- It expires.
- What if an employee leaves the company before the certificate expires?
- When a CA signing certificate expires, all of the certificates issued and signed using that certificate also expire. So will the CA signing certificate be renewed, allowing its issued certificates to remain valid, or will it be reissued?
- What if an employee loses a smart card or leaves it at home. Will a replacement certificate be issued using the original certificates keys? Will the other certificates be suspended or revoked? Are temporary certificates allowed?
- When a certificate expires, will a new certificate be issued or will the original certificate be renewed?
5.1.1. Using a Single Certificate Manager
Figure 5.1. CA Only Certificate System
5.1.2. Planning for Lost Keys: Key Archival and Recovery
Figure 5.2. CA and KRA
Note
5.1.3. Balancing Certificate Request Processing
5.1.4. Balancing Client OCSP Requests
Figure 5.3. CA and OCSP
5.2. Defining the Certificate Authority Hierarchy
Note
5.2.1. Subordination to a Public CA
5.2.2. Subordination to a Certificate System CA
5.2.3. Linked CA
5.3. Planning Security Domains
Example Corp Intranet PKI
. All other subsystems — KRA, TPS, TKS, OCSP, and other CAs — must become members of the security domain by supplying the security domain URL when configuring the subsystem.
ou=Security Domain,dc=server.example.com-pki-ca
pkiSecurityGroup
) to identify the group type:
cn=KRAList,ou=Security Domain,o=pki-tomcat-CA objectClass: top objectClass: pkiSecurityGroup cn: KRAList
pkiSubsystem
object class to identify the entry type:
dn: cn=kra.example.com:8443,cn=KRAList,ou=Security Domain,o=pki-tomcat-CA objectClass: top objectClass: pkiSubsystem cn: kra.example.com:8443 host: server.example.com UnSecurePort: 8080 SecurePort: 8443 SecureAdminPort: 8443 SecureAgentPort: 8443 SecureEEClientAuthPort: 8443 DomainManager: false Clone: false SubsystemName: KRA kra.example.com 8443
- 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 KRA; the KRA 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.
5.4. Determining the Requirements for Subsystem Certificates
5.4.1. Determining Which Certificates to Install
Table 5.1. Initial Subsystem Certificates
Subsystem | Certificates |
---|---|
Certificate Manager |
|
OCSP |
|
KRA |
|
TKS |
|
TPS |
|
- 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, KRAs, 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.Instead of creating new certificates from new key pairs, consider renewing the existing CA signing certificate.
- 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 KRA, the KRA information must be updated in the CA's configuration file,
CS.cfg
. The existing transport certificate must be replaced with the new one in theca.connector.KRA.transportCert
parameter. - If a CA is cloned, then when creating a new TLS server certificate for the master Certificate Manager, the clone CAs' certificate databases all need updated with the new TLS server certificate.
- If the Certificate Manager is configured to publish certificates and CRLs to an LDAP directory and uses the TLS server certificate for TLS client authentication, then the new TLS 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.
- Any number of TLS server certificates can be issued for a subsystem instance, but it really only needs one TLS certificate. This certificate can be renewed or replaced as many times as necessary.
5.4.2. Planning the CA Distinguished Name
cn=demoCA, o=Example Corporation, ou=Engineering, c=US
5.4.3. Setting the CA Signing Certificate Validity Period
5.4.4. Choosing the Signing Key Type and Length
- SHA256withRSA
- SHA384withRSA
- SHA512withRSA
- SHA256withEC
- SHA384withEC
- SHA512withEC
Note
5.4.5. Using Certificate Extensions
- 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.
- 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.
5.4.5.1. Structure of Certificate Extensions
Extension ::= SEQUENCE { extnID OBJECT IDENTIFIER, critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING }
- 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
). - A flag or Boolean field called
critical
.The value, which can be eithertrue
orfalse
, 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.
- 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
5.4.6. Using and Customizing Certificate Profiles
Certificate Profiles
Modifying the Certificate Profile Parameters
Certificate Profile Administration
Guidelines for Customizing Certificate Profiles
- Decide 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.
- Delete any certificate profiles that will not be used.
- Modify the existing certificate profiles for specific characteristics for the company's certificates.
- Change 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.
- Change the constraints set up by changing the value of the parameters.
- Change the authentication method.
- Change the inputs by adding or deleting inputs in the certificate profile, which control the fields on the input page.
- Add or delete the output.
5.4.6.1. Adding SAN Extensions to the TLS Server Certificate
/usr/share/pki/ca/profiles/ca/caInternalAuthServerCert.cfg
file and add the following parameters to the configuration file supplied to the pkispawn
utility:
pki_san_inject
- Set the value of this parameter to
True
. pki_san_for_server_cert
- Provide a list of the required SAN extensions separated by commas (,).
pki_san_inject=True pki_san_for_server_cert=intca01.example.com,intca02.example.com,intca.example.com
5.4.7. Planning Authentication Methods
5.4.8. Publishing Certificates and CRLs
- If certificates are published to the directory, than every user or server to which a certificate is issued must have a corresponding entry in the LDAP directory.
- If CRLs are published to the directory, than they must be published to an entry for the CA which issued them.
- For TLS, the directory service has to be configured in TLS and, optionally, be configured to allow the Certificate Manager to use certificate-based authentication.
- The directory administrator should configure appropriate access control rules to control DN (entry name) and password based authentication to the LDAP directory.
5.4.9. Renewing or Reissuing CA Signing Certificates
- Renewing a CA certificate involves issuing a new CA certificate with the same subject name and public and private key material as the old CA certificate, but with an extended validity period. As long as the new CA certificate is distributed to all users before the old CA certificate expires, renewing the certificate allows certificates issued under the old CA certificate to continue working for the full duration of their validity periods.
- Reissuing a CA certificate involves issuing a new CA certificate with a new name, public and private key material, and validity period. This avoids some problems associated with renewing a CA certificate, but it requires more work for both administrators and users to implement. All certificates issued by the old CA, including those that have not yet expired, must be renewed by the new CA.
Note
authorityKeyIdentifier
extension, can affect the transition from an old CA certificate to a new one.
5.5. Planning for Network and Physical Security
5.5.1. Considering Firewalls
- Protecting sensitive subsystems from unauthorized access
- Allowing appropriate access to other subsystems and clients outside of the firewall
389
for LDAP and 636
for LDAPS, by default) need to be open in the firewall to allow traffic to the directory service. Without access to the LDAP database, all subsystem operations can fail.
5.5.2. Considering Physical Security and Location
5.5.3. Planning Ports
- A non-secure HTTP port for end entity services that do not require authentication
- A secure HTTP port for end entity services, agent services, administrative console, and admin services that require authentication
- A Tomcat Server Management port
- A Tomcat AJP Connector Port
https://server.example.com:8443/ca/ee/ca
pkiconsole https://server.example.com:8443/ca
server.xml
file. If a port is not used, it can be disabled in that file. For example:
<Service name="Catalina">
<!--Connector port="8080"
... /--> unused standard port
<Connector port="8443" ... />
services
. On Red Hat Enterprise Linux, it is also helpful to confirm that a port is not assigned by SELinux, by running the command semanage port -l
to list all ports which currently have an SELinux context.
5.6. A Checklist for Planning the PKI
- Q: How many security domains will be created, and what subsystem instances will be placed in each domain?
- Q: What ports should be assigned for each subsystem? Is it necessary to have a single TLS port, or is it better to have port separation for extra security?
- Q: What subsystems should be placed behind firewalls? What clients or other subsystems need to access those firewall-protected subsystems and how will access be granted? Is firewall access allowed for the LDAP database?
- Q: What subsystems need to be physically secured? How will access be granted, and who will be granted access?
- Q: What is the physical location of all agents and administrators? What is the physical location of the subsystems? How will administrators or agents access the subsystem services in a timely-manner? Is it necessary to have subsystems in each geographical location or time zone?
- Q: How many subsystems do you need to install?
- Q: Will any subsystems need to be cloned and, if so, what are the methods for securely storing their key materials?
- Q: Will the subsystem certificates and keys be stored on the internal software token in Certificate System or on an external hardware token?
- Q: What are the requirements for the CA signing certificate? Does the Certificate System need control over attributes like the validity period? How will the CA certificates be distributed?
- Q: What kinds of certificates will be issued? What characteristics do they need to have, and what profile settings are available for those characteristics? What restrictions need to be placed on the certificates?
- Q: What are the requirements for approving a certificate request? How does the requester authenticate himself, and what kind of process is required to approve the request?
- Q: Will many external clients need to validate certificate status? Can the internal OCSP in the Certificate Manager handle the load?
- Q: Will the PKI allow replacement keys? Will it require key archival and recovery?
- Q: Will the organization use smart cards? If so, will temporary smart cards be allowed if smart cards are mislaid, requiring key archival and recovery?
- Q: Where will certificates and CRLs be published? What configuration needs to be done on the receiving end for publishing to work? What kinds of certificates or CRLs need to be published and how frequently?
Part II. Installing Red Hat Certificate System
Chapter 6. Prerequisites and Preparation for Installation
6.1. Installing Red Hat Enterprise Linux
Important
# sysctl crypto.fips_enabled
1
, FIPS mode is enabled.
6.2. Securing the System Using SELinux
enforcing
mode. If a procedure in the Certificate System documentation requires to manually set SELinux-related settings, such as when using a Hardware Security Module (HSM), it is mentioned in the corresponding section.
6.2.1. Verifying if SELinux is Running in Enforcing Mode
enforcing
mode and no further actions are required.
# getenforce
6.3. Firewall Configuration
Table 6.1. Certificate System Default Ports
Service
|
Port
|
Protocol
|
---|---|---|
HTTP
|
8080
|
TCP
|
HTTPS
|
8443
|
TCP
|
Tomcat Management
|
8005
|
TCP
|
pkispawn
utility, you can customize the port numbers. If you use different ports than the defaults listed above, open them correspondingly in the firewall as described in Section 6.3.1, “Opening the Required Ports in the Firewall”. For further details about ports, see Section 5.5.3, “Planning Ports”.
6.3.1. Opening the Required Ports in the Firewall
- Make sure the
firewalld
service is running.# systemctl status firewalld
- To start
firewalld
and configure it to start automatically when the system boots:# systemctl start firewalld # systemctl enable firewalld
- Open the required ports using the
firewall-cmd
utility. For example, to open the Certificate System default ports in the default firewall zone:# firewall-cmd --permanent --add-port={8080/tcp,8443/tcp,8009/tcp,8005/tcp}
For details on usingfirewall-cmd
to open ports on a system, see the Red Hat Enterprise Linux Security Guide or the firewall-cmd(1) man page. - Reload the firewall configuration to ensure that the change takes place immediately:
# firewall-cmd --reload
6.4. Hardware Security Module
6.4.1. Setting up SELinux for an HSM
- nCipher nShield
- After you installed the HSM and before you start installing Certificate System:
- Reset the context of files in the
/opt/nfast/
directory:# restorecon -R /opt/nfast/
- Restart the nfast software.
# /opt/nfast/sbin/init.d-ncipher restart
- Gemalto Safenet LunaSA HSM
- No SELinux-related actions are required before you start installing Certificate System.
6.4.2. Enabling FIPS Mode on an HSM
Important
- nCipher HSM
- On a nCipher HSM, the FIPS mode can only be enabled when generating the Security World, this cannot be changed afterwards. While there is a variety of ways to generate the Security World, the preferred method is always to use the
new-world
command. For guidance on how to generate a FIPS-compliant Security World, please follow the nCipher HSM vendor's documentation. - LunaSA HSM
- Similarly, enabling the FIPS mode on a Luna HSM must be done during the initial configuration, since changing this policy zeroizes the HSM as a security measure. For details, please refer to the Luna HSM vendor's documentation.
6.4.3. Verifying if FIPS Mode is Enabled on an HSM
6.4.3.1. Verifying if FIPS Mode is Enabled on an nCipher HSM
Note
# /opt/nfast/bin/nfkminfo
StrictFIPS140
is listed in the state flag, the FIPS mode is enabled. In newer vesions, it is however better to check the new mode
line and look for fips1402level3
. In all cases, there should also be an hkfips
key present in the nfkminfo
output.
6.4.3.2. Verifying if FIPS Mode is Enabled on a Luna SA HSM
Note
- Open the
lunash
management console - Use the
hsm show
command and verify that the output contains the textThe HSM is in FIPS 140-2 approved operation mode.
:lunash:> hsm show ... FIPS 140-2 Operation: ===================== The HSM is in FIPS 140-2 approved operation mode. ...
6.4.4. Preparing for Installing Certificate System with an HSM
pkispawn
Utility”, you are instructed to use the following parameters in the configuration file you pass to the pkispawn
utility when installing Certificate System with an HSM:
... [DEFAULT] ########################## # Provide HSM parameters # ########################## pki_hsm_enable=True pki_hsm_libfile=hsm_libfile pki_hsm_modulename=hsm_modulename pki_token_name=hsm_token_name pki_token_password=pki_token_password ######################################## # Provide PKI-specific HSM token names # ######################################## pki_audit_signing_token=hsm_token_name pki_ssl_server_token=hsm_token_name pki_subsystem_token=hsm_token_name ...
- The values of the
pki_hsm_libfile
andpki_token_name
parameter depend on your specific HSM installation. These values allow thepkispawn
utility to set up your HSM and enable Certificate System to connect to it. - The value of the
pki_token_password
depends upon your particular HSM token's password. The password gives thepkispawn
utility read and write permissions to create new keys on the HSM. - The value of the
pki_hsm_modulename
is a name used in laterpkispawn
operations to identify the HSM. The string is an identifier you can set as whatever you like. It allowspkispawn
and Certificate System to refer to the HSM and configuration information by name in later operations.
6.4.4.1. nCipher HSM Parameters
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so pki_hsm_modulename=nfast
pki_hsm_modulename
to any value. The above is a suggested value.
Example 6.1. Identifying the Token Name
root
user:
[root@example911 ~]# /opt/nfast/bin/nfkminfo
World
generation 2
...~snip~...
Cardset
name "NHSM6000-OCS"
k-out-of-n 1/4
flags NotPersistent PINRecoveryRequired(enabled) !RemoteEnabled
timeout none
...~snip~...
name
field in the Cardset
section lists the token name.
pki_token_name=NHSM6000-OCS
6.4.4.2. SafeNet / Luna SA HSM Parameters
pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so pki_hsm_modulename=lunasa
pki_hsm_modulename
to any value. The above is a suggested value.
Example 6.2. Identifying the Token Name
root
user:
# /usr/safenet/lunaclient/bin/vtl verify
The following Luna SA Slots/Partitions were found:
Slot Serial # Label
==== ================ =====
0 1209461834772 lunasaQE
label
column lists the token name.
pki_token_name=lunasaQE
6.4.5. Backing up Keys on Hardware Security Modules
.p12
file. If such an instance is to be backed-up, contact the manufacturer of your HSM for support.
6.5. Installing Red Hat Directory Server
6.5.1. Preparing a Directory Server Instance for Certificate System
- Attach a Directory Server subscription to the host.
- Install the Directory Server and openldap-clients packages:
# yum install redhat-ds openldap-clients
- Set up a Directory Server instance. For example:
- Create a setup configuration file, such as
/tmp/ds-setup.inf
with the following content:[General] FullMachineName=server.example.com SuiteSpotUserID=dirsrv SuiteSpotGroup=dirsrv [slapd] ServerIdentifier=instance_name ServerPort=389 Suffix=dc=example,dc=org RootDN=cn=Directory Manager RootDNPwd=password
- Create the instance using the setup configuration file:
setup-ds.pl --silent --file=/tmp/ds-setup.inf
For a detailed procedure, see the Red Hat Directory Server Installation Guide.
6.5.2. Enabling TLS Support in Directory Server
6.5.2.1. How to Enable LDAPS for new Red Hat Certificate System Subsystems Using Examples Values
Note
- Stop the Directory Server instance to avoid concurrent changes to the NSS database:
# systemctl stop dirsrv@instance_name.service
- Store the Directory Manager's password in the
/etc/dirsrv/instance_name/password.txt
file. For example:# echo password > /etc/dirsrv/slapd-instance_name/password.txt # chown dirsrv.dirsrv /etc/dirsrv/slapd-instance_name/password.txt # chmod 400 /etc/dirsrv/slapd-instance_name/password.txt
- Store the Directory Manager's password in the
/etc/dirsrv/instance_name/pin.txt
file. For example:# echo "Internal (Software) Token:password" > /etc/dirsrv/slapd-instance_name/pin.txt # chown dirsrv.dirsrv /etc/dirsrv/slapd-instance_name/pin.txt # chmod 400 /etc/dirsrv/slapd-instance_name/pin.txt
- Set the NSS database password:
# certutil -W -d /etc/dirsrv/slapd-instance_name/ -f /etc/dirsrv/slapd-instance_name/password.txt
- Create a temporary self-signed certificate for Directory Server:
$
cd /etc/dirsrv/slapd-instance_name$
openssl rand -out noise.bin 2048$
certutil -S \ -x \ -d . \ -f password.txt \ -z noise.bin \ -n "DS Certificate" \ -s "CN=$HOSTNAME" \ -t "CT,C,C" \ -m $RANDOM \ -k rsa \ -g 2048 \ -Z SHA256 \ --keyUsage certSigning,keyEncipherment - Verify whether the Directory Server certificate entry is available in the NSS database:
# certutil -L -d /etc/dirsrv/slapd-instance_name/
- Export the certificate:
# certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate" -a > ds.crt
- Verify the Directory Server certificate is self-signed:
# certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate" Issuer: "CN=server.example.com" Subject: "CN=server.example.com"
- Start the Directory Server instance:
#
systemctl start dirsrv@instance_name - Enable secure connection:
# ldapmodify -x -p 389 -h $HOSTNAME -D "cn=Directory Manager" -w password << EOF dn: cn=config changetype: modify replace: nsslapd-security nsslapd-security: on dn: cn=RSA,cn=encryption,cn=config changetype: add objectclass: top objectclass: nsEncryptionModule cn: RSA nsSSLPersonalitySSL: DS Certificate nsSSLToken: internal (software) nsSSLActivation: on EOF
- Optionally, set a different LDAPS port than the default (
636
).- For example, to set the LDAPS port to
11636
:ldapmodify -x -p 389 -h $HOSTNAME -D "cn=Directory Manager" -w password << EOF dn: cn=config changetype: modify replace: nsslapd-secureport nsslapd-secureport: 11636 EOF
- Set the SELinux policy for this non-standard port:
# semanage port -a -t ldap_port_t -p tcp 11636
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
- Verify in the
/var/log/dirsrv/slapd-instance_name/errors
file that Directory Server started in TLS mode:[30/Jun/2016:00:23:31 +0200] - SSL alert: Security Initialization: Enabling default cipher set. [30/Jun/2016:00:23:31 +0200] - SSL alert: Configured NSS Ciphers [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_RSA_WITH_AES_128_GCM_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_RSA_WITH_AES_128_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_DSS_WITH_AES_128_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_RSA_WITH_AES_256_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_DSS_WITH_AES_256_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_DHE_RSA_WITH_AES_256_CBC_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_RSA_WITH_AES_128_GCM_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_RSA_WITH_AES_128_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_RSA_WITH_AES_128_CBC_SHA256: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_RSA_WITH_AES_256_CBC_SHA: enabled [30/Jun/2016:00:23:31 +0200] - SSL alert: TLS_RSA_WITH_AES_256_CBC_SHA256: enabled [30/Jun/2016:00:23:31 +0200] SSL Initialization - Configured SSL version range: min: TLS1.0, max: TLS1.2 [30/Jun/2016:00:23:31 +0200] - 389-Directory/1.3.4.11 B2016.166.1911 starting up
- Verify the TLS connection using the
openldap-clients
and NSS database:$
LDAPTLS_CACERTDIR=/etc/dirsrv/slapd-instance_name \ ldapsearch -H ldaps://$HOSTNAME:11636 \ -x -D "cn=Directory Manager" -w Secret.123 \ -b "dc=example,dc=org" -s base "(objectClass=*)"
6.5.3. Preparing for Configuring Certificate System
pkispawn
Utility”, you are instructed to use the following parameters in the configuration file you pass to the pkispawn
utility when installing Certificate System:
Note
pki_ds_password
would no longer be relevant.
pki_ds_database=back_end_database_name pki_ds_hostname=host_name pki_ds_secure_connection=True pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate pki_ds_password=password pki_ds_ldaps_port=port pki_ds_bind_dn=cn=Directory Manager
pki_ds_database
parameter is a name used by the pkispawn
utility to create the corresponding subsystem database on the Directory Server instance.
pki_ds_hostname
parameter depends on the install location of the Directory Server instance. This depends on the values used in Section 6.5.1, “Preparing a Directory Server Instance for Certificate System” and Section 6.5.2, “Enabling TLS Support in Directory Server”.
pki_ds_secure_connection=True
, the following parameters must be set:
pki_ds_secure_connection_ca_pem_file
: Sets the fully-qualified path including the file name of the file which contains an exported copy of the Directory Server's CA certificate. This file must exist prior topkispawn
being able to utilize it.pki_ds_ldaps_port
: Sets the value of the secure LDAPS port Directory Server is listening to. The default is636
.
6.5.4. Replacing the Temporary Certificate
Note
- Obtain a new Directory Server server certificate. Submit the request for the new certificate signed by the CA. To get a new Directory Server certificate using the CMC method, see the Obtaining System and Server Certificates section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).In the above section, follow the guidance to create a TLS server certificate. Once the certificate is created, it must be imported back into the Directory Server's certificate database.
- Stop the Directory Server instance before accessing the NSS database:
# systemctl stop dirsrv@instance_name
- Delete the old Directory Server certificate:
# certutil -F -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "DS Certificate"
- Import the CA certificate downloaded earlier:
# PKICertImport -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "CA Certificate" -t "CT,C,C" -a -i ca.crt -u L
- Import the new Directory Server certificate downloaded earlier:
# PKICertImport -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "DS Certificate" -t ",," -a -i ds.crt -u V
- Start the Directory Server instance:
systemctl start dirsrv@instance_name
- Remove the old Directory Server Certificate from PKI CA:
- Stop the Certificate System instance:
# systemctl stop pki-tomcatd@instance_name.service
- Remove the certificate:
# certutil -D -d /var/lib/pki/instance_name/alias/ -n "DS Certificate"
- Start the Certificate System instance:
# systemctl start pki-tomcatd@instance_name.service
- Verify that the new Directory Server certificate is signed by the CA installed in the NSS database:
- Display the Directory Server certificate
$ certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate" Issuer: "CN=CA Signing Certificate,O=EXAMPLE" Subject: "CN=server.example.com"
- Verify the old Directory Server certificate no longer exists in the PKI NSS database:
$ certutil -L -d /var/lib/pki/instance_name/alias
- Verify Certificate System can connect to Directory Server using the new certificate:
$ pki cert-find
6.5.5. Enabling TLS Client Authentication
Note
pkispawn
already automatically created apkidbuser
on its internal directory server, where the CS instance's "subsystem certificate" (for examplesubsystemCert cert-pki-ca
) that is used for outbound TLS client authentication is stored in the user entry. Therefore, there is no need to create another LDAP user or another certificate for the TLS client-authentication.- When creating content for
/etc/dirsrv/slapd-instance_name/certmap.conf
, use the following format:certmap rhcs <certificate issuer DN> rhcs:CmapLdapAttr seeAlso rhcs:verifyCert on
For examplecertmap rhcs CN=CA Signing Certificate,OU=pki-tomcat-ca,O=pki-tomcat-ca-SD rhcs:CmapLdapAttr seeAlso rhcs:verifyCert on
- After configuring, restart the Directory Server.
CS.cfg
file located at <instance directory>/<subsystem type>/conf/CS.cfg
. For example /var/lib/pki/pki-tomcat/ca/conf/CS.cfg
CS.cfg
, please add the RHCS instance's subsystem certificate nickname to internaldb.ldapauth.clientCertNickname
, and remove the two unused entries:
internaldb.ldapauth.bindDN internaldb.ldapauth.bindPWPrompt
internaldb._000=## internaldb._001=## Internal Database internaldb._002=## internaldb.basedn=o=pki-tomcat-ca-SD internaldb.database=pki-tomcat-ca internaldb.maxConns=15 internaldb.minConns=3 internaldb.ldapauth.authtype=SslClientAuth internaldb.ldapauth.clientCertNickname=HSM-A:subsystemCert pki-tomcat-ca internaldb.ldapconn.host=example.com internaldb.ldapconn.port=11636 internaldb.ldapconn.secureConn=true
Note
internaldb.basedn
and internaldb.database
parameters must be configured to match your specific LDAP instance.
internaldb.ldapauth.authtype=SslClientAuth
and internaldb.ldapconn.secureConn=true
must be set, and the value of the internaldb.ldapauth.clientCertNickname
must match the nickname of the TLS client certificate to authenticate against LDAP with in the NSS DB.
6.6. Attaching a Red Hat Subscription and Enabling the Certificate System Package Repository
yum
utility, you must enable the corresponding repository:
- Attach the Red Hat subscriptions to the system:Skip this step, if your system is already registered or has a Certificate Server subscription attached.
- Register the system to the Red Hat subscription management service:
#
subscription-manager register --auto-attach
Username: admin@example.com Password: The system has been registered with id: 566629db-a4ec-43e1-aa02-9cbaa6177c3f Installed Product Current Status: Product Name: Red Hat Enterprise Linux Server Status: SubscribedUse the--auto-attach
option to automatically apply a subscription for the operating system. - List the available subscriptions and note the pool ID providing the Red Hat Certificate System. For example:
#
subscription-manager list --available --all
... Subscription Name: Red Hat Enterprise Linux Developer Suite Provides: ... Red Hat Certificate System ... Pool ID: 7aba89677a6a38fc0bba7dac673f7993 Available: 1 ...In case you have a lot of subscriptions, the output of the command can be very long. You can optionally redirect the output to a file:#
subscription-manager list --available --all > /root/subscriptions.txt
- Attach the Certificate System subscription to the system using the pool ID from the previous step:
#
subscription-manager attach --pool=7aba89677a6a38fc0bba7dac673f7993
Successfully attached a subscription for: Red Hat Enterprise Linux Developer Suite
- Enable the Certificate Server repository:
#
subscription-manager repos --enable=rhel-7-server-rhcmsys-9-rpms
Repository 'rhel-7-server-rhcmsys-9-rpms' is enabled for this system.
Note
subscription-manager
utility.
6.7. Certificate System Operating System Users and Groups
pkiuser
account and the corresponding pkiuser
group are automatically created. Certificate System uses this account and group to start services.
Chapter 7. Installing and Configuring Certificate System
- Certificate Authority (CA)
- Key Recovery Authority (KRA)
- Online Certificate Status Protocol (OCSP) Responder
- Token Key Service (TKS)
- Token Processing System (TPS)
7.1. Subsystem Configuration Order
- At least one CA is required before any of the other public key infrastructure (PKI) subsystems can be installed.
- Install the OCSP after the CA has been configured.
- The KRA, and TKS subsystems can be installed in any order, after the CA and OCSP have been configured.
- The TPS subsystem depends on the CA and TKS, and optionally on the KRA and OCSP subsystem.
Note
7.2. Certificate System Packages
Important
- pki-ca: Provides the Certificate Authority (CA) subsystem.
- pki-kra: Provides the Key Recovery Authority (KRA) subsystem.
- pki-ocsp: Provides the Online Certificate Status Protocol (OCSP) responder.
- pki-tks: Provides the Token Key Service (TKS).
- pki-tps: Provides the Token Processing Service (TPS).
- pki-console and redhat-pki-console-theme: Provides the Java-based Red Hat PKI console. Both packages must be installed.
- pki-server and redhat-pki-server-theme: Provides the web-based Certificate System interface. Both packages must be installed.This package is installed as a dependency if you install one of the following packages: pki-ca, pki-kra, pki-ocsp, pki-tks, pki-tps
7.2.1. Installing Certificate System Packages in non-TMS Environments
# yum install pki-ca redhat-pki-server-theme pki-console \ redhat-pki-console-theme pki-kra pki-ocsp
7.2.2. Installing Certificate System Packages in TMS Environments
# yum install redhat-pki
7.2.3. Updating Certificate System Packages
- Follow instructions in Section 7.2.4, “Determining Certificate System Product Version” to check the product version.
- Execute
# yum update
The command above updates the whole system including the RHCS packages.Note
We suggest scheduling a maintenance window during which you can take the PKI infrastructure offline to install the update.Important
Updating Certificate System requires the PKI infrastructure to be restarted. - Then check version again by following Section 7.2.4, “Determining Certificate System Product Version”.The version number should confirm that the update was successfully installed.
--downloadonly
option in the above procedure:
yum update --downloadonly
/var/cache/yum/
directory. The yum update
will later use the packages if they are the latest versions.
7.2.4. Determining Certificate System Product Version
/usr/share/pki/CS_SERVER_VERSION
file. To display the version:
# cat /usr/share/pki/CS_SERVER_VERSION Red Hat Certificate System 9.4 (Batch Update 3)
http://host_name:port_number/ca/admin/ca/getStatus
http://host_name:port_number/kra/admin/kra/getStatus
http://host_name:port_number/ocsp/admin/ocsp/getStatus
http://host_name:port_number/tks/admin/tks/getStatus
http://host_name:port_number/tps/admin/tps/getStatus
Note
7.3. Installing Using the pkispawn
Utility
7.3.1. About the pkispawn
Utility
pkispawn
utility.
pkispawn
utility requires a configuration file. This file contains parameters that are grouped into sections. These sections are stacked, so that parameters defined in earlier sections can be overridden by parameters defined in later sections. The sections are read in the following order:
[DEFAULT]
[Tomcat]
- The subsystem-specific sections:
[CA]
,[KRA]
,[OCSP]
,[TKS]
, or[TPS]
pkispawn
:
- First reads the default values from the
/etc/pki/default.cfg
file.Important
Do not edit the/etc/pki/default.cfg
file. You will be instructed to create a configuration file that overrides the defaults when passed to thepkispawn
utility. Parameters not set in the configuration file use the defaults. For details about using a configuration file, see Section 7.3.2, “Two-step Installation Usingpkispawn
”. - Reads the administrator-provided configuration file mentioned above to override the default values.
- Performs the installation of the requested PKI subsystem.
- Passes the settings to a Java servlet that performs the configuration based on the settings.
pkispawn
and examples, see the pkispawn(8) and pki_default.cfg(5) man pages.
pkispawn
”.
pkispawn
(TMS-only)”.
7.3.2. Two-step Installation Using pkispawn
pkispawn
two-step installation to enable the administrator to manually update configuration files between the two parts of the installation.
two-step installation
comes from the fact that the pkispawn
utility is often run twice with a slightly different set of parameters in its overwrite configuration file to complete the installation.
- Installation using the
pkispawn
Utility (Step 1)During this step,pkispawn
copies configuration files from the/usr/share/pki/
directory to the instance-specific/etc/pki/instance_name/
directory. Additionally,pkispawn
sets the settings based on values defined in the deployment configuration file.This part of the installation contains the following substeps: - Between-step configuration and customization
- Configuration Using the
pkispawn
Utility (Step 2)During this step,pkispawn
is run to continue the installation based on the configuration files in the instance-specific/etc/pki/instance_name/
directory.For details about this part of the installation see Section 7.3.2.4, “Starting thepkispawn
Step Two Installation”.
7.3.2.1. Creating the Configuration File for the First Step of the Installation
pkispawn
configuration settings, such as /root/pki/config.subsystem.txt
, and fill it with the settings described below. Every setting must be added.
Important
Subsystem-independent Settings
[DEFAULT]
section:- Set a unique instance name:
pki_instance_name=instance_name
- Set the host name and security domain name:
pki_host=server.example.com pki_security_domain_name=example.com Security Domain pki_security_domain_user=caadmin pki_security_domain_password=SD password
Note
Certificate System creates unique certificate nicknames based on these parameters and the instance name. The uniqueness of certificate nicknames is very important in keeping the HSM token shared by multiple PKI instances functional. - Set the port numbers for the HTTP and HTTPS protocols:
pki_https_port=port_number pki_http_port=port_number
Important
To run more than one Certificate System instance on the same host, you must set ports in thepki_https_port
andpki_http_port
parameters that are not used by any other service on the host. By default, Certificate System uses port8080
for HTTP and8443
for HTTPS. - Set the HSM-specific parameters:
pki_hsm_enable=True pki_hsm_libfile=HSM_PKCS11_library_path pki_hsm_modulename=HSM_module_name pki_token_name=HSM_token_name pki_token_password=HSM_token_password pki_audit_signing_token=HSM_token_name pki_subsystem_token=HSM_token_name pki_sslserver_token=HSM_token_name
For further details, see Section 6.4.4, “Preparing for Installing Certificate System with an HSM”. - If building an RSA Certificate System instance, use the following configuration:
pki_admin_key_algorithm=SHA256withRSA pki_admin_key_size=4096 pki_admin_key_type=rsa pki_sslserver_key_algorithm=SHA256withRSA pki_sslserver_key_size=4096 pki_sslserver_key_type=rsa pki_subsystem_key_algorithm=SHA256withRSA pki_subsystem_key_size=4096 pki_subsystem_key_type=rsa pki_audit_signing_key_algorithm=SHA256withRSA pki_audit_signing_key_size=4096 pki_audit_signing_key_type=rsa pki_audit_signing_signing_algorithm=SHA256withRSA
Allowed choices for thekey_algorithm
parameters are:SHA256withRSA
SHA384withRSA
SHA512withRSA
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowed
parameter in the CA'sCS.cfg
file. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (RSA) must matchkey_type
(rsa
).Allowed choices forkey_type
is onlyrsa
.Allowed choices forkey_size
are2048
and4096
. - To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:
pki_admin_key_algorithm=SHA256withEC pki_admin_key_size=nistp256 pki_admin_key_type=ecc pki_sslserver_key_algorithm=SHA256withEC pki_sslserver_key_size=nistp256 pki_sslserver_key_type=ecc pki_subsystem_key_algorithm=SHA256withEC pki_subsystem_key_size=nistp256 pki_subsystem_key_type=ecc pki_audit_signing_key_algorithm=SHA256withEC pki_audit_signing_key_size=nistp256 pki_audit_signing_key_type=ecc pki_audit_signing_signing_algorithm=SHA256withEC
Allowed choices for thekey_algorithm
parameters are:SHA256withEC
SHA384withEC
SHA512withEC
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowed
parameter in the CA'sCS.cfg
file. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (EC) must matchkey_type
(ecc
).Allowed choices forkey_size
are:nistp256
nistp384
nistp521
Allowed choice forkey_type
isecc
- Set the client directory of the bootstrap
admin
user:pki_client_dir=bootstrap_admin_directory
By default, the path is set to~/.dogtag/instance_name/
Important
Thepki_admin_*
andpki_client_*
parameters belong to the bootstrap user that is automatically created by the installation process. For further information about default roles (privileges) and the bootstrap user, see Section 2.6.6, “Users, Authorization, and Access Controls”.For descriptions about the parameters covered in this section, see the pki_default.cfg(5) man page. - Set various passwords for the bootstrap
admin
user:pki_admin_password=password pki_client_database_password=password pki_client_pkcs12_password=password
- Set the parameters for the LDAPS connection to Directory Server running on the same host:
pki_ds_database=back-end database name pki_ds_hostname=hostname pki_ds_secure_connection=True pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate pki_ds_password=password
- If you use a self-signed certificate in Directory Server use the following command to export it from the Directory Server's Network Security Services (NSS) database:
# certutil -L -d /etc/dirsrv/slapd-instance_name/ \ -n "server-cert" -a -o /root/ds.crt
[Tomcat]
section:- Set the Tomcat JServ Protocol (AJP) port:
pki_ajp_port=Tomcat_AJP_port
- Set the Tomcat server port:
pki_tomcat_server_port=Tomcat_server_port
Important
To run more than one PKI subsystem instance on the same host, you must set ports in thepki_ajp_port
andpki_tomcat_server_port
parameters that are not used by any other service on the host. By default, thepki_ajp_port
is set to8009
andpki_tomcat_server_port
to8005
.
pkispawn
single-step Installation, see Section 7.3.3.1, “Creating the Configuration File for pkispawn single-step Installation”.
CA Settings
[CA]
section to install a CA:
- Enable random serial numbers by adding following setting:
pki_random_serial_numbers_enable=true
- Set the following parameters to specify the data of the bootstrap
admin
user, which will be automatically created during the installation:pki_admin_nickname=bootstrap_CA_admin pki_admin_name=bootstrap_CA_administrator_name pki_admin_uid=caadmin pki_admin_email=caadmin@example.com
Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create actual administrator, agent, and auditor accounts. - Specify the HSM token for the subsystem-dependent certificates:
pki_ca_signing_token=HSM_token_name pki_ocsp_signing_token=HSM_token_name
- If building an RSA-based CA, use the following configuration:
pki_ca_signing_key_algorithm=SHA256withRSA pki_ca_signing_key_size=4096 pki_ca_signing_key_type=rsa pki_ca_signing_signing_algorithm=SHA256withRSA pki_ocsp_signing_key_algorithm=SHA256withRSA pki_ocsp_signing_key_size=4096 pki_ocsp_signing_key_type=rsa pki_ocsp_signing_signing_algorithm=SHA256withRSA
Allowed choices for thekey_algorithm
parameters are:SHA256withRSA
SHA384withRSA
SHA384withRSA
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowed
parameter in the CA'sCS.cfg
file. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (RSA) must matchkey_type
(rsa
).Allowed choices forkey_size
parameters are:2048
4096
Allowed choices forkey_type
parameters are onlyrsa
. - By default, the key type for system certificates is
rsa
and the key length is2048
bit. To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:pki_ocsp_signing_key_algorithm=SHA256withEC pki_ocsp_signing_key_size=nisp256 pki_ocsp_signing_key_type=ecc pki_ocsp_signing_signing_algorithm=SHA256withEC
Allowed choices forkey_algorithm
parameters are:SHA256withEC
SHA384withEC
SHA512withEC
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowed
parameter in the CA'sCS.cfg
file. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (EC) must matchkey_type
(ecc
).Allowed choices forkey_size
parameters are:nistp256
nistp384
nistp521
Allowed choices forkey_type
parameters isecc
.
Settings for Other Subsystems
[CA]
, [KRA]
, or [OCSP]
section to install a subordinate CA, KRA, or OCSP:
- Subsystems that are not a root CA use the two-step installation mechanism that is sometimes referred to as External CA. For the first step, add the following parameters under each respective subsystem-specific section:
pki_external=True pki_external_step_two=False
- This step depends on the subsystem you are installing:
- Subordinate CA
- Add the following settings to the
[CA]
section:- Add all settings from the
[CA]
section of the root CA. - Set the output paths for the system certificate signing requests (CSR):
pki_ca_signing_csr_path=path pki_ocsp_signing_csr_path=path pki_audit_signing_csr_path=path pki_sslserver_csr_path=path pki_subsystem_csr_path=path pki_admin_csr_path=path
- OCSP
- Set the following in the
[OCSP]
section:- Specify the following parameters to set the data of the bootstrap OCSP
admin
user which is automatically created during the installation:pki_admin_nickname=bootstrap_OCSP_admin pki_admin_name=bootstrap_OCSP_administrator_name pki_admin_uid=ocspadmin pki_admin_email=ocspadmin@example.com
Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create actual administrator, agent, and auditor accounts. - Specify the HSM token for the subsystem-dependent certificates:
pki_ocsp_signing_token=HSM_token_name
- If building an RSA Certificate System instance, use the following configuration:
pki_ocsp_signing_key_algorithm=SHA256withRSA pki_ocsp_signing_key_size=4096 pki_ocsp_signing_key_type=rsa pki_ocsp_signing_signing_algorithm=SHA256withRSA
Allowed choices for thekey_algorithm
parameters are:SHA256withRSA
SHA384withRSA
SHA384withRSA
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowed
parameter in the CA'sCS.cfg
file. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (RSA) must matchkey_type
(rsa
).Allowed choices forkey_size
parameters are:2048
4096
Allowed choices forkey_type
parameters are onlyrsa
.Note
It is suggested to match your CA instance type (RSA or ECC) with your OCSP responder type (RSA or ECC). - To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:
pki_ocsp_signing_key_algorithm=SHA256withEC pki_ocsp_signing_key_size=nisp256 pki_ocsp_signing_key_type=ecc pki_ocsp_signing_signing_algorithm=SHA256withEC
Allowed choices for thekey_algorithm
parameters are:SHA256withEC
SHA384withEC
SHA512withEC
Note
You can set this parameter to each value specified in theca.profiles.defaultSigningAlgsAllowed
parameter in the CA'sCS.cfg
file. For details, see the Signing Algorithm Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).Signature algorithm (EC) must matchkey_type
(ecc
).Allowed choices forkey_size
parameters are:nistp256
nistp384
nistp521
Allowed choices forkey_type
parameters are onlyecc
.Note
It is suggested to match your CA instance type (RSA or ECC) with your OCSP responder type (RSA or ECC). - Set the output paths for the system certificate signing requests (CSR):
pki_ocsp_signing_csr_path=path pki_audit_signing_csr_path=path pki_sslserver_csr_path=path pki_subsystem_csr_path=path pki_admin_csr_path=path
- KRA
- Set the following in the
[KRA]
section:- Specify the following parameters to set the data of the bootstrap KRA
admin
user which is automatically created during the installation:pki_admin_nickname=bootstrap_KRA_admin pki_admin_name=bootstrap_KRA_administrator_name pki_admin_uid=kraadmin pki_admin_email=kraadmin@example.com
Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create actual administrator, agent, and auditor accounts. - Specify the HSM token for the subsystem-dependent certificates:
pki_transport_token=HSM_token_name pki_storage_token=HSM_token_name
- RSA is the only key type supported for both the KRA storage and transport certificates. By default, the key length is
2048
bit. To choose a4096
bit key instead, add the following parameters:pki_transport_key_size=4096 pki_storage_key_size=4096
- Set the output paths for the system certificate signing requests (CSR):
pki_kra_signing_csr_path=path pki_audit_signing_csr_path=path pki_sslserver_csr_path=path pki_subsystem_csr_path=path pki_admin_csr_path=path
7.3.2.2. Starting the pkispawn
Step One Installation
- For a root CA:
# pkispawn -f /root/pki/config.root-CA.txt -s CA
- For a subordinate CA or other non-CA subsystems:
# pkispawn -f /root/pki/config.subsystem.txt -s subsystem
Replace subsystem with one of the following subsystems:CA
,KRA
, orOCSP
. For example, for a KRA installation:# pkispawn -f /root/pki/config.KRA.txt -s KRA
7.3.2.3. Configuration Between the Two pkispawn
Installation Steps
pkispawn
Step One Installation” has finished successfully, you can manually update the instance-specific configuration files before Section 7.3.2.4, “Starting the pkispawn
Step Two Installation” is performed, where the actual configuration begins.
pkispawn
procedure.
7.3.2.3.1. Enabling Signed Audit Logging
7.3.2.3.2. Setting the KRA into Encryption Mode
7.3.2.3.3. Enabling OCSP
7.3.2.4. Starting the pkispawn
Step Two Installation
pkispawn
Installation Steps”, start the second step of the pkispawn
installation:
- Root CA:
# pkispawn -f /root/pki/config.root-CA.txt -s CA --skip-installation
If the configuration step succeeds, thepkispawn
utility displays an installation summary. For example:================================================================ INSTALLATION SUMMARY ================================================================ Administrator's username: caadmin Administrator's PKCS #12 file: /root/.dogtag/instance_name/ca_admin_cert.p12 To check the status of the subsystem: systemctl status pki-tomcatd@instance_name.service To restart the subsystem: systemctl restart pki-tomcatd@instance_name.service The URL for the subsystem is: https://server.example.com:8443/ca/ PKI instances will be enabled upon system boot ================================================================
- Subordinate CA or other non-CA subsystems:
- Submit the CSRs to a CA to issue the certificates.One major difference between installing non-root CA subsystems and a root CA is that prior to running step two of the
pkispawn
utility, other subsystems require submitting the system certificate signing requests (CSR) to a CA:In the first step of the section called “Settings for Other Subsystems”, you added the*_csr_path
parameters in thepkispawn
configuration file for the subsystems to be installed. If the first step ofpkispawn
succeeded, Certificate System generated and stored the CSRs in the specified paths. These certificate requests are in PKCS#10 format and you must convert them to Certificate Management over CMS (CMC) format before submitting them to the CA. Follow instructions specified at 4.2. Creating Certificate Signing Requests in Red Hat Certificate System Administration Guide. You need the resulting system certificates when you execute the second step of thepkispawn
command.Additionally, you need the issuing CA's certificate chain in PKCS#7 format. To retrieve it:- Access the issuing CA's EE URL.
- Navigate to Retrieval → Import CA Certificate Chain and click Display the CA certificate chain in PKCS#7 for importing into a server.
- Click Submit.
- Copy the displayed PKCS#7-formatted output into a text file, such as
/root/pki/cert_chain.p7b
, on the Certificate System host.
- Create a configuration file for the second step of the
pkispawn
command:- Copy the
pkispawn
configuration file from the first step and edit the newly created file for step two of thepkispawn
command:- In the
[DEFAULT]
section, set the path to the issuing CA's certificate chain file you prepared in the previous step and the CA signing certificate's nickname. For example:[DEFAULT] pki_ca_signing_nickname=CA Signing Certificate pki_ca_signing_cert_path=/root/pki/cert_chain.p7b
- Add the following settings to the subsystem-specific section (
[CA]
,[KRA]
, or[OCSP]
) depending on the subsystem you install:- Subordinate CA
pki_ca_signing_crt_path=/root/pki/subsystem/ocsp_signing.crt pki_subsystem_crt_path=/root/pki/subsystem/subsystem.crt pki_sslserver_crt_path=/root/pki/subsystem/sslserver.crt pki_audit_signing_crt_path=/root/pki/subsystem/ca_audit_signing.crt pki_admin_crt_path=/root/pki/subsystem/ca_admin.crt pki_external_step_two=True
- OCSP
pki_ocsp_signing_crt_path=/root/pki/subsystem/ocsp_signing.crt pki_subsystem_crt_path=/root/pki/subsystem/subsystem.crt pki_sslserver_crt_path=/root/pki/subsystem/sslserver.crt pki_audit_signing_crt_path=/root/pki/subsystem/ocsp_audit_signing.crt pki_admin_crt_path=/root/pki/subsystem/ocsp_admin.crt pki_external_step_two=True
- KRA
pki_storage_crt_path=/root/pki/subsystem/kra_storage.crt pki_transport_crt_path=/root/pki/subsystem/kra_transport.crt pki_subsystem_crt_path=/root/pki/subsystem/subsystem.crt pki_sslserver_crt_path=/root/pki/subsystem/sslserver.crt pki_audit_signing_crt_path=/root/pki/subsystem/kra_audit_signing.crt pki_admin_crt_path=/root/pki/subsystem/kra_admin.crt pki_external_step_two=True
- Run the pkispawn command:
# pkispawn -f /root/pki/config.subsystem.txt -s subsystem
Replace subsystem with one of the following subsystems:CA
,KRA
, orOCSP
. For example, for a KRA installation:# pkispawn -f /root/pki/config.KRA.txt -s KRA
7.3.3. Single-step Installation Using pkispawn
(TMS-only)
pkispawn
single-step installation
process.
pkispawn
requires a configuration file.
7.3.3.1. Creating the Configuration File for pkispawn single-step Installation
pkispawn
configuration file.
[DEFAULT]
section add the following:
pki_security_domain_hostname=example.redhat.com pki_security_domain_https_port=8443 pki_security_domain_user=caadmin pki_security_domain_password=[SD password]
[TKS]
or [TPS]
) as following:
- TKS
- Set the following in the
[TKS]
section:- Specify the following parameters to set the data of the bootstrap
TKS
admin user which is automatically created during the installation:pki_admin_nickname=bootstrap_TKS_admin pki_admin_name=bootstrap_TKS_administrator_name pki_admin_uid=tksadmin pki_admin_email=tksadmin@example.com
Red Hat Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create the administrator, and auditor accounts.
- TPS
- Set the following in the
[TPS]
section:- Specify the following parameters to set the data of the bootstrap
TPS
admin user, which is automatically created during the installation:pki_admin_nickname=bootstrap_TPS_admin pki_admin_name=bootstrap_TPS_administrator_name pki_admin_uid=tpsadmin pki_admin_email=tpsadmin@example.com
Red Hat Certificate System assigns administrator and agent privileges to this bootstrap account. Use this account after the installation to create the administrator, and the auditor accounts. - Set the LDAP base DN of the
TPS
authentication database:pki_authdb_basedn=base_DN_of_the_TPS_authentication_database
- Enable the server-side key generation and archival:
pki_enable_server_side_keygen=True
7.3.3.2. Running pkispawn for single-step Installation
# pkispawn -f /root/pki/config.TKS.txt -s TKS
# pkispawn -f /root/pki/config.TPS.txt -s TPS
7.3.3.3. Post-Installation for Single-Step Installation
7.4. Post-installation Tasks
pkispawn
utility is complete, certain actions are required after the installation. In addition, some optional actions would also be helpful, depending on the site's preferences.
- Configuring or adding certificate enrollment profiles (CA). For details, see Section 11.1, “Creating and Editing Certificate Profiles Directly on the File System”
7.4.1. Setting Date/Time for RHCS
7.4.2. Replacing a Temporary Self-Signed Certificate in Directory Server (CA)
7.4.3. Enabling TLS Client Authentication for the Internal LDAP Server
7.4.4. Configuring Session Timeout
7.4.5. CRL or Certificate Publishing
7.4.6. Disabling Certificate Enrollment Profiles (CA)
7.4.7. Enabling Access Banner
7.4.8. Enabling the Watchdog Service
nuxwdog
) service provides secure system password management.
7.4.9. Configuration for CMC Enrollment and Revocation (CA)
- For details about enabling the CMC Shared Token Feature, see Section 9.6.3, “Enabling the CMC Shared Secret Feature”.
- For details about enabling the
PopLinkWittness
feature, see Section 9.6.2, “Enabling thePopLinkWittnessV2
Feature”. - For details about enabling
CMCRevoke
for the web user interface, see Section 9.6.4, “Enabling CMCRevoke for the Web User Interface”.
7.4.10. Requiring TLS client-authentication for the Java Console
pkiconsole
to use TLS Client Certificate Authentication”.
7.4.11. Creating a Role User
7.4.12. Removing the Bootstrap User
7.4.13. Disabling Multi-role Support
7.4.14. KRA Configurations
7.4.14.1. Adding Requirement for Multiple Agent Approval for Key Recovery Authority (KRA)
7.4.14.2. Configuring KRA Encryption Settings
7.4.15. Setting up Users to use User Interfaces
Chapter 8. Troubleshooting Installation
8.1. Frequently Asked Questions
- 8.1.1. Installation
- Q: I cannot see any Certificate System packages or updates.
- Q: The init script returned an OK status, but my CA instance does not respond. Why?
- Q: I want to customize the subject name for the CA signing certificate, but do not see a way to do this using the pkispawn interactive install mode.
- Q: I am seeing an HTTP 500 error code when I try to connect to the web services pages after configuring my subsystem instance.
- 8.1.2. Java Console
- Q: I cannot open the pkiconsole and I am seeing Java exceptions in stdout.
- Q: I tried to run pkiconsole, and I got Socket exceptions in stdout. Why?
- Q: I attempt to start the console, and the system prompts me for my user name and password. After I enter these credentials, the console fails to appear.
8.1.1. Installation
journal
log by running the following command:
journalctl -u pki-tomcatd@instance_name.service
journalctl -u pki-tomcatd-nuxwdog@instance_name.service (if using the nuxwdog watchdog
)
/var/log/pki/instance_name/subsystem_type/debug
.
catalina.out
file:
Oct 29, 2010 4:15:44 PM org.apache.coyote.http11.Http11Protocol init INFO: Initializing Coyote HTTP/1.1 on http-9080 java.lang.reflect.InvocationTargetException at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:64) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:615) at org.apache.catalina.startup.Bootstrap.load(Bootstrap.java:243) at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:408) Caused by: java.lang.UnsatisfiedLinkError: jss4
libnss3.so
in the path. Check this with this command:
ldd /usr/lib64/libjss4.so
libnss3.so
is not found, set the correct classpath in the /etc/sysconfig/instance_name
configuration file. Then restart the CA using the following command:
systemctl restart pki-tomcatd@instance_name.service
systemctl restart pki-tomcatd-nuxwdog@instance_name.service (if using the nuxwdog watchdog
)
pkispawn
interactive install mode.
/etc/pki/default.cfg
file is required. See the pkispawn(8) and pki_default.cfg(5) man pages.
journal
, system
, and debug
log files for the instance to see what errors have occurred. This lists a couple of common errors, but there are many other possibilities.
Error #1: The LDAP database is not running.
journal
file that the instance is not ready:
java.io.IOException: CS server is not ready to serve. com.netscape.cms.servlet.base.CMSServlet.service(CMSServlet.java:409) javax.servlet.http.HttpServlet.service(HttpServlet.java:688)
5558.main - [29/Oct/2010:11:13:40 PDT] [8] [3] In Ldap (bound) connection pool to host ca1 port 389, Cannot connect to LDAP server. Error: netscape.ldap.LDAPException: failed to connect to server ldap://ca1.example.com:389 (91)
debug
log:
[29/Oct/2010:11:39:10][main]: CMS:Caught EBaseException Internal Database Error encountered: Could not connect to LDAP server host ca1 port 389 Error netscape.ldap.LDAPException: failed to connect to server ldap://ca1:389 (91) at com.netscape.cmscore.dbs.DBSubsystem.init(DBSubsystem.java:262)
Error #2: A VPN is blocking access.
journal
log file for the instance's Tomcat service shows a series of connection errors that result in the HTTP 500 error:
May 26, 2010 7:09:48 PM org.apache.catalina.core.StandardWrapperValve invoke SEVERE: Servlet.service() for servlet services threw exception java.io.IOException: CS server is not ready to serve. at com.netscape.cms.servlet.base.CMSServlet.service(CMSServlet.java:441) at javax.servlet.http.HttpServlet.service(HttpServlet.java:803) at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:269) at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:188) at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:210) at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:172) at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:127) at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:117) at org.apache.catalina.valves.AccessLogValve.invoke(AccessLogValve.java:542) at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:108) at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:151) at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:870) at org.apache.coyote.http11.Http11BaseProtocol$Http11ConnectionHandler.processConnection(Http11BaseProtocol.java:665) at org.apache.tomcat.util.net.PoolTcpEndpoint.processSocket(PoolTcpEndpoint.java:528) at org.apache.tomcat.util.net.LeaderFollowerWorkerThread.runIt(LeaderFollowerWorkerThread.java:81) at org.apache.tomcat.util.threads.ThreadPool$ControlRunnable.run(ThreadPool.java:685) at java.lang.Thread.run(Thread.java:636)
8.1.2. Java Console
pkiconsole
and I am seeing Java exceptions in stdout.
alternatives --config java
to see what JRE is selected. Red Hat Certificate System requires OpenJDK 1.7.
pkiconsole
, and I got Socket exceptions in stdout. Why?
server.xml
) or the wrong port was given to access the admin interface.
NSS Cipher Supported '0xff04' java.io.IOException: SocketException cannot read on socket at org.mozilla.jss.ssl.SSLSocket.read(SSLSocket.java:1006) at org.mozilla.jss.ssl.SSLInputStream.read(SSLInputStream.java:70) at com.netscape.admin.certsrv.misc.HttpInputStream.fill(HttpInputStream.java:303) at com.netscape.admin.certsrv.misc.HttpInputStream.readLine(HttpInputStream.java:224) at com.netscape.admin.certsrv.connection.JSSConnection.readHeader(JSSConnection.java:439) at com.netscape.admin.certsrv.connection.JSSConnection.initReadResponse(JSSConnection.java:430) at com.netscape.admin.certsrv.connection.JSSConnection.sendRequest(JSSConnection.java:344) at com.netscape.admin.certsrv.connection.AdminConnection.processRequest(AdminConnection.java:714) at com.netscape.admin.certsrv.connection.AdminConnection.sendRequest(AdminConnection.java:623) at com.netscape.admin.certsrv.connection.AdminConnection.sendRequest(AdminConnection.java:590) at com.netscape.admin.certsrv.connection.AdminConnection.authType(AdminConnection.java:323) at com.netscape.admin.certsrv.CMSServerInfo.getAuthType(CMSServerInfo.java:113) at com.netscape.admin.certsrv.CMSAdmin.run(CMSAdmin.java:499) at com.netscape.admin.certsrv.CMSAdmin.run(CMSAdmin.java:548) at com.netscape.admin.certsrv.Console.main(Console.java:1655)
/usr/bin/pkiconsole
file, and add the following lines:
============================================ ${JAVA} ${JAVA_OPTIONS} -cp ${CP} -Djava.util.prefs.systemRoot=/tmp/.java -Djava.util.prefs.userRoot=/tmp/java com.netscape.admin.certsrv.Console -s instanceID -D 9:all -a $1 ---------- note: "-D 9:all" is for verbose output on the console. ============================================
8.2. Hardware Security Modules
8.2.1. Detecting Tokens
TokenInfo
utility, pointing to the alias
directory for the subsystem instance. This is a Certificate System tool which is available after the Certificate System packages are installed.
# TokenInfo /var/lib/pki/pki-tomcat/alias
8.2.2. Viewing Tokens
modutil
utility.
- Change to the instance
alias
directory. For example:# cd /var/lib/pki/pki-tomcat/alias
- 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
Part III. Configuring Certificate System
Chapter 9. The Certificate System Configuration Files
CS.cfg
file. This chapter covers basic information about and rules for editing the CS.cfg
file. This chapter also describes some other useful configuration files used by the subsystems, such as password and web services files.
9.1. File and Directory Locations for Certificate System Subsystems
pkispawn
command.
9.1.1. Instance-specific Information
Table 9.1. Certificate Server Port Assignments (Default)
Port Type | Port Number | Notes |
---|---|---|
Secure port | 8443 | Main port used to access PKI services by end-users, agents, and admins over HTTPS. |
Insecure port | 8080 | Used to access the server insecurely for some end-entity functions over HTTP. Used for instance to provide CRLs, which are already signed and therefore need not be encrypted. |
AJP port | 8009 | Used to access the server from a front end Apache proxy server through an AJP connection. Redirects to the HTTPS port. |
Tomcat port | 8005 | Used by the web server. |
9.1.2. CA Subsystem Information
Table 9.2. CA Subsystem Information for the Default Instance (pki-tomcat)
Setting | Value |
---|---|
Main directory | /var/lib/pki/pki-tomcat/ca/ |
Configuration directory | /var/lib/pki/pki-tomcat/ca/conf/[a] |
Configuration file | /var/lib/pki/pki-tomcat/ca/conf/CS.cfg |
Subsystem certificates | CA signing certificate |
OCSP signing certificate (for the CA's internal OCSP service) | |
TLS server certificate | |
Audit log signing certificate | |
Subsystem certificate[b] | |
Security databases | /var/lib/pki/pki-tomcat/alias/[c] |
Log files | /var/lib/pki/pki-tomcat/ca/logs/[d] |
Install log | /var/log/pki/pki-ca-spawn.date.log |
Uninstall log | /var/log/pki/pki-ca-destroy.date.log |
Audit logs | /var/log/pki/pki-tomcat/ca/signedAudit/ |
Profile files | /var/lib/pki/pki-tomcat/ca/profiles/ca/ |
Email notification templates | /var/lib/pki/pki-tomcat/ca/emails/ |
Web services files | Agent services: /var/lib/pki/pki-tomcat/ca/webapps/ca/agent/ |
Admin services: /var/lib/pki/pki-tomcat/ca/webapps/ca/admin/ | |
End user services: /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/ | |
[a]
Aliased to /etc/pki/pki-tomcat/ca/
[b]
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.
[c]
Note that all subsystem certificates are stored in the instance security database
[d]
Aliased to /var/log/pki/pki-tomcat/ca/
|
9.1.3. KRA Subsystem Information
Table 9.3. KRA Subsystem Information for the Default Instance (pki-tomcat)
Setting | Value |
---|---|
Main directory | /var/lib/pki/pki-tomcat/kra/ |
Configuration directory | /var/lib/pki/pki-tomcat/kra/conf/[a] |
Configuration file | /var/lib/pki/pki-tomcat/kra/conf/CS.cfg |
Subsystem certificates | Transport certificate |
Storage certificate | |
TLS server certificate | |
Audit log signing certificate | |
Subsystem certificate[b] | |
Security databases | /var/lib/pki/pki-tomcat/alias/[c] |
Log files | /var/lib/pki/pki-tomcat/kra/logs/ |
Install log | /var/log/pki/pki-kra-spawn-date.log |
Uninstall log | /var/log/pki/pki-kra-destroy-date.log |
Audit logs | /var/log/pki/pki-tomcat/kra/signedAudit/ |
Web services files | Agent services: /var/lib/pki/pki-tomcat/kra/webapps/kra/agent/ |
Admin services: /var/lib/pki/pki-tomcat/kra/webapps/kra/admin/ | |
[a]
Linked to /etc/pki/pki-tomcat/kra/
[b]
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.
[c]
Note that all subsystem certificates are stored in the instance security database
|
9.1.4. OCSP Subsystem Information
Table 9.4. OCSP Subsystem Information for the Default Instance (pki-tomcat)
Setting | Value |
---|---|
Main directory | /var/lib/pki/pki-tomcat/ocsp/ |
Configuration directory | /var/lib/pki/pki-tomcat/ocsp/conf/[a] |
Configuration file | /var/lib/pki/pki-tomcat/ocsp/conf/CS.cfg |
Subsystem certificates | Transport certificate |
Storage certificate | |
TLS server certificate | |
Audit log signing certificate | |
Subsystem certificate[b] | |
Security databases | /var/lib/pki/pki-tomcat/alias/[c] |
Log files | /var/lib/pki/pki-tomcat/ocsp/logs/ |
Install log | /var/log/pki/pki-ocsp-spawn-date.log |
Uninstall log | /var/log/pki/pki-ocsp-destroy-date.log |
Audit logs | /var/log/pki/pki-tomcat/ocsp/signedAudit/ |
Web services files | Agent services: /var/lib/pki/pki-tomcat/ocsp/webapps/ocsp/agent/ |
Admin services: /var/lib/pki/pki-tomcat/ocsp/webapps/ocsp/admin/ | |
[a]
Linked to /etc/pki/pki-tomcat/ocsp/
[b]
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.
[c]
Note that all subsystem certificates are stored in the instance security database
|
9.1.5. TKS Subsystem Information
Table 9.5. TKS Subsystem Information for the Default Instance (pki-tomcat)
Setting | Value |
---|---|
Main directory | /var/lib/pki/pki-tomcat/tks/ |
Configuration directory | /var/lib/pki/pki-tomcat/tks/conf/[a] |
Configuration file | /var/lib/pki/pki-tomcat/tks/conf/CS.cfg |
Subsystem certificates | Transport certificate |
Storage certificate | |
TLS server certificate | |
Audit log signing certificate | |
Subsystem certificate[b] | |
Security databases | /var/lib/pki/pki-tomcat/alias/[c] |
Log files | /var/lib/pki/pki-tomcat/tks/logs/ |
Install log | /var/log/pki/pki-tks-spawn-date.log |
Uninstall log | /var/log/pki/pki-tks-destroy-date.log |
Audit logs | /var/log/pki/pki-tomcat/tks/signedAudit/ |
Web services files | Agent services: /var/lib/pki/pki-tomcat/tks/webapps/tks/agent/ |
Admin services: /var/lib/pki/pki-tomcat/tks/webapps/tks/admin/ | |
[a]
Linked to /etc/pki/pki-tomcat/tks/
[b]
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.
[c]
Note that all subsystem certificates are stored in the instance security database
|
9.1.6. TPS Subsystem Information
Table 9.6. TPS Subsystem Information for the Default Instance (pki-tomcat)
Setting | Value |
---|---|
Main directory | /var/lib/pki/pki-tomcat/tps/ |
Configuration directory | /var/lib/pki/pki-tomcat/tps/conf/[a] |
Configuration file | /var/lib/pki/pki-tomcat/tps/conf/CS.cfg |
Subsystem certificates | Transport certificate |
Storage certificate | |
TLS server certificate | |
Audit log signing certificate | |
Subsystem certificate[b] | |
Security databases | /var/lib/pki/pki-tomcat/alias/[c] |
Log files | /var/lib/pki/pki-tomcat/tps/logs/ |
Install log | /var/log/pki/pki-tps-spawn-date.log |
Uninstall log | /var/log/pki/pki-tps-destroy-date.log |
Audit logs | /var/log/pki/pki-tomcat/tps/signedAudit/ |
Web services files | Agent services: /var/lib/pki/pki-tomcat/tps/webapps/tps/agent/ |
Admin services: /var/lib/pki/pki-tomcat/tps/webapps/tps/admin/ | |
[a]
Linked to /etc/pki/pki-tomcat/tps/
[b]
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.
[c]
Note that all subsystem certificates are stored in the instance security database
|
9.1.7. Shared Certificate System Subsystem File Locations
Table 9.7. Subsystem File Locations
Directory Location | Contents | |||||
---|---|---|---|---|---|---|
/var/lib/instance_name | Contains the main instance directory, which is the location for user-specific directory locations and customized configuration files, profiles, certificate databases, web files, and other files for the subsystem instance. | |||||
/usr/share/java/pki | Contains Java archive files shared by the Certificate System subsystems. Along with shared files for all subsystems, there are subsystem-specific files in subfolders:
| |||||
/usr/share/pki | 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:
| |||||
/usr/bin | Contains the pkispawn and pkidestroy instance configuration scripts and tools (Java, native, and security) shared by the Certificate System subsystems. | |||||
/var/lib/tomcat5/common/lib | Contains links to Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. Not used by the TPS subsystem. | |||||
/var/lib/tomcat5/server/lib | Contains links to Java archive files used by the local Tomcat web server and shared by the Certificate System subsystems. Not used by the TPS subsystem. | |||||
/usr/shared/pki | Contains the Java archive files used by the Tomcat server and applications used by the Certificate System instances. Not used by the TPS subsystem. | |||||
| Contains Apache modules used by the TPS subsystem. Not used by the CA, KRA, OCSP, or TKS subsystems. | |||||
| Mozilla LDAP SDK tools used by the TPS subsystem. Not used by the CA, KRA, OCSP, or TKS subsystems. |
9.2. CS.cfg Files
CS.cfg
.
CS.cfg
, an ASCII file, 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.
CS.cfg
configuration file directly, and in some cases this is the easiest way to manage the subsystem.
9.2.1. Locating the CS.cfg File
CS.cfg
. The contents of the file for each subsystem instance is different depending on the way the subsystem was configured, additional settings and configuration (like adding new profiles or enabling self-tests), and the type of subsystem.
CS.cfg
file is located in the configuration directory for the instance.
/var/lib/pki/instance_name/conf
/var/lib/pki/pki-tomcat/ca/conf
9.2.2. Editing the Configuration File
Warning
CS.cfg
file:
- Stop the subsystem instance.
systemctl stop pki-tomcatd@instance_name.service
ORsystemctl stop pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)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. - Open the
/var/lib/pki/instance_name/conf
directory. - Open the
CS.cfg
file in a text editor. - Edit the parameters in the file, and save the changes.
- Start the subsystem instance.
systemctl start pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)
9.2.3. Overview of the CS.cfg Configuration File
CS.cfg
, which contains all of the settings for the instance, such as plug-ins and Java classes for configuration. The parameters and specific settings are different depending on the type of subsystem, but, in a general sense, the CS.cfg
file defines these parts of the subsystem instance:
- Basic subsystem instance information, like its name, port assignments, instance directory, and hostname
- Logging
- Plug-ins and methods to authenticate to the instance's user directory (authorization)
- The security domain to which the instance belongs
- Subsystem certificates
- Other subsystems used by the subsystem instance
- Database types and instances used by the subsystem
- Settings for PKI-related tasks, like the key profiles in the TKS, the certificate profiles in the CA, and the required agents for key recovery in the KRA
CS.cfg
file a basic parameter=value format.
#comment parameter=value
CS.cfg
file, many of the parameter blocks have descriptive comments, commented out with a pound (#) character. Comments, blank lines, unknown parameters, or misspelled parameters are ignored by the server.
Note
Example 9.1. Logging Settings in the CS.cfg File
log.instance.System._000=## log.instance.System._001=## System Logging log.instance.System._002=## log.instance.System.bufferSize=512 log.instance.System.enable=true log.instance.System.expirationTime=0 log.instance.System.fileName=/var/lib/pki/pki-tomcat/ca/logs/system log.instance.System.flushInterval=5 log.instance.System.level=3 log.instance.System.maxFileSize=2000 log.instance.System.pluginName=file log.instance.System.rolloverInterval=2592000 log.instance.System.type=system
Example 9.2. Subsystem Authorization Settings
authz.impl._000=## authz.impl._001=## authorization manager implementations authz.impl._002=## authz.impl.BasicAclAuthz.class=com.netscape.cms.authorization.BasicAclAuthz authz.instance.BasicAclAuthz.pluginName=BasicAclAuthz
Note
- The values that need to be localized must be in UTF8 characters.
- The
CS.cfg
file supports forward slashes (/) in parameter values. If a back slash (\) is required in a value, it must be escaped with a back slash, meaning that two back slashes in a row must be used.
CS.cfg
file settings and parameters. These are not exhaustive references or examples of CS.cfg
file parameters. Also, the parameters available and used in each subsystem configuration file is very different, although there are similarities.
9.2.3.1. Basic Instance Parameters for the CA: pkispawn file ca.cfg
pkispawn
.
Example 9.3. Basic Instance Parameters for the CA
[DEFAULT] pki_admin_password=Secret.123 pki_client_pkcs12_password=Secret.123 pki_ds_password=Secret.123 # Optionally keep client databases pki_client_database_purge=False # Separated CA instance name and ports pki_instance_name=pki-ca pki_http_port=18080 pki_https_port=18443 # This Separated CA instance will be its own security domain pki_security_domain_https_port=18443 [Tomcat] # Separated CA Tomcat ports pki_ajp_port=18009 pki_tomcat_server_port=18005
Important
CS.cfg
file, it is not set in the CS.cfg
. The server configuration is set in the server.xml
file.
CS.cfg
and server.xml
must match for a working RHCS instance.
9.2.3.2. Logging Settings
CS.cfg
file.
log.instance.Transactions._000=## log.instance.Transactions._001=## Transaction Logging log.instance.Transactions._002=## log.instance.Transactions.bufferSize=512 log.instance.Transactions.enable=true log.instance.Transactions.expirationTime=0 log.instance.Transactions.fileName=/var/log/pki-ca/logs/transactions log.instance.Transactions.flushInterval=5 log.instance.Transactions.level=1 log.instance.Transactions.maxFileSize=2000 log.instance.Transactions.pluginName=file log.instance.Transactions.rolloverInterval=2592000 log.instance.Transactions.type=transaction
9.2.3.3. Authentication and Authorization Settings
CS.cfg
file sets how users are identified to access a subsystem instance (authentication) and what actions are approved (authorization) for each authenticated user.
SharedToken
that instantiates a JAVA plug-in named SharedSecret
.
auths.impl.SharedToken.class=com.netscape.cms.authentication.SharedSecret auths.instance.SharedToken.pluginName=SharedToken auths.instance.SharedToken.dnpattern= auths.instance.SharedToken.ldap.basedn=ou=People,dc=example,dc=org auths.instance.SharedToken.ldap.ldapauth.authtype=BasicAuth auths.instance.SharedToken.ldap.ldapauth.bindDN=cn=Directory Manager auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=Rule SharedToken auths.instance.SharedToken.ldap.ldapauth.clientCertNickname= auths.instance.SharedToken.ldap.ldapconn.host=server.example.com auths.instance.SharedToken.ldap.ldapconn.port=636 auths.instance.SharedToken.ldap.ldapconn.secureConn=true auths.instance.SharedToken.ldap.ldapconn.version=3 auths.instance.SharedToken.ldap.maxConns= auths.instance.SharedToken.ldap.minConns= auths.instance.SharedToken.ldapByteAttributes= auths.instance.SharedToken.ldapStringAttributes= auths.instance.SharedToken.shrTokAttr=shrTok
authz.impl.DirAclAuthz.class=com.netscape.cms.authorization.DirAclAuthz authz.instance.DirAclAuthz.ldap=internaldb authz.instance.DirAclAuthz.pluginName=DirAclAuthz authz.instance.DirAclAuthz.ldap._000=## authz.instance.DirAclAuthz.ldap._001=## Internal Database authz.instance.DirAclAuthz.ldap._002=## authz.instance.DirAclAuthz.ldap.basedn=dc=server.example.com-pki-ca authz.instance.DirAclAuthz.ldap.database=server.example.com-pki-ca authz.instance.DirAclAuthz.ldap.maxConns=15 authz.instance.DirAclAuthz.ldap.minConns=3 authz.instance.DirAclAuthz.ldap.ldapauth.authtype=SslClientAuth authz.instance.DirAclAuthz.ldap.ldapauth.bindDN=cn=Directory Manager authz.instance.DirAclAuthz.ldap.ldapauth.bindPWPrompt=Internal LDAP Database authz.instance.DirAclAuthz.ldap.ldapauth.clientCertNickname= authz.instance.DirAclAuthz.ldap.ldapconn.host=localhost authz.instance.DirAclAuthz.ldap.ldapconn.port=11636 authz.instance.DirAclAuthz.ldap.ldapconn.secureConn=true authz.instance.DirAclAuthz.ldap.multipleSuffix.enable=false
auths.impl.AgentCertAuth.class=com.netscape.cms.authentication.AgentCertAuthentication auths.instance.AgentCertAuth.agentGroup=Certificate Manager Agents auths.instance.AgentCertAuth.pluginName=AgentCertAuth
9.2.3.4. Subsystem Certificate Settings
ca.sslserver.cert=MIIDmDCCAoCgAwIBAgIBAzANBgkqhkiG9w0BAQUFADBAMR4wHAYDVQQKExVSZWR... ca.sslserver.certreq=MIICizCCAXMCAQAwRjEeMBwGA1UEChMVUmVkYnVkY29tcHV0ZXIgRG9tYWluMSQwIgYDV... ca.sslserver.nickname=Server-Cert cert-pki-ca ca.sslserver.tokenname=Internal Key Storage Token
9.2.3.5. Settings for Required Subsystems
conn.
and then the subsystem type and number.
conn.ca1.clientNickname=subsystemCert cert-pki-tps conn.ca1.hostadminport=server.example.com:9445 conn.ca1.hostagentport=server.example.com:9444 conn.ca1.hostport=server.example.com:9443 conn.ca1.keepAlive=true conn.ca1.retryConnect=3 conn.ca1.servlet.enrollment=/ca/ee/ca/profileSubmitSSLClient conn.ca1.servlet.renewal=/ca/ee/ca/profileSubmitSSLClient conn.ca1.servlet.revoke=/ca/subsystem/ca/doRevoke conn.ca1.servlet.unrevoke=/ca/subsystem/ca/doUnrevoke conn.ca1.timeout=100
9.2.3.6. Database Settings
internaldb
parameters, except for the TPS which configured it in the tokendb
parameters with a lot of other configuration settings.
internaldb._000=## internaldb._000=## internaldb._001=## Internal Database internaldb._002=## internaldb.basedn=o=pki-tomcat-ca-SD internaldb.database=pki-tomcat-ca internaldb.maxConns=15 internaldb.minConns=3 internaldb.ldapauth.authtype=SslClientAuth internaldb.ldapauth.clientCertNickname=HSM-A:subsystemCert pki-tomcat-ca internaldb.ldapconn.host=example.com internaldb.ldapconn.port=11636 internaldb.ldapconn.secureConn=true internaldb.multipleSuffix.enable=false
9.2.3.7. Enabling and Configuring a Publishing Queue
CS.cfg
file allows administrators to set other options for publishing, like the number of threads to use for publishing operations and the queue page size.
- Stop the CA server, so that you can edit the configuration files.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the CA's
CS.cfg
file.vim /var/lib/pki/instance_name/ca/conf/CS.cfg
- Set the
ca.publish.queue.enable
to true. If the parameter is not present, then add a line with the parameter.ca.publish.queue.enable=true
- Set other related publishing queue parameters:
ca.publish.queue.maxNumberOfThreads
sets the maximum number of threads that can be opened for publishing operations. The default is 3.ca.publish.queue.priorityLevel
sets the priority for publishing operations. The priority value ranges from-2
(lowest priority) to2
(highest priority). Zero (0) is normal priority and is also the default.ca.publish.queue.pageSize
sets the maximum number of requests that can be stored in the publishing queue page. The default is 40.ca.publish.queue.saveStatus
sets the interval to save its status every specified number of publishing operations. This allows the publishing queue to be recovered if the CA is restarted or crashes. The default is 200, but any non-zero number will recover the queue when the CA restarts. Setting this parameter to 0 disables queue recovery.
ca.publish.queue.maxNumberOfThreads=1 ca.publish.queue.priorityLevel=0 ca.publish.queue.pageSize=100 ca.publish.queue.saveStatus=200
Note
Settingca.publish.queue.enable
to false andca.publish.queue.maxNumberOfThreads
to 0 disables both the publishing queue and using separate threads for publishing issued certificates. - Restart the CA server.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
9.2.3.8. Settings for PKI Tasks
CS.cfg
file is used to configure the PKI tasks for every subsystem. The parameters are different for every single subsystem, without any overlap.
kra.noOfRequiredRecoveryAgents=1
CS.cfg
file for each subsystem to become familiar with its PKI task settings; the comments in the file are a decent guide for learning what the different parameters are.
- The CA configuration file lists all of the certificate profiles and policy settings, as well as rules for generating CRLs.
- The TPS configures different token operations.
- The TKS lists profiles for deriving keys from different key types.
- The OCSP sets key information for different key sets.
9.2.3.9. Changing DN Attributes in CA-Issued Certificates
Table 9.8. Allowed Characters for Value Types
Attribute | Value Type | Object Identifier |
---|---|---|
cn | DirectoryString | 2.5.4.3 |
ou | DirectoryString | 2.5.4.11 |
o | DirectoryString | 2.5.4.10 |
c | PrintableString , two-character | 2.5.4.6 |
l | DirectoryString | 2.5.4.7 |
st | DirectoryString | 2.5.4.8 |
street | DirectoryString | 2.5.4.9 |
title | DirectoryString | 2.5.4.12 |
uid | DirectoryString | 0.9.2342.19200300.100.1.1 |
mail | IA5String | 1.2.840.113549.1.9.1 |
dc | IA5String | 0.9.2342.19200300.100.1.2.25 |
serialnumber | PrintableString | 2.5.4.5 |
unstructuredname | IA5String | 1.2.840.113549.1.9.2 |
unstructuredaddress | PrintableString | 1.2.840.113549.1.9.8 |
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
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 aPrintableString
value. The string must have only printable characters.netscape.security.x509.IA5StringConverter
converts a string to anIA5String
value. The string must have only IA5String characters.netscape.security.x509.DirStrConverter
converts a string to aDirectoryString
. The string is expected to be inDirectoryString
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
X500Name.MY_ATTR.oid=1.2.3.4.5.6 X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter
9.2.3.9.1. Adding New or Custom Attributes
- Stop the Certificate Manager.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
/var/lib/pki/cs_instance/conf/
directory. - Open the configuration file,
CS.cfg
. - Add the new attributes to the configuration file.For example, to add three proprietary attributes,
MYATTR1
that is aDirectoryString
,MYATTR2
that is anIA5String
, andMYATTR3
that is aPrintableString
, 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
- Save the changes, and close the file.
- Restart the Certificate Manager.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
- Reload the enrollment page and verify the changes; the new attributes should show up in the form.
- 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
- Open the agent services page, and approve the request.
- When the certificate is issued, check the subject name. The certificate should show the new attribute values in the subject name.
9.2.3.9.2. Changing the DER-Encoding Order
DirectoryString
, so that the string is configurable since different clients support different encodings.
DirectoryString
is as follows:
X500Name.directoryStringEncodingOrder=encoding_list_separated_by_commas
Printable
IA5String
UniversalString
BMPString
UTF8String
X500Name.directoryStringEncodingOrder=Printable,BMPString
DirectoryString
encoding, do the following:
- Stop the Certificate Manager.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
/var/lib/pki/cs_instance/conf/
directory. - Open the
CS.cfg
configuration file. - Add the encoding order to the configuration file.For example, to specify two encoding values,
PrintableString
andUniversalString
, and the encoding order isPrintableString
first andUniversalString
next, add the following line at the end of the configuration file:X500Name.directoryStringEncodingOrder=PrintableString, UniversalString
- Save the changes, and close the file.
- Start the Certificate Manager.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
- To verify that the encoding orders are in effect, enroll for a certificate using the manual enrollment form. Use
John_Doe
for thecn
. - Open the agent services page, and approve the request.
- When the certificate is issued, use the
dumpasn1
tool to examine the encoding of the certificate.Thecn
component of the subject name should be encoded as aUniversalString
. - Create and submit a new request using
John Smith
for thecn
.Thecn
component of the subject name should be encoded as aPrintableString
.
9.2.3.10. Setting a CA to Use a Different Certificate to Sign CRLs
- Request and install a CRL signing certificate for the Certificate Manager using CMC. For details about requesting a system certificate, see 5.3.2.1. Obtaining System and Server Certificates in Red Hat Certificate System's Administration Guide.Note that the profile used to obtain the certificate must use the
keyUsageExtDefaultImpl
class id and the correspondingkeyUsageCrlSign
parameter set totrue
:policyset.userCertSet.6.default.class_id=keyUsageExtDefaultImpl policyset.userCertSet.6.default.params.keyUsageCrlSign=true
- After the CRL signing certificate is generated, install the certificate in the Certificate Manager's database through System Keys and Certificates in the console.
- Stop the Certificate Manager.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Update the Certificate Manager's configuration to recognize the new key pair and certificate.
- Change to the Certificate Manager instance configuration directory.
]# cd
/var/lib/pki/instance_name/ca/conf/
- Open the
CS.cfg
file and add the following lines:ca.crl_signing.cacertnickname=nickname cert-instance_ID ca.crl_signing.defaultSigningAlgorithm=signing_algorithm ca.crl_signing.tokenname=token_name
nickname is the name assigned to the CRL signing certificate.instance_ID is the name of the Certificate Manager instance.If the installed CA is a RSA-based CA, signing_algorithm can beSHA256withRSA
,SHA384withRSA
, orSHA512withRSA
. If the installed CA is an EC-based CA, signing_algorithm can beSHA256withEC
,SHA384withEC
,SHA512withEC
.token_name is the name of the token used for generating the key pair and the certificate. If the internal/software token is used, useInternal Key Storage Token
as the value.For example, the entries might look like this:ca.crl_signing.cacertnickname=crlSigningCert cert-pki-ca ca.crl_signing.defaultSigningAlgorithm=SHAMD512withRSA ca.crl_signing.tokenname=Internal Key Storage Token
- Save the changes, and close the file.
- Restart the Certificate Manager.
# systemctl restart pki-tomcatd-nuxwdog@instance_name.service
Now the Certificate Manager is ready to use the CRL signing certificate to sign the CRLs it generates.
9.2.3.11. Configuring CRL Generation from Cache in CS.cfg
- Stop the CA server.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the CA configuration directory.
# cd /var/lib/instance_name/conf/
- Edit the
CS.cfg
file, setting theenableCRLCache
andenableCacheRecovery
parameters to true:ca.crl.MasterCRL.enableCRLCache=true ca.crl.MasterCRL.enableCacheRecovery=true
- Start the CA server.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
9.2.3.12. Configuring Update Intervals for CRLs in CS.cfg
ca.crl.MasterCRL.updateSchema=3 ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240 ca.crl.MasterCRL.dailyUpdates=1:00 ca.crl.MasterCRL.nextUpdateGracePeriod=0
CS.cfg
file involves editing parameters.
Table 9.9. CRL Extended Interval Parameters
Parameter | Description | Accepted Values |
---|---|---|
updateSchema | Sets the ratio for how many delta CRLs are generated per full CRL. | An integer value |
enableDailyUpdates | Enables and disables setting CRL updates based on set times. | true or false |
enableUpdateInterval | Enables and disables setting CRL updates based on set intervals. | true or false |
dailyUpdates | Sets the times the CRLs should be updated | A comma-delimited list of times |
autoUpdateInterval | Sets the interval in minutes to update the CRLs. | An integer value |
nextUpdateGracePeriod | Adds the time in minutes to the CRL validity period to ensure that CRLs remain valid throughout the publishing or replication period. | An integer value |
refreshInSec | Sets the periodicity in seconds of the thread on the clone OCSP to check LDAP for any updates of the CRL. | An integer value |
Procedure 9.1. How to configure CRL update intervals in CS.cfg
- Stop the CA server.
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Change to the CA configuration directory.
# cd /var/lib/instance_name/conf/
- Edit the
CS.cfg
file, and add the following line to set the update interval:ca.crl.MasterCRL.updateSchema=3
The default interval is 1, meaning a full CRL is generated every time a CRL is generated. TheupdateSchema
interval can be set to any integer. - Set the update frequency, either by specifying a cyclical interval or set times for the updates to occur:
- Specify set times by enabling the
enableDailyUpdates
parameter, and add the desired times to thedailyUpdates
parameter:ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=false ca.crl.MasterCRL.dailyUpdates=0:50,04:55,06:55
This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separated list of times, such as01:50,04:55,06:55
. To enter a schedule for multiple days, enter a comma-separated list to set the times within the same day, and then a semicolon separated list to identify times for different days. For example, set01:50,04:55,06:55;02:00,05:00,17:00
to configure revocation on Day 1 of the cycle at 1:50am, 4:55am, and 6:55am and then Day 2 at 2am, 5am, and 5pm.Specify intervals by enabling theenableUpdateInterval
parameter, and add the required interval in minutes to theautoUpdateInterval
parameter:ca.crl.MasterCRL.enableDailyUpdates=false ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240
- Set the following parameters depending on your environment:
- If you run a CA without an OCSP subsystem, set:
ca.crl.MasterCRL.nextUpdateGracePeriod=0
- If you run a CA with an OCSP subsystem, set:
ca.crl.MasterCRL.nextUpdateGracePeriod=time_in_minutes
Theca.crl.MasterCRL.nextUpdateGracePeriod
parameter defines the time in minutes, and the value must be big enough to enable the CA to propagate the new CRL to the OCSP. You must set the parameter to a non-zero value.If you additionally have OCSP clones in your environment, also set:ocsp.store.defStore.refreshInSec=time_in_seconds
Theocsp.store.defStore.refreshInSec
parameter sets the frequency in seconds with which the clone OCSP instances are informed of CRL updates through LDAP replication updates from the master OCSP instance.
See Table 9.9, “CRL Extended Interval Parameters” for details on the parameters. - Restart the CA server.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
Note
enableDailyUpdates
and enableUpdateInterval
parameters to true, and add the required values to autoUpdateInterval
and dailyUpdates
:
ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240 ca.crl.MasterCRL.dailyUpdates=1:00
dailyUpdates
value will be accepted when updating CRLs by interval.
dailyUpdates
value every 24 hours preventing schedule drift.
9.2.3.13. Changing the Access Control Settings for the Subsystem
authz.evaluateOrder
parameter in the CS.cfg
.
authz.evaluateOrder=deny,allow
web.xml
file (basic ACLs) or more complex ACLs can be accessed by checking the LDAP database. The authz.sourceType
parameter identifies what type of authorization to use.
authz.sourceType=web.xml
Note
CS.cfg
file to load the updated settings.
9.2.3.14. Setting Requirement for pkiconsole
to use TLS Client Certificate Authentication
CS.cfg
file of each subsystem, search for the authType
parameter and set it as follows:
authType=sslclientauth
9.3. Managing System Passwords
password.conf
file stores system passwords in plain text. However, some administrators prefer to remove the password file entirely to allow nuxwdog
to prompt for manual entry of each password initially and store for auto-restart in case of an unplanned shutdown.
password.conf
file. If the file exists, then it uses those passwords to connect to other services, such as the internal LDAP database. If that file does not exist, then the watchdog daemon prompts for all of the passwords required by the PKI server to start.
Note
password.conf
file is present, the subsystem assumes that all the required passwords are present and properly formatted in clear text. If any passwords are missing or wrongly formatted, then the system fails to start correctly.
cms.passwordlist
parameter in the CS.cfg
file:
cms.passwordlist=internaldb,replicationdb,CA LDAP Publishing cms.password.ignore.publishing.failure=true
Note
cms.password.ignore.publishing.failure
parameter allows a CA subsystem to start up successfully even if it has a failed connection to one of its LDAP publishing directories.
internal
for the NSS databaseinternaldb
for the internal LDAP databasereplicationdb
for the replication password- Any passwords to access external LDAP databases for publishing (CA only)
Note
If a publisher is configured after thepassword.conf
file is removed, nothing is written to thepassword.conf
file. Unlessnuxwdog
is configured, the server will not have access to the prompts for the new publishing password the next time that the instance restarts. - Any external hardware token passwords
internal
for the NSS databasetokendbpass
for the internal LDAP database- Any external hardware token passwords
password.conf
file (the default)- nuxwdog (watchdog)
9.3.1. Configuring the password.conf File
Note
nuxwdog
watchdog. Please refer to Section 9.3.2, “Using the Certificate System Watchdog Service” to enable nuxwdog
, as it is required for full compliance.
password.conf
, in the subsystem conf/
directory. Therefore, it is possible to modify them simply through a text editor.
- The bind password used by the Certificate System instance to access and update the internal database.
- The password to the HSM
- The bind password used by the Certificate System instance to access the authentication directory, in case of CMC Shared Token.
- The bind password used by the subsystem to access and update the LDAP publishing directory; this is required only if the Certificate System instance is configured for publishing certificates and CRLs to an LDAP-compliant directory.
- the bind password used by the subsystem to access its replication database.
- For a TPS instance, the bind password used to access and update the token database.
password.conf
file also contains the token passwords needed to open the private keys of the subsystem.
CS.cfg
file:
passwordFile=/var/lib/pki/instance_name/conf/password.conf
password.conf
file are in the following format:
name=password
internal=413691159497
hardware-name=password
hardware-NHSM6000=MyHSM$S8cret
password.conf
file:
internal=376577078151 internaldb=secret12 replicationdb=1535106826 hardware-NHSM6000=MyHSM$S8cret
9.3.2. Using the Certificate System Watchdog Service
- prompts for the relevant passwords during server startup and caches them.
- uses cached passwords in case of a failure when the server is automatically restarted due to a crash.
9.3.2.1. Enabling the Watchdog Service
- If you also want to use the Shared Secret feature on this host, enable the Shared Secret feature as described in in the Enabling the CMC Shared Secret Feature section in the Certificate System Administration Guide (Common Criteria Edition).
- Backup the
server.xml
andpassword.conf
files from the/var/lib/pki/instance_name/conf/
directory. For example:# cp -p /var/lib/pki/instance_name/conf/server.xml /root/ # cp -p /var/lib/pki/instance_name/conf/password.conf /root/
- Stop and disable the Certificate System instance's service:
# systemctl stop pki-tomcatd@instance_name.service # systemctl disable pki-tomcatd@instance_name.service
- If you use a Hardware Security Module (HSM), enable the watchdog service to prompt for the password of the hardware token:
- Display the name of the hardware token:
# egrep "^hardware-" /var/lib/pki/instance_name/conf/password.conf hardware-HSM_token_name=password
The highlighted string in the previous example is the hardware token name. - Add the
cms.tokenList
parameter to the/var/lib/pki/instance_name/conf/ca/CS.cfg
file and set it to the name of the hardware token. For example:cms.tokenList=HMS_token_name
- Enable the watchdog configuration for the instance:
# pki-server instance-nuxwdog-enable instance_name
Alternatively, enable the watchdog for all instances:# pki-server nuxwdog-enable
For further details, see the pki-server-nuxwdog(8) man page. - By default,
nuxwdog
starts the server as the user configured in theTOMCAT_USER
variable in the/etc/sysconfig/pki-tomcat
file. Optionally, to modify the user and group:- Copy the watchdog
systemd
unit file of the instance to the/etc/systemd/system/
directory:# cp -p /usr/lib/systemd/system/instance_name-nuxwdog@.service /etc/systemd/system/
Note
Unit files in the/etc/systemd/system/
directory have a higher priority and are not replaced during updates. - Add the following entries to the
[Service]
section in the/etc/pki/instance_name/nuxwdog.conf
file:User new_user_name
- Reload the
systemd
configuration:# systemctl daemon-reload
- Enable the Certificate System service that uses the watchdog:
# systemctl enable pki-tomcatd-nuxwdog@instance_name.service
- To start the Certificate System instance, run the following command and enter the prompted passwords:
# systemctl start pki-tomcatd-nuxwdog@instance_name.service
9.3.2.2. Starting and Stopping Certificate System with the Watchdog Enabled
9.3.2.3. Verifying That the Certificate System Watchdog Service is Enabled
- Verify that the
pki-tomcatd-nuxwdog
service is enabled:# systemctl is-enabled pki-tomcatd-nuxwdog@instance_name.service enabled
- Verify that the
pki-tomcatd
service is disabled:# systemctl is-disabled pki-tomcatd@instance_name.service disabled
- In the
/etc/pki/instance_name/server.xml
file:- verify that the
passwordFile
parameter refers to theCS.cfg
file. For example:passwordFile="/var/lib/pki/instance_name/ca/CS.cfg"
- verify that the
passwordClass
parameter is set tocom.netscape.cms.tomcat.NuxwdogPasswordStore
:passwordClass="com.netscape.cms.tomcat.NuxwdogPasswordStore"
9.3.2.4. Disabling the Watchdog Service
- Stop and disable the Certificate System instance's service that uses the watchdog:
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service # systemctl disable pki-tomcatd-nuxwdog@instance_name.service
- Enable the regular service without watch dog for the instance:
# pki-server instance-nuxwdog-disable instance_name
- Disable the watchdog configuration for the instance:
# systemctl enable pki-tomcatd@instance_name.service
For further details, see the pki-server-nuxwdog(8) man page. - Restore the
password.conf
file to its original location. For example:# cp /root/password.conf.bak /var/lib/pki/instance_name/conf/password.conf
- Start the Certificate System instance:
# systemctl start pki-tomcatd@instance_name.service
9.4. Configuration Files for the Tomcat Engine and Web Services
/var/lib/pki/instance_name/conf/server.xml
provides the configuration for the Tomcat engine./usr/share/pki/subsystem_type/webapps/WEB-INF/web.xml
provides the configuration for the web services offered by this instance.
9.4.1. Tomcatjss
Note
server.xml
file found in the example pki-tomcat/conf
directory can be used to explain how Tomcatjss fits into the entire Certificate System ecosystem. Portions of the Connector entry for the secret port are shown below.
<Connector name="Secure" # Info about the socket itself port="8443" protocol="org.apache.coyote.http11.Http11Protocol" SSLEnabled="true" sslProtocol="SSL" scheme="https" secure="true" connectionTimeout="80000" maxHttpHeaderSize="8192" acceptCount="100" maxThreads="150" minSpareThreads="25" enableLookups="false" disableUploadTimeout="true" # Points to our tomcat jss implementation sslImplementationName="org.apache.tomcat.util.net.jss.JSSImplementation" # OCSP responder configuration can be enabled here enableOCSP="true" ocspCacheSize="1000" ocspMinCacheEntryDuration="60" ocspMaxCacheEntryDuration="120" ocspTimeout="10" # A collection of cipher related settings that make sure connections are secure. strictCiphers="true" # The "clientAuth" parameter configures the client authentication scheme # for this server socket. If you set "clientAuth" to "want", the client # authentication certificate is optional. Alternatively, set the # parameter to "required" to configure that the certificate is is mandatory. clientAuth="want" sslVersionRangeStream="tls1_1:tls1_2" sslVersionRangeDatagram="tls1_1:tls1_2" sslRangeCiphers="+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 serverCertNickFile="/var/lib/pki/pki-tomcat/conf/serverCertNick.conf" passwordFile="/var/lib/pki/pki-tomcat/conf/password.conf" passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile" certdbDir="/var/lib/pki/pki-tomcat/alias" />
server.xml
configuration file for the Tomcat engine, there is this Connector configuration element that contains the pointer to the tomcatjss implementation, which can be plugged into the sslImplementation
property of this Connector object.
9.4.1.1. TLS Cipher Configuration
server.xml
file provide system-wide defaults when Red Hat Certificate system is acting as a client and as a server. This includes when acting as a server (for example, when serving HTTPS connections from Tomcat) and as a client (for example, when communicating with the LDAP server or when communicating with another Certificate System instance).
/var/lib/pki/instance_name/conf/server.xml
file. The following parameters control the ciphers offered:
strictCiphers
, when set totrue
, ensures that only ciphers with a+
sign in thesslRangeCiphers
are enabled.strictCiphers="true"
Do not change the default value (true
).sslVersionRangeStream
andsslVersionRangeDatagram
sets the TLS version the server supports. The following are the defaults of the parameters:sslVersionRangeStream="tls1_1:tls1_2" sslVersionRangeDatagram="tls1_1:tls1_2"
Do not change the default value of the parameters.sslRangeCiphers
sets which ciphers are enabled and disabled. Ciphers with a+
sign are enabled, ciphers with a-
sign disabled.Set RSA ciphers as below:sslRangeCiphers="+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA,+TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
Set EC ciphers as below:sslRangeCiphers="+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,+TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,+TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
For a list of allowed ciphers, see Section 3.1, “Allowed TLS Cipher Suites”.- If you install Certificate System with either LunaSA or nCipher Hardware Security Module (HSM) on systems with FIPS mode enabled for RSA, disable the following ciphers, as they are unsupported on HSMs in FIPS mode:
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
9.4.1.2. Enabling Certificate Revocation Checking for Subsystems
server.xml
file.
- Allowed Method: Enabling a Certificate System subsystem to use the OCSP responder URL specified in the peer certificate's Authority Information Access (AIA) extension: This method allows for a more dynamic environment where peer certificates can be issued by more than one CA. For example, if the certificate of the LDAP server is issued by a different CA than other certificates. For details, see Section 9.4.1.2.2, “Enabling a Certificate System Subsystem to use the OCSP Responder URL Specified in the Peer Certificate's Authority Information Access (AIA) Extension”.
server.xml
file might be used.
server.xml
file.
Table 9.10. OCSP Parameters for server.xml
Parameter | Description |
---|---|
enableOCSP | Enables (or disables) OCSP checking for the subsystem. |
ocspResponderURL | N/A |
ocspResponderCertNickname | N/A |
ocspCacheSize |
Sets the maximum number of OCSP response cache entries kept by the Network Security Services (NSS).
There are two special values:
|
ocspMinCacheEntryDuration | Sets minimum seconds before another fetch attempt can be made. For example, if this is set to 120, then the validity of a certificate cannot be checked again until at least 2 minutes after the last validity check. |
ocspMaxCacheEntryDuration | Sets the maximum number of seconds to wait before making the next fetch attempt. This prevents having too large a window between validity checks. |
ocspTimeout | Sets the timeout period, in seconds, for the OCSP request. |
Note
nextUpdate
field is sent with the OCSP response, it can affect the next fetch time with ocspMinCacheEntryDuration
and ocspMaxCacheEntryDuration
like following:
- If the value in
nextUpdate
has been reached before the value set inocspMinCacheEntryDuration
, the fetch will not be started until the value set inocspMinCacheEntryDuration
has been reached. - If
ocspMinCacheEntryDuration
has been reached, the server checks if the value innextUpdate
has been reached. If the value has been reached, the fetch will happen. - Regardless of the value in
nextUpdate
, if the setting inocspMaxCacheEntryDuration
has been reached, the fetch will happen.
9.4.1.2.1. Setting Trust of the OCSP Signing Certificate
9.4.1.2.2. Enabling a Certificate System Subsystem to use the OCSP Responder URL Specified in the Peer Certificate's Authority Information Access (AIA) Extension
server.xml
file and
- Set the
enableOCSP
totrue
. - Remove the
ocspResponderURL
parameter. - Remove the
ocspResponderCertNickname
parameter.
Important
Example 9.4. server.xml
<Connector name="Secure" enableOCSP="true" ocspCacheSize="1000" ocspMinCacheEntryDuration="60" ocspMaxCacheEntryDuration="120" ocspTimeout="10" ... />
9.4.1.2.3. Adding an AIA Extension to an Enrollment Profile
policyset.cmcUserCertSet.5.default.params.authInfoAccessADLocation_0=http://example.com:8080/ocsp/ee/ocsp
9.4.1.3. Session Timeout
- TLS session timeout
- HTTP session timeout
Note
9.4.1.3.1. TLS Session Timeout
ACCESS_SESSION_ESTABLISH
audit event with Outcome=Success
when the connection is created. If the connection fails to be created, the server will generate an ACCESS_SESSION_ESTABLISH
audit event with Outcome=Failure
. When the connection is closed, the server will generate an ACCESS_SESSION_TERMINATED
audit event.
keepAliveTimeout
parameter in the Secure
<Connector> element in the /etc/pki/<instance>/server.xml
file:
... <Server> <Service> <Connector name="Secure" ... keepAliveTimeout="300000" ... /> </Service> </Server> ...
/etc/pki/<instance>/server.xml
file and then restart the server.
Note
9.4.1.3.2. HTTP Session Timeout
Note
<session-timeout>
value in this section to match the keepAliveTimeout
value in Section 9.4.1.3.1, “TLS Session Timeout”. For example if keepAliveTimeout
was set to 300000 (5 minutes), then set <session-timeout>
to 30.
<session-timeout>
element in the /etc/pki/<instance>/web.xml
file:
... <web-app> <session-config> <session-timeout>30</session-timeout> </session-config> </web-app> ...
/etc/pki/<instance>/web.xml
file and then restart the server.
Note
9.4.1.3.3. Session Timeout for PKI Web UI
9.4.1.3.4. Session Timeout for PKI Console
9.4.1.3.5. Session Timeout for PKI CLI
9.4.2. web.xml
9.4.2.1. Removing Unused Interfaces from web.xml (CA Only)
web.xml
file. However, since these features are deprecated and no longer in use, then they can be removed from the CA configuration to increase security.
- Stop the CA.
systemctl stop pki-tomcatd@instance_name.service
ORsystemctl stop pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
) - Open the web files directory for the CA. For example:
cd /var/lib/pki/pki-tomcat/ca/webapps/ca/WEB-INF
- Back up the current
web.xml
file.cp web.xml web.xml.servlets
- Edit the
web.xml
file and remove the entire<servlet>
entries for each of the following deprecated servlets:- caadminEnroll
- cabulkissuance
- cacertbasedenrollment
- caenrollment
- caProxyBulkIssuance
For example, remove thecaadminEnroll
servlet entry:<servlet> <servlet-name> caadminEnroll </servlet-name> <servlet-class> com.netscape.cms.servlet.cert.EnrollServlet </servlet-class> <init-param><param-name> GetClientCert </param-name> <param-value> false </param-value> </init-param> <init-param><param-name> successTemplate </param-name> <param-value> /admin/ca/EnrollSuccess.template </param-value> </init-param> <init-param><param-name> AuthzMgr </param-name> <param-value> BasicAclAuthz </param-value> </init-param> <init-param><param-name> authority </param-name> <param-value> ca </param-value> </init-param> <init-param><param-name> interface </param-name> <param-value> admin </param-value> </init-param> <init-param><param-name> ID </param-name> <param-value> caadminEnroll </param-value> </init-param> <init-param><param-name> resourceID </param-name> <param-value> certServer.admin.request.enrollment </param-value> </init-param> <init-param><param-name> AuthMgr </param-name> <param-value> passwdUserDBAuthMgr </param-value> </init-param> </servlet>
- After removing the servlet entries, remove the corresponding
<servlet-mapping>
entries.<servlet-mapping> <servlet-name> caadminEnroll </servlet-name> <url-pattern> /admin/ca/adminEnroll </url-pattern> </servlet-mapping>
- Remove three
<filter-mapping>
entries for an end-entity request interface.<filter-mapping> <filter-name> EERequestFilter </filter-name> <url-pattern> /certbasedenrollment </url-pattern> </filter-mapping> <filter-mapping> <filter-name> EERequestFilter </filter-name> <url-pattern> /enrollment </url-pattern> </filter-mapping> <filter-mapping> <filter-name> EERequestFilter </filter-name> <url-pattern> /profileSubmit </url-pattern> </filter-mapping>
- Start the CA again.
systemctl start pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)
9.4.3. Customizing Web Services
9.4.3.1. Customizing Subsystem Web Applications
- HTML pages containing texts, JavaScript codes, page layout, CSS formatting, and so on
- A
web.xml
file, which defines servlets, paths, security constraints, and other - Links to PKI libraries.
/var/lib/pki/pki-tomcat/conf/Catalina/localhost/
directory, for example, the ca.xml
file:
<Context docBase="/usr/share/pki/ca/webapps/ca" crossContext="true" allowLinking="true"> ... </Context>
docBase
points to the location of the default web application directory, /usr/share/pki/
.
webapps
directory:
$ cp -r /usr/share/pki/ca/webapps/ca /var/lib/pki/pki-tomcat/webapps
docBase
to point to the custom web application directory relative from the webapps
directory:
<Context docBase="ca" crossContext="true" allowLinking="true"> ... </Context>
docBase
and delete the custom web application directory:
$ rm -rf /var/lib/pki/pki-tomcat/webapps/ca
9.4.3.2. Customizing the Web UI Theme
- CSS files, which determine the global appearance
- Image files including logo, icons, and other
- Branding properties, which determine the page title, logo link, title color, and other.
pki.xml
context file in the /var/lib/pki/pki-tomcat/conf/Catalina/localhost/
directory:
<Context docBase="/usr/share/pki/common-ui" crossContext="true" allowLinking="true"> ... </Context>
/usr/share/pki/
.
pki
directory in the instance's webapps
directory:
$ cp -r /usr/share/pki/common-ui /var/lib/pki/pki-tomcat/webapps/pki
docBase
to point to the custom theme directory relative from the webapps
directory:
<Context docBase="pki" crossContext="true" allowLinking="true"> ... </Context>
docBase
and delete the custom theme directory:
$ rm -rf /var/lib/pki/pki-tomcat/webapps/pki
9.4.3.3. Customizing TPS Token State Labels
/usr/share/pki/tps/conf/token-states.properties
file and described in Section 2.5.2.4.1.4, “Token State and Transition Labels”.
$ cp /usr/share/pki/tps/conf/token-states.properties /var/lib/pki/pki-tomcat/tps/conf
$ rm /var/lib/pki/pki-tomcat/tps/conf/token-states.properties
9.5. Using an Access Banner
Application | When the banner is displayed |
---|---|
PKI Console |
|
Web interface |
|
pki command-line utility |
|
[a]
For details about changing the session timeout, see Section 9.4.1.3, “Session Timeout”.
|
Example 9.5. When the Access Banner is Displayed
pki
utility:
# $ pki cert-show 0x1
WARNING! Access to this service is restricted to those individuals with specific permissions. If you are not an authorized user, disconnect now. Any attempts to gain unauthorized access will be prosecuted to the fullest extent of the law. Do you want to proceed (y/N)? y
-----------------
Certificate "0x1"
-----------------
Serial Number: 0x1
Issuer: CN=CA Signing Certificate,OU=instance_name,O=EXAMPLE
Subject: CN=CA Signing Certificate,OU=instance_name,O=EXAMPLE
Status: VALID
Not Before: Mon Feb 20 18:21:03 CET 2017
Not After: Fri Feb 20 18:21:03 CET 2037
9.5.1. Enabling an Access Banner
/etc/pki/instance_name/banner.txt
file and enter the text to displayed.
Important
/etc/pki/instance_name/banner.txt
file must use the UTF-8 format. To validate, see Section 9.5.3, “Validating the Banner”.
9.5.2. Displaying the Banner
# pki-server banner-show -i instance_name
9.5.3. Validating the Banner
# pki-server banner-validate -i instance_name --------------- Banner is valid ---------------
9.6. Configuration for CMC
9.6.1. Understanding How CMC Works
- Requesting and Receiving Certificates Using CMC in the Certificate System Administration Guide (Common Criteria Edition).
- Making Rules for Issuing Certificates (Certificate Profiles) in the Certificate System Administration Guide (Common Criteria Edition).
9.6.2. Enabling the PopLinkWittnessV2
Feature
/var/lib/pki/instance_name/ca/conf/CS.cfg
file:
cmc.popLinkWitnessRequired=true
9.6.3. Enabling the CMC Shared Secret Feature
- If the watchdog service is enabled on the host, temporarily disable it. See Section 9.3.2.4, “Disabling the Watchdog Service”.
- Add the
shrTok
attribute to Directory Server's schema:# ldapmodify -D "cn=Directory Manager" -H ldaps://server.example.com:636 -W -x dn: cn=schema changetype: modify add: attributetypes attributetypes: ( 2.16.840.1.117370.3.1.123 NAME 'shrTok' DESC 'User Defined ObjectClass for SharedToken' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 SINGLE-VALUE X-ORIGIN 'custom for sharedToken')
- If the system keys are stored on a Hardware Security Module (HSM), set the
cmc.token
parameter in the/var/lib/pki/instance_name/ca/conf/CS.cfg
file. For example:cmc.token=NHSM6000
- Enable the shared token authentication plug-in by using one of the following methods:
- To enable the plug-in using the
pkiconsole
utility:- Log into the system using the
pkiconsole
utility. For example:# pkiconsole https:host.example.com:8443/ca
- On the Configuration tab, select Authentication.
- Click Add and select SharedToken.
- Click Next.
- Enter the following information:
Authentication InstanceID=SharedToken shrTokAttr=shrTok ldap.ldapconn.host=server.example.com ldap.ldapconn.port=636 ldap.ldapconn.secureConn=true ldap.ldapauth.bindDN=cn=Directory Manager password=password ldap.ldapauth.authtype=BasicAuth ldap.basedn=ou=People,dc=example,dc=org
- Click OK.
- To manually enable the plug-in, add the following settings into the
/var/lib/pki/instance_name/ca/conf/CS.cfg
file:auths.impl.SharedToken.class=com.netscape.cms.authentication.SharedSecret auths.instance.SharedToken.dnpattern= auths.instance.SharedToken.ldap.basedn=ou=People,dc=example,dc=org auths.instance.SharedToken.ldap.ldapauth.authtype=BasicAuth auths.instance.SharedToken.ldap.ldapauth.bindDN=cn=Directory Manager auths.instance.SharedToken.ldap.ldapauth.bindPWPrompt=Rule SharedToken auths.instance.SharedToken.ldap.ldapauth.clientCertNickname= auths.instance.SharedToken.ldap.ldapconn.host=server.example.com auths.instance.SharedToken.ldap.ldapconn.port=636 auths.instance.SharedToken.ldap.ldapconn.secureConn=true auths.instance.SharedToken.ldap.ldapconn.version=3 auths.instance.SharedToken.ldap.maxConns= auths.instance.SharedToken.ldap.minConns= auths.instance.SharedToken.ldapByteAttributes= auths.instance.SharedToken.ldapStringAttributes= auths.instance.SharedToken.pluginName=SharedToken auths.instance.SharedToken.shrTokAttr=shrTok
- Set the nickname of an RSA issuance protection certificate in the
ca.cert.issuance_protection.nickname
parameter in the/var/lib/pki/instance_name/ca/conf/CS.cfg
file. For example:ca.cert.issuance_protection.nickname=issuance_protection_certificate
This step is:- Optional if you use an RSA certificate in the
ca.cert.subsystem.nickname
parameter. - Required if you use an ECC certificate in the
ca.cert.subsystem.nickname
parameter.
Important
If theca.cert.issuance_protection.nickname
parameter is not set, Certificate System automatically uses the certificate of the subsystem specified in theca.cert.subsystem.nickname
. However, the issuance protection certificate must be an RSA certificate. - Restart Certificate System:
# systemctl restart pki-tomcatd@instance_name.service
When the CA starts, Certificate System prompts for the LDAP password used by the Shared Token plug-in. - If you temporarily disabled the watchdog service at the beginning of this procedure, re-enable it. See Section 9.3.2.1, “Enabling the Watchdog Service”.
9.6.4. Enabling CMCRevoke for the Web User Interface
CMCRevoke
utility to create revocation requests to be submitted through the web UI, add the following setting to the /var/lib/pki/instance_name/ca/conf/CS.cfg
file:
cmc.bypassClientAuth=true
Chapter 10. Managing Certificate/Key Crypto Token
About Crypto Tokens
10.1. About certutil
and PKICertImport
certutil
command is provided by Network Security Services (NSS). certutil
is used for validating and importing certificates. A basic overview of how we use certutil
is presented below, however, PKICertImport
is our wrapper script of choice for safely validating and importing certificates. Using certutil
to do so requires multiple command invocations and correct usage is outside the scope of this documentation.
10.1.1. certutil
Basic Usage
certutil [command] [options]
certutil
invocation takes a command flag, usually denoted by a capital letter, and a series of options which control what the command does. If an option takes a value, that value is named between "<" and ">" symbols.
10.1.2. PKICertImport Basic Usage
PKICertImport [options]
PKICertImport
invocation takes a series of options to validate and import a specified certificate. Unlike the broad use cases of certutil
, PKICertImport
is only focused on safely importing and validating certificates. See Section 10.1.4, “Common certutil
and PKICertImport
Options” for more information about available options.
Note
PKICertImport
prompts for the NSS DB and/or HSM passwords multiple times throughout the course of its execution. This is expected as PKICertImport
has to interact with the NSS DB multiple times. To avoid having to input the NSS DB password repetitively, specify a password file via -f <filename>
. When done, be sure to delete the password file.
10.1.3. certutil
Common Commands
certutil
and provide a brief overview of several common commands. PKICertImport
is not compatible with nor require these command flags.
certutil -A
-A
command denotes "adding" a certificate. It requires a certificate to import (-i
), a nickname (-n
) for that certificate, and a series of trust flags (-t
) for the certificate.
certutil -V
-V
command denotes "verifying" a certificate. It requires a certificate nickname to validate (-n
) and a type of verification (-u
) to perform.
certutil -D
-D
command denotes "deleting" a certificate. It requires a certificate nickname (-n
) to remove.
certutil -M
-M
command denotes "modifying" a certificate. It requires a certificate nickname (-n
) to modify, and a series of trust flags (-t
) to give the certificate.
certutil -L
-L
command denotes "listing" a certificate or all certificates. If given the nickname option (-n
), it will list detailed information about that certificate, else if omitted, it will list general information about all certificates present.
certutil -L
would show each certificate by its nickname along with its trust info. For example:
Table 10.1. Certificate nickname and trust info
Certificate Nickname
|
Trust Attributes |
---|---|
caSigningCert pki-ca1
|
CT, C, C
|
Note
certutil -L
correspond to what is specified with the -t
option.
certutil -L
does not modify the database, and can thus be executed safely as many times as desired.
10.1.4. Common certutil
and PKICertImport
Options
PKICertImport
as well.
-n <nickname>
-n <nickname>
option specifies the nickname for a certificate. This can be any text and is only used as a reference to the certificate. It MUST be unique.
-d <directory>
-d <directory>
option specifies the path to the NSS DB directory in use. We usually assume you are already in this directory and use "." to refer to the current directory.
-t <trust>
-t <trust>
option specifies the trust level for the certificate.
- trust for TLS
- trust for email
- trust for object signing
c
, C
, and T
.
c
states that this certificate should be a Certificate Authority (CA).C
states that this is a trusted certificate authority for signing server certificates (C
implies lowercasec
, hence you do not need to specify both).T
states that this certificate is a trusted authority for signing client certificates (T
implies lowercasec
, hence you do not need to specify bothT
andc
).
-t CT,C,c
means that the certificate is trusted for signing client and server TLS certificates, signing server email certificates (S/MIME), and is a valid CA for object signing (though untrusted).
- This ensures that, if this certificate signs another certificate, which in turn is used for object signing, it will be deemed invalid.
-t ,,
.
certutil -L -d
- Each certificate's nickname will be listed and the trust flags will be specified at the end of the line.
-h
option.
man certutil
command on a system with certutil properly installed.
-h <HSM>
-h <HSM>
option specifies the name of the HSM to perform operations on.
-h
option is incompatible with the -t
option, as HSMs cannot store trust. Only an NSS DB can store trust, so using the certutil -A
command or the certutil -M
command in conjunction with -h <HSM>
will fail. Instead, specify the desired trust level on a separate certutil -M
command without the -h
option.
-e
-e
option specifies that the validity of the signature is checked as well, when used in conjunction with the certutil -V
command. PKICertImport
always performs the certificate signature validation and does not understand the -e
option.
-a
-a
option specifies that the key in question is in PEM (ASCII) format.
-i <certificate>
-i <certificate>
option specifies the path to the certificate. This is only used in the certutil -A
command to specify the path to the certificate to import.
-u <usage>
-u <usage>
option specifies that usage of the certificate to verify when used in conjunction with the certutil -V
command.
-u C
stands for verify a client TLS certificate. Note that this mostly accepts any certificate, but will check expiration date and signature.-u V
stands for verify a server TLS certificate. Note that this will reject CA certificates and will check expiration date and signature.-u L
stands for verify a CA TLS certificate. Note that this will validate trust flags (to see ifc
is present) and will check key usage to ensure that the key is a CA key. This also checks expiration and signatures.-u O
stands for verify a OCSP status responder certificate. Note that this checks expiry and signatures.-u J
stands for verify an object signing certificate. Note that this checks expiry and signatures.
c
flag for an CA TLS certificate), certutil -V
will give incorrect results.
Note
man certutil
command on a system with certutil properly installed.
10.2. Importing a Root Certificate
cd
/path/to/nssdb
ca_root.crt
. Please substitute the correct name and path to this file as appropriate for your scenario.
certutil
and PKICertImport
options used below, see Section 10.1, “About certutil
and PKICertImport
”.
To import the root certificate:
- Execute
PKICertImport -d . -n "CA Root" -t "CT,C,C" -a -i ca_root.crt -u L
command.This command validates and imports the root certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate because it is expired or because it is not a CA certificate. Therefore, make sure your certificate file is correct and up-to-date. Contact the issuer and ensure that all intermediate and root certificates are present on your system.
10.3. Importing an Intermediate Certificate Chain
cd
/path/to/nssdb
ca_sub_<num>.crt
(for example ca_sub_1.crt
, ca_sub_2.crt
, and so on). Substitute names and paths for your certificates as appropriate to your deployment.
Note
fullchain.crt
, fullchain.pem
, or similar and it contains multiple certificates, split it into the above format by copying each block (between and including the ----BEGIN CERTIFICATE----- and an -----END CERTIFICATE----- markers) to its own file. The first ones should be named ca_sub_<num>.crt
and the last will be your server cert named service.crt
. Server certificates are discussed in later sections.
certutil
and PKICertImport
options used below, see Section 10.1, “About certutil
and PKICertImport
”.
For every intermediate certificate in the chain:
- Execute
PKICertImport -d . -n "CA Sub $num" -t "CT,C,C" -a -i ca_sub_$num.crt -u L
This command validates and imports the Intermediate CA certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
10.4. Importing a certificate into an HSM
cd
/path/to/nssdb for examplecd /var/lib/pki/pki-ca/alias
- For TLS server certs for all PKI substems, follow the server certificate steps.
- For any subsystem's audit signing cert, follow the steps below for validating an object Signing certificate.
- For the CA subsystem's signing cert, follow the steps above for importing and validating an intermediate certificate chain, but do so only with the
caSigningCert
. - For the CA subsystem's OCSP signing cert, follow the steps below for validating an OCSP certificate.
- For all other system certs of the PKI subsystems, follow the Client Certificate steps.
certutil
and PKICertImport
options used below, see Section 10.1, “About certutil
and PKICertImport
”.
To import a server certificate on the HSM:
- Execute
PKICertImport -d . -h HSM -n "host.name.example.com" -t ",," -a -i service.crt -u V
This command validates and imports the server certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate due to expiry of a parent certificate or a missing CA trust chain (such as a missing intermediate certificate or a missing CA Root). If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
To import a client certificate on the HSM:
- Execute
PKICertImport -d . -h HSM -n "client name" -t ",," -a -i client.crt -u C
This command validates and imports the client certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
To import an object signing certificate on the HSM:
- Execute
PKICertImport -d . -h HSM -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J
This command validates and imports the object signing certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
To import an OCSP response signing certificate on the HSM:
- Execute
PKICertImport -d . -h HSM -n "certificate name" -t ",," -a -i ocsp.crt -u O
This command validates and imports the OCSP responder certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
10.5. Importing a certificate into an NSS Database
- For any subsystem's
auditSigningCert
, please follow the steps below for validating an object Signing certificate. - For the CA subsystem's
caSigningCert
, please follow the steps above for importing and validating an intermediate certificate chain, but do so only with the caSigningCert. - For the CA subsystem's
ocspSigningCert
, please follow the steps below for validating an OCSP certificate. - For user's client or S/MIME certificate, follow the Client Certificate steps.
certutil
and PKICertImport
options used below, see Section 10.1, “About certutil
and PKICertImport
”.
Importing a Client Certificate Into the NSS Database
- Change into the NSS database directory. For example:
# cd /path/to/nssdb/
- Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 10.2, “Importing a Root Certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 10.3, “Importing an Intermediate Certificate Chain”.
- Validate and import the client certificate:
#
PKICertImport -d . -n "client name" -t ",," -a -i client.crt -u C
The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Importing an Object Signing Certificate
- Change into the NSS database directory. For example:
# cd /path/to/nssdb/
- Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 10.2, “Importing a Root Certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 10.3, “Importing an Intermediate Certificate Chain”.
- Validate and import the object signing certificate:
#
PKICertImport -d . -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J
The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Importing an OCSP Responder
- Change into the NSS database directory. For example:
# cd /path/to/nssdb/
- Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 10.2, “Importing a Root Certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 10.3, “Importing an Intermediate Certificate Chain”.
- Validate and import the OCSP responder certificate:
#
PKICertImport -d . -n "certificate name" -t ",," -a -i ocsp.crt -u O
The validation succeeds when no error message is printed and the return code is 0. To check the return code, executeecho $?
immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Chapter 11. Certificate Profiles Configuration
11.1. Creating and Editing Certificate Profiles Directly on the File System
/ca/profiles/ca/
, such as /var/lib/pki/pki-ca/ca/profiles/ca/
. The file is named profile_name.cfg
. All of the parameters for profile rules can be set or modified in those profile configuration files. Profile rules can be inputs, outputs, authentication, authorization, defaults, and constraints.
/var/lib/pki/instance_name/ca/conf
directory with the name *.profile
.
Note
11.1.1. Configuring non-CA System Certificate Profiles
11.1.1.1. Profile Configuration Parameters
policyset.
policyName.policyNumber. For example:
policyset.cmcUserCertSet.6.constraint.class_id=noConstraintImpl policyset.cmcUserCertSet.6.constraint.name=No Constraint policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl policyset.cmcUserCertSet.6.default.name=User Supplied Key Default policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15
Table 11.1. Profile Configuration File Parameters
Parameter | Description |
---|---|
desc | Gives a free text description of the certificate profile, which is shown on the end-entities page. For example, desc=This certificate profile is for enrolling server certificates with agent authentication. |
enable | Sets whether the profile is enabled, and therefore accessible through the end-entities page. For example, enable=true. |
auth.instance_id | Sets which authentication manager plug-in to use to authenticate the certificate request submitted through the profile. For automatic enrollment, the CA issues a certificate immediately if the authentication is successful. If authentication fails or there is no authentication plug-in specified, the request is queued to be manually approved by an agent. For example, auth.instance_id=CMCAuth. The authentication method must be one of the registered authentication instances from CS.cfg . |
authz.acl |
Specifies the authorization constraint. Most commonly, this us used to set the group evaluation ACL. For example, this caCMCUserCert parameter requires that the signer of the CMC request belong to the Certificate Manager Agents group:
authz.acl=group="Certificate Manager Agents"
In directory-based user certificate renewal, this option is used to ensure that the original requester and the currently-authenticated user are the same.
An entity must authenticate (bind or, essentially, log into the system) before authorization can be evaluated. The authorization method specified must be one of the registered authorization instances from
CS.cfg .
|
name | Gives the name of the profile. For example, name=Agent-Authenticated Server Certificate Enrollment. This name is displayed in the end users enrollment or renewal page. |
input.list | Lists the allowed inputs for the profile by name. For example, input.list=i1,i2. |
input.input_id.class_id | Gives the java class name for the input by input ID (the name of the input listed in input.list). For example, input.i1.class_id=cmcCertReqInputImpl. |
output.list | Lists the possible output formats for the profile by name. For example, output.list=o1. |
output.output_id.class_id | Gives the java class name for the output format named in output.list. For example, output.o1.class_id=certOutputImpl. |
policyset.list | Lists the configured profile rules. For dual certificates, one set of rules applies to the signing key and the other to the encryption key. Single certificates use only one set of profile rules. For example, policyset.list=serverCertSet. |
policyset.policyset_id.list | Lists the policies within the policy set configured for the profile by policy ID number in the order in which they should be evaluated. For example, policyset.serverCertSet.list=1,2,3,4,5,6,7,8. |
policyset.policyset_id.policy_number.constraint.class_id | Gives the java class name of the constraint plug-in set for the default configured in the profile rule. For example, policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl. |
policyset.policyset_id.policy_number.constraint.name | Gives the user-defined name of the constraint. For example, policyset.serverCertSet.1.constraint.name=Subject Name Constraint. |
policyset.policyset_id.policy_number.constraint.params.attribute | Specifies a value for an allowed attribute for the constraint. The possible attributes vary depending on the type of constraint. For example, policyset.serverCertSet.1.constraint.params.pattern=CN=.*. |
policyset.policyset_id.policy_number.default.class_id | Gives the java class name for the default set in the profile rule. For example, policyset.serverCertSet.1.default.class_id=userSubjectNameDefaultImpl |
policyset.policyset_id.policy_number.default.name | Gives the user-defined name of the default. For example, policyset.serverCertSet.1.default.name=Subject Name Default |
policyset.policyset_id.policy_number.default.params.attribute | Specifies a value for an allowed attribute for the default. The possible attributes vary depending on the type of default. For example, policyset.serverCertSet.1.default.params.name=CN=(Name)$request.requestor_name$. |
11.1.1.2. Modifying Certificate Extensions Directly on the File System
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
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
2.5.29.15
in the certificate request.
11.1.1.2.1. Key Usage and Extended Key Usage Consistency
Purpose / Extended Key Usages | Key Usages |
---|---|
TLS Server Authentication command
id-kp-serverAuth
| digitalSignature , keyEncipherment , or KeyAgreement |
TLS Client (Mutual) Authentication
id-kp-clientAuth
| digitalSignature , keyEncipherment , and/or KeyAgreement |
Code Signing
id-kp-codeSigning
| digitalSignature |
Email Protection
id-kp-emailProtection
| digitalSignature , nonRepudiation , and/or (keyEncipherment or keyAgreement ) |
OCSP Response Signing
id-kp-OCSPSigning
| KeyAgreement and/or nonRepudiation |
- An enrollment profile that is intended for purpose of OCSP response signing contains Extended key usage
id-kp-OCSPSigning
but withkeyEncipherment
key usage bit:policyset.ocspCertSet.6.default.class_id=keyUsageExtDefaultImpl policyset.ocspCertSet..6.default.name=Key Usage Default policyset.ocspCertSet..6.default.params.keyUsageCritical=true policyset.ocspCertSet..6.default.params.keyUsageCrlSign=false policyset.ocspCertSet..6.default.params.keyUsageDataEncipherment=false policyset.ocspCertSet..6.default.params.keyUsageDecipherOnly=false policyset.ocspCertSet..6.default.params.keyUsageDigitalSignature=true policyset.ocspCertSet..6.default.params.keyUsageEncipherOnly=false policyset.ocspCertSet..6.default.params.keyUsageKeyAgreement=false policyset.ocspCertSet..6.default.params.keyUsageKeyCertSign=false policyset.ocspCertSet..6.default.params.keyUsageKeyEncipherment=true policyset.ocspCertSet..6.default.params.keyUsageNonRepudiation=true policyset.ocspCertSet.7.constraint.params.exKeyUsageOIDs=1.3.6.1.5.5.7.3.9 policyset.ocspCertSet.7.default.class_id=extendedKeyUsageExtDefaultImpl policyset.ocspCertSet.7.default.name=Extended Key Usage Default policyset.ocspCertSet.7.default.params.exKeyUsageCritical=false policyset.ocspCertSet.7.default.params.exKeyUsageOIDs=1.3.6.1.5.5.7.3.9
- An enrollment profile that is intended for the purpose of TLS server authentication contains Extended key
usage id-kp-serverAuth
but with CRL signing key usage bit:policyset.serverCertSet.6.default.name=Key Usage Default policyset.serverCertSet.6.default.params.keyUsageCritical=true policyset.serverCertSet.6.default.params.keyUsageDigitalSignature=true policyset.serverCertSet.6.default.params.keyUsageNonRepudiation=false policyset.serverCertSet.6.default.params.keyUsageDataEncipherment=true policyset.serverCertSet.6.default.params.keyUsageKeyEncipherment=false policyset.serverCertSet.6.default.params.keyUsageKeyAgreement=true policyset.serverCertSet.6.default.params.keyUsageKeyCertSign=false policyset.serverCertSet.6.default.params.keyUsageCrlSign=true policyset.serverCertSet.6.default.params.keyUsageEncipherOnly=false policyset.serverCertSet.6.default.params.keyUsageDecipherOnly=false policyset.cmcUserCertSet.7.default.class_id=extendedKeyUsageExtDefaultImpl policyset.cmcUserCertSet.7.default.name=Extended Key Usage Extension Default policyset.cmcUserCertSet.7.default.params.exKeyUsageCritical=false policyset.serverCertSet.7.default.params.exKeyUsageOIDs=1.3.6.1.5.5.7.3.1
- The Extended Key Usage Extension Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
- The keyUsage section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
- The Extended Key Usage Extension Constraint section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
- The extKeyUsage section in the Red Hat Certificate System Administration Guide (Common Criteria Edition).
11.1.1.3. Adding Profile Inputs Directly on the File System
profiles/ca
directory contains the input information for 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
11.1.2. Changing the Default Validity Time of Certificates
825
days (approximately 27 months), open the /var/lib/pki/instance_name/ca/profiles/ca/caCACert.cfg
file in an editor and set:
policyset.caCertSet.2.default.params.range=825
11.1.3. Configuring CA System Certificate Profiles
/var/lib/pki/[instance name]/ca/conf
file. Those profiles are:
caAuditSigningCert.profile
eccAdminCert.profile
rsaAdminCert.profile
caCert.profile
eccServerCert.profile
saServerCert.profile
caOCSPCert.profile
eccSubsystemCert.profile
rsaSubsystemCert.profile
pkispawn
Step Two Installation” procedure is performed. The following is an example that demonstrates:
- How to change validity to CA signing certificate.
- How to add extensions (e.g. Certificate policies extension).
- Back up the original CA certificate profile used by
pkispawn
.cp -p /usr/share/pki/ca/conf/caCert.profile /usr/share/pki/ca/conf/caCert.profile.orig
- Open the CA certificate profile used by the configuration wizard.
vim /usr/share/pki/ca/conf/caCert.profile
- Reset the validity period in the Validity Default to whatever you want. For example, to change the period to two years:
2.default.class=com.netscape.cms.profile.def.ValidityDefault 2.default.name=Validity Default 2.default.params.range=7200
- Add any extensions by creating a new default entry in the profile and adding it to the list. For example, to add the Certificate Policies Extension, add the default (which, in this example, is default #9):
9.default.class_id=certificatePoliciesExtDefaultImpl 9.default.name=Certificate Policies Extension Default 9.default.params.Critical=false 9.default.params.PoliciesExt.certPolicy0.enable=false 9.default.params.PoliciesExt.certPolicy0.policyId= 9.default.params.PoliciesExt.certPolicy0.PolicyQualifiers0.CPSURI.enable=true 9.default.params.PoliciesExt.certPolicy0.PolicyQualifiers0.CPSURI.value=CertificatePolicies.example.com 9.default.params.PoliciesExt.certPolicy0.PolicyQualifiers0.usernotice.enable=false 9.default.params.PoliciesExt.certPolicy0.PolicyQualifiers0.usernotice.explicitText.value= 9.default.params.PoliciesExt.certPolicy0.PolicyQualifiers0.usernotice.noticeReference.noticeNumbers= 9.default.params.PoliciesExt.certPolicy0.PolicyQualifiers0.usernotice.noticeReference.organization=
Then, add the default number to the list of defaults to use the new default:list=2,4,5,6,7,8,
9
11.1.4. Managing Smart Card CA Profiles
Note
/var/lib/pki/instance_name/profiles/ca/
directory with the other CA profiles. The default profiles are listed in Table 11.2, “Default Token Certificate Profiles”.
Table 11.2. Default Token Certificate Profiles
Profile Name | Configuration File | Description |
---|---|---|
Regular Enrollment Profiles | ||
Token Device Key Enrollment | caTokenDeviceKeyEnrollment.cfg | For enrolling tokens used for devices or servers. |
Token User Encryption Certificate Enrollment | caTokenUserEncryptionKeyEnrollment.cfg | For enrolling encryption certificates on the token for a user. |
Token User Signing Certificate Enrollment | caTokenUserSigningKeyEnrollment.cfg | For enrolling signing certificates on the token for a user. |
Token User MS Login Certificate Enrollment | caTokenMSLoginEnrollment.cfg | For enrolling user certificates to use for single sign-on to a Windows domain or PC. |
Temporary Token Profiles | ||
Temporary Device Certificate Enrollment | caTempTokenDeviceKeyEnrollment.cfg | For enrolling certificates for a device on a temporary token. |
Temporary Token User Encryption Certificate Enrollment | caTempTokenUserEncryptionKeyEnrollment.cfg | For enrolling an encryption certificate on a temporary token for a user. |
Temporary Token User Signing Certificate Enrollment | caTempTokenUserSigningKeyEnrollment.cfg | For enrolling a signing certificates on a temporary token for a user. |
Renewal Profiles[a] | ||
Token User Encryption Certificate Enrollment (Renewal) | caTokenUserEncryptionKeyRenewal.cfg | For renewing encryption certificates on the token for a user, if renewal is allowed. |
Token User Signing Certificate Enrollment (Renewal) | caTokenUserSigningKeyRenewal.cfg | For renewing signing certificates on the token for a user, if renewal is allowed. |
[a]
Renewal profiles can only be used in conjunction with the profile that issued the original certificate. There are two settings that are beneficial:
|
11.1.4.1. Editing Enrollment Profiles for the TPS
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
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
.
dnpattern
parameter is covered in B.2.11. Subject Name Constraint and B.1.28. Subject Name Default in Red Hat Certificate System Administration Guide.
11.1.4.2. Creating Custom TPS Profiles
Note
- Create a new token profile for the issuing CA. Setting up profiles is covered in 3.2. Setting up Certificate Profiles in Red Hat Certificate System's Administration Guide.
- Copy the profile into the CA's profiles directory,
/var/lib/instance_name/ca/profiles/ca/
. - Edit the CA's
CS.cfg
file, and add the new profile references and the profile name to the CA's list of profiles. For example:vim etc/pki/instance_name/ca/CS.cfg profile.list=caUserCert,...,caManualRenewal,
tpsExampleEnrollProfile
... profile.caTokenMSLoginEnrollment.class_id=caUserCertEnrollImpl profile.caTokenMSLoginEnrollment.config=/var/lib/pki/instance_name/profiles/ca/tpsExampleEnrollProfile.cfg - Edit the TPS
CS.cfg
file, and add a line to point to the new CA enrollment profile. For example:vim /etc/pki/instance_name/tps/CS.cfg op.enroll.userKey.keyGen.signing.ca.profileId=tpsExampleEnrollProfile
- Restart the instance after editing the smart card profiles:
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
If the CA and TPS are in separate instances, restart both instances.
Note
externalReg
) setting are configured in the user LDAP entry.
11.1.4.3. Using the Windows Smart Card Logon Profile
caTokenMSLoginEnrollment.cfg
).
- Issue a certificate to the domain controller, if it is not already configured for TLS.
- Configure the smart card login per user, rather than as a global policy, to prevent locking out the domain administrator.
- Enable CRL publishing to the Active Directory server because the domain controller checks the CRL at every login.
11.1.5. Disabling Certificate Enrolment Profiles
*.cfg
file in the /var/lib/pki/instance_name/ca/profiles/ca/
directory and set the visible
and enable
parameters to false
.
- List all non-CMC profiles:
# ls -l /var/lib/pki/instance_name/ca/profiles/ca/ | grep -v "CMC"
- In each of the displayed files, set the following parameters to
false
:visible=false enable=false
visible=false
in all CMC profiles to make them invisible on the end entity page:
- List all CMC profiles:
# ls -l /var/lib/pki/instance_name/ca/profiles/ca/*CMC*
- In each of the displayed files, set:
visible=false
Chapter 12. Configuring the Key Recovery Authority
12.1. Manually Setting up Key Archival
Important
- Having a trusted relationship between a CA and a KRA.
- Having the enrollment form enabled for key archival, meaning it has key archival configured and the KRA transport certificate stored in the form.
- If necessary, create a trusted manager to establish a relationship between the Certificate Manager and the KRA.For the CA to be able to request key archival of the KRA, 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 TLS client authentication certificate, in the internal database of the KRA. By default, the Certificate Manager uses its subsystem certificate for TLS client authentication to the KRA.
- Copy the base-64 encoded transport certificate for the KRA.The transport certificate is stored in the KRA'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.Alternatively, download the transport certificate using thepki
ultility:# pki cert-find --name "KRA Transport certificate's subject common name" # pki cert-show serial_number --output transport.pem
- Add the transport certificate to the CA's
CS.cfg
file.ca.connector.KRA.enable=true ca.connector.KRA.host=server.example.com ca.connector.KRA.local=false ca.connector.KRA.nickName=subsystemCert cert-pki-ca ca.connector.KRA.port=8443 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
- Then edit the enrollment form and add or replace the transport certificate value in the
keyTransportCert
method.vim /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/ca/ProfileSelect.template var keyTransportCert = MIIDbDCCAlSgAwIBAgIBDDANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9Eb21haW4gc28gbmFtZWQxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0wNjExMTQxODI2NDdaFw0wODEwMTQxNzQwNThaMD4xGDAWBgNVBAoTD0RvbWFpbiBzbyBuYW1lZDEiMCAGA1UEAxMZRFJNIFRyYW5zcG9ydCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKnMGB3WkznueouwZjrWLFZBLpKt6TimNKV9iz5s0zrGUlpdt81/BTsU5A2sRUwNfoZSMs/d5KLuXOHPyGtmC6yVvaY719hr9EGYuv0Sw6jb3WnEKHpjbUO/vhFwTufJHWKXFN3V4pMbHTkqW/x5fu/3QyyUre/5IhG0fcEmfvYxIyvZUJx+aQBW437ATD99Kuh+I+FuYdW+SqYHznHY8BqOdJwJ1JiJMNceXYAuAdk+9t70RztfAhBmkK0OOP0vH5BZ7RCwE3Y/6ycUdSyPZGGc76a0HrKOz+lwVFulFStiuZIaG1pv0NNivzcj0hEYq6AfJ3hgxcC1h87LmCxgRWUCAwEAAaN5MHcwHwYDVR0jBBgwFoAURShCYtSg+Oh4rrgmLFB/Fg7X3qcwRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUFBzABhihodHRwOi8vY2x5ZGUucmR1LnJlZGhhdC5jb206OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIE8DANBgkqhkiG9w0BAQUFAAOCAQEAFYz5ibujdIXgnJCbHSPWdKG0T+FmR67YqiOtoNlGyIgJ42fi5lsDPfCbIAe3YFqmF3wU472h8LDLGyBjy9RJxBj+aCizwHkuoH26KmPGntIayqWDH/UGsIL0mvTSOeLqI3KM0IuH7bxGXjlION83xWbxumW/kVLbT9RCbL4216tqq5jsjfOHNNvUdFhWyYdfEOjpp/UQZOhOM1d8GFiw8N8ClWBGc3mdlADQp6tviodXueluZ7UxJLNx3HXKFYLleewwIFhC82zqeQ1PbxQDL8QLjzca+IUzq6Cd/t7OAgvv3YmpXgNR0/xoWQGdM1/YwHxtcAcVlskXJw5ZR0Y2zA==;
12.2. Encryption Of KRA Operations
- Archival:
- Encryption of keys to archive in a Certificate Request Message Format (CRMF) package for transport to the KRA.
- Encryption of the key for storage in the KRA LDAP database.
- Recovery:
- Encryption of a user-provided session key for transport to the key.
- Decryption of the secret and re-encryption using the user provided session key or creation of a PKCS#12 package.
- Generation:
- Encryption of a generated key for storage.
12.2.1. How Clients Manage Key Operation Encryption
12.2.2. Configuring the Encryption Algorithm in the KRA
Note
kra.allowEncDecrypt.archive=true
and kra.allowEncDecrypt.recovery=true
) and AES Key Wrap (in case when kra.allowEncDecrypt.archive=false
and kra.allowEncDecrypt.recovery=false
) are allowed in the following configuration. Any FIPS140-2 validated HSM that supports either algorithm is allowed for the key archival and recovery feature provided by KRA.
/var/lib/pki/pki-instance_name/conf/kra/CS.cfg
file. We recommend the following set of parameters (see note above for other option):
kra.allowEncDecrypt.archive=false kra.allowEncDecrypt.recovery=false kra.storageUnit.wrapping.1.sessionKeyLength=256 kra.storageUnit.wrapping.1.sessionKeyWrapAlgorithm=RSA kra.storageUnit.wrapping.1.payloadEncryptionPadding=PKCS5Padding kra.storageUnit.wrapping.1.sessionKeyKeyGenAlgorithm=AES kra.storageUnit.wrapping.1.payloadEncryptionAlgorithm=AES kra.storageUnit.wrapping.1.payloadEncryptionMode=CBC kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap kra.storageUnit.wrapping.1.sessionKeyType=AES kra.storageUnit.wrapping.1.payloadWrapIVLen=16 kra.storageUnit.wrapping.choice=1
kra.storageUnit.wrapping.0.*
vs kra.storageUnit.wrapping.1.*
) has individual settings, and the number defines which settings belong to the same configuration group. The current configuration group is set in the kra.storageUnit.wrapping.choice
parameter in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg
file.
kra.storageUnit.wrapping.choice=1
is set in the configuration file before continuing.
Note
12.2.2.1. Explanation of Parameters and their Values
payload
. The set of parameters to be used depends on the value of kra.allowEncDecrypt.archive
and kra.allowEncDecrypt.recovery
. By default, both of these are false. See Section 12.2.2.2, “Solving Limitations of HSMs When Using AES Encryption in KRAs” for the effect of these two parameters on HSMs.
kra.allowEncDecrypt.archive
and kra.allowEncDecrypt.recovery
are both false:
payloadWrapAlgorithm
determines the wrapping algorithm used. The only one valid choice isAES KeyWrap
.- When
payloadWrapAlgorithm=AES/CBC/PKCS5Padding
, thenpayloadWrapIVLength=16
has to be specified to tell PKI that we need to generate an IV (as CBC requires one).
kra.allowEncDecrypt.archive
and kra.allowEncDecrypt.recovery
are both true:
payloadEncryptionAlgorithm
determines the encryption algorithm used. The only valid choice is AES.payloadEncryptionMode
determines the block chaining mode. The only valid choice is CBC.payloadEncryptionPadding
determines the padding scheme. The only valid choice is PKCS5Padding.
sessionKey
.
sessionKeyType
is the type of key to generate. The only valid choice is AES.sessionKeyLength
is the length of the generated session key. Valid choices are 128 and 256, to encrypt the payload with 128-bit AES or 256-bit AES respectively.sessionKeyWrapAlgorithm
is the type of key the KRA Storage Certificate is. The only valid choice in this guide is RSA.
12.2.2.2. Solving Limitations of HSMs When Using AES Encryption in KRAs
Selecting a Different Algorithm for the Key Wrapping
AES-128-CBC
as the key wrapping algorithm:
- Set the following parameters in the
/var/lib/pki/pki-instance_name/conf/kra/CS.cfg
file:kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap kra.storageUnit.wrapping.1.payloadWrapIVLen=16 kra.storageUnit.wrapping.1.sessionKeyLength=128
- Restart the instance:
# systemctl restart pki-tomcatd@instance_name.service
OR# systemctl restart pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)If the KRA runs in a difference instance then the CA, you need to restart both instances.
kra.storageUnit.wrapping.1.payloadWrap{Algorithm,IVLen}
and kra.storageUnit.wrapping.1.payloadEncryption{Algorithm,Mode,Padding}
parameters.
Setting the KRA into Encryption Mode
- Set the following parameters in the
/var/lib/pki/pki-instance_name/conf/kra/CS.cfg
file totrue
:kra.allowEncDecrypt.archive=true kra.allowEncDecrypt.recovery=true
- Restart the service:
# systemctl restart pki-tomcatd@instance_name.service
OR# systemctl restart pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)If the KRA runs in a difference instance than the CA, you need to restart both instances.
kra.storageUnit.wrapping.1.payloadEncryption{Algorithm,Mode,Padding}
and kra.storageUnit.wrapping.1.payloadWrap{Algorithm,IVLen}
parameters.
Note
12.3. Setting up Agent-Approved Key Recovery Schemes
12.3.1. Configuring Agent-Approved Key Recovery in the Console
Note
CS.cfg
file. The Console uses the Key Recovery Authority Agents Group
by default.
- Open the KRA's console. For example:
pkiconsole https://server.example.com:8443/kra
- Click the Key Recovery Authority link in the left navigation tree.
- Enter the number of agents to use to approve key recover in the Required Number of Agents field.
12.3.2. Configuring Agent-Approved Key Recovery in the Command Line
- Set the number of recovery managers to require to approve a recovery.
- Set the group to which these users must belong.
CS.cfg
configuration file.
- Stop the server before editing the configuration file.
systemctl stop pki-tomcatd@instance_name.service
ORsystemctl stop pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
) - Open the KRA's
CS.cfg
file.vim /var/lib/pki/pki-tomcat/kra/conf/CS.cfg
- Edit the two recovery scheme parameters.
kra.noOfRequiredRecoveryAgents=3 kra.recoveryAgentGroup=Key Recovery Authority Agents
- Restart the server.
systemctl start pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service
12.3.3. Customizing the Key Recovery Form
/var/lib/pki/pki-tomcat/kra/webapps/kra/agent/kra/
directory, called confirmRecover.html
.
Important
Chapter 13. Configuring Logs
13.1. Certificate System Log Settings
13.1.1. Services That Are Logged
Table 13.1. Services Logged
Service | Description |
---|---|
ACLs | Logs events related to access control lists. |
Administration | Logs events related to administration activities, such as HTTPS communication between the Console and the instance. |
All | Logs events related to all the services. |
Authentication | Logs events related to activity with the authentication module. |
Certificate Authority | Logs events related to the Certificate Manager. |
Database | Logs events related to activity with the internal database. |
HTTP |
Logs events related to the HTTP activity of the server. Note that HTTP events are actually logged to the errors log belonging to the Apache server incorporated with the Certificate System to provide HTTP services.
|
Key Recovery Authority | Logs events related to the KRA. |
LDAP | Logs events related to activity with the LDAP directory, which is used for publishing certificates and CRLs. |
OCSP | Logs events related to OCSP, such as OCSP status GET requests. |
Others | Logs events related to other activities, such as command-line utilities and other processes. |
Request Queue | Logs events related to the request queue activity. |
User and Group | Logs events related to users and groups of the instance. |
13.1.2. Log Levels (Message Categories)
0
to 10
, each number indicating the level of logging to be performed by the server. The level sets how detailed the logging should be.
Note
1
and this value should not be changed. To enable debug logging, see Section 13.3.3, “Additional Configuration for Debug Log”.
Table 13.2. Log Levels and Corresponding Log Messages
Log level | Message category | Description |
---|---|---|
0 | Debugging | These messages contain debugging information. This level is not recommended for regular use because it generates too much information. |
1 | All logging levels | This log level enables all logging levels. |
2 | Warning | These messages are warnings only and do not indicate any failure in the normal operation of the server. |
3 | 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). |
4 | Misconfiguration | These 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 | Security-related events | These messages identify occurrences that affect the security of the server. For example, Privileged access attempted by user with revoked or unlisted certificate . |
7 | PDU-related events (debugging) | These messages contain debugging information for PDU events. This level is not recommended for regular use because it generates more information than is normally useful. |
8 | PDU-related events | These messages relate transactions and rules processed on a PDU, such as creating MAC tokens. |
9 | PDU-related events | This log level provides verbose log messages for events processed on a PDU, such as creating MAC tokens. |
10 | Informational (default selection for audit log) | 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. |
13.1.3. Buffered and Unbuffered Logging
- 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.
13.1.4. Log File Rotation
- 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. - 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).
log
directory to an archive medium.
Note
signtool
, that signs log files before archiving them as a means of tamper detection.
13.2. Operating System (external to RHCS) Log Settings
13.2.1. Enabling OS-level Audit Logs
Warning
sudo
.
auditd
logging framework provides many additional audit capabilities. These OS-level audit logs complement functionality provided by Certificate System directly. Before performing any of the following steps in this section, make sure the audit
package is installed:
#
sudo yum install audit
yum
and rpm
and including Certificate System) is automatically performed and requires no additional configuration.
Note
auditd
service, validate the new rules were added by running:
# auditctl -l
13.2.1.1. Auditing Certificate System Audit Log Deletion
/etc/audit/rules.d/rhcs-audit-log-deletion.rules
with the following contents:
-a always,exit -F arch=b32 -S unlink -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b32 -S rename -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b32 -S rmdir -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b32 -S unlinkat -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b32 -S renameat -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b64 -S unlink -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b64 -S rename -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b64 -S rmdir -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b64 -S unlinkat -F dir=/var/log/pki -F key=rhcs_audit_deletion
-a always,exit -F arch=b64 -S renameat -F dir=/var/log/pki -F key=rhcs_audit_deletion
auditd
:
#
service auditd restart
13.2.1.2. Auditing Unauthorized Certificate System Use of Secret Keys
/etc/audit/rules.d/rhcs-audit-nssdb-access.rules
file with the following contents:
-w /etc/pki/<instance name>/alias -p warx -k rhcs_audit_nssdb
/etc/pki/<instance name>/alias
, add to /etc/audit/rules.d/rhcs-audit-nssdb-access.rules
the following line :
-w /etc/pki/<instance name>/alias/<file> -p warx -k rhcs_audit_nssdb
pki-ca121318ec
and cert8.db
, key3.db
, NHSM6000-OCScert8.db
, NHSM6000-OCSkey3.db
, and secmod.db
are files, then the configuration file would contain:
-w /etc/pki/pki-ca121318ec/alias -p warx -k rhcs_audit_nssdb
-w /etc/pki/pki-ca121318ec/alias/cert8.db -p warx -k rhcs_audit_nssdb
-w /etc/pki/pki-ca121318ec/alias/key3.db -p warx -k rhcs_audit_nssdb
-w /etc/pki/pki-ca121318ec/alias/NHSM6000-OCScert8.db -p warx -k rhcs_audit_nssdb
-w /etc/pki/pki-ca121318ec/alias/NHSM6000-OCSkey3.db -p warx -k rhcs_audit_nssdb
-w /etc/pki/pki-ca121318ec/alias/secmod.db -p warx -k rhcs_audit_nssdb
auditd
:
#
service auditd restart
13.2.1.3. Auditing Time Change Events
/etc/audit/rules.d/rhcs-audit-rhcs_audit_time_change.rules
file with the following contents:
-a always,exit -F arch=b32 -S adjtimex,settimeofday,stime -F key=rhcs_audit_time_change
-a always,exit -F arch=b64 -S adjtimex,settimeofday -F key=rhcs_audit_time_change
-a always,exit -F arch=b32 -S clock_settime -F a0=0x0 -F key=rhcs_audit_time_change
-a always,exit -F arch=b64 -S clock_settime -F a0=0x0 -F key=rhcs_audit_time_change
-a always,exit -F arch=b32 -S clock_adjtime -F key=rhcs_audit_time_change
-a always,exit -F arch=b64 -S clock_adjtime -F key=rhcs_audit_time_change
-w /etc/localtime -p wa -k rhcs_audit_time_change
auditd
:
#
service auditd restart
13.2.1.4. Auditing Access to Certificate System Configuration
/etc/audit/rules.d/rhcs-audit-config-access.rules
file with the following contents:
-w /etc/pki/instance_name/server.xml -p wax -k rhcs_audit_config
/etc/pki/instance_name/
directory the following contents:
-w /etc/pki/instance_name/subsystem/CS.cfg -p wax -k rhcs_audit_config
Example 13.1. rhcs-audit-config-access.rules Configuration File
pki-ca121318ec
and only a CA is installed, the /etc/audit/rules.d/rhcs-audit-config-access.rules
file would contain:
-w /etc/pki/pki-ca121318ec/server.xml -p wax -k rhcs_audit_config -w /etc/pki/pki-ca121318ec/ca/CS.cfg -p wax -k rhcs_audit_config
rhcs_audit_nssdb
.
13.3. Configuring Logs in the CS.cfg File
CS.cfg
for the instance.
- Stop the subsystem instance.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
CS.cfg
file in the/var/lib/pki/instance_name/subsystem_name/conf/
directory. - 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
orlog.instance.System
. Paste all entries at the bottom of the logging section and change the name of this instance by changing the wordTransactions
orSystem
in each parameter to the new name. - To configure a log instance, modify the parameters associated with that log. These parameters begin with
log.instance
.Table 13.3. Log Entry Parameters
Parameter Description type The type of log file. system creates error and system logs; transaction records audit logs. enable Sets whether the log is active. Only enabled logs actually record events. level Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The log level setting is a numeric value, as listed in Section 13.1.2, “Log Levels (Message Categories)”. fileName The full path, including the file name, to the log file. The subsystem user should have read/write permission to the file. bufferSize The buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB. For more information on buffered logging, see Section 13.1.3, “Buffered and Unbuffered Logging”. flushInterval The amount of time, in seconds, before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds. maxFileSize The size, kilobytes (KB), 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 new. For more information on log file rotation, see Section 13.1.4, “Log File Rotation”. The default size is 2000 KB. rolloverInterval The frequency which the server rotates the active log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 13.1.4, “Log File Rotation”. register[a] If this variable is set to false
(the default value), the self-test messages are only logged to the log file specified byselftests.container.logger.fileName
. If this variable is set totrue
, then the self-test messages are written to both the log file specified byselftests.container.logger.fileName
as well as to the log file specified bylog.
instance.Transactions.
fileName.logSigning[b] Enables signed logging. When this parameter is enabled, provide a value for the signedAuditCertNickname parameter. This option means the log can only be viewed by an auditor. The value is either true
orfalse
.signedAuditCertNickname[b] 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[b] Specifies which events are logged to the audit log. Log events are separated by commas with no spaces. [a] This is for self-test logs only.[b] This is for audit logs only. - Save the file.
- Start the subsystem instance.
systemctl start pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)
13.3.1. Enabling and Configuring Signed Audit Log
13.3.1.1. Enabling Signed Audit Logging
# pki-server subsystem-audit-config-show Enabled: True Log File: audit_signing_log_file Buffer Size (bytes): 512 Flush Interval (seconds): 5 Max File Size (bytes): 2000 Rollover Interval (seconds): 2592000 Expiration Time (seconds): 0 Log Signing: False Signing Certificate: audit_signing_certificate
- Use the
pki-server
utility to set the--logSigning
option totrue
:# pki-server subsystem-audit-config-mod --logSigning True ... Log Signing: True ...
- Restart the instance:
# systemctl restart pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)
13.3.1.2. Configuring Audit Events
13.3.1.2.1. Enabling and Disabling Audit Events
Important
13.3.1.2.2. Filtering Audit Events
Table 13.4. Supported Audit Event Filters
Type | Format | Example |
---|---|---|
Presence | (attribute=*) | (ReqID=*) |
Equality | (attribute=value) | (Outcome=Failure) |
Substring | (attribute=initial*any*...*any*final) | (SubjectID=*admin*) |
AND operation | (&(filter_1)(filter_2)...(filter_n)) | (&(SubjectID=admin)(Outcome=Failure)) |
OR operation | (|(filter_1)(filter_2)...(filter_n)) | (|(SubjectID=admin)(Outcome=Failure)) |
NOT operation | (!(filter)) | (!(SubjectID=admin)) |
Example 13.2. Filtering Audit Events
$ pki-server ca-audit-event-show PROFILE_CERT_REQUEST Event Name: PROFILE_CERT_REQUEST Enabled: True Filter: None $ pki-server ca-audit-event-show CERT_REQUEST_PROCESSED Event Name: CERT_REQUEST_PROCESSED Enabled: True Filter: None
InfoName
field set to rejectReason
or cancelReason
:
- Execute the following commands:
$ pki-server ca-audit-event-update PROFILE_CERT_REQUEST --filter "(Outcome=Failure)" ... Filter: (Outcome=Failure) $ pki-server ca-audit-event-update CERT_REQUEST_PROCESSED --filter "(|(InfoName=rejectReason)(InfoName=cancelReason))" ... Filter: (|(InfoName=rejectReason)(InfoName=cancelReason))
- Restart Certificate System:
# systemctl restart pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)
13.3.2. Configuring Self-Tests
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
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.
CS.cfg
file.
13.3.2.1. Default Self-Tests at Startup
CAPresence
- used to verify the presence of the CA subsystem.CAValidity
- used to determine that the CA subsystem is currently valid and has not expired. This involves checking the expiration of the CA certificate.SystemCertsVerification
- used to determine that the system certificates are currently valid and have not expired or been revoked. For the CA subsystem, only validity tests for each certificate are done, leaving out certificate verification tests which could result in an OCSP request. This behavior can be overridden with the following config parameter:selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=true
By default, this config parameter is consideredfalse
if not present at all.
KRAPresence
- used to verify the presence of the KRA subsystem.KRAValidity
- used to determine that the KRA subsystem is currently valid and has not expired. This involves checking the expiration of the KRA certificate.SystemCertsVerification
- used to determine that the system certificates are currently valid and have not expired or been revoked.
OCSPPresence
- used to verify the presence of the OCSP subsystem.OCSPValidity
- used to determine that the OCSP subsystem is currently valid and has not expired. This involves checking the expiration of the OCSP certificate.SystemCertsVerification
- used to determine that the system certificates are currently valid and have not expired or been revoked. For the OCSP subsystem, only validity tests for each certificate are done, leaving out certificate verification tests which could result in an OCSP request. This behavior can be overridden with the following config parameter:selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=true
By default, this config parameter is consideredfalse
if not present at all.
TKSKnownSessionKey
- used to verify the known session key of a TKS subsystem. This verifies the TKS is able to properly assist in creating keys on behalf of the TPS and supported smart cards.SystemCertsVerification
- used to determine that the system certificates are currently valid and have not expired or been revoked.
TPSPresence
- used to verify the presence of the TPS subsystem.TPSValidity
- used to determine that the TPS subsystem is currently valid and has not expired. This involves checking the expiration of the TPS certificate.SystemCertsVerification
- used to determine that the system certificates are currently valid and have not expired or been revoked.
13.3.2.2. Modifying Self-Test Configuration
- Stop the subsystem instance.
- Open the
CS.cfg
file located in the instance'sconf/
directory. - To edit the settings for the self-test log, edit the entries that begin with
selftests.container.logger
. Unless otherwise specified, these parameters do not affect compliance. These include the following parameters:- bufferSize — Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. 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. Only enabled logs actually record events. This value must be enabled for compliance. - fileName — Specify the full path, including the filename, to the file to write messages. The server must have read/write permission to the file. By default, the self-test log file is
/var/lib/pki/instance_name/logs/subsystem_type/selftests.log
- 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 it reaches this size, the file is copied to a rotated file, and a new log file is started. - register — If this variable is set to
false
(the default value), the self-test messages are only logged to the log file specified byselftests.container.logger.fileName
. If this variable is set totrue
, then the self-test messages are written to both the log file specified byselftests.container.logger.fileName
and the log file specified bylog.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.
- type — Set to
transaction
; do not change this.
- 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
orselftests.container.order.startup
parameters. - Save the file.
- Start the subsystem.
13.3.3. Additional Configuration for Debug Log
13.3.3.1. Enabling and Disabling Debug Logging
- Edit the
/var/lib/pki/instance_name/subsystem/conf/CS.cfg
file and set thedebug.enabled
parameter:- To disable debug logging, set:
debug.enabled=false
Note
Debug logs are not part of audit logging. Debug logs are helpful when trying to debug specific failures in Certificate System or a failing installation.By default, debug logs are enabled. If it is not desired, the administrator can safely disable debug logging to turn down verbosity. - To enable debug logging, set:
debug.enabled=true
- Restart the Certificate System instance:
# systemctl restart pki-tomcatd@instance-name.service
OR# systemctl restart pki-tomcatd-nuxwdog@instance-name.service (if using
nuxwdog watchdog
)
13.3.3.2. Setting up Rotation of Debug Log Files
logrotate
, to rotate the logs.
Example 13.3. Using logrotate
to Rotate Debug Logs
/etc/logrotate.d/rhcs_debug
with the following content:
/var/log/pki/instance_name/subsystem/debug { copytruncate weekly rotate 5 notifempty missingok }
/var/log/pki/instance_name/ca/debug /var/log/pki/instance_name/kra/debug { ... }
logrotate
and the parameters used in the example, see the logrotate(8) man page.
13.4. Audit Retention
- Extended Audit Retention: Audit data that is retained for necessary maintenance for a certificate's lifetime (from issuance to its expiration or revocation date). In Certificate System, they appear in the following areas:
- Signed audit logs: All events defined in Appendix E. Audit Events of Red Hat Certificate System's Administration Guide.
- In the CA's internal LDAP server, certificate request records received by the CA and the certificate records as the requests are approved.
- Normal Audit Retention: Audit data that is typically retained only to support normal operation. This includes all events that do not fall under the extended audit retention category.
Note
13.4.1. Location of Audit Data
13.4.1.1. Location of Audit Logs
/var/lib/pki/instance_name/subsystem_type/logs/signedAudit/
directory. For example, the audit logs of a CA are stored in the /var/lib/pki/instance_name/ca/logs/signedAudit/
directory. Normal users cannot access files in this directory. See
Important
13.4.1.2. Location of Certificate Requests and Certificate Records
pkispawn
utility:
pki_ds_hostname
pki_ds_ldap_port
pki_ds_database
pki_ds_base_dn
- Log into the CA EE portal under
https://host_name:port/ca/ee/ca/
. - Click Check Request Status.
- Enter the Request Identifier.
- Click Issued Certificate.
- Search for Validity.
- Log into the CA EE portal under
https://host_name:port/ca/ee/ca/
. - Enter the serial number range. If you search for one specific record, enter the record's serial number in both the lowest and highest serial number field.
- Click on the search result.
- Search for Validity.
Important
Chapter 14. Creating a Role User
- Create a Certificate System administrative user on the operating system
- Create a PKI role in Certificate System
14.1. Creating a PKI Administrative User on the Operating System
Note
- Create the
pkiadmin
group on the operating system.# groupadd -r pkiadmin
- Add the
pkiuser
to thepkiadmin
group:# usermod -a -G pkiadmin pkiuser
- Create a user on the operating system. For example, to create the
jsmith
account:# useradd -g pkiadmin -d /home/jsmith -s /bin/bash -c "Red Hat Certificate System Administrator John Smith" -m jsmith
For details, see the useradd(8) man page. - Add the user
jsmith
to thepkiadmin
group:# usermod -a -G pkiadmin jsmith
For details, see the usermod(8) man page.If you are using a nCipher hardware security module (HSM), add the user who manages the HSM device to thenfast
group:# usermod -a -G nfast pkiuser # usermod -a -G nfast jsmith
- Add proper
sudo
rules to allow thepkiadmin
group to Certificate System and other system services.For both simplicity of administration and security, the Certificate System and Directory Server processes can be configured so that PKI administrators (instead of only root) can start and stop the services.A recommended option when setting up subsystems is to use apkiadmin
system group. (Details are Section 6.7, “Certificate System Operating System Users and Groups”). All of the operating system users which will be Certificate System administrators are then added to this group. If thispkiadmin
system group exists, then it can be granted sudo access to perform certain tasks.- Edit the
/etc/sudoers
file; on Red Hat Enterprise Linux, this can be done using thevisudo
command:# visudo
- Depending on what is installed on the machine, add a line for the Directory Server, the Administration Server, PKI management tools, and each PKI subsystem instance, granting
sudo
rights to thepkiadmin
group:# For Directory Server services %pkiadmin ALL = PASSWD: /usr/bin/systemctl * dirsrv.target %pkiadmin ALL = PASSWD: /usr/bin/systemctl * dirsrv-admin.service # For PKI instance management %pkiadmin ALL = PASSWD: /usr/sbin/pkispawn * %pkiadmin ALL = PASSWD: /usr/sbin/pkidestroy * # For PKI instance services %pkiadmin ALL = PASSWD: /usr/bin/systemctl * pki-tomcatd@instance_name.service
Important
Make sure to set sudo permissions for every Certificate System, Directory Server, and Administration Server on the machine — and only for those instances on the machine. There could be multiple instances of the same subsystem type on a machine or no instance of a subsystem type. It depends on the deployment. - Set the group on the following files to
pkiadmin
:# chgrp pkiadmin /etc/pki/instance_name/server.xml # chgrp -R pkiadmin /etc/pki/instance_name/alias # chgrp pkiadmin /etc/pki/instance_name/subsystem/CS.cfg # chgrp pkiadmin /var/log/pki/instance_name/subsystem/debug
14.2. Creating a PKI Role User in Certificate System
Chapter 15. Deleting the Bootstrap User
Important
15.1. Disabling Multi-roles Support
multirole
attribute in the instance's configuration.
- Stop the server:
systemctl stop pki-tomcatd@instance_name.service
ORsystemctl stop pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
) - Open the
CS.cfg
file:vim /var/lib/pki/instance_name/ca/conf/CS.cfg
- Change the
multiroles.enable
parameter value fromtrue
tofalse
. - Add or edit the list of default roles in Certificate System that are affected by the multi-roles setting. If multi-roles is disabled and a user belongs to one of the roles listed in the
multiroles.false.groupEnforceList
parameter, then the user cannot be added to any group for any of the other roles in the list.multiroles.false.groupEnforceList
=Administrators,Auditors,Trusted Managers,Certificate Manager Agents,Registration Manager Agents,Key Recovery Authority Agents,Online Certificate Status Manager Agents,Token Key Service Manager Agents,Enterprise CA Administrators,Enterprise KRA Adminstrators,Enterprise OCSP Administrators,Enterprise TKS Administrators,Enterprise TPS Administrators,Security Domain Administrators,Subsystem Group - Restart the server:
systemctl start pki-tomcatd@instance_name.service
ORsystemctl start pki-tomcatd-nuxwdog@instance_name.service (if using
nuxwdog watchdog
)
Part IV. Uninstalling Certificate System Subsystems
Chapter 16. Removing a Subsystem
pkidestroy -s subsystem_type -i instance_name
-s
option specifies the subsystem to be removed (such as CA, KRA, OCSP, TKS, or TPS). The -i
option specifies the instance name, such as pki-tomcat
.
Example 16.1. Removing a CA Subsystem
$ pkidestroy -s CA -i pki-tomcat Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg. Uninstalling CA from /var/lib/pki/pki-tomcat. Removed symlink /etc/systemd/system/multi-user.target.wants/pki-tomcatd.target. Uninstallation complete.
pkidestroy
utility removes the subsystem and any related files, such as the certificate databases, certificates, keys, and associated users. It does not uninstall the subsystem packages. If the subsystem is the last subsystem on the server instance, the server instance is removed as well.
Chapter 17. Removing Certificate System Subsystem Packages
yum
, to remove each package individually.
- Remove all the associated subsystems. For example:
pkidestroy -s CA -i pki-tomcat
- Run the uninstall utility. For example:
yum remove pki-subsystem_type
The subsystem type can beca
,kra
,ocsp
,tks
, ortps
. - To remove other packages and dependencies, remove the packages specifically, using
yum
. The complete list of installed packages is at Section 7.2, “Certificate System Packages”.
Glossary
A
- access control
- 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).
- access control instructions (ACI)
- 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).
- 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).
- administrator
- The person who installs and configures one or more Certificate System managers and sets up privileged users, or agents, for them. See also agent.
- Advanced Encryption Standard (AES)
- The Advanced Encryption Standard (AES), like its predecessor Data Encryption Standard (DES), is a FIPS-approved symmetric-key encryption standard. AES was adopted by the US government in 2002. It defines three block ciphers, AES-128, AES-192 and AES-256. The National Institute of Standards and Technology (NIST) defined the AES standard in U.S. FIPS PUB 197. For more information, see http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf.
- agent
- A user who belongs to a group authorized to manage agent services for a Certificate System manager. See also Certificate Manager agent, Key Recovery Authority agent.
- agent services
- 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.
- agent-approved enrollment
- An enrollment that requires an agent to approve the request before the certificate is issued.
- APDU
- Application protocol data unit. A communication unit (analogous to a byte) that is used in communications between a smart card and a smart card reader.
- attribute value assertion (AVA)
- An assertion of the form attribute = value, where attribute is a tag, such as
o
(organization) oruid
(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. - audit log
- 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.
- auditor
- A privileged user who can view the signed audit logs.
- authentication
- 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.
- authentication module
- 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.
- authorization
- 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).
- automated enrollment
- 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
- A user ID, in the form of a distinguished name (DN), used with a password to authenticate to Red Hat Directory Server.
C
- CA certificate
- A certificate that identifies a certificate authority. See also certificate authority (CA), subordinate CA, root CA.
- CA hierarchy
- 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.
- CA server key
- The TLS server key of the server providing a CA service.
- CA signing key
- The private key that corresponds to the public key in the CA certificate. A CA uses its signing key to sign certificates and CRLs.
- certificate
- 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.
- certificate authority (CA)
- 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 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.
- certificate chain
- 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.
- certificate extensions
- 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.
- certificate fingerprint
- 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.
- Certificate Management Message Formats (CMMF)
- 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 https://tools.ietf.org/html/draft-ietf-pkix-cmmf-02.
- Certificate Management Messages over Cryptographic Message Syntax (CMC)
- 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 https://tools.ietf.org/html/draft-ietf-pkix-cmc-02.
- Certificate Manager
- 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).
- Certificate Manager agent
- 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.
- certificate profile
- 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.
- Certificate Request Message Format (CRMF)
- 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 http://www.ietf.org/rfc/rfc2511.txt.
- certificate revocation list (CRL)
- As defined by the X.509 standard, a list of revoked certificates by serial number, generated and signed by a certificate authority (CA).
- Certificate System
- Certificate System console
- 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.
- Certificate System subsystem
- One of the five Certificate System managers: Certificate Manager, Online Certificate Status Manager, Key Recovery Authority, Token Key Service, or Token Processing System.
- certificate-based authentication
- Authentication based on certificates and public-key cryptography. See also password-based authentication.
- chain of trust
- See certificate chain.
- chained CA
- See linked CA.
- cipher
- client authentication
- 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.
- client TLS certificate
- A certificate used to identify a client to a server using the TLS protocol. See Transport Layer Security (TLS).
- CMC
- CMC Enrollment
- 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.
- CMMF
- Common Criteria
- A certification standard that evaluates computer security, both for software and hardware components. The software or hardware vendor defines the operating environment and specified configuration, identifies any threats, and outlines both the development and deployment processes for the target of evaluation (the thing being evaluated). The Common Criteria certification laboratory then tests the implementation design to look for any vulnerabilities.
- CRL
- CRMF
- cross-certification
- 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).
- cross-pair certificate
- 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.
- cryptographic algorithm
- A set of rules or directions used to perform cryptographic operations such as encryption and decryption.
- Cryptographic Message Syntax (CS)
- The syntax used to digitally sign, digest, authenticate, or encrypt arbitrary messages, such as CMMF.
- cryptographic module
- See PKCS #11 module.
- cryptographic service provider (CSP)
- 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.
- CSP
D
- decryption
- Unscrambling data that has been encrypted. See encryption.
- delta CRL
- A CRL containing a list of those certificates that have been revoked since the last full CRL was issued.
- digital ID
- See certificate.
- digital signature
- 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.
- distinguished name (DN)
- A series of AVAs that identify the subject of a certificate. See attribute value assertion (AVA).
- distribution points
- 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.
- dual key pair
- 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, public-key cryptography, signing key.
- Key Recovery Authority
- 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 Key Recovery Authority before issuing new certificates. The Key Recovery Authority 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.
- Key Recovery Authority agent
- A user who belongs to a group authorized to manage agent services for a Key Recovery Authority, including managing the request queue and authorizing recovery operation using HTML-based administration pages.
- Key Recovery Authority recovery agent
- One of the m of n people who own portions of the storage key for the Key Recovery Authority.
- Key Recovery Authority storage key
- Special key used by the Key Recovery Authority to encrypt the end entity's encryption key after it has been decrypted with the Key Recovery Authority's private transport key. The storage key never leaves the Key Recovery Authority.
- Key Recovery Authority transport certificate
- Certifies the public key used by an end entity to encrypt the entity's encryption key for transport to the Key Recovery Authority. The Key Recovery Authority uses the private key corresponding to the certified public key to decrypt the end entity's key before encrypting it with the storage key.
E
- eavesdropping
- Surreptitious interception of information sent over a network by an entity for which the information is not intended.
- Elliptic Curve Cryptography (ECC)
- A cryptographic algorithm which uses elliptic curves to create additive logarithms for the mathematical problems which are the basis of the cryptographic keys. ECC ciphers are more efficient to use than RSA ciphers and, because of their intrinsic complexity, are stronger at smaller bits than RSA ciphers. For more information, see https://tools.ietf.org/html/draft-ietf-tls-ecc-12.
- encryption
- Scrambling information in a way that disguises its meaning. See decryption.
- encryption key
- 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.
- end entity
- In a public-key infrastructure (PKI), a person, router, server, or other entity that uses a certificate to identify itself.
- enrollment
- The process of requesting and receiving an X.509 certificate for use in a public-key infrastructure (PKI). Also known as registration.
- extensions field
F
- Federal Bridge Certificate Authority (FBCA)
- A configuration where two CAs form a circle of trust by issuing cross-pair certificates to each other and storing the two cross-pair certificates as a single certificate pair.
- fingerprint
- FIPS PUBS 140
- Federal Information Standards Publications (FIPS PUBS) 140 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.nist.gov/itl/fipscurrent.cfm.
- firewall
- A system or combination of systems that enforces a boundary between two or more networks.
I
- impersonation
- The act of posing as the intended recipient of information sent over a network. Impersonation can take two forms: spoofing and misrepresentation.
- input
- 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.
- intermediate CA
- A CA whose certificate is located between the root CA and the issued certificate in a certificate chain.
- IP spoofing
- The forgery of client IP addresses.
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)
- 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.
- Java™ Development Kit (JDK)
- Software development kit provided by Sun Microsystems for developing applications and applets using the Java™ programming language.
- Java™ Native Interface (JNI)
- 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 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.
- Java™ Security Services (JSS)
- A Java™ interface for controlling security operations performed by Network Security Services (NSS).
K
- KEA
- key
- 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.
- key exchange
- A procedure followed by a client and server to determine the symmetric keys they will both use during a TLS session.
- Key Exchange Algorithm (KEA)
- An algorithm used for key exchange by the US Government.
L
- Lightweight Directory Access Protocol (LDAP)
- 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.
- linked CA
- 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
- 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.
- MD5
- A message digest algorithm that was developed by Ronald Rivest. See also one-way hash.
- message digest
- See one-way hash.
- misrepresentation
- 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 is really a site that takes credit-card payments but never sends any goods. Misrepresentation is one form of impersonation. See also spoofing.
N
- Network Security Services (NSS)
- A set of libraries designed to support cross-platform development of security-enabled communications applications. Applications built using the NSS libraries support the Transport Layer Security (TLS) 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.
- non-TMS
- Non-token management system. Refers to a configuration of subsystems (the CA and, optionally, KRA and OCSP) which do not handle smart cards directly.
See Also token management system (TMS).
- nonrepudiation
- The inability by the sender of a message to deny having sent the message. A digital signature provides one form of nonrepudiation.
O
- object signing
- A method of file signing 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.
- object-signing certificate
- A certificate that is associated private key is used to sign objects; related to object signing.
- OCSP
- Online Certificate Status Protocol.
- one-way hash
- 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.
- operation
- The specific operation, such as read or write, that is being allowed or denied in an access control instruction.
- output
- 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
- Confident identification by means of a name and password. See also authentication, certificate-based authentication.
- PKCS #10
- The public-key cryptography standard that governs certificate requests.
- PKCS #11
- The public-key cryptography standard that governs cryptographic tokens such as smart cards.
- PKCS #11 module
- 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.
- PKCS #12
- The public-key cryptography standard that governs key portability.
- PKCS #7
- The public-key cryptography standard that governs signing and encryption.
- private key
- 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.
- proof-of-archival (POA)
- Data signed with the private Key Recovery Authority transport key that contains information about an archived end-entity key, including key serial number, name of the Key Recovery Authority, subject name of the corresponding certificate, and date of archival. The signed proof-of-archival data are the response returned by the Key Recovery Authority to the Certificate Manager after a successful key archival operation. See also Key Recovery Authority transport certificate.
- public key
- 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.
- public-key cryptography
- 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.
- public-key infrastructure (PKI)
- The standards and services that facilitate the use of public-key cryptography and X.509 v3 certificates in a networked environment.
R
- RC2, RC4
- Cryptographic algorithms developed for RSA Data Security by Rivest. See also cryptographic algorithm.
- Red Hat Certificate System
- A highly configurable set of software components and tools for creating, deploying, and managing certificates. Certificate System is comprised of five major subsystems that can be installed in different Certificate System instances in different physical locations: Certificate Manager, Online Certificate Status Manager, Key Recovery Authority, Token Key Service, and Token Processing System.
- registration
- See enrollment.
- root CA
- The certificate authority (CA) with a self-signed certificate at the top of a certificate chain. See also CA certificate, subordinate CA.
- RSA algorithm
- 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.
- RSA key exchange
- A key-exchange algorithm for TLS based on the RSA algorithm.
S
- sandbox
- A Java™ term for the carefully defined limits within which Java™ code must operate.
- secure channel
- A security association between the TPS and the smart card which allows encrypted communciation based on a shared master key generated by the TKS and the smart card APDUs.
- security domain
- A centralized repository or inventory of PKI subsystems. Its primary purpose is to facilitate the installation and configuration of new PKI services by automatically establishing trusted relationships between subsystems.
- self tests
- A feature that tests a Certificate System instance both when the instance starts up and on-demand.
- server authentication
- The process of identifying a server to a client. See also client authentication.
- server TLS certificate
- A certificate used to identify a server to a client using the Transport Layer Security (TLS) protocol.
- servlet
- Java™ code that handles a particular kind of interaction with end entities on behalf of a Certificate System subsystem. For example, certificate enrollment, revocation, and key recovery requests are each handled by separate servlets.
- SHA-1
- Secure Hash Algorithm, a hash function used by the US government.
- signature algorithm
- A cryptographic algorithm used to create digital signatures. Certificate System supports the MD5 and SHA-1 signing algorithms. See also cryptographic algorithm, digital signature.
- signed audit log
- See audit log.
- signing certificate
- A certificate that is public key corresponds to a private key used to create digital signatures. For example, a Certificate Manager must have a signing certificate that is public key corresponds to the private key it uses to sign the certificates it issues.
- signing key
- 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.
- single sign-on
- 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 private-key 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.
- slot
- The portion of a PKCS #11 module, implemented in either hardware or software, that contains a token.
- smart card
- 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.
- spoofing
- Pretending to be someone else. For example, a person can pretend to have the email address
jdoe@example.com
, or a computer can identify itself as a site calledwww.redhat.com
when it is not. Spoofing is one form of impersonation. See also misrepresentation. - subject
- The entity identified by a certificate. In particular, the subject field of a certificate contains a subject name that uniquely describes the certified entity.
- subject name
- subordinate CA
- A certificate authority that is certificate is signed by another subordinate CA or by the root CA. See CA certificate, root CA.
- symmetric encryption
- An encryption method that uses the same cryptographic key to encrypt and decrypt a given message.
- TLS
T
- tamper detection
- A mechanism ensuring that data received in electronic form entirely corresponds with the original version of the same data.
- token
- 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.
- token key service (TKS)
- A subsystem in the token management system which derives specific, separate keys for every smart card based on the smart card APDUs and other shared information, like the token CUID.
- token management system (TMS)
- The interrelated subsystems — CA, TKS, TPS, and, optionally, the KRA — which are used to manage certificates on smart cards (tokens).
- token processing system (TPS)
- A subsystem which interacts directly the Enterprise Security Client and smart cards to manage the keys and certificates on those smart cards.
- Transport Layer Security (TLS)
- A protocol that allows mutual authentication between a client and server and the establishment of an authenticated and encrypted connection. TLS runs above TCP/IP and below HTTP, LDAP, IMAP, NNTP, and other high-level network protocols.
- tree hierarchy
- 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.
Index
A
- active logs
- default file location, Logs
- message categories, Services That Are Logged
- adding new directory attributes, Adding New or Custom Attributes
- agents
- authorizing key recovery, Recovering Keys
- port used for operations, Planning Ports
- archiving
- rotated log files, Log File Rotation
- Audit log
- defined, Transactions Log
B
- buffered logging, Buffered and Unbuffered Logging
C
- CA chaining, Linked CA
- CA decisions for deployment
- CA renewal, Renewing or Reissuing CA Signing Certificates
- distinguished name, Planning the CA Distinguished Name
- root versus subordinate, Defining the Certificate Authority Hierarchy
- signing certificate, Setting the CA Signing Certificate Validity Period
- signing key, Choosing the Signing Key Type and Length
- CA hierarchy, Subordination to a Certificate System CA
- root CA, Subordination to a Certificate System CA
- subordinate CA, Subordination to a Certificate System CA
- CA signing certificate, Setting the CA Signing Certificate Validity Period
- Certificate Manager
- as root CA, Subordination to a Certificate System CA
- as subordinate CA, Subordination to a Certificate System CA
- CA hierarchy, Subordination to a Certificate System CA
- chaining to third-party CAs, Linked CA
- KRA and, Planning for Lost Keys: Key Archival and Recovery
- certificate profiles
- Windows smart card login, Using the Windows Smart Card Logon Profile
- changing
- DER-encoding order of DirectoryString, Changing the DER-Encoding Order
- configuration file, CS.cfg Files
- CRLs
- Certificate Manager support for, CRLs
- publishing to online validation authority, OCSP Services
- CS.cfg, CS.cfg Files
- comments and TPS, Overview of the CS.cfg Configuration File
D
- deployment planning
- CA decisions
- distinguished name, Planning the CA Distinguished Name
- root versus subordinate, Defining the Certificate Authority Hierarchy
- signing certificate, Setting the CA Signing Certificate Validity Period
- signing key, Choosing the Signing Key Type and Length
- token management, Smart Card Token Management with Certificate System
- DER-encoding order of DirectoryString, Changing the DER-Encoding Order
- directory attributes
- adding new, Adding New or Custom Attributes
- supported in CS, Changing DN Attributes in CA-Issued Certificates
- distinguished name (DN)
- extending attribute support, Changing DN Attributes in CA-Issued Certificates
- for CA, Planning the CA Distinguished Name
E
- Error log
- defined, Tomcat Error and Access Logs
- extending directory-attribute support in CS, Changing DN Attributes in CA-Issued Certificates
- extensions
- structure of, Structure of Certificate Extensions
F
- flush interval for logs, Buffered and Unbuffered Logging
H
- how to search for keys, Archiving Keys
I
- installation, Installing and Configuring Certificate System
- planning, A Checklist for Planning the PKI
K
- key archival, Archiving Keys
- how it works, Archiving Keys
- how keys are stored, Archiving Keys
- how to set up, Manually Setting up Key Archival
- PKI setup required, Archiving, Recovering, and Rotating Keys
- reasons to archive, Archiving Keys
- where keys are stored, Archiving Keys
- key length, Choosing the Signing Key Type and Length
- key recovery, Recovering Keys
- how to set up, Setting up Agent-Approved Key Recovery Schemes
- Key Recovery Authority
- setting up
- key archival, Manually Setting up Key Archival
- key recovery, Setting up Agent-Approved Key Recovery Schemes
- KRA
- Certificate Manager and, Planning for Lost Keys: Key Archival and Recovery
L
- linked CA, Linked CA
- location of
- active log files, Logs
- logging
- buffered vs. unbuffered, Buffered and Unbuffered Logging
- log files
- archiving rotated files, Log File Rotation
- default location, Logs
- timing of rotation, Log File Rotation
- log levels, Log Levels (Message Categories)
- default selection, Log Levels (Message Categories)
- how they relate to message categories, Log Levels (Message Categories)
- significance of choosing the right level, Log Levels (Message Categories)
- services that are logged, Services That Are Logged
- types of logs, Logs
- Audit, Transactions Log
- Error, Tomcat Error and Access Logs
O
- OCSP responder, OCSP Services
- OCSP server, OCSP Services
P
- password.conf
- configuring contents, Configuring the password.conf File
- configuring location, Configuring the password.conf File
- contents, Configuring the password.conf File
- passwords
- configuring the password.conf file, Configuring the password.conf File
- for subsystem instances, Managing System Passwords
- used by subsystem instances, Configuring the password.conf File
- planning installation, A Checklist for Planning the PKI
- ports
- for agent operations, Planning Ports
- how to choose numbers, Planning Ports
- publishing
- of CRLs
- to online validation authority, OCSP Services
- queue, Enabling and Configuring a Publishing Queue
- (see also publishing queue)
- publishing queue, Enabling and Configuring a Publishing Queue
R
- recovering users' private keys, Recovering Keys
- restarting
- subsystem instance
- without the java security manager, Starting a Subsystem Instance without the Java Security Manager
- root CA, Subordination to a Certificate System CA
- root versus subordinate CA, Defining the Certificate Authority Hierarchy
- rotating log files
- archiving files, Log File Rotation
- how to set the time, Log File Rotation
- RSA, Choosing the Signing Key Type and Length
S
- setting up
- key archival, Manually Setting up Key Archival
- key recovery, Setting up Agent-Approved Key Recovery Schemes
- signing certificate
- signing key, for CA, Choosing the Signing Key Type and Length
- smart cards
- Windows login, Using the Windows Smart Card Logon Profile
- starting
- subsystem instance
- without the java security manager, Starting a Subsystem Instance without the Java Security Manager
- subordinate CA, Subordination to a Certificate System CA
- subsystems
- configuring password file, Configuring the password.conf File
T
- timing log rotation, Log File Rotation
- Token Key Service, Smart Card Token Management with Certificate System
- Token Processing System and, Smart Card Token Management with Certificate System
- Token Processing System, Smart Card Token Management with Certificate System
- Token Key Service and, Smart Card Token Management with Certificate System
- tokens
- viewing which tokens are installed, Viewing Tokens
- Windows login, Using the Windows Smart Card Logon Profile
- topology decisions, for deployment, Smart Card Token Management with Certificate System
- TPS
- comments in the CS.cfg file, Overview of the CS.cfg Configuration File
- Windows smart card login, Using the Windows Smart Card Logon Profile
- transport certificate
- when used, Archiving Keys
U
- unbuffered logging, Buffered and Unbuffered Logging
W
- Windows smart card login, Using the Windows Smart Card Logon Profile
Appendix A. Revision History
Revision History | |||
---|---|---|---|
Revision 9.4-1 | Thu Feb 11, 2021 | ||
| |||
Revision 9.4-0 | Wed Apr 02, 2019 | ||
|