Chapter 2. Introduction to Red Hat Certificate System Every common PKI operation, such as issuing, renewing, and revoking certificates; archiving and recovering keys; publishing CRLs and verifying certificate status, is carried out by interoperating subsystems within Red Hat Certificate System. The functions of each individual subsystem and the way that they work together to establish a robust and local PKI is described in this chapter. 2.1. A review of Certificate System subsystems Red Hat Certificate System provides five different subsystems, each focusing on different aspects of a PKI deployment: 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 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. Even with all possible subsystems installed, the core of the Certificate System is still the CA (or CAs), since they ultimately process all certificate-related requests. The other subsystems connect to the CA or CAs likes spokes in a wheel. These subsystems work together, in tandem, to create a public key infrastructure (PKI). Depending on what subsystems are installed, a PKI can function in one (or both) of two ways: 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. Note Red Hat Certificate System includes Technology Preview code (e.g., EST). This early access to upcoming product functionality is not evaluated and not to be used in the evaluated configuration. 2.2. Overview of Certificate System subsystems 2.2.1. Separate versus shared instances Red Hat Certificate System supports deployment of separate PKI instances for all subsystems: 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). Alternatively, Certificate System supports deployment of a shared PKI instance: 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 Prior to installation of a Certificate System instance, a local or remote Red Hat Directory Server LDAP instance must be available. For instructions on installing Red Hat Directory Server, see the Red Hat Directory Server Installation Guide . 2.2.2.2. PKI packages Red Hat Certificate System is composed of packages listed below: The following base packages form the core of Certificate System and are available in base Red Hat Enterprise Linux repositories: pki-core 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 attach a Red Hat Certificate System subscription pool and enable the RHCS repository. For more information, see Section 6.2, "Enabling the repositories" . pki-core pki-console pki-ocsp pki-tks pki-tps redhat-pki redhat-pki : contains all the packages of the pki-core module. If you wish to pick redhat-pki packages individually, it is advised to disable the pki-core module. redhat-pki-console-theme redhat-pki-server-theme Use a Red Hat Enterprise Linux 8 system (optionally, use one that has been configured with a supported Hardware Security Module listed in Chapter 4, Supported platforms ), and make sure that all packages are up to date before installing Red Hat Certificate System. To install all Certificate System packages (with the exception of pki-javadoc ), use dnf to install the redhat-pki metapackage: Alternatively, you can install one or more of the top level PKI subsystem packages as required; see the list above for exact package names. If you use this approach, make sure to also install the redhat-pki-server-theme package, and optionally redhat-pki-console-theme and pki-console to use the PKI Console. Finally, developers and administrators may also want to install the JSS and PKI javadocs (the jss-javadoc and pki-javadoc ). Note The jss-javadoc package requires you to enable the Server-Optional repository in Subscription Manager . 2.2.2.3. Instance installation and configuration The 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 may be run either interactively, as a batch process, or a combination of both (batch process with prompts for passwords). The utility does not provide a way to install or configure the browser-based graphical interface. For usage information, use the pkispawn --help command. The pkispawn command: Reads in its default name=value pairs from a plain text configuration file ( /etc/pki/default.cfg ). Interactively or 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 See the pkispawn man page for additional information. The default configuration file, /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. If you use the -s option with pkispawn and specify a subsystem name, then only the section for that subsystem will be read. The sections have a hierarchy: a 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 overriden by interactive input, or by pairs in a specified PKI instance configuration file. Note Whenever non-interactive 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. See the pki_default.cfg man page for more information. The Configuration Servlet consists of Java bytecode stored in /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 . An example of an interactive installation only involves running the pkispawn command on a command line as root : Important Interactive installation currently only exists for very basic deployments. For example, deployments intent upon using advanced features such as cloning, Elliptic Curve Cryptography (ECC), external CA, Hardware Security Module (HSM), subordinate CA, and others, must provide the necessary override parameters in a separate configuration file. A non-interactive installation requires a PKI instance configuration override file, and the process may look similar to the following example: Create the pki directory: Use a text editor such as vim to create a configuration file named /root/pki/ca.cfg with the following contents: See the pkispawn man page for various configuration examples. 2.2.2.4. Instance removal To remove an existing PKI instance, use the pkidestroy command. It can be run interactively or as a batch process. Use pkidestroy -h to display detailed usage inforamtion on the command line. The 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. An interactive removal procedure using pkidestroy may look similar to the following: A non-interactive removal procedure may look similar to the following example: 2.2.3. Execution management (systemctl) 2.2.3.1. Starting, stopping, restarting, and obtaining status Red Hat Certificate System subsystem instances can be stopped and started using the systemctl execution management system tool on Red Hat Enterprise Linux 8: <unit-file> has one of the following values: For more details on the watchdog service, refer to Section 2.3.10, "Passwords and watchdog (nuxwdog)" and Section 9.3.2, "Using the Certificate System watchdog service" . Note In RHCS 10, these systemctl actions support the pki-server alias: pki-server <command> subsystem_instance_name is the alias for systemctl <command> pki-tomcatd@<instance>.service . 2.2.3.2. Starting the instance automatically The systemctl utility in Red Hat Enterprise Linux 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 Configuring basic system settings guide for Red Hat Enterprise Linux 8. Certificate System instances can be managed by 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 : To re-enable the instance: Note The 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 The primary process management tool for Red Hat Certificate System is pki-server . Use the pki-server --help command and see the pki-server man page for usage information. The pki-server command-line interface (CLI) manages local server instances (for example server configuration or system certificates). Invoke the CLI as follows: The CLI uses the configuration files and NSS database of the server instance, therefore the CLI does not require any prior initialization. Since the CLI accesses the files directly, it can only be executed by the root user, and it does not require client certificate. Also, the CLI can run regardless of the status of the server; it does not require a running server. The CLI supports a number of commands organized in a hierarchical structure. To list the top-level commands, execute the CLI without any additional commands or parameters: Some commands have subcommands. To list them, execute the CLI with the command name and no additional options. For example: To view command usage information, use the --help option: 2.2.4.2. Enabling and disabling an installed subsystem using pki-server To enable or disable an installed subsystem, use the pki-server utility. Replace subsystem_id with a valid subsystem identifier: ca , kra , tks , ocsp , or tps . Note One instance can have only one of each type of subsystem. For example, to disable the OCSP subsystem on an instance named pki-tomcat : To list the installed subsystems for an instance: To show the status of a particular subsystem: 2.2.4.3. The pkidaemon command line tool Another process management tool for Red Hat Certificate System is the pkidaemon tool: 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 using systemctl . See the pkidaemon man page for additional information. 2.2.4.4. Finding the subsystem web services URLs The CA, KRA, OCSP, TKS, and TPS subsystems have web services pages for agents, as well as regular users and administrators, when appropriate. These web services can be accessed by opening the URL to the subsystem host over the subsystem's secure end user's port. For example, for the CA: Note To get a complete list of all of the interfaces, URLs, and ports for an instance, check the status of the service. For example: The main web services page for each subsystem has a list of available services pages; these are summarized in the below table. To access any service specifically, access the appropriate port and append the appropriate directory to the URL. For example, to access the CA's end entities (regular users) web services: If DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the services pages. For example: Note Anyone can access the end user pages for a subsystem. However, accessing agent or admin web services pages requires that an agent or administrator certificate be issued and installed in the web browser. Otherwise, authentication to the web services fails. Table 2.1. Default web services pages Port Used for SSL/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 kra/ee/kra 8443 Yes No End Entities 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 ocsp/ee/ocsp 8443 Yes No End Entities 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 tks/ee/tks 8443 Yes No End Entities 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 [b] 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] 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 Important This console is being deprecated. The CA, KRA, OCSP, and TKS subsystems have a Java interface which can be accessed to perform administrative functions. For the KRA, OCSP, and TKS, this includes very basic tasks like configuring logging and managing users and groups. For the CA, this includes other configuration settings such as creating certificate profiles and configuring publishing. The Console is opened by connecting to the subsystem instance over its SSL/TLS port using the pkiconsole utility. This utility uses the format: The subsystem_type can be ca , kra , ocsp , or tks . For example, this opens the KRA console: If DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the console. For example: 2.3. Certificate System architecture overview Although each provides a different service, all Red Hat Certificate System subsystems (CA, KRA, OCSP, TKS, TPS) share a common architecture. The following architectural diagram shows the common architecture shared by all of these subsystems. 2.3.1. Java application server Java application server is a Java framework to run server applications. The Certificate System is designed to run within a Java application server. Currently the only Java application server supported is Tomcat 8. Support for other application servers may be added in the future. More information can be found at http://tomcat.apache.org/ . Each Certificate System instance is a Tomcat server instance. The Tomcat configuration is stored in server.xml . The following link provides more information about Tomcat configuration: https://tomcat.apache.org/tomcat-8.0-doc/config/ . Each Certificate System subsystem (such as CA or KRA) is deployed as a web application in Tomcat. The web application configuration is stored in a web.xml file, which is defined in Java Servlet 3.1 specification. See https://www.jcp.org/en/jsr/detail?id=340 for details. The Certificate System configuration itself is stored in CS.cfg . See Section 2.3.16, "Instance layout" for the actual locations of these files. 2.3.2. Java security manager Java services have the option of having a Security Manager which defines unsafe and safe operations for applications to perform. When the subsystems are installed, they have the Security Manager enabled automatically, meaning each Tomcat instance starts with the Security Manager running. The Security Manager is disabled if the instance is created by running pkispawn and using an override configuration file which specifies the pki_security_manager=false option under its own Tomcat section. The Security Manager can be disabled from an installed instance using the following procedure: First stop the instance: OR if using the Nuxwdog watchdog: Open the /etc/sysconfig/instance_name file, and set SECURITY_MANAGER="false" After saving, restart the instance: OR if using the Nuxwdog watchdog: When you start or restart an instance, a Java security policy is constructed or reconstructed by pkidaemon from the following files: Then, it is saved into /var/lib/pki/instance_name/conf/catalina.policy . 2.3.3. Interfaces This section describes the various interfaces of Red Hat Certificate System. 2.3.3.1. Servlet interface Each subsystem contains interfaces allowing interaction with various portions of the subsystem. All subsystems share a common administrative interface and have an agent interface that allows for agents to perform the tasks assigned to them. A CA Subsystem has an end-entity interface that allows end-entities to enroll in the PKI. An OCSP Responder subsystem has an end-entity interface allowing end-entities and applications to check for current certificate revocation status. Finally, a TPS has an operator interface. While the application server provides the connection entry points, Certificate System completes the interfaces by providing the servlets specific to each interface. The servlets for each subsystem are defined in the corresponding web.xml file. 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 The agent interface provides Java servlets to process HTML form submissions coming from the agent entry point. Based on the information given in each form submission, the agent servlets allow agents to perform agent tasks, such as editing and approving requests for certificate approval, certificate renewal, and certificate revocation, approving certificate profiles. The agent interfaces for a KRA subsystem, or a TKS subsystem, or an OCSP Responder are specific to the subsystems. In the non-TMS setup, the agent interface is also used for inter-CIMC boundary communication for the CA-to-KRA trusted connection. This connection is protected by SSL client-authentication and differentiated by separate trusted roles called Trusted Managers . Like the agent role, the Trusted Managers (pseudo-users created for inter-CIMC boundary connection only) are required to be SSL client-authenticated. However, unlike the agent role, they are not offered any agent capability. In the TMS setup, inter-CIMC boundary communication goes from TPS-to-CA, TPS-to-KRA, and TPS-to-TKS. 2.3.3.3. End-entity interface For the CA subsystem, the end-entity interface provides Java servlets to process HTML form submissions coming from the end-entity entry point. Based on the information received from the form submissions, the end-entity servlets allow end-entities to enroll, renew certificates, revoke their own certificates, and pick up issued certificates. The OCSP Responder subsystem's End-Entity interface provides Java servlets to accept and process OCSP requests. The KRA, TKS, and TPS subsystems do not offer any End-Entity services. 2.3.3.4. Operator interface The operator interface is only found in the TPS subsystem. 2.3.4. REST interface Representational state transfer (REST) is a way to use HTTP to define and organize web services which will simplify interoperability with other applications. Red Hat Certificate System provides a REST interface to access various services on the server. The REST services in Red Hat Certificate System are implemented using the RESTEasy framework. RESTEasy is actually running as a servlet in the web application, so the RESTEasy configuration can also be found in the web.xml of the corresponding subsystem. More information about RESTEasy can be found at http://resteasy.jboss.org/ . Each REST service is defined as a separate URL. For example: 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/ Some services can be accessed using plain HTTP connection, but some others may require HTTPS connection for security. The REST operation is specified as HTTP method (for example, GET, PUT, POST, DELETE). For example, to get the CA users the client will send a GET /ca/rest/users request. The REST request and response messages can be sent in XML or JSON format. For example: The REST interface can be accessed using tools such as CLI, Web UI, or generic REST client. Certificate System also provides Java, Python, and JavaScript libraries to access the services programmatically. The REST interface supports two types of authentication methods: user name and password client certificate The authentication method required by each service is defined in /usr/share/pki/ca/conf/auth-method.properties . The REST interface may require certain permissions to access the service. The permissions are defined in the ACL resources in LDAP. The REST interface are mapped to the ACL resources in the /usr/share/pki/<subsystem>/conf/acl.properties . For more information about the REST interface, see http://www.dogtagpki.org/wiki/REST . 2.3.5. JSS Java Security Services (JSS) provides a Java interface for cryptographic operations performed by NSS. JSS and higher levels of the Certificate System architecture are built with Java Native Interface (JNI), which provides access to native system libraries from within the Java Virtual Machine (JVM). This design allows us to use FIPS approved cryptographic providers such as NSS which are distributed as part of the system. JSS supports most of the security standards and encryption technologies supported by NSS. JSS also provides a pure Java interface for ASN.1 types and BER-DER encoding. 2.3.6. Tomcatjss Java-based subsystems in Red Hat Certificate System use a single JAR file called 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. Tomcatjss implements the interfaces needed to use TLS and to create TLS sockets. The socket factory, which tomcatjss implements, makes use of the various properties listed below to create a TLS server listening socket and return it to tomcat. Tomcatjss itself, makes use of our java JSS system to ultimately communicate with the native NSS cryptographic services on the machine. Tomcatjss is loaded when the Tomcat server and the Certificate System classes are loaded. The load process is described below: 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. Note that when the sockets are created at startup, Tomcatjss is the first entity in Certificate System that actually deals with the underlying JSS security services. Once the first listening socket is processed, an instance of JSS is created for use going forward. For further details about the server.xml file, see Section 9.4, "Configuration files for the tomcat engine and web services" . 2.3.7. PKCS #11 Public-Key Cryptography Standard (PKCS) #11 specifies an API used to communicate with devices that hold cryptographic information and perform cryptographic operations. Because it supports PKCS #11, Certificate System is compatible with a wide range of hardware and software devices. At least one PKCS #11 module must be available to any Certificate System subsystem instance. A PKCS #11 module (also called a cryptographic module or cryptographic service provider) manages cryptographic services such as encryption and decryption. PKCS #11 modules are analogous to drivers for cryptographic devices that can be implemented in either hardware or software. Certificate System contains a built-in PKCS #11 module and can support third-party modules. A PKCS #11 module always has one or more slots which can be implemented as physical hardware slots in a physical reader such as smart cards or as conceptual slots in software. Each slot for a PKCS #11 module can in turn contain a token, which is a hardware or software device that actually provides cryptographic services and optionally stores certificates and keys. The Certificate System defines two types of tokens, the internal and the external . The internal token is used for storing certificate trust anchors. The external token is used for storing key pairs and certificates that belong to the Certificate System subsystems. 2.3.7.1. NSS soft token (internal token) Note Certificate System uses an NSS soft token for storing certificate trust anchors. NSS Soft Token is also called an internal token or a software token. The software token consists of two files, which are usually called the certificate database (cert9.db) and key database (key4.db). The files are created during the Certificate System subsystem configuration. These security databases are located in the /var/lib/pki/instance_name/alias directory. Two cryptographic modules provided by the NSS soft token are included in the Certificate System: The default internal PKCS #11 module, which comes with two tokens: The internal crypto services token, which performs all cryptographic operations such as encryption, decryption, and hashing. The internal key storage token ("Certificate DB token"), 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. Specific instructions on how to import certificates onto the NSS soft token are in Chapter 10, Managing certificate/key crypto token . For more information on the Network Security Services (NSS), see Mozilla Developer web pages of the same name. 2.3.7.2. Hardware security module (HSM, external token) Note Certificate System uses an HSM for storing key pairs and certificates that belong to the Certificate System subsystems. Any PKCS #11 module can be used with the Certificate System. To use an external hardware token with a subsystem, load its PKCS #11 module before the subsystem is configured, and the new token is available to the subsystem. Available PKCS #11 modules are tracked in the pkcs11.txt 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. PKCS #11 hardware devices also provide key backup and recovery features for the information stored on hardware tokens. Refer to the PKCS #11 vendor documentation for information on retrieving keys from the tokens. Specific instructions on how to import certificates and to manage the HSM are in Chapter 10, Managing certificate/key crypto token . Supported Hardware Security Modules are located in Section 4.4, "Supported Hardware Security Modules" . 2.3.8. Certificate System serial number management 2.3.8.1. Serial number ranges Certificate request and serial numbers are represented by Java's big integers By default, due to their efficiency, certificate request numbers, certificate serial numbers, and replica IDs are assigned sequentially for CA subsystems. Serial number ranges are specifiable for requests, certificates, and replica IDs: 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. For new clones: 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. All ranges are configurable at CA instance installation time by adding a [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: 2.3.8.2. Random serial number management In addition to sequential serial number management, Red Hat Certificate System provides optional random serial number management. Using random serial numbers is selectable at CA instance installation time by adding a [CA] section to the PKI instance override file and adding the following name=value pair under that section: If selected, certificate request numbers and certificate serial numbers will be selected randomly within the specified ranges. 2.3.9. Security domain A security domain is a registry of PKI services. Services such as CAs register information about themselves in these domains so users of PKI services can find other services by inspecting the registry. The security domain service in RHCS manages both the registration of PKI services for Certificate System subsystems and a set of shared trust policies. See Section 5.3, "Planning security domains" for further details. 2.3.10. Passwords and watchdog (nuxwdog) In the default setup, an RHCS subsystem instance needs to act as a client and authenticate to some other services, such as an LDAP internal database (unless TLS mutual authentication is set up, where a certificate will be used for authentication instead), the NSS token database, or sometimes an HSM with a password. The administrator is prompted to set up this password at the time of installation configuration. This password is then written to the file <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 . The configuration file, CS.cfg , is protected by Red Hat Enterprise Linux, and only accessible by the PKI administrators. No passwords are stored in CS.cfg . During installation, the installer will select and log into either the internal software token or a hardware cryptographic token. The login passphrase to these tokens is also written to password.conf . Configuration at a later time can also place passwords into password.conf . LDAP publishing is one example where the newly configured Directory Manager password for the publishing directory is entered into password.conf . Nuxwdog (watchdog) is a lightweight auxiliary daemon process that is used to start, stop, monitor the status of, and reconfigure server programs. It is most useful when users need to be prompted for passwords to start a server, because it caches these passwords securely in the kernel keyring, so that restarts can be done automatically in the case of a server crash. Note Nuxwdog is the only allowed watchdog service. Once installation is complete, it is possible to remove the 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. When using the watchdog service, starting and stopping an RHCS instance are done differently. For details, see Section 9.3.2, "Using the Certificate System watchdog service" . For further information, see Section 9.3, "Managing system passwords" . 2.3.11. Internal LDAP database Red Hat Certificate System employs Red Hat Directory Server (RHDS) as its internal database for storing information such as certificates, requests, users, roles, ACLs, as well as other miscellaneous internal information. Certificate System communicates with the internal LDAP database either with a password, or securely by means of SSL authentication. If certificate-based authentication is required between a Certificate System instance and Directory Server, it is important to follow instruction to set up trust between these two entities. Proper pkispawn options will also be needed for installing such Certificate System instance. For details, see Section 7.1.2, "Installing and configuring the DS instances" . 2.3.12. Security-enhanced Linux (SELinux) SELinux is a collection of mandatory access control rules which are enforced across a system to restrict unauthorized access and tampering. SELinux is described in more detail in Using SELinux guide for Red Hat Enterprise Linux 8 . Basically, SELinux identifies objects on a system, which can be files, directories, users, processes, sockets, or any other resource on a Linux host. These objects correspond to the Linux API objects. Each object is then mapped to a security context , which defines the type of object and how it is allowed to function on the Linux server. Objects can be grouped into domains, and then each domain is assigned the proper rules. Each security context has rules which set restrictions on what operations it can perform, what resources it can access, and what permissions it has. SELinux policies for the Certificate System are incorporated into the standard system SELinux policies. These SELinux policies apply to every subsystem and service used by Certificate System. By running Certificate System with SELinux in enforcing mode, the security of the information created and maintained by Certificate System is enhanced. Figure 2.1. CA SELinux port policy The Certificate System SELinux policies define the SELinux configuration for every subsystem instance: 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. For Certificate System, each subsystem is treated as an SELinux object, and each subsystem has unique rules assigned to it. The defined SELinux policies allow Certificate System objects run with SELinux set in enforcing mode. Every time 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 . The central definition in an SELinux policy is the 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. When each Certificate System process is started, it initially runs in an unconfined 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. The SELinux mode can be changed from enforcing to permissive, or even off, though this is not recommended. 2.3.13. Self-tests Red Hat Certificate System provides a Self-Test framework which allows the PKI system integrity to be checked during startup or on demand or both. In the event of a non-critical self test failure, the message will be stored in the log file, while in the event of a critical self test failure, the Certificate System subsystem will record the reasons in the logs and shut down gracefully. The administrator is expected to watch the self-test log during the startup of the subsystem if they wish to see the self-test report during startup. They can also view the log after startup. When a subsystem is shut down due to a self-test failure, it will also be automatically disabled. This is done to ensure that the subsystem does not partially run and produce misleading responses. Once the issue is resolved, the subsystem can be re-enabled by running the following command on the server: For details on how to configure self-tests, see Section 13.3.2, "Configuring self-tests" . 2.3.14. Logs The Certificate System subsystems create log files that record events related to activities, such as administration, communications using any of the protocols the server supports, and various other processes employed by the subsystems. While a subsystem instance is running, it keeps a log of information and error messages on all the components it manages. Additionally, the Apache and Tomcat web servers generate error and access logs. Each subsystem instance maintains its own log files for installation, audit, and other logged functions. Log plugin modules are listeners which are implemented as #JavaTM classes and are registered in the configuration framework. All the log files and rotated log files, except for audit logs, are located in whatever directory was specified in 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. For details about log configuration during the installation and additional information, see Chapter 13, Configuring logs . For details about log administration after the installation, see Chapter 12 Configuring Subsystem Logs in the Administration Guide (Common Criteria Edition) . 2.3.14.1. Audit log The audit log contains records for selectable events that have been set up as recordable events. You can configure audit logs also to be signed for integrity-checking purposes. Note Audit records should be kept according to the audit retention rules specified in - Section 13.4, "Audit retention" . 2.3.15. Signed Audit Logs The Certificate System maintains audit logs for all events, such as requesting, issuing and revoking certificates and publishing CRLs. These logs are then signed. This allows authorized access or activity to be detected. An outside auditor can then audit the system if required. The assigned auditor user account is the only account which can view the signed audit logs. This user's certificate is used to sign and encrypt the logs. Audit logging is configured to specify the events that are logged. Signed audit logs are written to /var/log/pki/instance_name/subsystem_name/signedAudit. However, you can change the default location for logs by modifying the configuration. For more information, see the "Displaying and verifying signed audit logs" in the Planning, Installation and Deployment Guide (Common Criteria Edition) . 2.3.15.1. Debug logs Debug logs, which are enabled by default, are maintained for all subsystems, with varying degrees and types of information. Debug logs for each subsystem record much more detailed information than system, transaction, and access logs. Debug logs contain very specific information for every operation performed by the subsystem, including plugins and servlets which are run, connection information, and server request and response messages. Services which are recorded to the debug log include authorization requests, processing certificate requests, certificate status checks, and archiving and recovering keys, and access to web services. The debug logs record detailed information about the processes for the subsystem. Each log entry has the following format: The message can be a return message from the subsystem or contain values submitted to the subsystem. For example, the TKS records this message for connecting to an LDAP server: The processor is main , and the message is the message from the server about TKS engine status, and there is no servlet. The INFO is LogLevel , its value could be INFO , WARNING , SEVERE , depending on the log level. The CA, on the other hand, records information about certificate operations as well as subsystem connections: In this case, the processor is the HTTP protocol over the CA's agent port, while it specifies the servlet for handling profiles and contains a message giving a profile parameter (the subsystem owner of a request) and its value (that the KRA initiated the request). Example 2.1. CA Certificate request log messages Likewise, the OCSP shows OCSP request information: 2.3.15.2. Installation logs All subsystems keep an install log. Every time a subsystem is created either through the initial installation or creating additional instances with 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 . Each line in the install log follows a step in the installation process. Example 2.2. CA install log 2.3.15.3. Tomcat error and access logs The CA, KRA, OCSP, TKS, and TPS subsystems use a Tomcat web server instance for their agent and end-entities' interfaces. Error and access logs are created by the Tomcat web server, which are installed with the Certificate System and provide HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface. Logs created by Tomcat: admin. timestamp catalina. timestamp catalina.out host-manager. timestamp localhost. timestamp localhost_access_log. timestamp manager. timestamp These logs are not available or configurable within the Certificate System; they are only configurable within Apache or Tomcat. See the Apache documentation for information about configuring these logs. 2.3.15.4. Self-tests log The self-tests log records information obtained during the self-tests run when the server starts or when the self-tests are manually run. The tests can be viewed by opening this log. This log is not configurable through the Console. This log can only be configured by changing settings in the CS.cfg file. The information about logs in this section does not pertain to this log. See Section 2.3.13, "Self-tests" for more information about self-tests. 2.3.15.5. journalctl logs When starting a Certificate System instance, there is a short period of time before the logging subsystem is set up and enabled. During this time, log contents are written to standard out, which is captured by systemd and exposed via the journalctl utility. To view these logs, run the following command: OR if using the Nuxwdog watchdog: Often it is helpful to watch these logs as the instance is starting (for example, in the event of a self-test failure on startup). To do this, run these commands in a separate console prior to starting the instance: OR if using the Nuxwdog watchdog: 2.3.16. Instance layout Each Certificate System instance depends on a number of files. Some of them are located in instance-specific folders, while some others are located in a common folder which is shared with other server instances. For example, the server configuration files are stored in /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 Certificate System servers are Tomcat instances which consist of one or more Certificate System subsystems. Certificate System subsystems are web applications that provide specific type of PKI functions. General, shared subsystem information is contained in non-relocatable, RPM-defined shared libraries, Java archive files, binaries, and templates. These are stored in a fixed location. The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat ; the true value is whatever is specified at the time the subsystem is created with pkispawn . The directories contain customized configuration files and templates, profiles, certificate databases, and other files for the subsystem. 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 SSL 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 The /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 The directories are instance specific, tied to the instance name. In these examples, the instance name is 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 The directories are instance specific, tied to the instance name. In these examples, the instance name is 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 The directories are instance specific, tied to the instance name. In these examples, the instance name is 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 The directories are instance specific, tied to the instance name. In these examples, the instance name is 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 The directories are instance specific, tied to the instance name. In these examples, the instance name is 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 There are some directories used by or common to all Certificate System subsystem instances for general server operations, listed in Table 2.8, "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: pki/ca (CA) pki/kra (KRA) pki/ocsp (OCSP) pki/tks (TKS) pki/tps (TPS) /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 The Certificate System is comprised of subsystems which each contribute different functions of a public key infrastructure. A PKI environment can be customized to fit individual needs by implementing different features and functions for the subsystems. Note A conventional PKI environment provides the basic framework to manage certificates stored in software databases. This is a non-TMS environment, since it does not manage certificates on smart cards. A TMS environment manages the certificates on smart cards. 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.4.1. Issuing certificates As stated, the Certificate Manager is the heart of the Certificate System. It manages certificates at every stage, from requests through enrollment (issuing), renewal, and revocation. The Certificate System supports enrolling and issuing certificates and processing certificate requests from a variety of end entities, such as web browsers, servers, and virtual private network (VPN) clients. Issued certificates conform to X.509 version 3 standards. For more information, see 5.1 About Enrolling and Renewing Certificates in the Administration Guide (Common Criteria Edition) . 2.4.1.1. The enrollment process An end entity enrolls in the PKI environment by submitting an enrollment request through the end-entity interface. There can be many kinds of enrollment that use different enrollment methods or require different authentication methods. Different interfaces can also accept different types of Certificate Signing Requests (CSR). The Certificate Manager supports different ways to submit CSRs, such as using the graphical interface and command-line tools. 2.4.1.1.1. Enrollment using the user interface For each enrollment through the user interface, there is a separate enrollment page created that is specific to the type of enrollment, type of authentication, and the certificate profiles associated with the type of certificate. The forms associated with enrollment can be customized for both appearance and content. Alternatively, the enrollment process can be customized by creating certificate profiles for each enrollment type. Certificate profiles dynamically-generate forms which are customized by configuring the inputs associated with the certificate profile. Different interfaces can also accept different types of Certificate Signing Requests (CSR). When an end entity enrolls in a PKI by requesting a certificate, the following events can occur, depending on the configuration of the PKI and the subsystems installed: The end entity provides the information in one of the enrollment forms and submits a request. The information gathered from the end entity is customizable in the form depending on the information collected to store in the certificate or to authenticate against the authentication method associated with the form. The form creates a request that is then submitted to the Certificate Manager. The enrollment form triggers the creation of the public and private keys or for dual-key pairs for the request. The end entity provides authentication credentials before submitting the request, depending on the authentication type. This can be LDAP authentication, PIN-based authentication, or certificate-based authentication. The request is submitted either to an agent-approved enrollment process or an automated process. The agent-approved process, which involves no end-entity authentication, sends the request to the request queue in the agent services interface, where an agent must processes the request. An agent can then modify parts of the request, change the status of the request, reject the request, or approve the request. Automatic notification can be set up so an email is sent to an agent any time a request appears in the queue. Also, an automated job can be set to send a list of the contents of the queue to agents on a pre configured schedule. The automated process, which involves end-entity authentication, processes the certificate request as soon as the end entity successfully authenticates. The form collects information about the end entity from an LDAP directory when the form is submitted. For certificate profile-based enrollment, the defaults for the form can be used to collect the user LDAP ID and password. The certificate profile associated with the form determine aspects of the certificate that is issued. Depending on the certificate profile, the request is evaluated to determine if the request meets the constraints set, if the required information is provided, and the contents of the new certificate. The form can also request that the user export the private encryption key. If the KRA subsystem is set up with this CA, the end entity's key is requested, and an archival request is sent to the KRA. This process generally requires no interaction from the end entity. The certificate request is either rejected because it did not meet the certificate profile or authentication requirements, or a certificate is issued. The certificate is delivered to the end entity. In automated enrollment, the certificate is delivered to the user immediately. Since the enrollment is normally through an HTML page, the certificate is returned as a response on another HTML page. In agent-approved enrollment, the certificate can be retrieved by serial number or request Id in the end-entity interface. If the notification feature is set up, the link where the certificate can be obtained is sent to the end user. An automatic notice can be sent to the end entity when the certificate is issued or rejected. The new certificate is stored in the Certificate Manager's internal database. If publishing is set up for the Certificate Manager, the certificate is published to a file or an LDAP directory. The internal OCSP service checks the status of certificates in the internal database when a certificate status request is received. The end-entity interface has a search form for certificates that have been issued and for the CA certificate chain. By default, the user interface supports CSR in the PKCS #10 and Certificate Request Message Format (CRMF). 2.4.1.1.2. Enrollment using the command line This section describes the general workflows when enrolling certificates using the command line. 2.4.1.1.2.1. Enrolling using the pki utility For details, see: The pki-cert(1) man page 2.5 Command-Line Interfaces in the Administration Guide (Common Criteria Edition) . 2.4.1.1.2.2. Enrolling with CMC To enroll a certificate with CMC, proceed as follows: Generate a PKCS #10 or CRMF certificate signing request (CSR) using a utility, such as certutil , PKCS10Client , CRMFPopClient , or pki client-cert-request . For details, see 5.2 Creating certificate signing requests in the Administration Guide (Common Criteria Edition) . Note If key archival is enabled in the Key Recovery Agent (KRA), use the CRMFPopClient utility with the KRA's transport certificate in Privacy Enhanced Mail (PEM) format set in the kra.transport file. Use the CMCRequest utility to convert the CSR into a CMC request. The CMCRequest utility uses a configuration file as input. This file specifies, for example, the input path to the CSR, the CSR's format, the output CMC request file, or nickname of the signing certificate. 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 input CMC request file, the path to the output CMC response file, the nickname of the TLS mutual authentication certificate, and the servlet complete with the enrollment profile. If the HttpClient 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 the HttpClient command without any parameters. Use the CMCResponse utility to check the issuance result of the CMC response file generated by HttpClient . If the request is successful, CMCResponse displays the certificate chain in a readable format along with status information. You can also display the PEM of each certificate in chain using the -v option. 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 by HttpClient is in CMC response format that contains PKCS #7. If the application supports only Base64-encoded certificates, use the -v option to show the PEM of each certificate in the chain. 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. 2.4.1.1.2.2.1. CMC Enrollment without POP In situations when Proof Of Possession (POP) is missing, the 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. For details, see 5.3.1 CMC Enrollment Process in the Administration Guide (Common Criteria Edition) . 2.4.1.1.2.2.2. Signed CMC requests CMC requests can either be signed by a user or a CA agent: 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 . For details, see 8.3 CMC Authentication Plugins in the Administration Guide (Common Criteria Edition) . 2.4.1.1.2.2.3. Unsigned CMC requests When the CMCUserSignedAuth authentication plugin is configured in the profile, you must use an unsigned CMC request in combination with the Shared Secret authentication mechanism. Note Unsigned CMC requests are also called self-signed CMC requests . For details, see 8.3 CMC Authentication Plugins in the Administration Guide (Common Criteria Edition) , and Section 9.6.3, "Enabling the CMC Shared Secret feature" . 2.4.1.1.2.2.4. The Shared Secret workflow Certificate System provides the Shared Secret authentication mechanism for CMC requests according to RFC 5272 . In order to protect the passphrase, an issuance protection certificate must be provided when using the CMCSharedToken command. The issuance protection certificate works similar to the KRA transport certificate. Note This section assumes that you have enabled the CMC Shared Secret feature, by following Section 9.6.3, "Enabling the CMC Shared Secret feature" . Shared Secret created by the end entity user (preferred) The following describes the workflow, if the user generates the shared secret: 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. See 8.4.1 Creating a Shared Secret token in the Administration Guide (Common Criteria Edition). 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. See 8.4.2 Setting a CMC Shared Secret in the Administration Guide (Common Criteria Edition). The end entity user uses the passphrase to set the witness.sharedSecret parameter in the configuration file passed to the CMCRequest utility. See 5.2.2.2 Using PKCS10Client to create a CSR for SharedSecret-based CMC and 5.2.3.2 Using CRMFPopClient to create a CSR for SharedSecret-based CMC in the Administration Guide (Common Criteria Edition). For further details, see the CMCSharedToken(1) man page. Shared Secret created by the CA administrator The following describes the workflow, if the CA administrator generates the shared secret for a user: The administrator uses the CMCSharedToken utility to generate a shared secret token for the user. See 8.4.1 Creating a Shared Secret token in the Administration Guide (Common Criteria Edition). 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. See 8.4.2 Setting a CMC Shared Secret in the Administration Guide (Common Criteria Edition). 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 the CMCRequest utility. See 5.2.2.2 Using PKCS10Client to create a CSR for SharedSecret-based CMC and 5.2.3.2 Using CRMFPopClient to create a CSR for SharedSecret-based CMC in the Administration Guide (Common Criteria Edition). 2.4.1.1.2.2.5. Simple CMC requests Certificate System allows simple CMC requests. However, this process does not support the same level of security requirements as full CMC requests and, therefore, must only be used in a secure environment. When using simple CMC requests, set the following in the HttpClient utility's configuration file: 2.4.1.2. Certificate profiles The Certificate System uses certificate profiles to configure the content of the certificate, the constraints for issuing the certificate, the enrollment method used, and the input and output forms for that enrollment. A single certificate profile is associated with issuing a particular type of certificate. A set of certificate profiles is included for the most common certificate types; the profile settings can be modified. Certificate profiles are configured by an administrator, and then sent to the agent services page for agent approval. Once a certificate profile is approved, it is enabled for use. In case of a UI-enrollment, a dynamically-generated HTML form for the certificate profile is used in the end-entities page for certificate enrollment, which calls on the certificate profile. In case of a command line-based enrollment, the certificate profile is called upon to perform the same processing, such as authentication, authorization, input, output, defaults, and constraints. The server verifies that the defaults and constraints set in the certificate profile are met before acting on the request and uses the certificate profile to determine the content of the issued certificate. The Certificate Manager can issue certificates with any of the following characteristics, depending on the configuration in the profiles and the submitted certificate request: 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 By default, the certificate enrollment profiles are stored in <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 Certificate System provides authentication options for certificate enrollment. These include agent-approved enrollment, in which an agent processes the request, and automated enrollment, in which an authentication method is used to authenticate the end entity and then the CA automatically issues a certificate. CMC enrollment is also supported, which automatically processes a request approved by an agent. 2.4.1.4. Cross-pair certificates It is possible to create a trusted relationship between two separate CAs by issuing and storing cross-signed certificates between these two CAs. By using cross-signed certificate pairs, certificates issued outside the organization's PKI can be trusted within the system. 2.4.2. Renewing certificates When certificates reach their expiration date, they can either be allowed to lapse, or they can be renewed. Renewal regenerates a certificate request using the existing key pairs for that certificate, and then resubmits the request to Certificate Manager. The renewed certificate is identical to the original (since it was created from the same profile using the same key material) with one exception - it has a different, later expiration date. Renewal can make managing certificates and relationships between users and servers much smoother, because the renewed certificate functions precisely as the old one. For user certificates, renewal allows encrypted data to be accessed without any loss. 2.4.3. Publishing certificates and CRLs Certificates can be published to files and an LDAP directory, and CRLs to files, an LDAP directory, and an OCSP responder. The publishing framework provides a robust set of tools to publish to all three places and to set rules to define with more detail which types of certificates or CRLs are published where. 2.4.4. Revoking certificates and checking status End entities can request that their own certificates be revoked. When an end entity makes the request, the certificate has to be presented to the CA. If the certificate and the keys are available, the request is processed and sent to the Certificate Manager, and the certificate is revoked. The Certificate Manager marks the certificate as revoked in its database and adds it to any applicable CRLs. An agent can revoke any certificate issued by the Certificate Manager by searching for the certificate in the agent services interface and then marking it revoked. Once a certificate is revoked, it is marked revoked in the database and in the publishing directory, if the Certificate is set up for publishing. If the internal OCSP service has been configured, the service determines the status of certificates by looking them up in the internal database. Automated notifications can be set to send email messages to end entities when their certificates are revoked by enabling and configuring the certificate revoked notification message. 2.4.4.1. Revoking certificates Users can revoke their certificates using: The end-entity pages. For details, see 6.1.7 Certificate Revocation Pages in the Administration Guide (Common Criteria Edition) . The CMCRequest utility on the command line. For details, see 6.2.1 Performing a CMC Revocation in the Administration Guide (Common Criteria Edition) . The pki utility on the command line. For details, see pki-cert(1) man page. 2.4.4.2. Certificate status 2.4.4.2.1. CRLs The Certificate System can create certificate revocation lists (CRLs) from a configurable framework which allows user-defined issuing points so a CRL can be created for each issuing point. Delta CRLs can also be created for any issuing point that is defined. CRLs can be issued for each type of certificate, for a specific subset of a type of certificate, or for certificates generated according to a profile or list of profiles. The extensions used and the frequency and intervals when CRLs are published can all be configured. The Certificate Manager issues X.509-standard CRLs. A CRL can be automatically updated whenever a certificate is revoked or at specified intervals. 2.4.4.2.2. OCSP services The Certificate System CA supports the Online Certificate Status Protocol (OCSP) as defined in PKIX standard RFC 6960 . The OCSP protocol enables OCSP-compliant applications to determine the state of a certificate, including the revocation status, without having to directly check a CRL published by a CA to the validation authority. The validation authority, which is also called an OCSP responder , checks for the application. 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 Every response that the client receives, including a rejection notification, is digitally signed by the responder; the client is expected to verify the signature to ensure that the response came from the responder to which it submitted the request. The key the responder uses to sign the message depends on how the OCSP responder is deployed in a PKI setup. RFC 6960 recommends that the key used to sign the response belong to one of the following: 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 . The end-entities page of a Certificate Manager includes a form for manually requesting a certificate for the OCSP responder. The default enrollment form includes all the attributes that identify the certificate as an OCSP responder certificate. The required certificate extensions, such as OCSPNoCheck and Extended Key Usage, can be added to the certificate when the certificate request is submitted. 2.4.4.2.2.2. OCSP responses The OCSP response that the client receives indicates the current status of the certificate as determined by the OCSP responder. The response could be any of the following: Good or Verified . Specifies a positive response to the status inquiry, meaning the certificate has not been revoked. It does not necessarily mean that the certificate was issued or that it is within the certificate's validity interval. Response extensions may be used to convey additional information on assertions made by the responder regarding the status of the certificate. Revoked . Specifies that the certificate has been revoked, either permanently or temporarily. Based on the status, the client decides whether to validate the certificate. Note The OCSP responder will never return a response of Unknown . The response will always be either Good or Revoked . 2.4.4.2.2.3. OCSP services There are two ways to set up OCSP services: The OCSP built into the Certificate Manager The Online Certificate Status Manager subsystem In addition to the built-in OCSP service, the Certificate Manager can publish CRLs to an OCSP-compliant validation authority. CAs can be configured to publish CRLs to the Certificate System Online Certificate Status Manager. The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses the appropriate CRL to verify the revocation status of a certificate when queried by an OCSP-compliant client. The Certificate Manager can generate and publish CRLs whenever a certificate is revoked and at specified intervals. Because the purpose of an OCSP responder is to facilitate immediate verification of certificates, the Certificate Manager should publish the CRL to the Online Certificate Status Manager every time a certificate is revoked. Publishing only at intervals means that the OCSP service is checking an outdated CRL. Note If the CRL is large, the Certificate Manager can take a considerable amount of time to publish the CRL. The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL to verify certificates. The Online Certificate Status Manager can also use the CRL published to an LDAP directory, meaning the Certificate Manager does not have to update the CRLs directly to the Online Certificate Status Manager. 2.4.5. Archiving, recovering, and rotating keys In the world of PKI, private key archival allows parties the possibility to recover the encrypted data in case the private key is lost. Private keys can be lost due to various reasons such as hardware failure, forgotten passwords, lost smartcards, incapacitated password holder, et caetera. Such archival and recovery feature is offered by the Key Recovery Authority (KRA) subsystem of RHCS. Only keys that are used exclusively for encrypting data should be archived; signing keys in particular should never be archived. Having two copies of a signing key makes it impossible to identify with certainty who used the key; a second archived copy could be used to impersonate the digital identity of the original key owner. 2.4.5.1. Archiving keys There are two types of key archival mechanisms provided by KRA: Client-side key generation : With this mechanism, clients are to generate CSRs in CRMF format, and submit the requests to the CA (with proper KRA setup) for enrollment and key archival. See 5.2.3 Creating a CSR Using CRMFPopClient in the Administration Guide (Common Criteria Edition) . Server-side key generation : With this mechanism, the properly equipped certificate enrollment profiles would trigger the PKI keys to be generated on KRA and thereby optionally archived along with newly issued certificates. See 5.2.3 Generating CSRs Using Server-Side Key Generation in the Administration Guide (Common Criteria Edition) . The KRA automatically archives private encryption keys if archiving is configured. The KRA stores private encryption keys in a secure key repository; each key is encrypted and stored as a key record and is given a unique key identifier. The archived copy of the key remains wrapped with the KRA's storage key. It can be decrypted, or unwrapped, only by using the corresponding private key pair of the storage certificate. A combination of one or more key recovery (or KRA) agents' certificates authorizes the KRA to complete the key recovery to retrieve its private storage key and use it to decrypt/recover an archived private key. See Section 12.3.1, "Configuring agent-approved key recovery in the command line" . The KRA indexes stored keys by key number, owner name, and a hash of the public key, allowing for highly efficient searching. The key recovery agents have the privilege to insert, delete, and search for key records. When the key recovery agents search by the key ID, only the key that corresponds to that ID is returned. When the agents search by username, 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. When a Certificate Manager receives a certificate request that contains the key archival option, it automatically forwards the request to the KRA to archive the encryption key. The private key is encrypted by the transport key, and the KRA receives the encrypted copy and stores the key in its key repository. To archive the key, the KRA uses two special key pairs: A transport key pair and corresponding certificate. A storage key pair. Figure 2.2, "How the Key Archival Process works in client-side key generation" illustrates how the key archival process occurs when an end entity requests a certificate in the case of client-side key generation. Figure 2.2. How the Key Archival Process works in client-side key generation The client generates a CRMF request and submits it through the CA's enrollment portal. The client's private key is wrapped within the CRMF request and can only be unwrapped by the KRA. Detecting that it's a CRMF request with key archival option, CA forwards the request to KRA for private key archival. The KRA decrypts / unwraps the user private key, and after confirming that the private key corresponds to the public key, the KRA encrypts / wraps it again before storing it in its internal LDAP database. Once the private encryption key has been successfully stored, the KRA responds to CA confirming that the key has been successfully archived. The CA sends the request down its Enrollment Profile Framework for certificate information content creation as well as validation. When everything passes, it then issues the certificate and sends it back to the end entity in its response. 2.4.5.2. Recovering keys The KRA supports agent-initiated key recovery . Agent-initiated recovery is when designated recovery agents use the key recovery form on the KRA agent services portal to process and approve key recovery requests. With the approval of a specified number of agents, an organization can recover keys when the key's owner is unavailable or when keys have been lost. Through the KRA agent services portal, key recovery agents can collectively authorize and retrieve private encryption keys and associated certificates into a PKCS #12 package, which can then be imported into the client. In key recovery authorization, one of the key recovery agents informs all required recovery agents about an impending key recovery. All recovery agents access the KRA key recovery portal. One of the agents initiates the key recovery process. The KRA returns a notification to the agent includes a recovery authorization reference number identifying the particular key recovery request that the agent is required to authorize. Each agent uses the reference number and authorizes key recovery separately. KRA supports Asynchronous recovery , meaning that each step of the recovery process - the initial request and each subsequent approval or rejection - is stored in the KRA's internal LDAP database, under the key entry. The status data for the recovery process can be retrieved even if the original browser session is closed or the KRA is shut down. Agents can search for the key to recover, without using a reference number. This asynchronous recovery option is illustrated in Figure 2.3, "Asynchronous recovery" . Figure 2.3. Asynchronous recovery The KRA informs the agent who initiated the key recovery process of the status of the authorizations. When all of the authorizations are entered, the KRA checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process. Warning The PKCS #12 package contains the encrypted private key. To minimize the risk of key compromise, the recovery agent must use a secure method to deliver the PKCS #12 package and password to the key recipient. The agent should use a good password to encrypt the PKCS #12 package and set up an appropriate delivery mechanism. The key recovery agent scheme configures the KRA to recognize to which group the key recovery agents belong and specifies how many of these recovery agents are required to authorize a key recovery request before the archived key is restored. Important The above information refers to using a web browser, such as Firefox. However, functionality critical to KRA usage is no longer newer versions of browsers. In such cases, it is necessary to use the pki utility to replicate this behavior. For more information, see the pki(1) and pki-key(1) man pages or run CRMFPopClient --help and man CMCRequest. Apart from storing asymmetric keys, KRA can also store symmetric keys or secrets similar to symmetric keys, such as volume encryption secrets, or even passwords and passphrases. The pki utility supports options that enable storing and retrieving these other types of secrets. 2.4.5.3. KRA transport key rotation KRA transport rotation allows for seamless transition between CA and KRA subsystem instances using a current and a new transport key. This allows KRA transport keys to be periodically rotated for enhanced security by allowing both old and new transport keys to operate during the time of the transition; individual subsystem instances take turns being configured while other clones continue to serve with no downtime. In the KRA transport key rotation process, a new transport key pair is generated, a certificate request is submitted, and a new transport certificate is retrieved. The new transport key pair and certificate have to be included in the KRA configuration to provide support for the second transport key. Once KRA supports two transport keys, administrators can start transitioning CAs to the new transport key. KRA support for the old transport key can be removed once all CAs are moved to the new transport key. To configure 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 After this, the rotation of KRA transport certificates is complete, and all the affected CAs and KRAs use the new KRA certificate only. For more information on how to perform the above steps, see the procedures below. Generating the new KRA transport key and certificate Request the KRA transport certificate. Stop the KRA: OR if using the Nuxwdog watchdog: Go to the KRA NSS database directory: Create a subdirectory and save all the NSS database files into it. For example: Create a new request by using the PKCS10Client utility. For example: Alternatively, use the certutil utility. For example: 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: 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: Import the transport certificate into the KRA NSS database: Update the KRA transport certificate configuration. Go to the KRA NSS database directory: Verify that the new KRA transport certificate is imported: Open the /var/lib/pki/pki-kra/kra/conf/CS.cfg file and add the following line: Propagating the new transport key and certificate to KRA clones Start the KRA: OR if using the Nuxwdog watchdog: Extract the new transport key and certificate for propagation to clones. Go to the KRA NSS database directory: Stop the KRA: OR if using the Nuxwdog watchdog: Verify that the new KRA transport certificate is present: Export the KRA new transport key and certificate: Verify the exported KRA transport key and certificate: 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: Stop the KRA clone: OR if using the Nuxwdog watchdog: Check the content of the clone NSS database: Import the new transport key and certificate of the clone: Add the following line to the /var/lib/pki/pki-kra/kra/conf/CS.cfg file on the clone: Start the KRA clone: OR 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 procedure. Convert the Base64-encoded certificate included in cert-serial_number.txt to a single-line file: Do the following for the CA and all its clones corresponding to the KRA above: Stop the CA: OR 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: Replace that certificate with the one contained in cert-one-line-serial_number.txt . Start the CA: OR 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: Stop the KRA: OR if using the Nuxwdog watchdog: Verify that the new KRA transport certificate is imported: Open the /var/lib/pki/pki-kra/kra/conf/CS.cfg file, and look for the nickName value included in the following line: Replace the nickName value with the newNickName value included in the following line: As a result, the CS.cfg file includes this line: Remove the following line from /var/lib/pki/pki-kra/kra/conf/CS.cfg : Start the KRA: OR if using the Nuxwdog watchdog: 2.5. Smart card token management with Certificate System A smart card is a hardware cryptographic device containing cryptographic certificates and keys. It can be employed by the user to participate in operations such as secure website access and secure mail. It can also serve as an authentication device to log in to various operating systems such as Red Hat Enterprise Linux. The management of these cards or tokens throughout their entire lifetime in service is accomplished by the Token Management System (TMS). A TMS environment requires a Certificate Authority (CA), Token Key Service (TKS), and Token Processing System (TPS), with an optional Key Recovery Authority (KRA) for server-side key generation and key archival and recovery. Online Certificate Status Protocol (OCSP) can also be used to work with the CA to serve online certificate status requests. This chapter provides an overview of the TKS and TPS systems, which provide the smart card management functions of Red Hat Certificate System, as well as Enterprise Security Client (ESC), that works with TMS from the user end. Figure 2.4. How the TMS manages smart cards 2.5.1. Token Key Service (TKS) The Token Key Service (TKS) is responsible for managing one or more master keys. It maintains the master keys and is the only entity within the TMS that has access to the key materials. In an operational environment, each valid smart card token contains a set of symmetric keys that are derived from both the master key and the ID that is unique to the card (CUID). Initially, a default (unique only per manufacturer master key) set of symmetric keys is initialized on each smart card by the manufacturer. This default set should be changed at the deployment site by going through a Key Changeover operation to generate the new master key on TKS. As the sole owner to the master key, when given the CUID of a smart card, TKS is capable of deriving the set of symmetric keys residing on that particular smart card, which would then allow TKS to establish a session-based Secure Channel for secure communication between TMS and each individual smart card. Note Because of the sensitivity of the data that the TKS manages, the TKS should be set behind the firewall with restricted access. 2.5.1.1. Master keys and key sets The TKS supports multiple smart card key sets. Each smart card vendor creates different default (developer) static key sets for their smart card token stocks, and the TKS is equipped with the static key set (per manufacturer) to kickstart the format process of a blank token. During the format process of a blank smart card token, a Java applet and the uniquely derived symmetric key set are injected into the token. Each master key (in some cases referred to as keySet ) that the TKS supports is to have a set of entries in the TKS configuration file ( 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. On TKS, master keys are defined by named keySets for references by TPS. On TPS, depending on the enrollment type (internal or external registration), The keySet is either specified in the TPS profile, or determined by the keySet Mapping Resolver. 2.5.1.2. Key ceremony (shared key transport) A Key Ceremony is a process for transporting highly sensitive keys in a secure way from one location to another. In one scenario, in a highly secure deployment environment, the master key can be generated in a secure vault with no network to the outside. Alternatively, an organization might want to have TKS and TPS instances on different physical machines. In either case, under the assumption that no one single person is to be trusted with the key, Red Hat Certificate System TMS provides a utility called tkstool to manage the secure key transportation. 2.5.1.3. Key update (key changeover) When Global Platform-compliant smart cards are created at the factory, the manufacturer will burn a set of default symmetric keys onto the token. The TKS is initially configured to use these symmetric keys (one KeySet entry per vendor in the TKS configuration). However, since these symmetric keys are not unique to the smart cards from the same stock, and because these are well-known keys, it is strongly encouraged to replace these symmetric keys with a set that is unique per token, not shared by the manufacturer, to restrict the set of entities that can manipulate the token. The changing over of the keys takes place with the assistance of the Token Key Service subsystem. One of the functions of the TKS is to oversee the Master Keys from which the previously discussed smart card token keys are derived. There can be more than one master key residing under the control of the TKS. Important When this key changeover process is done on a token, the token may become unusable in the future since it no longer has the default key set enabled. The key is essentially only as good as long as the TPS and TKS system that provisioned the token is valid. Because of this, it is essential to keep all the master keys, even if any of them are outdated. You can disable the old master keys in TKS for better control, but do not delete them unless disabled tokens are part of your plan. There is support to revert the token keys back to the original key set, which is viable if the token is to be reused again in some sort of a testing scenario. 2.5.1.4. APDUs and secure channels The Red Hat Certificate System Token Management System (TMS) supports the GlobalPlatform smart card specification, in which the Secure Channel implementation is done with the Token Key System (TKS) managing the master key and the Token Processing System (TPS) communicating with the smart card (tokens) with Application Protocol Data Units (APDUs). There are two types of APDUs: Command APDUs , sent by the TPS to smart cards Response APDUs , sent by smart cards to the TPS as response to command APDUs The initiation of the APDU commands may be triggered when clients take action and connect to the Certificate System server for requests. A secure channel begins with an InitializeUpdate APDU sent from TPS to the smart card token, and is fully established with the ExternalAuthenticate APDU. Then, both the token and TMS would have established a set of shared secrets, called session keys, which are used to encrypt and authenticate the communication. This authenticated and encrypted communication channel is called Secure Channel. Because TKS is the only entity that has access to the master key which is capable of deriving the set of unique symmetric on-token smart card keys, the Secure Channel provides the adequately safeguarded communication between TMS and each individual token. Any disconnection of the channel will require reestablishment of new session keys for a new channel. 2.5.2. Token Processing System (TPS) The Token Processing System (TPS) is a registration authority for smart card certificate enrollment. It acts as a conduit between the user-centered Enterprise Security Client (ESC), which interacts with client side smart card tokens, and the Certificate System back end subsystems, such as the Certificate Authority (CA) and the Key Recovery Authority (KRA). In TMS, the TPS is required in order to manage smart cards, as it is the only TMS entity that understands the APDU commands and responses. TPS sends commands to the smart cards to help them generate and store keys and certificates for a specific entity, such as a user or device. Smart card operations go through the TPS and are forwarded to the appropriate subsystem for action, such as the CA to generate certificates or the KRA to generate, archive, or recover keys. 2.5.2.1. Coolkey applet Red Hat Certificate System includes the Coolkey Java applet, written specifically to run on TMS-supported smart card tokens. The Coolkey applet connects to a PKCS#11 module that handles the certificate and key related operations. During a token format operation, this applet is injected onto the smart card token using the Secure Channel protocol, and can be updated per configuration. 2.5.2.2. Token operations The TPS in Red Hat Certificate System is available to provision smart cards on the behalf of end users of the smart cards. The Token Processing System provides support for the following major 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. The following other operations can be considered supplementary or inherent operations to the main ones listed above. They can be triggered per relevant configuration or by the state of the token. 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 Certificate System Token Processing System subsystem facilitates the management of smart card tokens. Tokens are provisioned by the TPS such that they are taken from a blank state to either a Formatted or Enrolled condition. A Formatted token is one that contains the CoolKey applet supported by TPS, while an Enrolled token is personalized (a process called binding ) to an individual with the requisite certificates and cryptographic keys. This fully provisioned token is ready to use for crytptographic operations. The TPS can also manage Profiles . The notion of a token Profile is related to: The steps taken to Format or Enroll a token. The attributes contained within the finished token after the operation has been successfully completed. The following list contains some of the quantities that make up a unique token profile: 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? These above and many others can be configured for each token type or profile. A full list of available configuration options is available in the Red Hat Certificate System Administration Guide . Another question to consider is how a given token being provisioned by a user will be mapped to an individual token profile. There are two types of registration: 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. The registration to be used is configured globally per TPS instance. 2.5.2.4. Token database The Token Processing System makes use of the LDAP token database store, which is used to keep a list of active tokens and their respective certificates, and to keep track of the current state of each token. A brand new token is considered Uninitialized , while a fully enrolled token is Enrolled . This data store is constantly updated and consulted by the TPS when processing tokens. 2.5.2.4.1. Token states and transitions The Token Processing System stores states in its internal database in order to determine the current token status as well as actions which can be performed on the token. 2.5.2.4.1.1. Token states The following table lists all possible 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 The command line interface displays token states using the Name listed above. The graphical interface uses the Label instead. Note The above table contains no state with code 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 Each token state has a limited amount of states it can transition into. For example, a token can change state from FORMATTED to ACTIVE or DAMAGED , but it can never transition from FORMATTED to UNFORMATTED . Furthermore, the list of states a token can transition into is different depending on whether the transition is triggered manually using a command line or the graphical interface, or automatically using a token operation. The list of allowed manual transitions is stored in the tokendb.allowedTransitions property, and the tps.operations.allowedTransitions property controls allowed transitions triggered by token operations. The default configurations for both manual and token operation-based transitions are stored in the /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 All possible transitions allowed in the command line or graphical interface are described in the TPS configuration file using the tokendb.allowedTransitions property: The property contains a comma-separated list of transitions. Each transition is written in the format of <current code> :_<new code>_ . The codes are described in Table 2.10, "Possible manual token state transitions" . The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg . The following table describes each possible transition in more detail: Table 2.10. Possible manual token state transitions Transition Current State 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. The following transitions are generated automatically depending on the token's original state. If a token was originally 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 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 All possible transitions that can be done using token operations are described in the TPS configuration file using the tokendb.allowedTransitions property: The property contains a comma-separated list of transitions. Each transition is written in the format of <current code> :_<new code>_ . The codes are described in Table 2.10, "Possible manual token state transitions" . The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg . The following table describes each possible transition in more detail: Table 2.12. Possible token state transitions using token operations Transition Current State 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 The default labels for token states and transitions are stored in the /usr/share/pki/tps/conf/token-states.properties configuration file. By default, the file has the following contents: 2.5.2.4.1.5. Customizing allowed token state transitions To customize the list of token state transition, edit the following properties in /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 interface tps.operations.allowedTransitions to customize the list of allowed transitions using token operations Transitions can be removed from the default list if necessary, but new transitions cannot be added unless they were in the default list. The defaults are stored in /usr/share/pki/tps/conf/CS.cfg . 2.5.2.4.1.6. Customizing token state and transition labels To customize token state and transition labels, copy the default /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. Changes will be effective immediately, the server does not need to be restarted. The TPS user interface may require a reload. To revert to default state and label names, delete the edited token-states.properties file from your instance folder. 2.5.2.4.1.7. Token activity log Certain TPS activities are logged. Possible events in the log file are listed in the table below. 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 In case of internal registration, each token can be governed by a set of token policies. The default policies are: All TPS operations under internal registration are subject to the policies specified in the token's record. If no policies are specified for a token, the TPS uses the default set of policies. 2.5.2.5. Mapping resolver The Mapping Resolver is an extensible mechanism used by the TPS to determine which token profile to assign to a specific token based on configurable criteria. Each mapping resolver instance can be uniquely defined in the configuration, and each operation can point to various defined mapping resolver instance. Note The mapping resolver framework provides a platform for writing custom plugins. However instructions on how to write a plugin is outside the scope of this document. 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 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. The input filter parameters are information received from the smart card token with or without extensions. They are run against the 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 or tokenType 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. The keySetMappingResolver 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 The TPS supports the following roles by default: 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 During TMS installation, a shared symmetric key is established between the Token Key Service and the Token Processing System. The purpose of this key is to wrap and unwrap session keys which are essential to Secure Channels. Note The shared secret key is currently only kept in a software cryptographical database. There are plans to support keeping the key on a Hardware Security Module (HSM) devices in a future release of Red Hat Certificate System. Once this functionality is implemented, you will be instructed to run a Key Ceremony using tkstool to transfer the key to the HSM. 2.5.4. Enterprise Security Client (ESC) The Enterprise Security Client is an HTTP client application, similar to a web browser, that communicates with the TPS and handles smart card tokens from the client side. While an HTTPS connection is established between the ESC and the TPS, an underlying Secure Channel is also established between the token and the TMS within each TLS session. 2.6. Red Hat Certificate System services Certificate System has a number of different features for administrators to use which makes it easier to maintain the individual subsystems and the PKI as a whole. 2.6.1. Notifications When a particular event occurs, such as when a certificate is issued or revoked, then a notification can be sent directly to a specified email address. The notification framework comes with default modules that can be enabled and configured. 2.6.2. Jobs Automated jobs run at defined intervals. 2.6.3. Logging The Certificate System and each subsystem produce extensive system and error logs that record system events so that the systems can be monitored and debugged. All log records are stored in the local file system for quick retrieval. Logs are configurable, so logs can be created for specific types of events and at the required logging level. Certificate System allows logs to be signed digitally before archiving them or distributing them for auditing. This feature enables log files to be checked for tampering after being signed. 2.6.4. Auditing The Certificate System maintains audit logs for all events, such as requesting, issuing and revoking certificates and publishing CRLs. These logs are then signed. This allows authorized access or activity to be detected. An outside auditor can then audit the system if required. The assigned auditor user account is the only account which can view the signed audit logs. This user's certificate is used to sign and encrypt the logs. Audit logging is configured to specify the events that are logged. 2.6.5. Self-tests The Certificate System provides the framework for system self-tests that are automatically run at startup and can be run on demand. A set of configurable self-tests are already included with the Certificate System. See Section 2.3.13, "Self-tests" for more information about self-tests. 2.6.6. Users, authorization, and access controls Certificate System users can be assigned to groups, which are also known as roles, and they then have the privileges of whichever group they are members. A user only has privileges for the instance of the subsystem in which the user is created and the privileges of the group to which the user is a member. Authentication is the means that Certificate System subsystems use to verify the identity of clients, whether they are authenticating to a certificate profile or to one of the services interfaces. There are a number of different ways for a client to perform authentication, including simple user name/password, SSL/TLS mutual authentication, LDAP authentication, NIS authentication, or CMC. Authentication can be performed for any access to the subsystem; for certificate enrollments, for example, the profile defines how the requestor authenticates to the CA. Once the client is identified and authenticated, then the subsystems perform an authorization check to determine what level of access to the subsystem that particular user is allowed. Authorization is tied to group, or role, permissions, rather than directly to individual users. The Certificate System provides an authorization framework for creating groups and assigning access control to those groups. The default access control on preexisting groups can be modified, and access control can be assigned to individual users and IP addresses. Access points for authorization have been created for the major portions of the system, and access control rules can be set for each point. 2.6.6.1. Default administrative roles Note Red Hat Certificate System uses the words roles and groups interchangeably in the context of the permissions given to users. The Certificate System is configured by default with three user types with different access levels to the system: 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 By default, for bootstrapping purposes, an administrative user processing both Administrator and Agent privileges is created during the Red Hat Certificate System instance creation, when running the 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 Additionally, when a security domain is created, the CA subsystem which hosts the domain is automatically granted the special role of Security Domain Administrator , which gives the subsystem the ability to manage the security domain and the subsystem instances within it. Other security domain administrator roles can be created for the different subsystem instances. These special roles should not have actual users as members.

Commands:
dnf install redhat-pki
pkispawn
mkdir -p /root/pki
[DEFAULT] pki_admin_password=<password> pki_client_pkcs12_password=<password> pki_ds_password=<password>
pkispawn -s CA -f /root/pki/ca.cfg
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.
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 With watchdog disabled pki-tomcatd-nuxwdog With watchdog enabled
systemctl disable pki-tomcatd@instance_name.service
systemctl enable pki-tomcatd@instance_name.service
pki-server [CLI options] <command> [command parameters]
pki-server
pki-server ca
pki-server ca-audit
pki-server --help
pki-server ca-audit-event-find --help
pki-server subsystem-disable -i instance_id subsystem_id
pki-server subsystem-enable -i instance_id subsystem_id
pki-server subsystem-disable -i pki-tomcat ocsp
pki-server subsystem-find -i instance_id
pki-server subsystem-find -i instance_id subsystem_id
pkidaemon {start|status} instance-type [instance_name]
https://server.example.com:8443/ca/services
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
pkiconsole -d nssdb -n 'optional client cert nickname' https://server.example.com:admin_port/subsystem_type
pkiconsole -d nssdb -n 'optional client cert nickname' https://server.example.com:8443/kra
https://192.0.2.1:8443/ca https://[2001:DB8::1111]:8443/ca
pki-server stop instance_name
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
pki-server start instance_name
systemctl start pki-tomcatd-nuxwdog@instance_name.service
/usr/share/pki/server/conf/catalina.policy /usr/share/tomcat/conf/catalina.policy /var/lib/pki/USDPKI_INSTANCE_NAME/conf/pki.policy /var/lib/pki/USDPKI_INSTANCE_NAME/conf/custom.policy
id: admin
UserID: admin
FullName: Administrator
Email: admin@example.com
[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
[CA] pki_random_serial_numbers_enable=True
pki-server subsystem-enable <subsystem>
date time [processor] LogLevel: servlet: message
{YY-MM-DD} [main] INFO: TKS engine started
{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.requestownerUSD value=KRA-server.example.com-8443
{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.profileapprovedbyUSD value=admin {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.cert_requestUSD value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOB {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.profileUSD value=true {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.cert_request_typeUSD value=crmf {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.requestversionUSD value=1.0.0 {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.req_localeUSD value=en {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.requestownerUSD value=KRA-server.example.com-8443 {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.dbstatusUSD value=NOT_UPDATED {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.subjectUSD value=uid=jsmith, e=jsmith@example.com {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.requeststatusUSD value=begin {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.auth_token.userUSD value=uid=KRA-server.example.com-8443,ou=People,dc=example,dc=com {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.req_keyUSD value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M HTmlOqm4HwFxzy0RRQIDAQAB {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.auth_token.authmgrinstnameUSD value=raCertAuth {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.auth_token.uidUSD value=KRA-server.example.com-8443 {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.auth_token.useridUSD value=KRA-server.example.com-8443 {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.requestor_nameUSD value= {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.profileidUSD value=caUserCert {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.auth_token.userdnUSD value=uid=KRA-server.example.com-4747,ou=People,dc=example,dc=com {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.requestidUSD value=20 {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.auth_token.authtimeUSD value=1212782378071 {YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=USDrequest.req_x509infoUSD 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=
{YY-MM-DD}[http-11180-Processor25]: OCSPServlet: OCSP Request: {YY-MM-DD}[http-11180-Processor25]{LogLevel}: OCSPServlet: MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU
========================================================================== INSTALLATION SUMMARY ========================================================================== Administrator's username: caadmin Administrator's PKCS #12 file: /root/.dogtag/pki-tomcat/ca_admin_cert.p12 Administrator's certificate nickname: caadmin Administrator's certificate database: /root/.dogtag/pki-tomcat/ca/alias To check the status of the subsystem: systemctl status pki-tomcatd@pki-tomcat.service To restart the subsystem: systemctl restart pki-tomcatd@pki-tomcat.service The URL for the subsystem is: https://localhost.localdomain:8443/ca PKI instances will be enabled upon system boot ==========================================================================
journalctl -u pki-tomcatd@instance_name.service
journalctl -u pki-tomcatd-nuxwdog@instance_name.service
journalctl -f -u pki-tomcatd@instance_name.service
journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service
servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert
pki-server stop pki-kra
systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
cd /etc/pki/pki-kra/alias
mkdir nss_db_backup
cp *.db nss_db_backup
PKCS10Client -p password -d '.' -o 'req.txt' -n 'CN=KRA Transport 2 Certificate,O=example.com Security Domain'
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
cd /etc/pki/pki-kra/alias
cd /etc/pki/pki-kra/alias
certutil -d . -A -n 'transportCert-serial_number cert-pki-kra KRA' -t 'u,u,u' -a -i cert-serial_number.txt
cd /etc/pki/pki-kra/alias
certutil -d . -L
certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
pki-server start pki-kra
systemctl start pki-tomcatd-nuxwdog@pki-kra.service
cd /etc/pki/pki-kra/alias
pki-server stop pki-kra
systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
certutil -d . -L
certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'
pk12util -l transport.p12
cd /etc/pki/pki-kra/alias
pki-server stop pki-kra
systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
certutil -d . -L
pk12util -i transport.p12 -d .
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
pki-server start pki-kra
systemctl start pki-tomcatd-nuxwdog@pki-kra.service
tr -d '\n' < cert-serial_number.txt > cert-one-line-serial_number.txt
pki-server stop pki-ca
systemctl stop pki-tomcatd-nuxwdog@pki-ca.service
ca.connector.KRA.transportCert=certificate
pki-server start pki-ca
systemctl start pki-tomcatd-nuxwdog@pki-ca.service
cd /etc/pki/pki-kra/alias
pki-server stop pki-kra
systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
certutil -d . -L
certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
kra.transportUnit.nickName=transportCert cert-pki-kra KRA
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
pki-server start pki-kra
systemctl start pki-tomcatd-nuxwdog@pki-kra.service
tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7
tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0
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.
RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES