Planning, Installation, and Deployment Guide (Common Criteria Edition)

Red Hat Certificate System supports deployment of separate PKI instances for all subsystems:

Alternatively, Certificate System supports deployment of a shared PKI instance:

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.

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:

When you start or restart an instance, a Java security policy is constructed or reconstructed by pkidaemon from the following files:

/usr/share/pki/server/conf/catalina.policy
/usr/share/tomcat/conf/catalina.policy
/var/lib/pki/$PKI_INSTANCE_NAME/conf/pki.policy
/var/lib/pki/$PKI_INSTANCE_NAME/conf/custom.policy

Then, it is saved into /var/lib/pki/instance_name/conf/catalina.policy.

This section describes the various interfaces of Red Hat Certificate System.

2.3.3.2. Administrative interface

Copy link

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

Copy link

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

Copy link

The operator interface is only found in the TPS subsystem.

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:

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:

{
	"id":"admin",
	"UserID":"admin",
	"FullName":"Administrator",
	"Email":"admin@example.com",
	...
}

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:

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.

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.

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:

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”.

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.

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.

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.

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”.

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”.

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:

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.

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:

# pki-server subsystem-enable <subsystem>

For details on how to configure self-tests, see Section 13.3.2, “Configuring self-tests”.

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 #Java™ 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).

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).

date time [processor] LogLevel: servlet: message

{YY-MM-DD} [main] INFO: TKS engine started

{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443

				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profileapprovedby$ value=admin
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.cert_request$ value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOB...
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profile$ value=true
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.cert_request_type$ value=crmf
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestversion$ value=1.0.0
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_locale$ value=en
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.dbstatus$ value=NOT_UPDATED
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.subject$ value=uid=jsmith, e=jsmith@example.com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requeststatus$ value=begin
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.user$ value=uid=KRA-server.example.com-8443,ou=People,dc=example,dc=com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_key$ value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M
				HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M
				k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M
				HTmlOqm4HwFxzy0RRQIDAQAB
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.authmgrinstname$ value=raCertAuth
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.uid$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.userid$ value=KRA-server.example.com-8443
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestor_name$ value=
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.profileid$ value=caUserCert
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.userdn$ value=uid=KRA-server.example.com-4747,ou=People,dc=example,dc=com
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.requestid$ value=20
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.auth_token.authtime$ value=1212782378071
				{YY-MM-DD}[http-8443;-Processor24]{LogLevel}: ProfileSubmitServlet: key=$request.req_x509info$ value=MIICIKADAgECAgEAMA0GCSqGSIb3DQEBBQUAMEAxHjAcBgNVBAoTFVJlZGJ1ZGNv^M
				bXB1dGVyIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X^M
				DTA4MDYwNjE5NTkzOFoXDTA4MTIwMzE5NTkzOFowOzEhMB8GCSqGSIb3DQEJARYS^M
				anNtaXRoQGV4YW1wbGUuY29tMRYwFAYKCZImiZPyLGQBARMGanNtaXRoMIGfMA0G^M
				CSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLPHcN0cusY^M
				7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChVk9HYDhmJ^M
				8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaMHTmlOqm4^M
				HwFxzy0RRQIDAQABo4HFMIHCMB8GA1UdIwQYMBaAFG8gWeOJIMt+aO8VuQTMzPBU^M
				78k8MEoGCCsGAQUFBwEBBD4wPDA6BggrBgEFBQcwAYYuaHR0cDovL3Rlc3Q0LnJl^M
				ZGJ1ZGNvbXB1dGVyLmxvY2FsOjkwODAvY2Evb2NzcDAOBgNVHQ8BAf8EBAMCBeAw^M
				HQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMCQGA1UdEQQdMBuBGSRyZXF1^M
				ZXN0LnJlcXVlc3Rvcl9lbWFpbCQ=

{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

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.

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).

servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert

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.

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.

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.

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

Copy link

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

1. The client generates a CRMF request and submits it through the CA’s enrollment portal.

   1. The client’s private key is wrapped within the CRMF request and can only be unwrapped by the KRA.
2. Detecting that it’s a CRMF request with key archival option, CA forwards the request to KRA for private key archival.
3. 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.
4. Once the private encryption key has been successfully stored, the KRA responds to CA confirming that the key has been successfully archived.
5. 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

Copy link

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.

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.

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.

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

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.

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.

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.

Automated jobs run at defined intervals.

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.

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.

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.

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.

Cipher and hashing algorithms are in a constant flux with regard to various vulnerabilities and security strengths. As a general rule, Red Hat Certificate System follows the NIST guideline and supports TLS 1.2 cipher suites.

The Transport Layer Security (TLS) protocol is a universally accepted standard for authenticated and encrypted communication between clients and servers.

Red Hat Certificate System supports the following TLS 1.2 cipher suites when the server is acting either as a server or as a client:

The core of the Certificate System PKI is the Certificate Manager, a certificate authority. The CA receives certificate requests and issues all certificates.

Figure 5.1. CA only Certificate System

All of the basic processing for requests and issuing certificates can be handled by the Certificate Manager, and it is the only required subsystem. There can be a single Certificate Manager or many Certificate Managers, arranged in many different relationships, depending on the demands of the organization.

Along with issuing certificates, a Certificate Manager can also revoke certificates. One question for administrators is how to handle certificates if they are lost, compromised, or if the person or equipment for which they are issued leaves the company. Revoking a certificate invalidates it before its expiration date, and a list of revoked certificates is compiled and published by the issuing CA so that clients can verify the certificate status.

One operation the CA cannot perform, though, is key archival and recovery. A very real scenario is that a user is going to lose his private key -for instance, the keys could be deleted from a browser database or a smart card could be left at home. Many common business operations use encrypted data, like encrypted email, and losing the keys which unlock that data means the data itself is lost. Depending on the policies in the company, there probably has to be a way to recover the keys in order to regenerate or reimport a replacement certificate, and both operations require the private key.

That requires a KRA, the subsystem which specially archives and retrieves keys.

Figure 5.2. CA and KRA

The Key Recovery Authority stores encryption keys (key archival) and can retrieve those keys so that the CA can reissue a certificate (key recovery). A KRA can store keys for any certificate generated by Certificate System, whether it is done for a regular certificate or when enrolling a smart card.

The key archival and recovery process is explained in more detail in Section 2.4.5, “Archiving, recovering, and rotating keys”.

Another aspect of how the subsystems work together is load balancing. If a site has high traffic, then it is possible to simply install a lot of CAs, as clones of each other or in a flat hierarchy (where each CA is independent) or in a tree hierarchy (where some CAs are subordinate to other CAs); this is covered more in Section 5.2, “Defining the Certificate Authority hierarchy”.

If a certificate is within its validity period but needs be invalidated, it can be revoked. A Certificate Manager can publish lists of revoked certificates, so that when a client needs to verify that a certificate is still valid, it can check the list. These requests are online certificate status protocol requests, meaning that they have a specific request and response format. The Certificate Manager has a built-in OCSP responder so that it can verify OCSP requests by itself.

However, as with certificate request traffic, a site may have a significant number of client requests to verify certificate status. Example Corp. has a large web store, and each customer’s browser tries to verify the validity of their SSL/TLS certificates. Again, the CA can handle issuing the number of certificates, but the high request traffic affects its performance. In this case, Example Corp. uses the external OCSP Manager subsystem to verify certificate statuses, and the Certificate Manager only has to publish updated CRLs every so often.

Figure 5.3. CA and OCSP

Smart cards usually require in-person enrollment and approval processes, since they use a physical medium to store key and certificate data. That means that multiple agents need to have access to the TPS and, possibly, multiple TPS subsystems in different offices or geographic locations.

The token management system is very scalable. Multiple TPSs can be configured to work with a single CA, TKS, or KRA instance, while multiple Enterprise Security Clients can communicate with a single TPS. As additional clients are installed, they can point back to the TPS instance without having to reconfigure the TPS; likewise, as TPSs are added, they can point to the same CA, TKS, and KRA instances without having to reconfigure those subsystems.

After installation, the TPS configuration can be edited to use additional CA, KRA, and TKS instances for failover support, so if the primary subsystem is unavailable, the TPS can switch to the next available system without interrupting its token services.

Chaining the Certificate System CA to a third-party public CA introduces the restrictions that public CAs place on the kinds of certificates the subordinate CA can issue and the nature of the certificate chain. For example, a CA that chains to a third-party CA might be restricted to issuing only Secure Multipurpose Internet Mail Extensions (S/MIME) and SSL/TLS mutual authentication certificates, but not SSL/TLS server certificates. There are other possible restrictions with using a public CA. This may not be acceptable for some PKI deployments.

One benefit of chaining to a public CA is that the third party is responsible for submitting the root CA certificate to a web browser or other client software. This can be a major advantage for an extranet with certificates that are accessed by different companies with browsers that cannot be controlled by the administrator. Creating a root CA in the CA hierarchy means that the local organization must get the root certificate into all the browsers which will use the certificates issued by the Certificate System. There are tools to do this within an intranet, but it can be difficult to accomplish with an extranet.

The Certificate System CA can function as a root CA, meaning that the server signs its own CA signing certificate as well as other CA signing certificates, creating an organization-specific CA hierarchy. The server can alternatively be configured as a subordinate CA, meaning the server’s CA signing key is signed by another CA in an existing CA hierarchy.

Setting up a Certificate System CA as the root CA means that the Certificate System administrator has control over all subordinate CAs by setting policies that control the contents of the CA signing certificates issued. A subordinate CA issues certificates by evaluating its own authentication and certificate profile configuration, without regard for the root CA’s configuration.

The Certificate System Certificate Manager can function as a linked CA, chaining up to many third-party or public CAs for validation; this provides cross-company trust, so applications can verify certificate chains outside the company certificate hierarchy. A Certificate Manager is chained to a third-party CA by requesting the Certificate Manager’s CA signing certificate from the third-party CA.

Related to this, the Certificate Manager also can issue cross-pair or cross-signed certificates. Cross-pair certificates 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.

These are also called bridge certificates, related to the Federal Bridge Certification Authority (FBCA) definition.

Instead of creating a hierarchy of root and subordinate CAs, it is possible to create multiple clones of a Certificate Manager and configure each clone to issue certificates within a range of serial numbers.

A cloned Certificate Manager uses the same CA signing key and certificate as another Certificate Manager, the master Certificate Manager.

Because clone CAs and original CAs use the same CA signing key and certificate to sign the certificates they issue, the issuer name in all the certificates is the same. Clone CAs and the original Certificate Managers issue certificates as if they are a single CA. These servers can be placed on different hosts for high availability failover support.

The advantage of cloning is that it distributes the Certificate Manager’s load across several processes or even several physical machines. For a CA with a high enrollment demand, the distribution gained from cloning allows more certificates to be signed and issued in a given time interval.

A cloned Certificate Manager has the same features, such as agent and end-entity gateway functions, of a regular Certificate Manager.

The serial numbers for certificates issued by clones are distributed dynamically. The databases for each clone and master are replicated, so all of the certificate requests and issued certificates, both, are also replicated. This ensures that there are no serial number conflicts while serial number ranges do not have to be manually assigned to the cloned Certificate Managers.

When a Certificate System subsystem is first installed and configured, the certificates necessary to access and administer it are automatically created. These include an agent’s certificate, server certificate, and subsystem-specific certificates. These initial certificates are shown in Table 5.1, “Initial subsystem certificates”.

There are some cautionary considerations about replacing existing subsystem certificates.

The core elements of a CA are a signing unit and the Certificate Manager identity. The signing unit digitally signs certificates requested by end entities. A Certificate Manager must have its own distinguished name (DN), which is listed in every certificate it issues.

Like any other certificate, a CA certificate binds a DN to a public key. A DN is a series of name-value pairs that in combination uniquely identify an entity. For example, the following DN identifies a Certificate Manager for the Engineering department of a corporation named Example Corporation:

cn=demoCA, o=Example Corporation, ou=Engineering, c=US

Many combinations of name-value pairs are possible for the Certificate Manager’s DN. The DN must be unique and readily identifiable, since any end entity can examine it.

Every certificate, including a Certificate Manager signing certificate, must have a validity period. The Certificate System does not restrict the validity period that can be specified. Set as long a validity period as possible, depending on the requirements for certificate renewal, the place of the CA in the certificate hierarchy, and the requirements of any public CAs that are included in the PKI.

A Certificate Manager cannot issue a certificate that has a validity period longer than the validity period of its CA signing certificate. If a request is made for a period longer than the CA certificate’s validity period, the requested validity date is ignored and the CA signing certificate validity period is used.

A signing key is used by a subsystem to verify and "seal" something. CAs use a CA signing certificate to sign certificates or CRLs that it issues; OCSPs use signing certificates to verify their responses to certificate status requests; all subsystems use log file signing certificates to sign their audit logs.

The signing key must be cryptographically strong to provide protection and security for its signing operations. The following signing algorithms are considered secure:

Along with a key type, each key has a specific bit length. Longer keys are considered cryptographically stronger than shorter keys. However, longer keys require more time for signing operations.

The default RSA key length in the configuration wizard is 2048 bits; for certificates that provide access to highly sensitive data or services, consider increasing the length to 4096 bits. ECC keys are much stronger than RSA keys, so the recommended length for ECC keys is 256 bits, which is equivalent in strength to a 2048-bit RSA key.

An X.509 v3 certificate contains an extension field that permits any number of additional fields to be added to the certificate. Certificate extensions provide a way of adding information such as alternative subject names and usage restrictions to certificates. Older Netscape servers, such as Red Hat Directory Server and Red Hat Certificate System, require Netscape-specific extensions because they were developed before PKIX part 1 standards were defined.

The X.509 v1 certificate specification was originally designed to bind public keys to names in an X.500 directory. As certificates began to be used on the Internet and extranets and directory lookups could not always be performed, problem areas emerged that were not covered by the original specification.

The X.509 v3 specification addressed these issues by altering the certificate format to include additional information within a certificate by defining a general format for certificate extensions and specifying extensions that can be included in the certificate. The extensions defined for X.509 v3 certificates enable additional attributes to be associated with users or public keys and manage the certification hierarchy. The Internet X.509 Public Key Infrastructure Certificate and CRL Profile recommends a set of extensions to use for Internet certificates and standard locations for certificate or CA information. These extensions are called standard extensions.

The X.509 v3 standard for certificates allows organizations to define custom extensions and include them in certificates. These extensions are called private, proprietary, or custom extensions, and they carry information unique to an organization or business. Applications may not able to validate certificates that contain private critical extensions, so it not recommended that these be used in wide-spread situations.

The X.500 and X.509 specifications are controlled by the International Telecommunication Union (ITU), an international organization that primarily serves large telecommunication companies, government organizations, and other entities concerned with the international telecommunications network. The Internet Engineering Task Force (IETF), which controls many of the standards that underlie the Internet, is currently developing public-key infrastructure X.509 (PKIX) standards. These proposed standards further refine the X.509 v3 approach to extensions for use on the Internet. The recommendations for certificates and CRLs have reached proposed standard status and are in a document referred to as PKIX Part 1.

Two other standards, Abstract Syntax Notation One (ASN.1) and Distinguished Encoding Rules (DER), are used with Certificate System and certificates in general. These are specified in the CCITT Recommendations X.208 and X.209. For a quick summary of ASN.1 and DER, see A Layman’s Guide to a Subset of ASN.1, BER, and DER, which is available at RSA Laboratories' web site, http://www.rsa.com.

Extension  ::=  SEQUENCE  {

extnID OBJECT IDENTIFIER,
critical BOOLEAN DEFAULT FALSE,
extnValue OCTET STRING  }

Certificates have different types and different applications. They can be used to establish a single sign-on environment for a corporate network, to set up VPNs, to encrypt email, or to authenticate to a website. The requirements for all of these certificates can be different, just as there may also be different requirements for the same type of certificate for different kinds of users. These certificate characteristics are set in certificate profiles. The Certificate Manager defines a set of certificate profiles that it uses as enrollment forms when users or machines request certificates.

Certificate profiles

A certificate profile defines everything associated with issuing a particular type of certificate, including the authentication method, the certificate content (defaults), constraints for the values of the content, and the contents of the input and output for the certificate profile. Enrollment requests are submitted to a certificate profile and are then subject to the defaults and constraints set in that certificate profile. These constraints are in place whether the request is submitted through the input form associated with the certificate profile or through other means. The certificate that is issued from a certificate profile request contains the content required by the defaults with the information required by the default parameters. The constraints provide rules for what content is allowed in the certificate.

For example, a certificate profile for user certificates defines all aspects of that certificate, including the validity period of the certificate. The default validity period can be set to two years, and a constraint can be set on the profile that the validity period for certificates requested through this certificate profile cannot exceed two years. When a user requests a certificate using the input form associated with this certificate profile, the issued certificate contains the information specified in the defaults and will be valid for two years. If the user submits a pre-formatted request for a certificate with a validity period of four years, the request is rejected since the constraints allow a maximum of two years validity period for this type of certificate.

A set of certificate profiles have been predefined for the most common certificates issued. These certificate profiles define defaults and constraints, associate the authentication method, and define the needed inputs and outputs for the certificate profile.

Modifying the certificate profile parameters

The parameters of the default certificate profiles can be modified; this includes the authentication method, the defaults, the constraints used in each profile, the values assigned to any of the parameters in a profile, the input, and the output. It is also possible to create new certificate profiles for other types of certificates or for creating more than one certificate profile for a certificate type. There can be multiple certificate profiles for a particular type of certificate to issue the same type of certificate with a different authentication method or different definitions for the defaults and constraints. For example, there can be two certificate profiles for enrollment of SSL/TLS server certificates where one certificate profile issues certificates with a validity period of six months and another certificate profile issues certificates with a validity period of two years.

An input sets a text field in the enrollment form and what kind of information needs gathered from the end entity; this includes setting the text area for a certificate request to be pasted, which allows a request to be created outside the input form with any of the request information required. The input values are set as values in the certificate. The default inputs are not configurable in the Certificate System.

An output specifies how the response page to a successful enrollment is presented. It usually displays the certificate in a user-readable format. The default output shows a printable version of the resultant certificate; other outputs set the type of information generated at the end of the enrollment, such as PKCS #7.

Policy sets are sets of constraints and default extensions attached to every certificate processed through the profile. The extensions define certificate content such as validity periods and subject name requirements. A profile handles one certificate request, but a single request can contain information for multiple certificates. A PKCS#10 request contains a single public key. One CRMF request can contain multiple public keys, meaning multiple certificate requests. A profile may contain multiple sets of policies, with each set specifying how to handle one certificate request within a CRMF request.

Certificate Profile Administration

An administrator sets up a certificate profile by associating an existing authentication plugin, or method, with the certificate profile; enabling and configuring defaults and constraints; and defining inputs and outputs. The administrator can use the existing certificate profiles, modify the existing certificate profiles, create new certificate profiles, and delete any certificate profile that will not be used in this PKI.

Once a certificate profile is set up, it appears on the Manage Certificate Profiles page of the agent services page where an agent can approve, and thus enable, a certificate profile. Once the certificate profile is enabled, it appears on the Certificate Profile tab of the end-entities page where end entities can enroll for a certificate using the certificate profile.

The certificate profile enrollment page in the end-entities interface contains links to each certificate profile that has been enabled by the agents. When an end entity selects one of those links, an enrollment page appears containing an enrollment form specific to that certificate profile. The enrollment page is dynamically generated from the inputs defined for the profile. If an authentication plugin is configured, additional fields may be added to authenticate the user.

When an end entity submits a certificate profile request that is associated with an agent-approved (manual) enrollment, an enrollment where no authentication plugin is configured, the certificate request is queued in the agent services interface. The agent can change some aspects of the enrollment, request, validate it, cancel it, reject it, update it, or approve it. The agent is able to update the request without submitting it or validate that the request adheres to the profile’s defaults and constraints. This validation procedure is only for verification and does not result in the request being submitted. The agent is bound by the constraints set; they cannot change the request in such a way that a constraint is violated. The signed approval is immediately processed, and a certificate is issued.

When a certificate profile is associated with an authentication method, the request is approved immediately and generates a certificate automatically if the user successfully authenticates, all the information required is provided, and the request does not violate any of the constraints set up for the certificate profile. There are profile policies which allow user-supplied settings like subject names or validity periods. The certificate profile framework can also preserve user-defined content set in the original certificate request in the issued certificate.

The issued certificate contains the content defined in the defaults for this certificate profile, such as the extensions and validity period for the certificate. The content of the certificate is constrained by the constraints set for each default. Multiple policies (defaults and constraints) can be set for one profile, distinguishing each set by using the same value in the policy set ID. This is particularly useful for dealing with dual keys enrollment where encryption keys and signing keys are submitted to the same profile. The server evaluates each set with each request it receives. When a single certificate is issued, one set is evaluated, and any other sets are ignored. When dual-key pairs are issued, the first set is evaluated with the first certificate request, and the second set is evaluated with the second certificate request. There is no need for more than one set for issuing a single certificate or more than two sets for issuing dual-key pairs.

Guidelines for customizing certificate profiles

Tailor the profiles for the organization to the real needs and anticipated certificate types used by the organization:

pki_san_inject=True
pki_san_for_server_cert=intca01.example.com,intca02.example.com,intca.example.com

As implied in Section 5.4.6, “Using and customizing certificate profiles”, authentication for the certificate process means the way that a user or entity requesting a certificate proves that they are who they say they are. There are three ways that the Certificate System can authenticate an entity:

A Certificate Manager is initially configured for agent-approved enrollment and for CMC authentication. Automated enrollment is enabled by configuring one of the authentication plugin modules. More than one authentication method can be configured in a single instance of a subsystem. The HTML registration pages contain hidden values specifying the method used. With certificate profiles, the end-entity enrollment pages are dynamically-generated for each enabled profile. The authentication method associated with this certificate profile is specified in the dynamically-generated enrollment page.

The authentication process is simple.

The requirements for how a certificate request is authenticated can have a direct impact on the necessary subsystems and profile settings. For example, if an agent-approved enrollment requires that an agent meet the requester in person and verify their identity through supported documentation, the authentication process can be time-intensive, as well as constrained by the physical availability of both the agent and the requester.

A CA can publish both certificates and CRLs. Certificates can be published to a plain file or to an LDAP directory; CRLs can be published to file or an LDAP directory, as well, and can also be published to an OCSP responder to handle certificate verification.

Configuring publishing is fairly straightforward and is easily adjusted. For continuity and accessibility, though, it is good to plan out where certificates and CRLs need to be published and what clients need to be able to access them.

Publishing to an LDAP directory requires special configuration in the directory for publishing to work:

When a CA signing certificate expires, all certificates signed with the CA’s corresponding signing key become invalid. End entities use information in the CA certificate to verify the certificate’s authenticity. If the CA certificate itself has expired, applications cannot chain the certificate to a trusted CA.

There are two ways of resolving CA certificate expiration:

There are problems and advantages with either renewing or reissuing a CA certificate. Begin planning the CA certificate renewal or re-issuance before installing any Certificate Managers, and consider the ramifications the planned procedures may have for extensions, policies, and other aspects of the PKI deployment.

There are two considerations about using firewalls with Certificate System subsystems:

The CA, KRA, and TKS are always placed inside a firewall because they contain critical information that can cause devastating security consequences if they are compromised.

The TPS and OCSP can be placed outside the firewall. Likewise, other services and clients used by the Certificate System can be on a different machine outside the firewall. In that case, the local networks have to be configured to allow access between the subsystems behind the firewall and the services outside it.

The LDAP database can be on a different server, even on a different network, than the subsystem which uses it. In this case, all LDAP ports (389 for LDAP and 636 for LDAPS, by default) need to be open in the firewall to allow traffic to the directory service. Without access to the LDAP database, all subsystem operations can fail.

As part of configuring the firewalls, if iptables is enabled, then it must have configured policies to allow communication over the appropriate Certificate System ports. Configuring iptables is described in the Using and configuring firewalld guide.

Because of the sensitive data they hold, consider keeping the CA, KRA, and TKS in a secure facility with adequate physical access restrictions. Just as network access to the systems needs to be restricted, the physical access also needs to be restricted.

Along with finding a secure location, consider the proximity to the subsystem agents and administrators. Key recovery, for example, can require multiple agents to give approval; if these agents are spread out over a large geographical area, then the time differences may negatively impact the ability to retrieve keys. Plan the physical locations of the subsystems, then according to the locations of the agents and administrators who will manage the subsystem.

Each Certificate System server uses up to four ports:

All of the service pages and interfaces described in Chapter 2 User Interfaces in the Administration Guide (Common Criteria Edition) are connected to using the instance’s URL and the corresponding port number. For example:

https://server.example.com:8443/ca/ee/ca

To access the admin console, the URL specifies the admin port:

# pkiconsole -d nssdb -n 'optional client cert nickname' https://server.example.com:8443/ca

All agent and admin functions require SSL/TLS mutual authentication. For requests from end entities, the Certificate System listens on both the SSL/TLS (encrypted) port and non-SSL/TLS ports.

The ports are defined in the server.xml file. If a port is not used, it can be disabled in that file. For example:

<Service name="Catalina">
    <!--Connector port="8080" ... /-->  unused standard port
    <Connector port="8443" ... />

Whenever a new instance in installed, make sure that the new ports are unique on the host system.

To verify that a port is available for use, check the appropriate file for the operating system. Port numbers for network-accessible services are usually maintained in a file named services. On Red Hat Enterprise Linux, it is also helpful to confirm that a port is not assigned by SELinux, by running the command semanage port -l to list all ports which currently have an SELinux context.

When a new subsystem instance is created, any number between 1 and 65535 can be specified as the secure port number.

To use a Hardware Security Module (HSM), a Federal Information Processing Standard (FIPS) 140-2 validated HSM is required. Certain deployments require to setup their HSM to use FIPS mode. To enable FIPS Mode on HSMs, please refer to your HSM vendor’s documentation.

The below steps help you verify if FIPS mode is enabled for nShield Connect XC and Luna HSMs. For other HSMs, please refer to your HSM manufacturer’s documentation.

# /opt/nfast/bin/nfkminfo

With older versions of the software, if the StrictFIPS140 is listed in the state flag, the FIPS mode is enabled. In newer versions, it is however better to check the new mode line and look for fips1402level3. In all cases, there should also be an hkfips key present in the nfkminfo output.

Certain HSMs require that you manually update SELinux settings before you can install Certificate System. The following describes nShield and Luna HSMs. For other HSMs, please refer to your HSM manufacturer’s documentation.

For details about supported HSMs and their limits, see Section 4.4, “Supported Hardware Security Modules”.

In Chapter 7, Installing and configuring Red Hat Certificate System, you are instructed to use the following parameters in the configuration file you pass to the pkispawn utility when installing Certificate System with an HSM:

...
[DEFAULT]
##########################
# Provide HSM parameters #
##########################
pki_hsm_enable=True
pki_hsm_libfile=hsm_libfile
pki_hsm_modulename=hsm_modulename
pki_token_name=hsm_token_name
pki_token_password=pki_token_password

########################################
# Provide PKI-specific HSM token names #
########################################
pki_audit_signing_token=hsm_token_name
pki_ssl_server_token=hsm_token_name
pki_subsystem_token=hsm_token_name
...

The following section provides settings for individual HSMs. If your HSM is not listed, consult your HSM manufacturer’s documentation.

pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast

Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.

# /opt/nfast/bin/nfkminfo

Module #1 Slot #0 IC 1
 generation    1
 phystype      SmartCard
 slotlistflags 0x2 SupportsAuthentication
 state         0x5 Operator
 flags         0x10000
 shareno       1 (`CONNXC-1')
 shares        LTU(PIN) LTFIPS
 error         OK
Cardset
 name          "NHSM-CONN-XC"
 k-out-of-n    1/2
 flags         Persistent PINRecoveryForbidden(disabled) !RemoteEnabled
 timeout       none
 card names    "CONNXC-1" "CONNXC-2"
 hkltu         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 gentime       2021-11-17 21:19:47

Module #1 Slot #1 IC 0
 generation    1
 phystype      SoftToken
 slotlistflags 0x0
 state         0x2 Empty
 flags         0x0
 shareno       0
 shares
 error         OK
No Cardset

No Pre-Loaded Objects

Set the token name as follows:

pki_token_name=NHSM-CONN-XC

pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
pki_hsm_modulename=thalesluna

Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.

# /usr/safenet/lunaclient/bin/vtl verify

The following Luna Slots/Partitions were found:

Slot    Serial #            Label
===    ===============    =====
   0       1209461834772     thaleslunaQE

Set the token name as follows:

pki_token_name=thaleslunaQE

To test the HSM connection:

When installing Red Hat Certificate System, the pkiuser account and the corresponding pkiuser group are automatically created. Certificate System uses this account and group to start services.

This section describes the creation of users and groups on the OS that hosts the RHCS system; rhcs10.example.com in this example.

pkiadmin is a group at the OS level which allows users under this group to have access to PKI files. This group should contain the following users:

Other PKI roles such as Agents and Auditors do not have direct access to the PKI/CS files on the OS file systems, so they are only recognized and authenticated through a PKI/CS instance.

For the purpose of this example, three OS users will be created to serve the three distinct PKI roles: