Planning, Installation, and Deployment Guide
Updated for Red Hat Certificate System 10.4
Abstract
Part I. Planning How to Deploy Red Hat Certificate System
Chapter 1. Introduction to Public-Key Cryptography
- Eavesdropping
- Information remains intact, but its privacy is compromised. For example, someone could gather credit card numbers, record a sensitive conversation, or intercept classified information.
- Tampering
- Information in transit is changed or replaced and then sent to the recipient. For example, someone could alter an order for goods or change a person's resume.
- Impersonation
- Information passes to a person who poses as the intended recipient. Impersonation can take two forms:
- Spoofing. A person can pretend to be someone else. For example, a person can pretend to have the email address
jdoe@example.net
or a computer can falsely identify itself as a site calledwww.example.net
. - Misrepresentation. A person or organization can misrepresent itself. For example, a site called
www.example.net
can purport to be an on-line furniture store when it really receives credit-card payments but never sends any goods.
- Encryption and decryption
- Encryption and decryption allow two communicating parties to disguise information they send to each other. The sender encrypts, or scrambles, information before sending it. The receiver decrypts, or unscrambles, the information after receiving it. While in transit, the encrypted information is unintelligible to an intruder.
- Tamper detection
- Tamper detection allows the recipient of information to verify that it has not been modified in transit. Any attempts to modify or substitute data are detected.
- Authentication
- Authentication allows the recipient of information to determine its origin by confirming the sender's identity.
- Nonrepudiation
- Nonrepudiation prevents the sender of information from claiming at a later date that the information was never sent.
1.1. Encryption and Decryption
1.1.1. Symmetric-Key Encryption
Figure 1.1. Symmetric-Key Encryption
1.1.2. Public-Key Encryption
Figure 1.2. Public-Key Encryption
1.1.3. Key Length and Encryption Strength
1.2. Digital Signatures
- The value of the hash is unique for the hashed data. Any change in the data, even deleting or altering a single character, results in a different value.
- The content of the hashed data cannot be deduced from the hash.
Figure 1.3. Using a Digital Signature to Validate Data Integrity
1.3. Certificates and Authentication
1.3.1. A Certificate Identifies Someone or Something
1.3.2. Authentication Confirms an Identity
- Password-based authentication
- Certificate-based authentication
1.3.2.1. Password-Based Authentication
- The user has already trusted the server, either without authentication or on the basis of server authentication over SSL/TLS.
- The user has requested a resource controlled by the server.
- The server requires client authentication before permitting access to the requested resource.
Figure 1.4. Using a Password to Authenticate a Client to a Server
- When the server requests authentication from the client, the client displays a dialog box requesting the user name and password for that server.
- The client sends the name and password across the network, either in plain text or over an encrypted SSL/TLS connection.
- The server looks up the name and password in its local password database and, if they match, accepts them as evidence authenticating the user's identity.
- The server determines whether the identified user is permitted to access the requested resource and, if so, allows the client to access it.
1.3.2.2. Certificate-Based Authentication
Figure 1.5. Using a Certificate to Authenticate a Client to a Server
Note
- The client software maintains a database of the private keys that correspond to the public keys published in any certificates issued for that client. The client asks for the password to this database the first time the client needs to access it during a given session, such as the first time the user attempts to access an SSL/TLS-enabled server that requires certificate-based client authentication.After entering this password once, the user does not need to enter it again for the rest of the session, even when accessing other SSL/TLS-enabled servers.
- The client unlocks the private-key database, retrieves the private key for the user's certificate, and uses that private key to sign data randomly-generated from input from both the client and the server. This data and the digital signature are evidence of the private key's validity. The digital signature can be created only with that private key and can be validated with the corresponding public key against the signed data, which is unique to the SSL/TLS session.
- The client sends both the user's certificate and the randomly-generated data across the network.
- The server uses the certificate and the signed data to authenticate the user's identity.
- The server may perform other authentication tasks, such as checking that the certificate presented by the client is stored in the user's entry in an LDAP directory. The server then evaluates whether the identified user is permitted to access the requested resource. This evaluation process can employ a variety of standard authorization mechanisms, potentially using additional information in an LDAP directory or company databases. If the result of the evaluation is positive, the server allows the client to access the requested resource.
1.3.3. Uses for Certificates
1.3.3.1. SSL/TLS
1.3.3.2. Signed and Encrypted Email
1.3.3.3. Single Sign-on
1.3.3.4. Object Signing
1.3.4. Types of Certificates
https
://server.example.com:8443/ca/ee/ca
.
Certificate Type | Use | Example |
---|---|---|
Client SSL/TLS certificates | Used for client authentication to servers over SSL/TLS. Typically, the identity of the client is assumed to be the same as the identity of a person, such as an employee. See Section 1.3.2.2, “Certificate-Based Authentication” for a description of the way SSL/TLS client certificates are used for client authentication. Client SSL/TLS certificates can also be used as part of single sign-on. |
A bank gives a customer an SSL/TLS client certificate that allows the bank's servers to identify that customer and authorize access to the customer's accounts.
A company gives a new employee an SSL/TLS client certificate that allows the company's servers to identify that employee and authorize access to the company's servers.
|
Server SSL/TLS certificates | Used for server authentication to clients over SSL/TLS. Server authentication may be used without client authentication. Server authentication is required for an encrypted SSL/TLS session. For more information, see Section 1.3.3.1, “SSL/TLS”. | Internet sites that engage in electronic commerce usually support certificate-based server authentication to establish an encrypted SSL/TLS session and to assure customers that they are dealing with the web site identified with the company. The encrypted SSL/TLS session ensures that personal information sent over the network, such as credit card numbers, cannot easily be intercepted. |
S/MIME certificates | Used for signed and encrypted email. As with SSL/TLS client certificates, the identity of the client is assumed to be the same as the identity of a person, such as an employee. A single certificate may be used as both an S/MIME certificate and an SSL/TLS certificate; see Section 1.3.3.2, “Signed and Encrypted Email”. S/MIME certificates can also be used as part of single sign-on. | A company deploys combined S/MIME and SSL/TLS certificates solely to authenticate employee identities, thus permitting signed email and SSL/TLS client authentication but not encrypted email. Another company issues S/MIME certificates solely to sign and encrypt email that deals with sensitive financial or legal matters. |
CA certificates | Used to identify CAs. Client and server software use CA certificates to determine what other certificates can be trusted. For more information, see Section 1.3.6, “How CA Certificates Establish Trust”. | The CA certificates stored in Mozilla Firefox determine what other certificates can be authenticated. An administrator can implement corporate security policies by controlling the CA certificates stored in each user's copy of Firefox. |
Object-signing certificates | Used to identify signers of Java code, JavaScript scripts, or other signed files. | Software companies frequently sign software distributed over the Internet to provide users with some assurance that the software is a legitimate product of that company. Using certificates and digital signatures can also make it possible for users to identify and control the kind of access downloaded software has to their computers. |
1.3.4.1. CA Signing Certificates
Note
1.3.4.2. Other Signing Certificates
Note
1.3.4.3. SSL/TLS Server and Client Certificates
Note
1.3.4.4. User Certificates
1.3.4.5. Dual-Key Pairs
1.3.4.6. Cross-Pair Certificates
crossCertificatePair
entry.
1.3.5. Contents of a Certificate
1.3.5.1. Certificate Data Formats
1.3.5.1.1. Binary
- DER-encoded certificate. This is a single binary DER-encoded certificate.
- PKCS #7 certificate chain. This is a PKCS #7
SignedData
object. The only significant field in theSignedData
object is the certificates; the signature and the contents, for example, are ignored. The PKCS #7 format allows multiple certificates to be downloaded at a single time. - Netscape Certificate Sequence. This is a simpler format for downloading certificate chains in a PKCS #7
ContentInfo
structure, wrapping a sequence of certificates. The value of thecontentType
field should benetscape-cert-sequence
, while the content field has the following structure:CertificateSequence ::= SEQUENCE OF Certificate
This format allows multiple certificates to be downloaded at the same time.
1.3.5.1.2. Text
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
1.3.5.2. Distinguished Names
uid=doe
, that uniquely identify an entity. This is also called the certificate subject name.
uid=doe, cn=John Doe,o=Example Corp.,c=US
uid
is the user name, cn
is the user's common name, o
is the organization or company name, and c
is the country.
1.3.5.3. A Typical Certificate
- The data section
- This section includes the following information:
- The version number of the X.509 standard supported by the certificate.
- The certificate's serial number. Every certificate issued by a CA has a serial number that is unique among the certificates issued by that CA.
- Information about the user's public key, including the algorithm used and a representation of the key itself.
- The DN of the CA that issued the certificate.
- The period during which the certificate is valid; for example, between 1:00 p.m. on November 15, 2004, and 1:00 p.m. November 15, 2022.
- The DN of the certificate subject, which is also called the subject name; for example, in an SSL/TLS client certificate, this is the user's DN.
- Optional certificate extensions, which may provide additional data used by the client or server. For example:
- the Netscape Certificate Type extension indicates the type of certificate, such as an SSL/TLS client certificate, an SSL/TLS server certificate, or a certificate for signing email
- the Subject Alternative Name (SAN) extension links a certificate to one or more host names
Certificate extensions can also be used for other purposes.
- The signature section
- This section includes the following information:
- The cryptographic algorithm, or cipher, used by the issuing CA to create its own digital signature.
- The CA's digital signature, obtained by hashing all of the data in the certificate together and encrypting it with the CA's private key.
Certificate: Data: Version: v3 (0x2) Serial Number: 3 (0x3) Signature Algorithm: PKCS #1 MD5 With RSA Encryption Issuer: OU=Example Certificate Authority, O=Example Corp, C=US Validity: Not Before: Fri Oct 17 18:36:25 1997 Not After: Sun Oct 17 18:36:25 1999 Subject: CN=Jane Doe, OU=Finance, O=Example Corp, C=US Subject Public Key Info: Algorithm: PKCS #1 RSA Encryption Public Key: Modulus: 00:ca:fa:79:98:8f:19:f8:d7:de:e4:49:80:48:e6:2a:2a:86: ed:27:40:4d:86:b3:05:c0:01:bb:50:15:c9:de:dc:85:19:22: 43:7d:45:6d:71:4e:17:3d:f0:36:4b:5b:7f:a8:51:a3:a1:00: 98:ce:7f:47:50:2c:93:36:7c:01:6e:cb:89:06:41:72:b5:e9: 73:49:38:76:ef:b6:8f:ac:49:bb:63:0f:9b:ff:16:2a:e3:0e: 9d:3b:af:ce:9a:3e:48:65:de:96:61:d5:0a:11:2a:a2:80:b0: 7d:d8:99:cb:0c:99:34:c9:ab:25:06:a8:31:ad:8c:4b:aa:54: 91:f4:15 Public Exponent: 65537 (0x10001) Extensions: Identifier: Certificate Type Critical: no Certified Usage: TLS Client Identifier: Authority Key Identifier Critical: no Key Identifier: f2:f2:06:59:90:18:47:51:f5:89:33:5a:31:7a:e6:5c:fb:36: 26:c9 Signature: Algorithm: PKCS #1 MD5 With RSA Encryption Signature: 6d:23:af:f3:d3:b6:7a:df:90:df:cd:7e:18:6c:01:69:8e:54:65:fc:06: 30:43:34:d1:63:1f:06:7d:c3:40:a8:2a:82:c1:a4:83:2a:fb:2e:8f:fb: f0:6d:ff:75:a3:78:f7:52:47:46:62:97:1d:d9:c6:11:0a:02:a2:e0:cc: 2a:75:6c:8b:b6:9b:87:00:7d:7c:84:76:79:ba:f8:b4:d2:62:58:c3:c5: b6:c1:43:ac:63:44:42:fd:af:c8:0f:2f:38:85:6d:d6:59:e8:41:42:a5: 4a:e5:26:38:ff:32:78:a1:38:f1:ed:dc:0d:31:d1:b0:6d:67:e9:46:a8: d:c4
-----BEGIN CERTIFICATE----- MIICKzCCAZSgAwIBAgIBAzANBgkqhkiG9w0BAQQFADA3MQswCQYDVQQGEwJVUzER MA8GA1UEChMITmV0c2NhcGUxFTATBgNVBAsTDFN1cHJpeWEncyBDQTAeFw05NzEw MTgwMTM2MjVaFw05OTEwMTgwMTM2MjVaMEgxCzAJBgNVBAYTAlVTMREwDwYDVQQK EwhOZXRzY2FwZTENMAsGA1UECxMEUHViczEXMBUGA1UEAxMOU3Vwcml5YSBTaGV0 dHkwgZ8wDQYJKoZIhvcNAQEFBQADgY0AMIGJAoGBAMr6eZiPGfjX3uRJgEjmKiqG 7SdATYazBcABu1AVyd7chRkiQ31FbXFOGD3wNktbf6hRo6EAmM5/R1AskzZ8AW7L iQZBcrXpc0k4du+2Q6xJu2MPm/8WKuMOnTuvzpo+SGXelmHVChEqooCwfdiZywyZ NMmrJgaoMa2MS6pUkfQVAgMBAAGjNjA0MBEGCWCGSAGG+EIBAQQEAwIAgDAfBgNV HSMEGDAWgBTy8gZZkBhHUfWJM1oxeuZc+zYmyTANBgkqhkiG9w0BAQQFAAOBgQBt I6/z07Z635DfzX4XbAFpjlRl/AYwQzTSYx8GfcNAqCqCwaSDKvsuj/vwbf91o3j3 UkdGYpcd2cYRCgKi4MwqdWyLtpuHAH18hHZ5uvi00mJYw8W2wUOsY0RC/a/IDy84 hW3WWehBUqVK5SY4/zJ4oTjx7dwNMdGwbWfpRqjd1A== -----END CERTIFICATE-----
1.3.6. How CA Certificates Establish Trust
1.3.6.1. CA Hierarchies
Figure 1.6. Example of a Hierarchy of Certificate Authorities
1.3.6.2. Certificate Chains
Figure 1.7. Example of a Certificate Chain
- Each certificate is followed by the certificate of its issuer.
- Each certificate contains the name (DN) of that certificate's issuer, which is the same as the subject name of the next certificate in the chain.In Figure 1.7, “Example of a Certificate Chain”, the
Engineering CA
certificate contains the DN of the CA,USA CA
, that issued that certificate.USA CA
's DN is also the subject name of the next certificate in the chain. - Each certificate is signed with the private key of its issuer. The signature can be verified with the public key in the issuer's certificate, which is the next certificate in the chain.In Figure 1.7, “Example of a Certificate Chain”, the public key in the certificate for the
USA CA
can be used to verify theUSA CA
's digital signature on the certificate for theEngineering CA
.
1.3.6.3. Verifying a Certificate Chain
- The certificate validity period is checked against the current time provided by the verifier's system clock.
- The issuer's certificate is located. The source can be either the verifier's local certificate database on that client or server or the certificate chain provided by the subject, as with an SSL/TLS connection.
- The certificate signature is verified using the public key in the issuer's certificate.
- The host name of the service is compared against the Subject Alternative Name (SAN) extension. If the certificate has no such extension, the host name is compared against the subject's CN.
- The system verifies the Basic Constraint requirements for the certificate, that is, whether the certificate is a CA and how many subsidiaries it is allowed to sign.
- If the issuer's certificate is trusted by the verifier in the verifier's certificate database, verification stops successfully here. Otherwise, the issuer's certificate is checked to make sure it contains the appropriate subordinate CA indication in the certificate type extension, and chain verification starts over with this new certificate. Figure 1.8, “Verifying a Certificate Chain to the Root CA” presents an example of this process.
Figure 1.8. Verifying a Certificate Chain to the Root CA
Engineering CA
, is found in the verifier's local database, verification stops with that certificate, as shown in Figure 1.9, “Verifying a Certificate Chain to an Intermediate CA”.
Figure 1.9. Verifying a Certificate Chain to an Intermediate CA
Figure 1.10. A Certificate Chain That Cannot Be Verified
1.3.7. Certificate Status
1.4. Certificate Life Cycle
1.4.1. Certificate Issuance
1.4.2. Certificate Expiration and Renewal
- Verify if the certificate is present in the directory
- Servers can be configured so that the authentication process checks the directory for the presence of the certificate being presented. When an administrator revokes a certificate, the certificate can be automatically removed from the directory, and subsequent authentication attempts with that certificate will fail, even though the certificate remains valid in every other respect.
- Certificate revocation list (CRL)
- A list of revoked certificates, a CRL, can be published to the directory at regular intervals. The CRL can be checked as part of the authentication process.
- Real-time status checking
- The issuing CA can also be checked directly each time a certificate is presented for authentication. This procedure is sometimes called real-time status checking.
- Online Certificate Status Protocol
- The Online Certificate Status Protocol (OCSP) service can be configured to determine the status of certificates.
1.5. Key Management
Chapter 2. Introduction to Red Hat Certificate System
2.1. A Review of Certificate System Subsystems
- A certificate authority called Certificate Manager. The CA is the core of the PKI; it issues and revokes all certificates. The Certificate Manager is also the core of the Certificate System. By establishing a security domain of trusted subsystems, it establishes and manages relationships between the other subsystems.
- A key recovery authority (KRA). Certificates are created based on a specific and unique key pair. If a private key is ever lost, then the data which that key was used to access (such as encrypted emails) is also lost because it is inaccessible. The KRA stores key pairs, so that a new, identical certificate can be generated based on recovered keys, and all of the encrypted data can be accessed even after a private key is lost or damaged.
Note
In previous versions of Certificate System, KRA was also referred to as the data recovery manager (DRM). Some code, configuration file entries, web panels, and other resources might still use the term DRM instead of KRA. - An online certificate status protocol (OCSP) responder. The OCSP verifies whether a certificate is valid and not expired. This function can also be done by the CA, which has an internal OCSP service, but using an external OCSP responder lowers the load of the issuing CA.
- A token key service (TKS). The TKS derives keys based on the token CCID, private information, and a defined algorithm. These derived keys are used by the TPS to format tokens and enroll certificates on the token.
- A token processing system (TPS). The TPS interacts directly with external tokens, like smart cards, and manages the keys and certificates on those tokens through a local client, the Enterprise Security Client (ESC). The ESC contacts the TPS when there is a token operation, and the TPS interacts with the CA, KRA, or TKS, as required, then send the information back to the token by way of the Enterprise Security Client.
- A token management system or TMS environment, which manages smart cards. This requires a CA, TKS, and TPS, with an optional KRA for server-side key generation.
- A traditional non token management system or non-TMS environment, which manages certificates used in an environment other than smart cards, usually in software databases. At a minimum, a non-TMS requires only a CA, but a non-TMS environment can use OCSP responders and KRA instances as well.
2.2. Overview of Certificate System Subsystems
2.2.2. Instance Installation Prerequisites
2.2.2.1. Directory Server Instance Availability
2.2.2.2. PKI Packages
- The following base packages form the core of Certificate System, and are available in base Red Hat Enterprise Linux repositories:
- pki-core
- 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.8, “Attaching a Red Hat Subscription and Enabling the Certificate System Package Repository”.
- 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
#
dnf install redhat-pki
Note
2.2.2.3. Instance Installation and Configuration
pkispawn
command line tool is used to install and configure a new PKI instance. It eliminates the need for separate installation and configuration steps, and 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.
pkispawn --help
command.
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
pkispawn
man page for additional information.
/etc/pki/default.cfg
, is a plain text file containing the default installation and configuration values which are read at the beginning of the process described above. It consists of name=value
pairs divided into [DEFAULT]
, [Tomcat]
, [CA]
, [KRA]
, [OCSP]
, [TKS]
, and [TPS]
sections.
-s
option with pkispawn
and specify a subsystem name, then only the section for that subsystem will be read.
name=value
pair specified in a subsystem section will override the pair in the [Tomcat]
section, which in turn override the pair in the [DEFAULT]
section. Default pairs can further be overriden by interactive input, or by pairs in a specified PKI instance configuration file.
Note
name=value
pairs, they may be stored in any location and specified at any time. These files are referred to as myconfig.txt
in the pkispawn
man pages, but they are also often referred to as .ini
files, or more generally as PKI instance configuration override files.
pki_default.cfg
man page for more information.
/usr/share/java/pki/pki-certsrv.jar
as com/netscape/certsrv/system/ConfigurationRequest.class
. The servlet processes data passed in as a JSON object from the configuration scriptlet using pkispawn
, and then returns to pkispawn
using Java bytecode served in the same file as com/netscape/certsrv/system/ConfigurationResponse.class
.
pkispawn
command on a command line as root
:
#
pkispawn
Important
#
mkdir -p /root/pki
- Use a text editor such as vim to create a configuration file named
/root/pki/ca.cfg
with the following contents:[DEFAULT] pki_admin_password=<password> pki_client_pkcs12_password=<password> pki_ds_password=<password>
#
pkispawn -s CA -f /root/pki/ca.cfg
pkispawn
man page for various configuration examples.
2.2.2.4. Instance Removal
pkidestroy
command. It can be run interactively or as a batch process. Use pkidestroy -h
to display detailed usage inforamtion on the command line.
pkidestroy
command reads in a PKI subsystem deployment configuration file which was stored when the subsystem was created (/var/lib/pki/instance_name/<subsystem>/registry/<subsystem>/deployment.cfg
), uses the read-in file in order to remove the PKI subsystem, and then removes the PKI instance if it contains no additional subsystems. See the pkidestroy
man page for more information.
pkidestroy
may look similar to the following:
#
pkidestroy
Subsystem (CA/KRA/OCSP/TKS/TPS) [CA]: Instance [pki-tomcat]: Begin uninstallation (Yes/No/Quit)? Yes Log file: /var/log/pki/pki-ca-destroy.20150928183547.log Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg. Uninstalling CA from /var/lib/pki/pki-tomcat. rm '/etc/systemd/system/multi-user.target.wants/pki-tomcatd.target' Uninstallation complete.
#
pkidestroy -s CA -i pki-tomcat
Log file: /var/log/pki/pki-ca-destroy.20150928183159.log Loading deployment configuration from /var/lib/pki/pki-tomcat/ca/registry/ca/deployment.cfg. Uninstalling CA from /var/lib/pki/pki-tomcat. rm '/etc/systemd/system/multi-user.target.wants/pki-tomcatd.target' Uninstallation complete.
2.2.3. Execution Management (systemctl)
2.2.3.1. Starting, Stopping, Restarting, and Obtaining Status
systemctl
execution management system tool on Red Hat Enterprise Linux 8:
#
systemctl start <unit-file>@instance_name.service
#
systemctl status <unit-file>@instance_name.service
#
systemctl stop <unit-file>@instance_name.service
#
systemctl restart <unit-file>@instance_name.service
pki-tomcatd
Withwatchdog
disabledpki-tomcatd-nuxwdog
Withwatchdog
enabled
watchdog
service, refer to the Section 2.3.10, “Passwords and Watchdog (nuxwdog)” and Section 14.3.2, “Using the Certificate System Watchdog Service”.
Note
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
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.
systemctl
, so this utility can set whether to restart instances automatically. After a Certificate System instance is created, it is enabled on boot. This can be changed by using systemctl
:
#
systemctl disable pki-tomcatd@instance_name.service
#
systemctl enable pki-tomcatd@instance_name.service
Note
systemctl enable
and systemctl disable
commands do not immediately start or stop Certificate System.
2.2.4. Process Management (pki-server and pkidaemon)
2.2.4.1. The pki-server Command Line Tool
pki-server
. Use the pki-server --help
command and see the pki-server
man page for usage information.
pki-server
command-line interface (CLI) manages local server instances (for example server configuration or system certificates). Invoke the CLI as follows:
$
pki-server [CLI options] <command> [command parameters]
$
pki-server
$
pki-server ca
$
pki-server ca-audit
--help
option:
$
pki-server
--help
$
pki-server ca-audit-event-find
--help
2.2.4.2. Enabling and Disabling an Installed Subsystem Using pki-server
pki-server
utility.
#
pki-server subsystem-disable -i instance_id subsystem_id
#
pki-server subsystem-enable -i instance_id subsystem_id
ca
, kra
, tks
, ocsp
, or tps
.
Note
pki-tomcat
:
#
pki-server subsystem-disable -i pki-tomcat ocsp
#
pki-server subsystem-find -i instance_id
#
pki-server subsystem-find -i instance_id subsystem_id
2.2.4.3. The pkidaemon Command Line Tool
pkidaemon
tool:
pkidaemon {start|status} instance-type [instance_name]
pkidaemon status tomcat
- Provides status information such as on/off, ports, URLs of each PKI subsystem of all PKI instances on the system.pkidaemon status tomcat instance_name
- Provides status information such as on/off, ports, URLs of each PKI subsystem of a specific instance.pkidaemon start tomcat instance_name.service
- Used internally usingsystemctl
.
pkidaemon
man page for additional information.
2.2.4.4. Finding the Subsystem Web Services URLs
https://server.example.com:8443/ca/services
Note
pkidaemon status instance_name
https://server.example.com:8443/ca/ee/ca
https://192.0.2.1:8443/ca/services https://[2001:DB8::1111]:8443/ca/services
Note
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[b] | kra/ee/kra | |
8443 | Yes | No | End Entities[b] | kra/ee/kra |
8443 | Yes | Yes | Agents | kra/agent/kra |
8443 | Yes | No | Services | kra/services |
8443 | Yes | No | Console | pkiconsole https://host:port/kra |
Online Certificate Status Manager | ||||
8080 | No | End Entities[c] | ocsp/ee/ocsp | |
8443 | Yes | No | End Entities[c] | ocsp/ee/ocsp |
8443 | Yes | Yes | Agents | ocsp/agent/ocsp |
8443 | Yes | No | Services | ocsp/services |
8443 | Yes | No | Console | pkiconsole https://host:port/ocsp |
Token Key Service | ||||
8080 | No | End Entities[b] | tks/ee/tks | |
8443 | Yes | No | End Entities[b] | tks/ee/tks |
8443 | Yes | Yes | Agents | tks/agent/tks |
8443 | Yes | No | Services | tks/services |
8443 | Yes | No | Console | pkiconsole https://host:port/tks |
Token Processing System | ||||
8080 | No | Unsecure Services | tps/tps | |
8443 | Yes | Secure Services | tps/tps | |
8080 | No | Enterprise Security Client Phone Home | tps/phoneHome | |
8443 | Yes | Enterprise Security Client Phone Home | tps/phoneHome | |
8443 | Yes | Yes | Admin, Agent, and Operator Services [d] | tps/ui |
[a]
Services with a client authentication value of No can be reconfigured to require client authentication. Services which do not have either a Yes or No value cannot be configured to use client authentication.
[b]
Although this subsystem type does have end entities ports and interfaces, these end-entity services are not accessible through a web browser, as other end-entity services are.
[c]
Although the OCSP does have end entities ports and interfaces, these end-entity services are not accessible through a web browser, as other end-entity services are. End user OCSP services are accessed by a client sending an OCSP request.
[d]
The agent, admin, and operator services are all accessed through the same web services page. Each role can only access specific sections which are only visible to the members of that role.
|
2.2.4.5. Starting the Certificate System Console
Important
pkiconsole
utility. This utility uses the format:
pkiconsole https://server.example.com:admin_port/subsystem_type
ca
, kra
, ocsp
, or tks
. For example, this opens the KRA console:
pkiconsole https://server.example.com:8443/kra
https://192.0.2.1:8443/ca https://[2001:DB8::1111]:8443/ca
2.3. Certificate System Architecture Overview
2.3.1. Java Application Server
server.xml
. The following link provides more information about Tomcat configuration: https://tomcat.apache.org/tomcat-8.0-doc/config/.
web.xml
file, which is defined in Java Servlet 3.1 specification. See https://www.jcp.org/en/jsr/detail?id=340 for details.
CS.cfg
.
2.3.2. Java Security Manager
pki_security_manager=false
option under its own Tomcat section.
# pki-server stop instance_name
or (if using thenuxwdog
watchdog)# systemctl stop pki-tomcatd-nuxwdog@instance_name.service
- Open the
/etc/sysconfig/instance_name
file, and setSECURITY_MANAGER="false"
# pki-server start instance_name
or (if using thenuxwdog
watchdog)# systemctl start pki-tomcatd-nuxwdog@instance_name.service
pkidaemon
from the following files:
/usr/share/pki/server/conf/catalina.policy /usr/share/tomcat/conf/catalina.policy /var/lib/pki/$PKI_INSTANCE_NAME/conf/pki.policy /var/lib/pki/$PKI_INSTANCE_NAME/conf/custom.policy
/var/lib/pki/instance_name/conf/catalina.policy
.
2.3.3. Interfaces
2.3.3.1. Servlet Interface
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
2.3.3.3. End-Entity Interface
2.3.3.4. Operator Interface
2.3.4. REST Interface
web.xml
of the corresponding subsystem. More information about RESTEasy can be found at http://resteasy.jboss.org/.
- CA certificate service:
http://<host_name>:<port>/ca/rest/certs/
- KRA key service:
http://<host_name>:<port>/kra/rest/agent/keys/
- TKS user service:
http://<host_name>:<port>/tks/rest/admin/users/
- TPS group service:
http://<host_name>:<port>/tps/rest/admin/groups/
{ "id":"admin", "UserID":"admin", "FullName":"Administrator", "Email":"admin@example.com", ... }
- user name and password
- client certificate
/usr/share/pki/ca/conf/auth-method.properties
.
/usr/share/pki/<subsystem>/conf/acl.properties
.
2.3.5. JSS
2.3.6. Tomcatjss
tomcatjss
as a bridge between the Tomcat Server HTTP engine and JSS, the Java interface for security operations performed by NSS. Tomcatjss is a Java Secure Socket Extension (JSSE) implementation using Java Security Services (JSS) for Tomcat.
- The server is started.
- Tomcat gets to the point where it needs to create the listening sockets for the Certificate System installation.
- The
server.xml
file is processed. Configuration in this file tells the system to use a socket factory implemented by Tomcatjss. - For each requested socket, Tomcajss reads and processes the included attributes when it creates the socket. The resulting socket will behave as it has been asked to by those parameters.
- Once the server is running, we have the required set of listening sockets waiting for incoming connections to the Tomcat-based Certificate System.
server.xml
file, see Section 14.4, “Configuration Files for the Tomcat Engine and Web Services”.
2.3.7. PKCS #11
2.3.7.1. NSS Soft Token (internal token)
Note
/var/lib/pki/instance_name/alias
directory.
- The default internal PKCS #11 module, which comes with two tokens:
- The internal crypto services token, which performs all cryptographic operations such as encryption, decryption, and hashing.
- The internal key storage token ("Certificate DB token"), which handles all communication with the certificate and key database files that store certificates and keys.
- The FIPS 140 module. This module complies with the FIPS 140 government standard for cryptographic module implementations. The FIPS 140 module includes a single, built-in FIPS 140 certificate database token, which handles both cryptographic operations and communication with the certificate and key database files.
2.3.7.2. Hardware Security Module (HSM, external token)
Note
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.
2.3.8. Certificate System Serial Number Management
2.3.8.1. Serial Number Ranges
- Current serial number management is based on assigning ranges of sequential serial numbers.
- Instances request new ranges when crossing below a defined threshold.
- Instances store information about a newly acquired range once it is assigned to the instance.
- Instances continue using old ranges until all numbers are exhausted from it, and then it moves to the new range.
- Cloned subsystems synchronize their range assignment through replication conflicts.
- Part of the current range of the master is transferred to a new clone in the process of cloning.
- New clones may request a new range if the transferred range is below the defined threshold.
[CA]
section to the PKI instance override configuration file, and adding the following name=value
pairs under that section as needed. Default values which already exist in /etc/pki/default.cfg
are shown in the following example:
[CA] pki_serial_number_range_start=1 pki_serial_number_range_end=10000000 pki_request_number_range_start=1 pki_request_number_range_end=10000000 pki_replica_number_range_start=1 pki_replica_number_range_end=100
2.3.8.2. Random Serial Number Management
[CA]
section to the PKI instance override file and adding the following name=value
pair under that section:
[CA] pki_random_serial_numbers_enable=True
2.3.9. Security Domain
2.3.10. Passwords and Watchdog (nuxwdog)
<instance_dir>/conf/password.conf
. At the same time, an identifying string is stored in the main configuration file CS.cfg
as part of the parameter cms.passwordlist
.
CS.cfg
, is protected by Red Hat Enterprise Linux, and only accessible by the PKI administrators. No passwords are stored in CS.cfg
.
password.conf
.
password.conf
. LDAP publishing is one example where the newly configured Directory Manager password for the publishing directory is entered into password.conf
.
Note
password.conf
file altogether. On restart, the nuxwdog watchdog program will prompt the administrator for the required passwords, using the parameter cms.passwordlist
(and cms.tokenList
if an HSM is used) as a list of passwords for which to prompt. The passwords are then cached by nuxwdog in the kernel keyring to allow automated recovery from a server crash. This automated recovery (automatic subsystem restart) happens in case of uncontrolled shutdown (crash). In case of a controlled shutdown by the administrator, administrators are prompted for passwords again.
2.3.11. Internal LDAP Database
pkispawn
options will also be needed for installing such Certificate System instance.
2.3.12. Security-Enhanced Linux (SELinux)
Figure 2.1. CA SELinux Port Policy
- Files and directories for each subsystem instance are labeled with a specific SELinux context.
- The ports for each subsystem instance are labeled with a specific SELinux context.
- All Certificate System processes are constrained within a subsystem-specific domain.
- Each domain has specific rules that define what actions that are authorized for the domain.
- Any access not specified in the SELinux policy is denied to the Certificate System instance.
pkispawn
is run to configure a Certificate System subsystem, files and ports associated with that subsystem are labeled with the required SELinux contexts. These contexts are removed when the particular subsystems are removed using pkidestroy
.
pki_tomcat_t
domain. Certificate System instances are Tomcat servers, and the pki_tomcat_t
domain extends the policies for a standard tomcat_t
Tomcat domain. All Certificate System instances on a server share the same domain.
unconfined_t
) and then transitions into the pki_tomcat_t
domain. This process then has certain access permissions, such as write access to log files labeled pki_tomcat_log_t
, read and write access to configuration files labeled pki_tomcat_etc_rw_t
, or the ability to open and write to http_port_t
ports.
2.3.13. Self-tests
#
pki-server subsystem-enable <subsystem>
2.3.14. Logs
pki_subsystem_log_path
when the instance was created with pkispawn
. Regular audit logs are located in the log directory with other types of logs, while signed audit logs are written to /var/log/pki/instance_name/subsystem_name/signedAudit
. The default location for logs can be changed by modifying the configuration.
2.3.14.1. Audit Log
Note
2.3.14.2. Debug Logs
[date:time] [processor]: servlet: message
[10/Jun/2022:05:14:51][main]: Established LDAP connection using basic authentication to host localhost port 389 as cn=Directory Manager
main
, and the message is the message from the server about the LDAP connection, and there is no servlet.
[06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443
Example 2.1. CA Certificate Request Log Messages
[06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.profileapprovedby$ value=admin [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.cert_request$ value=MIIBozCCAZ8wggEFAgQqTfoHMIHHgAECpQ4wDDEKMAgGA1UEAxMBeKaBnzANBgkqhkiG9w0BAQEFAAOB... [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.profile$ value=true [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.cert_request_type$ value=crmf [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestversion$ value=1.0.0 [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.req_locale$ value=en [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443 [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.dbstatus$ value=NOT_UPDATED [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.subject$ value=uid=jsmith, e=jsmith@example.com [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requeststatus$ value=begin [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.user$ value=uid=KRA-server.example.com-8443,ou=People,dc=example,dc=com [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.req_key$ value=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLP^M HcN0cusY7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChV^M k9HYDhmJ8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaM^M HTmlOqm4HwFxzy0RRQIDAQAB [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.authmgrinstname$ value=raCertAuth [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.uid$ value=KRA-server.example.com-8443 [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.userid$ value=KRA-server.example.com-8443 [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestor_name$ value= [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.profileid$ value=caUserCert [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.userdn$ value=uid=KRA-server.example.com-4747,ou=People,dc=example,dc=com [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.requestid$ value=20 [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.auth_token.authtime$ value=1212782378071 [06/Jun/2022:14:59:38][http-8443;-Processor24]: ProfileSubmitServlet: key=$request.req_x509info$ value=MIICIKADAgECAgEAMA0GCSqGSIb3DQEBBQUAMEAxHjAcBgNVBAoTFVJlZGJ1ZGNv^M bXB1dGVyIERvbWFpbjEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4X^M DTA4MDYwNjE5NTkzOFoXDTA4MTIwMzE5NTkzOFowOzEhMB8GCSqGSIb3DQEJARYS^M anNtaXRoQGV4YW1wbGUuY29tMRYwFAYKCZImiZPyLGQBARMGanNtaXRoMIGfMA0G^M CSqGSIb3DQEBAQUAA4GNADCBiQKBgQDreuEsBWq9WuZ2MaBwtNYxvkLPHcN0cusY^M 7gxLzB+XwQ/VsWEoObGldg6WwJPOcBdvLiKKfC605wFdynbEgKs0fChVk9HYDhmJ^M 8hX6+PaquiHJSVNhsv5tOshZkCfMBbyxwrKd8yZ5G5I+2gE9PUznxJaMHTmlOqm4^M HwFxzy0RRQIDAQABo4HFMIHCMB8GA1UdIwQYMBaAFG8gWeOJIMt+aO8VuQTMzPBU^M 78k8MEoGCCsGAQUFBwEBBD4wPDA6BggrBgEFBQcwAYYuaHR0cDovL3Rlc3Q0LnJl^M ZGJ1ZGNvbXB1dGVyLmxvY2FsOjkwODAvY2Evb2NzcDAOBgNVHQ8BAf8EBAMCBeAw^M HQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMCQGA1UdEQQdMBuBGSRyZXF1^M ZXN0LnJlcXVlc3Rvcl9lbWFpbCQ=
[07/Jul/2022:06:25:40][http-11180-Processor25]: OCSPServlet: OCSP Request: [07/Jul/2022:06:25:40][http-11180-Processor25]: OCSPServlet: MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU
2.3.14.3. Installation Logs
pkispawn
, an installation file with the complete debug output from the installation, including any errors and, if the installation is successful, the URL and PIN to the configuration interface for the instance. The file is created in the /var/log/pki/
directory for the instance with a name in the form pki-subsystem_name-spawn.timestamp.log
.
Example 2.2. CA Install Log
========================================================================== 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 ==========================================================================
2.3.14.4. Tomcat Error and Access Logs
- admin.timestamp
- catalina.timestamp
- catalina.out
- host-manager.timestamp
- localhost.timestamp
- localhost_access_log.timestamp
- manager.timestamp
2.3.14.5. Self-Tests Log
CS.cfg
file. The information about logs in this section does not pertain to this log. See Section 2.6.5, “Self-Tests” for more information about self-tests.
2.3.14.6. journalctl
Logs
systemd
and exposed via the journalctl
utility.
# journalctl -u pki-tomcatd@instance_name.service
nuxwdog
service:
# journalctl -u pki-tomcatd-nuxwdog@instance_name.service
# journalctl -f -u pki-tomcatd@instance_name.service
nuxwdog
service:
# journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service
2.3.15. Instance Layout
/etc/pki/instance_name/server.xml
, which is instance-specific, but the CA servlets are defined in /usr/share/pki/ca/webapps/ca/WEB-INF/web.xml
, which is shared by all server instances on the system.
2.3.15.1. File and Directory Locations for Certificate System
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
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
/var/lib/pki/instance_name/conf/
directory is a symbolic link to the /etc/pki/instance_name/
directory.
2.3.15.2. CA Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
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.15.3. KRA Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
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.15.4. OCSP Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
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.15.5. TKS Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
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.15.6. TPS Subsystem Information
pki-tomcat
; the true value is whatever is specified at the time the subsystem is created with pkispawn
.
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.15.7. Shared Certificate System Subsystem File Locations
Directory Location | Contents |
---|---|
/usr/share/pki | Contains common files and templates used to create Certificate System instances. Along with shared files for all subsystems, there are subsystem-specific files in subfolders:
|
/usr/bin | Contains the pkispawn and pkidestroy instance configuration scripts and tools (Java, native, and security) shared by the Certificate System subsystems. |
/usr/share/java/pki | Contains Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. |
2.4. PKI with Certificate System
Note
2.4.1. Issuing Certificates
2.4.1.1. The Enrollment Process
2.4.1.1.1. Enrollment Using the User Interface
- 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.
2.4.1.1.2. Enrollment Using the Command Line
2.4.1.1.2.1. Enrolling Using the pki
Utility
- The pki-cert(1) man page
- The Command-Line Interfaces section in the Red Hat Certificate System Administration Guide.
2.4.1.1.2.2. Enrolling with CMC
- Generate a PKCS #10 or CRMF certificate signing request (CSR) using a utility, such as
PKCS10Client
orCRMFPopClient
.Note
If key archival is enabled in the Key Recovery Agent (KRA), use theCRMFPopClient
utility with the KRA's transport certificate in Privacy Enhanced Mail (PEM) format set in thekra.transport
file. - Use the
CMCRequest
utility to convert the CSR into a CMC request. TheCMCRequest
utility uses a configuration file as input. This file contains, for example, the path to the CSR and the CSR's format.For further details and examples, see the CMCRequest(1) man page. - Use the
HttpClient
utility to send the CMC request to the CA.HttpClient
uses a configuration file with settings, such as the path to the CMC request file and the servlet.If theHttpClient
command succeeds, the utility receives a PKCS #7 chain with CMC status controls from the CA.For details about what parameters the utility provides, enter theHttpClient
command without any parameters. - Use the
CMCResponse
utility to check the issuance result of the PKCS #7 file generated byHttpClient
. If the request is successful,CMCResponse
displays the certificate chain in a readable format.For further details, see the CMCResponse(1) man page. - Import the new certificate into the application. For details, follow the instructions of the application to which you want to import the certificate.
Note
The certificate retrieved byHttpClient
is in PKCS #7 format. If the application supports only Base64-encoded certificates, use theBtoA
utility to convert the certificate.Additionally, certain applications require a header and footer for certificates in Privacy Enhanced Mail (PEM) format. If these are required, add them manually to the PEM file after you converted the certificate.
2.4.1.1.2.2.1. CMC Enrollment without POP
HttpClient
utility receives an EncryptedPOP
CMC status, which is displayed by the CMCResponse
command. In this case, enter the CMCRequest
command again with different parameters in the configuration file.
2.4.1.1.2.2.2. Signed CMC Requests
- If an agent signs the request, set the authentication method in the profile to
CMCAuth
. - If a user signs the request, set the authentication method in the profile to
CMCUserSignedAuth
.
2.4.1.1.2.2.3. Unsigned CMC Requests
CMCUserSignedAuth
authentication plug-in is configured in the profile, you must use an unsigned CMC request in combination with the Shared Secret authentication mechanism.
Note
self-signed CMC requests
.
2.4.1.1.2.2.5. Simple CMC Requests
HttpClient
utility's configuration file:
servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert
2.4.1.2. Certificate Profiles
- Certificates that are X.509 version 3-compliant
- Unicode support for the certificate subject name and issuer name
- Support for empty certificate subject names
- Support for customized subject name components
- Support for customized extensions
<instance directory>/ca/profiles/ca
with names in the format of <profile id>.cfg
. LDAP-based profiles are possible with proper pkispawn
configuration parameters.
2.4.1.3. Authentication for Certificate Enrollment
2.4.1.4. Cross-Pair Certificates
2.4.2. Renewing Certificates
2.4.3. Publishing Certificates and CRLs
2.4.4. Revoking Certificates and Checking Status
2.4.4.1. Revoking Certificates
- The end-entity pages. For details, see the Certificate Revocation Pages section in the Red Hat Certificate System Administration Guide.
- The
CMCRequest
utility on the command line. For details, see the Performing a CMC Revocation section in the Red Hat Certificate System Administration Guide. - 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
2.4.4.2.2. OCSP Services
- A CA is set up to issue certificates that include the Authority Information Access extension, which identifies an OCSP responder that can be queried for the status of the certificate.
- The CA periodically publishes CRLs to an OCSP responder.
- The OCSP responder maintains the CRL it receives from the CA.
- An OCSP-compliant client sends requests containing all the information required to identify the certificate to the OCSP responder for verification. The applications determine the location of the OCSP responder from the value of the Authority Information Access extension in the certificate being validated.
- The OCSP responder determines if the request contains all the information required to process it. If it does not or if it is not enabled for the requested service, a rejection notice is sent. If it does have enough information, it processes the request and sends back a report stating the status of the certificate.
2.4.4.2.2.1. OCSP Response Signing
- The CA that issued the certificate whose status is being checked.
- A responder with a public key trusted by the client. Such a responder is called a trusted responder.
- A responder that holds a specially marked certificate issued to it directly by the CA that revokes the certificates and publishes the CRL. Possession of this certificate by a responder indicates that the CA has authorized the responder to issue OCSP responses for certificates revoked by the CA. Such a responder is called a CA-designated responder or a CA-authorized responder.
2.4.4.2.2.2. OCSP Responses
- Good or Verified . Specifies a positive response to the status inquiry, meaning the certificate has not been revoked. It does not necessarily mean that the certificate was issued or that it is within the certificate's validity interval. Response extensions may be used to convey additional information on assertions made by the responder regarding the status of the certificate.
- Revoked . Specifies that the certificate has been revoked, either permanently or temporarily.
Note
2.4.4.2.2.3. OCSP Services
- The OCSP built into the Certificate Manager
- The Online Certificate Status Manager subsystem
Note
2.4.5. Archiving, Recovering, and Rotating Keys
2.4.5.1. Archiving Keys
- 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 the Creating a CSR Using CRMFPopClient section in the Red Hat Certificate System Administration Guide.
- 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 the Generating CSRs Using Server-Side Key Generation section in the Red Hat Certificate System Administration Guide.
- 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.
- 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
- 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
Figure 2.3. Asynchronous Recovery
Warning
Important
pki
utility to replicate this behavior. For more information, see the pki(1) and pki-key(1) man pages or run CRMFPopClient --help and man CMCRequest.
pki
utility supports options that enable storing and retrieving these other types of secrets.
2.4.5.3. KRA Transport Key Rotation
- Generate a new KRA transport key and certificate
- Transfer the new transport key and certificate to KRA clones
- Update the CA configuration with the new KRA transport certificate
- Update the KRA configuration to use only the new transport key and certificate
- Generating the new KRA transport key and certificate
- Request the KRA transport certificate.
- Stop the KRA:
# pki-server stop pki-kra
OR (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Create a subdirectory and save all the NSS database files into it. For example:
mkdir nss_db_backup cp *.db nss_db_backup
- Create a new request by using the
PKCS10Client
utility. For example:# PKCS10Client -p password -d '.' -o 'req.txt' -n 'CN=KRA Transport 2 Certificate,O=example.com Security Domain'
Alternatively, use thecertutil
utility. For example:# certutil -d . -R -k rsa -g 2048 -s 'CN=KRA Transport 2 Certificate,O=example.com Security Domain' -f password-file -a -o transport-certificate-request-file
- Submit the transport certificate request on the Manual Data Recovery Manager Transport Certificate Enrollment page of the CA End-Entity page.
- Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
- Approve the KRA transport certificate through the CA Agent Services interface.
- Retrieve the KRA transport certificate.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
- Once the new KRA transport certificate is available, paste its Base64-encoded value into a text file, for example a file named
cert-serial_number.txt
. Do not include the header (-----BEGIN CERTIFICATE-----
) or the footer (-----END CERTIFICATE-----
).
- Import the KRA transport certificate.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Import the transport certificate into the KRA NSS database:
# certutil -d . -A -n 'transportCert-serial_number cert-pki-kra KRA' -t 'u,u,u' -a -i cert-serial_number.txt
- Update the KRA transport certificate configuration.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Verify that the new KRA transport certificate is imported:
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file and add the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Propagating the new transport key and certificate to KRA clones
- Start the KRA:
# pki-server start pki-kra
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-kra.service
- Extract the new transport key and certificate for propagation to clones.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Stop the KRA:
# pki-server stop pki-kra
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Verify that the new KRA transport certificate is present:
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Export the KRA new transport key and certificate:
# pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'
- Verify the exported KRA transport key and certificate:
# pk12util -l transport.p12
- Perform these steps on each KRA clone:
- Copy the
transport.p12
file, including the transport key and certificate, to the KRA clone location. - Go to the clone NSS database directory:
# cd /etc/pki/pki-kra/alias
- Stop the KRA clone:
# pki-server stop pki-kra
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Check the content of the clone NSS database:
# certutil -d . -L
- Import the new transport key and certificate of the clone:
# pk12util -i transport.p12 -d .
- Add the following line to the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file on the clone:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Start the KRA clone:
# pki-server start pki-kra
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-kra.service
- Updating the CA configuration with the new KRA transport certificate
- Format the new KRA transport certificate for inclusion in the CA.
- Obtain the
cert-serial_number.txt
KRA transport certificate file created when retrieving the KRA transport certificate in the previous procedure. - Convert the Base64-encoded certificate included in
cert-serial_number.txt
to a single-line file:# tr -d '\n' < cert-serial_number.txt > cert-one-line-serial_number.txt
- Do the following for the CA and all its clones corresponding to the KRA above:
- Stop the CA:
# pki-server stop pki-ca
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-ca.service
- In the
/var/lib/pki/pki-ca/ca/conf/CS.cfg
file, locate the certificate included in the following line:ca.connector.KRA.transportCert=certificate
Replace that certificate with the one contained incert-one-line-serial_number.txt
. - Start the CA:
# pki-server start pki-ca
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-ca.service
Note
While the CA and all its clones are being updated with the new KRA transport certificate, the CA instances that have completed the transition use the new KRA transport certificate, and the CA instances that have not yet been updated continue to use the old KRA transport certificate. Because the corresponding KRA and its clones have already been updated to use both transport certificates, no downtime occurs.- Updating the KRA configuration to use only the new transport key and certificate
- For the KRA and each of its clones, do the following:
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Stop the KRA:
# pki-server stop pki-kra
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Verify that the new KRA transport certificate is imported:
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file, and look for thenickName
value included in the following line:kra.transportUnit.nickName=transportCert cert-pki-kra KRA
Replace thenickName
value with thenewNickName
value included in the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
As a result, theCS.cfg
file includes this line:kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRA
- Remove the following line from
/var/lib/pki/pki-kra/kra/conf/CS.cfg
:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Start the KRA:
# pki-server start pki-kra
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-kra.service
2.5. Smart Card Token Management with Certificate System
Figure 2.4. How the TMS Manages Smart Cards
2.5.1. Token Key Service (TKS)
Note
2.5.1.1. Master Keys and Key Sets
CS.cfg
). Each TPS profile contains a configuration to direct its enrollment to the proper TKS keySet for the matching key derivation process that would essentially be responsible for establishing the Secure Channel secured by a set of session-specific keys between TMS and the smart card token.
2.5.1.3. Key Update (Key Changeover)
Important
2.5.1.4. APDUs and Secure Channels
- Command APDUs, sent by the TPS to smart cards
- Response APDUs, sent by smart cards to the TPS as response to command APDUs
2.5.2. Token Processing System (TPS)
2.5.2.1. Coolkey Applet
2.5.2.2. Token Operations
- Token Format - The format operation is responsible for installing the proper Coolkey applet onto the token. The applet provides a platform where subsequent cryptographic keys and certificates can be later placed.
- Token Enrollment - The enrollment operation results in a smart card populated with required cryptographic keys and cryptographic certificates. This material allows the user of the smart card to participate in operations such as secure web site access and secure mail. Two types of enrollments are supported, which is configured globally:
- Internal Registration - Enrollment by TPS profiles determined by the profile Mapping Resolver.
- External Registration - Enrollment by TPS profiles determined by the entries in the user’s LDAP record.
- Token PIN Reset - The token PIN reset operation allows the user of the token to specify a new PIN that is used to log into the token, making it available for performing cryptographic operations.
- Key Generation - Each PKI certificate is comprised of a public/private key pair. In Red Hat Certificate System, the generation of the keys can be done in two ways, depending on the TPS profile configuration:
- Token Side Key Generation - The PKI key pairs are generated on the smart card token. Generating the key pairs on the token side does not allow for key archival.
- Server Side Key Generation - The PKI key pairs are generated on the TMS server side. The key pairs are then sent back to the token using Secure Channel. Generating the key pairs on the server side allows for key archival.
- Certificate Renewal - This operation allows a previously enrolled token to have the certificates currently on the token reissued while reusing the same keys. This is useful in situations where the old certificates are due to expire and you want to create new ones but maintain the original key material.
- Certificate Revocation - Certificate revocation can be triggered based on TPS profile configuration or based on token state.Normally, only the CA which issued a certificate can revoke it, which could mean that retiring a CA would make it impossible to revoke certain certificates. However, it is possible to route revocation requests for tokens to the retired CA while still routing all other requests such as enrollment to a new, active CA. This mechanism is called Revocation Routing.
- Token Key Changeover - The key changeover operation, triggered by a format operation, results in the ability to change the internal keys of the token from the default developer key set to a new key set controlled by the deployer of the Token Processing System. This is usually done in any real deployment scenario since the developer key set is better suited to testing situations.
- Applet Update - During the course of a TMS deployment, the Coolkey smart card applet can be updated or downgraded if required.
2.5.2.3. TPS Profiles
- The steps taken to Format or Enroll a token.
- The attributes contained within the finished token after the operation has been successfully completed.
- How does the TPS connect to the user's authentication LDAP database?
- Will user authentication be required for this token operation? If so, what authentication manager will be used?
- How does the TPS connect to a Certificate System CA from which it will obtain certificates?
- How are the private and public keys generated on this token? Are they generated on the token side or on the server side?
- What key size (in bits) is to be used when generating private and public keys?
- Which certificate enrollment profile (provisioned by the CA) is to be used to generate the certificates on this token?
Note
This setting will determine the final structure of the certificates to be written to the token. Different certificates can be created for different uses, based on extensions included in the certificate. For example, one certificate can specialize in data encryption, and another one can be used for signature operations. - What version of the Coolkey applet will be required on the token?
- How many certificates will be placed on this token for an enrollment operation?
- Internal Registration - In this case, the TPS profile (
tokenType
) is determined by the profile Mapping Resolver. This filter-based resolver can be configured to take any of the data provided by the token into account and determine the target profile. - External Registration - When using external registration, the profile (in name only - actual profiles are still defined in the TPS in the same fashion as those used by the internal registration) is specified in each user's LDAP record, which is obtained during authentication. This allows the TPS to obtain key enrollment and recovery information from an external registration Directory Server where user information is stored. This gives you the control to override the enrollment, revocation, and recovery policies that are inherent to the TPS internal registration mechanism. The user LDAP record attribute names relevant to external registration are configurable.External registration can be useful when the concept of a "group certificate" is required. In that case, all users within a group can have a special record configured in their LDAP profiles for downloading a shared certificate and keys.
2.5.2.4. Token Database
2.5.2.4.1. Token States and Transitions
2.5.2.4.1.1. Token States
Name | Code | Label |
---|---|---|
FORMATTED | 0 | Formatted (uninitialized) |
DAMAGED | 1 | Physically damaged |
PERM_LOST | 2 | Permanently lost |
SUSPENDED | 3 | Suspended (temporarily lost) |
ACTIVE | 4 | Active |
TERMINATED | 6 | Terminated |
UNFORMATTED | 7 | Unformatted |
Note
5
, which previously belonged to a state that was removed.
2.5.2.4.1.2. Token State Transitions Done Using the Graphical or Command Line Interface
FORMATTED
to ACTIVE
or DAMAGED
, but it can never transition from FORMATTED
to UNFORMATTED
.
tokendb.allowedTransitions
property, and the tps.operations.allowedTransitions
property controls allowed transitions triggered by token operations.
/usr/share/pki/tps/conf/CS.cfg
configuration file.
2.5.2.4.1.2.1. Token State Transitions Using the Command Line or Graphical Interface
tokendb.allowedTransitions
property:
tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7
<current code>:<new code>
. The codes are described in Table 2.9, “Possible Token States”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg
.
Transition | Current State | Next State | Description |
---|---|---|---|
0:1 | FORMATTED | DAMAGED | This token has been physically damaged. |
0:2 | FORMATTED | PERM_LOST | This token has been permanently lost. |
0:3 | FORMATTED | SUSPENDED | This token has been suspended (temporarily lost). |
0:6 | FORMATTED | TERMINATED | This token has been terminated. |
3:2 | SUSPENDED | PERM_LOST | This suspended token has been permanently lost. |
3:6 | SUSPENDED | TERMINATED | This suspended token has been terminated. |
4:1 | ACTIVE | DAMAGED | This token has been physically damaged. |
4:2 | ACTIVE | PERM_LOST | This token has been permanently lost. |
4:3 | ACTIVE | SUSPENDED | This token has been suspended (temporarily lost). |
4:6 | ACTIVE | TERMINATED | This token has been terminated. |
6:7 | TERMINATED | UNFORMATTED | Reuse this token. |
FORMATTED
and then became SUSPENDED
, it can only return to the FORMATTED
state. If a token was originally ACTIVE
and then became SUSPENDED
, it can only return to the ACTIVE
state.
Transition | Current State | Next State | Description |
---|---|---|---|
3:0 | SUSPENDED | FORMATTED | This suspended (temporarily lost) token has been found. |
3:4 | SUSPENDED | ACTIVE | This suspended (temporarily lost) token has been found. |
2.5.2.4.1.3. Token State Transitions using Token Operations
tokendb.allowedTransitions
property:
tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0
<current code>:<new code>
. The codes are described in Table 2.9, “Possible Token States”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg
.
Transition | Current State | Next State | Description |
---|---|---|---|
0:0 | FORMATTED | FORMATTED | This allows reformatting a token or upgrading applet/key in a token. |
0:4 | FORMATTED | ACTIVE | This allows enrolling a token. |
4:4 | ACTIVE | ACTIVE | This allows re-enrolling an active token. May be useful for external registration. |
4:0 | ACTIVE | FORMATTED | This allows formatting an active token. |
7:0 | UNFORMATTED | FORMATTED | This allows formatting a blank or previously used token. |
2.5.2.4.1.4. Token State and Transition Labels
/usr/share/pki/tps/conf/token-states.properties
configuration file. By default, the file has the following contents:
# Token states UNFORMATTED = Unformatted FORMATTED = Formatted (uninitialized) ACTIVE = Active SUSPENDED = Suspended (temporarily lost) PERM_LOST = Permanently lost DAMAGED = Physically damaged TEMP_LOST_PERM_LOST = Temporarily lost then permanently lost TERMINATED = Terminated # Token state transitions FORMATTED.DAMAGED = This token has been physically damaged. FORMATTED.PERM_LOST = This token has been permanently lost. FORMATTED.SUSPENDED = This token has been suspended (temporarily lost). FORMATTED.TERMINATED = This token has been terminated. SUSPENDED.ACTIVE = This suspended (temporarily lost) token has been found. SUSPENDED.PERM_LOST = This suspended (temporarily lost) token has become permanently lost. SUSPENDED.TERMINATED = This suspended (temporarily lost) token has been terminated. SUSPENDED.FORMATTED = This suspended (temporarily lost) token has been found. ACTIVE.DAMAGED = This token has been physically damaged. ACTIVE.PERM_LOST = This token has been permanently lost. ACTIVE.SUSPENDED = This token has been suspended (temporarily lost). ACTIVE.TERMINATED = This token has been terminated. TERMINATED.UNFORMATTED = Reuse this token.
2.5.2.4.1.5. Customizing Allowed Token State Transitions
/var/lib/pki/instance_name/tps/conf/CS.cfg
:
tokendb.allowedTransitions
to customize the list of allowed transitions performed using the command line or graphical interfacetps.operations.allowedTransitions
to customize the list of allowed transitions using token operations
/usr/share/pki/tps/conf/CS.cfg
.
2.5.2.4.1.6. Customizing Token State and Transition Labels
/usr/share/pki/tps/conf/token-states.properties
into your instance folder (/var/lib/pki/instance_name/tps/conf/CS.cfg
), and change the labels listed inside as needed.
token-states.properties
file from your instance folder.
2.5.2.4.1.7. Token Activity Log
Activity | Description |
---|---|
add | A token was added. |
format | A token was formatted. |
enrollment | A token was enrolled. |
recovery | A token was recovered. |
renewal | A token was renewed. |
pin_reset | A token PIN was reset. |
token_status_change | A token status was changed using the command line or graphical interface. |
token_modify | A token was modified. |
delete | A token was deleted. |
cert_revocation | A token certificate was revoked. |
cert_unrevocation | A token certificate was unrevoked. |
2.5.2.4.2. Token Policies
RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES
2.5.2.5. Mapping Resolver
Note
FilterMappingResolver
is the only mapping resolver implementation provided with the TPS by default. It allows you to define a set of mappings and a target result for each mapping. Each mapping contains a set of filters, where:
- If the input filter parameters pass all filters within a mapping, the
target
value is assigned. - If the input parameters fail a filter, that mapping is skipped and the next one in order is tried.
- If a filter has no specified value, it always passes.
- If a filter does have a specified value, then the input parameters must match exactly.
- The order in which mappings are defined is important. The first mapping which passes is considered resolved and is returned to the caller.
FilterMappingResolver
according to the above rules. The following input filter parameters are supported by FilterMappingResolver
:
appletMajorVersion
- The major version of the Coolkey applet on the token.appletMinorVersion
- The minor version of the Coolkey applet on the token.keySet
ortokenType
keySet
- can be set as an extension in the client request. Must match the value in the filter if the extension is specified. The keySet mapping resolver is meant for determining keySet value when using external registration. The Key Set Mapping Resolver is necessary in the external registration environment when multiple key sets are supported (for example, different smart card token vendors). The keySet value is needed for identifying the master key on TKS, which is crucial for establishing Secure Channel. When a user's LDAP record is populated with a set tokenType (TPS profile), it does not know which card will end up doing the enrollment, and therefore keySet cannot be predetermined. ThekeySetMappingResolver
helps solve the issue by allowing the keySet to be resolved before authentication.tokenType
- okenType can be set as an extension in the client request. It must match the value in the filter if the extension is specified. tokenType (also referred to as TPS Profile) is determined at this time for the internal registration environment.
tokenATR
- The token's Answer to Reset (ATR).tokenCUID
- "start" and "end" define the range the Card Unique IDs (CUID) of the token must fall in to pass this filter.
2.5.2.6. TPS Roles
- TPS Administrator - this role is allowed to:
- Manage TPS tokens
- View TPS certificates and activities
- Manage TPS users and groups
- Change general TPS configuration
- Manage TPS authenticators and connectors
- Configure TPS profiles and profile mappings
- Configure TPS audit logging
- TPS Agent - this role is allowed to:
- Configure TPS tokens
- View TPS certificates and activities
- Change the status of TPS profiles
- TPS Operator - this role is allowed to:
- View TPS tokens, certificates, and activities
2.5.4. Enterprise Security Client (ESC)
2.6. Red Hat Certificate System Services
2.6.1. Notifications
2.6.2. Jobs
2.6.3. Logging
2.6.4. Auditing
2.6.5. Self-Tests
2.6.6. Users, Authorization, and Access Controls
2.6.6.1. Default Administrative Roles
Note
- Administrators, who can perform any administrative or configuration task for a subsystem.
- Agents, who perform PKI management tasks, like approving certificate requests, managing token enrollments, or recovering keys.
- Auditors, who can view and configure audit logs.
Note
pkispawn
utility. This bootstrap administrator uses the caadmin
user name by default but can be overridden by the pki_admin_uid
parameter in the configuration file passed to the pkispawn
command. The purpose of the bootstrap administrator is to create the first administrator and agent user. This operation requires the administrator privilege to mange user and groups, and the agent privilege to issue certificates.
2.6.6.2. Built-in Subsystem Trust Roles
2.7. Cloning
2.7.1. About Cloning
Note
Figure 2.5. Cloning Example
- DNS round-robin, a feature for managing network congestion that distributes load across several different servers.
- Sticky SSL/TLS, which makes it possible for a user returning to the system to be routed the same host used previously.
[Tomcat]
section to the PKI instance override configuration file and adding the following two name=value
pairs under that section:
[Tomcat] pki_clone_setup_replication=False pki_clone_reindex_data=False
Important
pkispawn
is invoked when specifying this kind of installation.
2.7.2. Preparing Clones
p12
file which can then be used while installing a clone subsystem. This command does not install or setup a clone subsystem, but prepares it for installation. Here is an example how to export subsystem certificates using the pki-server SUBSYSTEM-clone-prepare
command.
Example 2.3. Exporting Subsystem Certificates
[root@pki1 ~]$
pki-server ca-clone-prepare --i topology-02-CA --pkcs12-file /tmp/caclone.p12 --pkcs12-password SECret.123
----------------------------------------------------- Added certificate "subsystemCert cert-topology-02-CA" ----------------------------------------------------- -------------------------------------------------------- Added certificate "caSigningCert cert-topology-02-CA CA" -------------------------------------------------------- ---------------------------------------------------------- Added certificate "ocspSigningCert cert-topology-02-CA CA" ---------------------------------------------------------- ----------------------------------------------------------- Added certificate "auditSigningCert cert-topology-02-CA CA" -----------------------------------------------------------
p12
file contains the certificates. In the following example, the output of the pki pkcs12-cert-find
returns four certificates:
[root@pki1 ~]$
pki pkcs12-cert-find --pkcs12-file /tmp/caclone.p12 --pkcs12-password SECret.123
--------------- 4 entries found --------------- Certificate ID: 4649cef11b90c78d126874b91654de98ded54073 Serial Number: 0x4 Nickname: subsystemCert cert-topology-02-CA Subject DN: CN=Subsystem Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Issuer DN: CN=CA Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Trust Flags: u,u,u Has Key: true Certificate ID: a304cf107abd79fbda06d887cd279fb02cefe438 Serial Number: 0x1 Nickname: caSigningCert cert-topology-02-CA CA Subject DN: CN=CA Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Issuer DN: CN=CA Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Trust Flags: CTu,Cu,Cu Has Key: true Certificate ID: 4a09e057c1edfee40f412551db1959831abe117d Serial Number: 0x2 Nickname: ocspSigningCert cert-topology-02-CA CA Subject DN: CN=CA OCSP Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Issuer DN: CN=CA Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Trust Flags: u,u,u Has Key: true Certificate ID: 3f42f88026267f90f59631d38805cc60ee4c711a Serial Number: 0x5 Nickname: auditSigningCert cert-topology-02-CA CA Subject DN: CN=CA Audit Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Issuer DN: CN=CA Signing Certificate,OU=topology-02-CA,O=topology-02_Foobarmaster.org Trust Flags: u,u,Pu Has Key: true
p12
file, you can now set up a clone subsystem.
2.7.3. Cloning for CAs
begin*Number
and end*Number
attributes, with separate ranges defined for requests and certificate serial numbers. For example:
dbs.beginRequestNumber=1 dbs.beginSerialNumber=1 dbs.enableSerialManagement=true dbs.endRequestNumber=9980000 dbs.endSerialNumber=ffe0000 dbs.replicaCloneTransferNumber=5
Note
Important
CS.cfg
file — such as adding a KRA connection or creating a custom profile — are not copied into a clone's configuration if the change occurs after the clone is created.
2.7.4. Cloning for KRAs
Important
2.7.5. Cloning for Other Subsystems
2.7.6. Cloning and Key Stores
pki_backup_keys
and pki_backup_password
parameters in the pkispawn
configuration file. See the BACKUP PARAMETERS
section in the pki_default.cfg(5) man page for more details.
PKCS12Export
utility, as described in Section 10.1, “Backing up Subsystem Keys from a Software Database”.
pkispawn
configuration file using the pki_clone_pkcs12_password
and pki_clone_pkcs12_path
parameters For more information, see the Installing a Clone
section in the pkispawn(8) man page. In particular, make sure that the PKCS#12 file is accessible by the pkiuser
user and that it has the correct SELinux label.
- Duplicate all the required keys and certificates, except the SSL/TLS server key and certificate to the clone instance. Keep the nicknames for those certificates the same. Additionally, copy all the necessary trusted root certificates from the master instance to the clone instance, such as chains or cross-pair certificates.
- If the token is network-based, then the keys and certificates simply need to be available to the token; the keys and certificates do not need to be copied.
- When using a network-based hardware token, make sure the high-availability feature is enabled on the hardware token to avoid single point of failure.
2.7.7. LDAP and Port Considerations
Note
- If the master uses SSL/TLS to connect to its database, then the clone uses SSL/TLS, and the master/clone Directory Server databases use SSL/TLS connections for replication.
- If the master uses a standard connection to its database, then the clone must use a standard connection, and the Directory Server databases can use unencrypted connections for replication.
- If the master uses a standard connection to its database, then the clone must use a standard connection, but there is an option to use Start TLS for the master/clone Directory Server databases for replication. Start TLS opens a secure connection over a standard port.
Note
To use Start TLS, the Directory Server must still be configured to accept SSL/TLS connections. This means that prior to configuring the clone, a server certificate and a CA certificate must be installed on the Directory Server, and SSL/TLS must be enabled.
Important
2.7.8. Replica ID Numbers
dbs.beginReplicaNumber=1 dbs.endReplicaNumber=95
2.7.9. Custom Configuration and Clones
CS.cfg
file — outside the replicated database.
CS.cfg
file, but this connector information is not added to the clone CA configuration. If a certificate request that includes a key archival is submitted to the master CA, then the key archival is forwarded to the KRA using the CA-KRA connector information. If the request is submitted to the clone CA, no KRA is recognized, and the key archival request is disallowed.
Note
Chapter 3. Supported Standards and Protocols
3.1. TLS, ECC, and RSA
Note
3.1.1. Supported Cipher Suites
3.1.1.1. Recommended TLS Cipher Suites
ECC
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
RSA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
3.2. Allowed Key Algorithms and Their Sizes
- Allowed RSA key sizes:
- 2048 bits or greater
- Allowed EC curves or equivalent as defined in the FIPS PUB 186-4 standard:
- nistp256
- nistp384
- nistp521
3.3. Allowed Hash Functions
- SHA-256
- SHA-384
- SHA-512
- SHA-256
- SHA-384
- SHA-512
3.4. IPv4 and IPv6 Addresses
- Communications between subsystems, including between the TPS, TKS, and CA and for joining security domains
- Token operations between the TPS and the Enterprise Security Client
- Subsystem logging
- Access control instructions
- Operations performed with Certificate System tools, including the
pki
utility, the Subject Alt Name Extension tool, HttpClient, and the Bulk Issuance Tool - Client communications, including both the
pkiconsole
utility and IPv6-enabled browsers for web services - Certificate request names and certificate subject names, including user, server, and router certificates
- Publishing
- Connecting to LDAP databases for internal databases and authentication directories
- An IPv4 address must be in the format
n.n.n.n
orn.n.n.n,m.m.m.m
. For example,128.21.39.40
or128.21.39.40,255.255.255.00
. - An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, or 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0.
https://ipv6host.example.com:8443/ca/services pkiconsole https://ipv6host.example.com:8443/ca
[]
). For example:
https://[00:00:00:00:123:456:789:00:]:8443/ca/services pkiconsole https://[00:00:00:00:123:456:789:00:]:8443/ca
3.5. Supported PKIX Formats and Protocols
Format or Protocol | RFC or Draft | Description |
---|---|---|
X.509 version 1 and version 3 | Digital certificate formats recommended by the International Telecommunications Union (ITU). | |
Certificate Request Message Format (CRMF) | RFC 4211 | A message format to send a certificate request to a CA. |
Certificate Management Message Formats (CMMF) | Message formats to send certificate requests and revocation requests from end entities to a CA and to return information to end entities. CMMF has been subsumed by another standard, CMC. | |
Certificate Management Messages over CS (CMC) | RFC 5274 | A general interface to public-key certification products based on CS and PKCS #10, including a certificate enrollment protocol for RSA-signed certificates with Diffie-Hellman public-keys. CMC incorporates CRMF and CMMF. |
Cryptographic Message Syntax (CMS) | RFC 2630 | A superset of PKCS #7 syntax used for digital signatures and encryption. |
PKIX Certificate and CRL Profile | RFC 5280 | A standard developed by the IETF for a public-key infrastructure for the Internet. It specifies profiles for certificates and CRLs. |
Online Certificate Status Protocol (OCSP) | RFC 6960 | A protocol useful in determining the current status of a digital certificate without requiring CRLs. |
Chapter 4. Supported Platforms
4.1. General Requirements
4.2. Server Support
Note
4.3. Supported Web Browsers
Platform | Agent Services | End User Pages |
---|---|---|
Red Hat Enterprise Linux | Firefox 60 and later [a] | Firefox 60 and later [a] |
[a]
This Firefox version no longer supports the crypto web object used to generate and archive keys from the browser. As a result, expect limited functionality in this area.
|
Note
4.4. Supported Hardware Security Modules
HSM | Firmware | Appliance Software | Client Software |
---|---|---|---|
nCipher nShield Connect XC (High) | nShield_HSM_Firmware-12.72.1 | 12.71.0 | SecWorld_Lin64-12.71.0 |
Thales TCT Luna Network HSM Luna-T7 | lunafw_update-7.11.1-4 | 7.11.0-25 | 610-500244-001_LunaClient-7.11.1-5 |
Chapter 5. Planning the Certificate System
5.1. Deciding on the Required Subsystems
- It is requested and issued.
- It is valid.
- It expires.
- What if an employee leaves the company before the certificate expires?
- When a CA signing certificate expires, all of the certificates issued and signed using that certificate also expire. So will the CA signing certificate be renewed, allowing its issued certificates to remain valid, or will it be reissued?
- What if an employee loses a smart card or leaves it at home. Will a replacement certificate be issued using the original certificates keys? Will the other certificates be suspended or revoked? Are temporary certificates allowed?
- When a certificate expires, will a new certificate be issued or will the original certificate be renewed?
5.1.1. Using a Single Certificate Manager
Figure 5.1. CA Only Certificate System
5.1.2. Planning for Lost Keys: Key Archival and Recovery
Figure 5.2. CA and KRA
Note
5.1.3. Balancing Certificate Request Processing
5.1.4. Balancing Client OCSP Requests
Figure 5.3. CA and OCSP
5.1.5. Using Smart Cards
5.2. Defining the Certificate Authority Hierarchy
Note
5.2.1. Subordination to a Public CA
5.2.2. Subordination to a Certificate System CA
5.2.3. Linked CA
5.2.4. CA Cloning
Note
pk12util
or the PKCS12Export
commands.
5.3. Planning Security Domains
Example Corp Intranet PKI
. All other subsystems — KRA, TPS, TKS, OCSP, and other CAs — must become members of the security domain by supplying the security domain URL when configuring the subsystem.
ou=Security Domain,dc=server.example.com-pki-ca
pkiSecurityGroup
) to identify the group type:
cn=KRAList,ou=Security Domain,o=pki-tomcat-CA objectClass: top objectClass: pkiSecurityGroup cn: KRAList
pkiSubsystem
object class to identify the entry type:
dn: cn=kra.example.com:8443,cn=KRAList,ou=Security Domain,o=pki-tomcat-CA objectClass: top objectClass: pkiSubsystem cn: kra.example.com:8443 host: server.example.com UnSecurePort: 8080 SecurePort: 8443 SecureAdminPort: 8443 SecureAgentPort: 8443 SecureEEClientAuthPort: 8443 DomainManager: false Clone: false SubsystemName: KRA kra.example.com 8443
- The CA hosting the security domain can be signed by an external authority.
- Multiple security domains can be set up within an organization. However, each subsystem can belong to only one security domain.
- Subsystems within a domain can be cloned. Cloning subsystem instances distributes the system load and provides failover points.
- The security domain streamlines configuration between the CA and KRA; the KRA can push its KRA connector information and transport certificates automatically to the CA instead of administrators having to manually copy the certificates over to the CA.
- The Certificate System security domain allows an offline CA to be set up. In this scenario, the offline root has its own security domain. All online subordinate CAs belong to a different security domain.
- The security domain streamlines configuration between the CA and OCSP. The OCSP can push its information to the CA for the CA to set up OCSP publishing and also retrieve the CA certificate chain from the CA and store it in the internal database.
5.4. Determining the Requirements for Subsystem Certificates
5.4.1. Determining Which Certificates to Install
Subsystem | Certificates |
---|---|
Certificate Manager |
|
OCSP |
|
KRA |
|
TKS |
|
TPS |
|
- Generating new key pairs when creating a new self-signed CA certificate for a root CA will invalidate all certificates issued under the previous CA certificate.This means none of the certificates issued or signed by the CA using its old key will work; subordinate Certificate Managers, KRAs, OCSPs, TKSs, and TPSs will no longer function, and agents can no longer to access agent interfaces.This same situation occurs if a subordinate CA's CA certificate is replaced by one with a new key pair; all certificates issued by that CA are invalidated and will no longer work.Instead of creating new certificates from new key pairs, consider renewing the existing CA signing certificate.
- If the CA is configured to publish to the OCSP and it has a new CA signing certificate or a new CRL signing certificate, the CA must be identified again to the OCSP.
- If a new transport certificate is created for the KRA, the KRA information must be updated in the CA's configuration file,
CS.cfg
. The existing transport certificate must be replaced with the new one in theca.connector.KRA.transportCert
parameter. - If a CA is cloned, then when creating a new SSL/TLS server certificate for the master Certificate Manager, the clone CAs' certificate databases all need updated with the new SSL/TLS server certificate.
- If the Certificate Manager is configured to publish certificates and CRLs to an LDAP directory and uses the SSL/TLS server certificate for SSL/TLS client authentication, then the new SSL/TLS server certificate must be requested with the appropriate extensions. After installing the certificate, the publishing directory must be configured to use the new server certificate.
- Any number of SSL/TLS server certificates can be issued for a subsystem instance, but it really only needs one SSL/TLS certificate. This certificate can be renewed or replaced as many times as necessary.
5.4.2. Planning the CA Distinguished Name
cn=demoCA, o=Example Corporation, ou=Engineering, c=US
5.4.3. Setting the CA Signing Certificate Validity Period
5.4.4. Choosing the Signing Key Type and Length
- SHA256withRSA
- SHA512withRSA
- SHA256withEC
- SHA512withEC
Note
5.4.5. Using Certificate Extensions
- Trust. The X.500 specification establishes trust by means of a strict directory hierarchy. By contrast, Internet and extranet deployments frequently involve distributed trust models that do not conform to the hierarchical X.500 approach.
- Certificate use. Some organizations restrict how certificates are used. For example, some certificates may be restricted to client authentication only.
- Multiple certificates. It is not uncommon for certificate users to possess multiple certificates with identical subject names but different key material. In this case, it is necessary to identify which key and certificate should be used for what purpose.
- Alternate names. For some purposes, it is useful to have alternative subject names that are also bound to the public key in the certificate.
- Additional attributes. Some organizations store additional information in certificates, such as when it is not possible to look up information in a directory.
- Relationship with CA. When certificate chaining involves intermediate CAs, it is useful to have information about the relationships among CAs embedded in their certificates.
- CRL checking. Since it is not always possible to check a certificate's revocation status against a directory or with the original certificate authority, it is useful for certificates to include information about where to check CRLs.
5.4.5.1. Structure of Certificate Extensions
Extension ::= SEQUENCE { extnID OBJECT IDENTIFIER, critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING }
- The object identifier (OID) for the extension. This identifier uniquely identifies the extension. It also determines the ASN.1 type of value in the value field and how the value is interpreted. When an extension appears in a certificate, the OID appears as the extension ID field (
extnID
) and the corresponding ASN.1 encoded structure appears as the value of the octet string (extnValue
). - A flag or Boolean field called
critical
.The value, which can be eithertrue
orfalse
, assigned to this field indicates whether the extension is critical or noncritical to the certificate.- If the extension is critical and the certificate is sent to an application that does not understand the extension based on the extension's ID, the application must reject the certificate.
- If the extension is not critical and the certificate is sent to an application that does not understand the extension based on the extension's ID, the application can ignore the extension and accept the certificate.
- An octet string containing the DER encoding of the value of the extension.
- Authority Key Identifier extension, which identifies the CA's public key, the key used to sign the certificate.
- Subject Key Identifier extension, which identifies the subject's public key, the key being certified.
Note
5.4.6. Using and Customizing Certificate Profiles
Certificate Profiles
Modifying the Certificate Profile Parameters
Certificate Profile Administration
Guidelines for Customizing Certificate Profiles
- Decide which certificate profiles are needed in the PKI. There should be at least one profile for each type of certificate issued. There can be more than one certificate profile for each type of certificate to set different authentication methods or different defaults and constraints for a particular type of certificate type. Any certificate profile available in the administrative interface can be approved by an agent and then used by an end entity to enroll.
- Delete any certificate profiles that will not be used.
- Modify the existing certificate profiles for specific characteristics for the company's certificates.
- Change the defaults set up in the certificate profile, the values of the parameters set in the defaults, or the constraints that control the certificate content.
- Change the constraints set up by changing the value of the parameters.
- Change the authentication method.
- Change the inputs by adding or deleting inputs in the certificate profile, which control the fields on the input page.
- Add or delete the output.
5.4.6.1. Adding SAN Extensions to the SSL Server Certificate
/usr/share/pki/ca/profiles/ca/caInternalAuthServerCert.cfg
file and add the following parameters to the configuration file supplied to the pkispawn
utility:
pki_san_inject
- Set the value of this parameter to
True
. pki_san_for_server_cert
- Provide a list of the required SAN extensions separated by commas (,).
pki_san_inject=True pki_san_for_server_cert=intca01.example.com,intca02.example.com,intca.example.com
5.4.7. Planning Authentication Methods
- In agent-approved enrollment, end-entity requests are sent to an agent for approval. The agent approves the certificate request.
- In automatic enrollment, end-entity requests are authenticated using a plug-in, and then the certificate request is processed; an agent is not involved in the enrollment process.
- In CMC enrollment, a third party application can create a request that is signed by an agent and then automatically processed.
- An end entity submits a request for enrollment. The form used to submit the request identifies the method of authentication and enrollment. All HTML forms are dynamically-generated by the profiles, which automatically associate the appropriate authentication method with the form.
- If the authentication method is an agent-approved enrollment, the request is sent to the request queue of the CA agent. If the automated notification for a request in queue is set, an email is sent to the appropriate agent that a new request has been received. The agent can modify the request as allowed for that form and the profile constraints. Once approved, the request must pass the certificate profiles set for the Certificate Manager, and then the certificate is issued. When the certificate is issued, it is stored in the internal database and can be retrieved by the end entity from the end-entities page by serial number or by request ID.
- If the authentication method is automated, the end entity submits the request along with required information to authenticate the user, such as an LDAP user name and password. When the user is successfully authenticated, the request is processed without being sent to an agent's queue. If the request passes the certificate profile configuration of the Certificate Manager, the certificate is issued and stored in the internal database. It is delivered to the end entity immediately through the HTML forms.
5.4.8. Publishing Certificates and CRLs
- If certificates are published to the directory, than every user or server to which a certificate is issued must have a corresponding entry in the LDAP directory.
- If CRLs are published to the directory, than they must be published to an entry for the CA which issued them.
- For SSL/TLS, the directory service has to be configured in SSL/TLS and, optionally, be configured to allow the Certificate Manager to use certificate-based authentication.
- The directory administrator should configure appropriate access control rules to control DN (entry name) and password based authentication to the LDAP directory.
5.4.9. Renewing or Reissuing CA Signing Certificates
- Renewing a CA certificate involves issuing a new CA certificate with the same subject name and public and private key material as the old CA certificate, but with an extended validity period. As long as the new CA certificate is distributed to all users before the old CA certificate expires, renewing the certificate allows certificates issued under the old CA certificate to continue working for the full duration of their validity periods.
- Reissuing a CA certificate involves issuing a new CA certificate with a new name, public and private key material, and validity period. This avoids some problems associated with renewing a CA certificate, but it requires more work for both administrators and users to implement. All certificates issued by the old CA, including those that have not yet expired, must be renewed by the new CA.
Note
authorityKeyIdentifier
extension, can affect the transition from an old CA certificate to a new one.
5.5. Planning for Network and Physical Security
5.5.1. Considering Firewalls
- Protecting sensitive subsystems from unauthorized access
- Allowing appropriate access to other subsystems and clients outside of the firewall
389
for LDAP and 636
for LDAPS, by default) need to be open in the firewall to allow traffic to the directory service. Without access to the LDAP database, all subsystem operations can fail.
5.5.2. Considering Physical Security and Location
5.5.3. Planning Ports
- A non-secure HTTP port for end entity services that do not require authentication
- A secure HTTP port for end entity services, agent services, administrative console, and admin services that require authentication
- A Tomcat Server Management port
- A Tomcat AJP Connector Port
https://server.example.com:8443/ca/ee/ca
pkiconsole https://server.example.com:8443/ca
server.xml
file. If a port is not used, it can be disabled in that file. For example:
<Service name="Catalina">
<!--Connector port="8080"
... /--> unused standard port
<Connector port="8443" ... />
services
. On Red Hat Enterprise Linux, it is also helpful to confirm that a port is not assigned by SELinux, by running the command semanage port -l
to list all ports which currently have an SELinux context.
5.6. Tokens for Storing Certificate System Subsystem Keys and Certificates
cert9.db
) and key database (key4.db
), that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System automatically generates these files in the filesystem of its host machine when first using the internal token. These files are created during the Certificate System subsystem configuration if the internal token was selected for key-pair generation.
/var/lib/pki/instance_name/alias
directory.
- All system keys for a subsystem must be generated on the same token.
- The subsystem must be installed in an empty HSM slot. If the HSM slot has previously been used to store other keys, then use the HSM vendor's utilities to delete the contents of the slot. The Certificate System has to be able to create certificates and keys on the slot with default nicknames. If not properly cleaned up, the names of these objects may collide with previous instances.
- Fast SSL/TLS connections. Speed is important to accommodate a high number of simultaneous enrollment or service requests.
- Hardware protection of private keys. These devices behave like smart cards by not allowing private keys to be copied or removed from the hardware token. This is important as a precaution against key theft from an active attack of an online Certificate Manager.
pkcs11.txt
database with modutil
during the pre-configuration stage of the installation, if the PKCS #11 library modules are in the default installation paths.
5.7. A Checklist for Planning the PKI
- Q: How many security domains will be created, and what subsystem instances will be placed in each domain?
- Q: What ports should be assigned for each subsystem? Is it necessary to have a single SSL/TLS port, or is it better to have port separation for extra security?
- Q: What subsystems should be placed behind firewalls? What clients or other subsystems need to access those firewall-protected subsystems and how will access be granted? Is firewall access allowed for the LDAP database?
- Q: What subsystems need to be physically secured? How will access be granted, and who will be granted access?
- Q: What is the physical location of all agents and administrators? What is the physical location of the subsystems? How will administrators or agents access the subsystem services in a timely-manner? Is it necessary to have subsystems in each geographical location or time zone?
- Q: How many subsystems do you need to install?
- Q: Will any subsystems need to be cloned and, if so, what are the methods for securely storing their key materials?
- Q: Will the subsystem certificates and keys be stored on the internal software token in Certificate System or on an external hardware token?
- Q: What are the requirements for the CA signing certificate? Does the Certificate System need control over attributes like the validity period? How will the CA certificates be distributed?
- Q: What kinds of certificates will be issued? What characteristics do they need to have, and what profile settings are available for those characteristics? What restrictions need to be placed on the certificates?
- Q: What are the requirements for approving a certificate request? How does the requester authenticate himself, and what kind of process is required to approve the request?
- Q: Will many external clients need to validate certificate status? Can the internal OCSP in the Certificate Manager handle the load?
- Q: Will the PKI allow replacement keys? Will it require key archival and recovery?
- Q: Will the organization use smart cards? If so, will temporary smart cards be allowed if smart cards are mislaid, requiring key archival and recovery?
- Q: Where will certificates and CRLs be published? What configuration needs to be done on the receiving end for publishing to work? What kinds of certificates or CRLs need to be published and how frequently?
5.8. Optional Third-party Services
5.8.1. Load Balancers
5.8.2. Backup Hardware and Software
Part II. Installing Red Hat Certificate System
Chapter 6. Prerequisites and Preparation for Installation
6.1. Installing Red Hat Enterprise Linux
Important
# sysctl crypto.fips_enabled
1
, FIPS mode is enabled.
6.2. Securing the System Using SELinux
enforcing
mode. If a procedure in the Certificate System documentation requires to manually set SELinux-related settings, such as when using a Hardware Security Module (HSM), it is mentioned in the corresponding section.
6.2.1. Verifying if SELinux is Running in Enforcing Mode
enforcing
mode and no further actions are required.
# getenforce
6.3. Firewall Configuration
Service
|
Port
|
Protocol
|
---|---|---|
HTTP
|
8080
|
TCP
|
HTTPS
|
8443
|
TCP
|
Tomcat Management
|
8005
|
TCP
|
pkispawn
utility, you can customize the port numbers. If you use different ports than the defaults listed above, open them correspondingly in the firewall as described in Section 6.3.1, “Opening the Required Ports in the Firewall”. For further details about ports, see Section 5.5.3, “Planning Ports”.
6.3.1. Opening the Required Ports in the Firewall
- Make sure the
firewalld
service is running.# systemctl status firewalld
- To start
firewalld
and configure it to start automatically when the system boots:# systemctl start firewalld # systemctl enable firewalld
- Open the required ports using the
firewall-cmd
utility. For example, to open the Certificate System default ports in the default firewall zone:# firewall-cmd --permanent --add-port={8080/tcp,8443/tcp,8009/tcp,8005/tcp}
For details on usingfirewall-cmd
to open ports on a system, see the in the Securing Networks or the firewall-cmd(1) man page. - Reload the firewall configuration to ensure that the change takes place immediately:
# firewall-cmd --reload
6.4. Hardware Security Module
6.4.1. Setting up SELinux for an HSM
- nCipher nShield
- After you installed the HSM and before you start installing Certificate System:
- Reset the context of files in the
/opt/nfast/
directory:# restorecon -R /opt/nfast/
- Restart the nfast software.
# /opt/nfast/sbin/init.d-ncipher restart
- Thales Luna HSM
- No SELinux-related actions are required before you start installing Certificate System.
6.4.2. Enabling FIPS Mode on an HSM
Important
- nCipher HSM
- On a nCipher HSM, the FIPS mode can only be enabled when generating the Security World, this cannot be changed afterwards. While there is a variety of ways to generate the Security World, the preferred method is always to use the
new-world
command. For guidance on how to generate a FIPS-compliant Security World, please follow the nCipher HSM vendor's documentation. - LunaSA HSM
- Similarly, enabling the FIPS mode on a Luna HSM must be done during the initial configuration, since changing this policy zeroizes the HSM as a security measure. For details, please refer to the Luna HSM vendor's documentation.
6.4.3. Verifying if FIPS Mode is Enabled on an HSM
6.4.3.1. Verifying if FIPS Mode is Enabled on an nCipher HSM
Note
# /opt/nfast/bin/nfkminfo
StrictFIPS140
is listed in the state flag, the FIPS mode is enabled. In newer vesions, it is however better to check the new mode
line and look for fips1402level3
. In all cases, there should also be an hkfips
key present in the nfkminfo
output.
6.4.3.2. Verifying if FIPS Mode is Enabled on a Luna SA HSM
Note
- Open the
lunash
management console - Use the
hsm show
command and verify that the output contains the textThe HSM is in FIPS 140-2 approved operation mode.
:lunash:> hsm show ... FIPS 140-2 Operation: ===================== The HSM is in FIPS 140-2 approved operation mode. ...
6.4.4. Preparing for Installing Certificate System with an HSM
pkispawn
Utility”, you are instructed to use the following parameters in the configuration file you pass to the pkispawn
utility when installing Certificate System with an HSM:
... [DEFAULT] ########################## # Provide HSM parameters # ########################## pki_hsm_enable=True pki_hsm_libfile=hsm_libfile pki_hsm_modulename=hsm_modulename pki_token_name=hsm_token_name pki_token_password=pki_token_password ######################################## # Provide PKI-specific HSM token names # ######################################## pki_audit_signing_token=hsm_token_name pki_ssl_server_token=hsm_token_name pki_subsystem_token=hsm_token_name ...
- The values of the
pki_hsm_libfile
andpki_token_name
parameter depend on your specific HSM installation. These values allow thepkispawn
utility to set up your HSM and enable Certificate System to connect to it. - The value of the
pki_token_password
depends upon your particular HSM token's password. The password gives thepkispawn
utility read and write permissions to create new keys on the HSM. - The value of the
pki_hsm_modulename
is a name used in laterpkispawn
operations to identify the HSM. The string is an identifier you can set as whatever you like. It allowspkispawn
and Certificate System to refer to the HSM and configuration information by name in later operations.
6.4.4.1. nCipher HSM Parameters
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so pki_hsm_modulename=nfast
pki_hsm_modulename
to any value. The above is a suggested value.
Example 6.1. Identifying the Token Name
root
user:
[root@example911 ~]# /opt/nfast/bin/nfkminfo
World
generation 2
...~snip~...
Cardset
name "NHSM-CONN-XC"
k-out-of-n 1/4
flags NotPersistent PINRecoveryRequired(enabled) !RemoteEnabled
timeout none
...~snip~...
name
field in the Cardset
section lists the token name.
pki_token_name=NHSM-CONN-XC
6.4.4.2. SafeNet / Luna SA HSM Parameters
pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so pki_hsm_modulename=lunasa
pki_hsm_modulename
to any value. The above is a suggested value.
Example 6.2. Identifying the Token Name
root
user:
# /usr/safenet/lunaclient/bin/vtl verify
The following Luna SA Slots/Partitions were found:
Slot Serial # Label
==== ================ =====
0 1209461834772 lunasaQE
label
column lists the token name.
pki_token_name=lunasaQE
6.4.5. Backing up Keys on Hardware Security Modules
.p12
file. If such an instance is to be backed-up, contact the manufacturer of your HSM for support.
6.5. Installing Red Hat Directory Server
Important
# sysctl crypto.fips_enabled
1
, FIPS mode is enabled.
6.5.1. Preparing a Directory Server Instance for Certificate System
- Make sure you have attached a subscription that provides Directory Server to the host.
- Enable the Directory Server repository:
#
subscription-manager repos --enable=dirsrv-11-for-rhel-8-x86_64-rpms
- Install the Directory Server and the openldap-clients packages:
#
dnf module install redhat-ds
#
dnf install openldap-clients
- Set up a Directory Server instance.
- Generate a DS configuration file; for example,
/tmp/ds-setup.inf
:$
dscreate create-template /tmp/ds-setup.inf
- Customize the DS configuration file as follows:
$ sed -i \ -e "s/;instance_name = .*/instance_name = localhost/g" \ -e "s/;root_password = .*/root_password = Secret.123/g" \ -e "s/;suffix = .*/suffix = dc=example,dc=com/g" \ -e "s/;create_suffix_entry = .*/create_suffix_entry = True/g" \ -e "s/;self_sign_cert = .*/self_sign_cert = False/g" \ /tmp/ds-setup.inf
- Create the instance using the
dscreate
command with thesetup
configuration file:#
dscreate from-file /tmp/ds-setup.inf
For a detailed procedure, see the Red Hat Directory Server Installation Guide.
6.5.2. Preparing for Configuring Certificate System
pkispawn
Utility”, if you chose to set up TLS between Certificate System and Directory Server, use the following parameters in the configuration file you pass to the pkispawn
utility when installing Certificate System:
Note
pki_ds_password
would no longer be relevant.
pki_ds_database=back_end_database_name pki_ds_hostname=host_name pki_ds_secure_connection=True pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate pki_ds_password=password pki_ds_ldaps_port=port pki_ds_bind_dn=cn=Directory Manager
pki_ds_database
parameter is a name used by the pkispawn
utility to create the corresponding subsystem database on the Directory Server instance.
pki_ds_hostname
parameter depends on the install location of the Directory Server instance. This depends on the values used in Section 6.5.1, “Preparing a Directory Server Instance for Certificate System”.
pki_ds_secure_connection=True
, the following parameters must be set:
pki_ds_secure_connection_ca_pem_file
: Sets the fully-qualified path including the file name of the file which contains an exported copy of the Directory Server's CA certificate. This file must exist prior topkispawn
being able to utilize it.pki_ds_ldaps_port
: Sets the value of the secure LDAPS port Directory Server is listening to. The default is636
.
6.6. Replacing a Temporary Self-Signed Certificate in Directory Server (CA)
6.7. Enabling TLS Client Authentication for the Internal LDAP Server
6.8. Attaching a Red Hat Subscription and Enabling the Certificate System Package Repository
- Attach the Red Hat subscriptions to the system:Skip this step, if your system is already registered or has a subscription that provides Certificate Server attached.
- Register the system to the Red Hat subscription management service.You can use the
--auto-attach
option to automatically apply an available subscription for the operating system.#
subscription-manager register --auto-attach
Username: admin@example.com Password: The system has been registered with id: 566629db-a4ec-43e1-aa02-9cbaa6177c3f Installed Product Current Status: Product Name: Red Hat Enterprise Linux Server Status: Subscribed - List the available subscriptions and note the pool ID providing the Red Hat Certificate System. For example:
#
subscription-manager list --available --all
... Subscription Name: Red Hat Enterprise Linux Developer Suite Provides: ... Red Hat Certificate System ... Pool ID: 7aba89677a6a38fc0bba7dac673f7993 Available: 1 ...In case you have a lot of subscriptions, the output of the command can be very long. You can optionally redirect the output to a file:#
subscription-manager list --available --all > /root/subscriptions.txt
- Attach the Certificate System subscription to the system using the pool ID from the previous step:
#
subscription-manager attach --pool=7aba89677a6a38fc0bba7dac673f7993
Successfully attached a subscription for: Red Hat Enterprise Linux Developer Suite
- Enable the Certificate System repository:
#
subscription-manager repos --enable certsys-10.x-for-rhel-8-x86_64-rpms
Where x denotes the latest Certificate System version. For example, to enable the Certificate System repository for RHCS 10.4, please use the below command:#
subscription-manager repos --enable certsys-10.4-for-rhel-8-x86_64-rpms
Repository 'certsys-10.4-for-rhel-8-x86_64-rpms' is enabled for this system. - Enable the Certificate System module stream:
#
dnf module enable redhat-pki
Note
subscription-manager
utility.
6.9. Certificate System Operating System Users and Groups
pkiuser
account and the corresponding pkiuser
group are automatically created. Certificate System uses this account and group to start services.
Chapter 7. Installing and Configuring Certificate System
- Certificate Authority (CA)
- Key Recovery Authority (KRA)
- Online Certificate Status Protocol (OCSP) Responder
- Token Key Service (TKS)
- Token Processing System (TPS)
7.1. Subsystem Configuration Order
- At least one CA running as a security domain is required before any of the other public key infrastructure (PKI) subsystems can be installed.
- Install the OCSP after the CA has been configured.
- The KRA, and TKS subsystems can be installed in any order, after the CA and OCSP have been configured.
- The TPS subsystem depends on the CA and TKS, and optionally on the KRA and OCSP subsystem.
Note
7.2. Certificate System Packages
Important
- pki-ca: Provides the Certificate Authority (CA) subsystem.
- pki-kra: Provides the Key Recovery Authority (KRA) subsystem.
- pki-ocsp: Provides the Online Certificate Status Protocol (OCSP) responder.
- pki-tks: Provides the Token Key Service (TKS).
- pki-tps: Provides the Token Processing Service (TPS).
- pki-console and redhat-pki-console-theme: Provides the Java-based Red Hat PKI console. Both packages must be installed.
- pki-server and redhat-pki-server-theme: Provides the web-based Certificate System interface. Both packages must be installed.This package is installed as a dependency if you install one of the following packages: pki-ca, pki-kra, pki-ocsp, pki-tks, pki-tps
7.2.1. Installing Certificate System Packages
- With the redhat-pki module, you can install all Certificate System subsystem packages and components at once on a RHEL 8 system. The redhat-pki module installs the five subsystems of Red Hat Certificate System: in addition to the pki-core module (CA, KRA) which is part of Red Hat Identity Management (IdM), includes the RHCS-specific subsystems (OCSP, TKS and TPS) as well as the pki-deps module that takes care of the required dependencies.
# yum install redhat-pki
- Alternatively, you can install packages separately. For example, to install the CA subsystem and the optional web interface:
# yum install pki-ca redhat-pki-server-theme
For other subsystems, replace the pki-ca package name with the one of the subsystem you want to install. - If you require the optional PKI console:
# yum install pki-console redhat-pki-console-theme
Note
Thepkiconsole
tool will be deprecated.
7.2.2. Updating Certificate System Packages
- Follow instructions in Section 7.2.3, “Determining Certificate System Product Version” to check the product version.
- Execute
# yum update
The command above updates the whole system including the RHCS packages.Note
We suggest scheduling a maintenance window during which you can take the PKI infrastructure offline to install the update.Important
Updating Certificate System requires the PKI infrastructure to be restarted. - Then check version again by following Section 7.2.3, “Determining Certificate System Product Version”.The version number should confirm that the update was successfully installed.
--downloadonly
option in the above procedure:
yum update --downloadonly
/var/cache/yum/
directory. The yum update
will later use the packages if they are the latest versions.
7.2.3. Determining Certificate System Product Version
/usr/share/pki/CS_SERVER_VERSION
file. To display the version:
# cat /usr/share/pki/CS_SERVER_VERSION Red Hat Certificate System 10.0 (Batch Update 1)
http://host_name:port_number/ca/admin/ca/getStatus
http://host_name:port_number/kra/admin/kra/getStatus
http://host_name:port_number/ocsp/admin/ocsp/getStatus
http://host_name:port_number/tks/admin/tks/getStatus
http://host_name:port_number/tps/admin/tps/getStatus
Note
7.3. Understanding the pkispawn
Utility
pkispawn
utility. During the setup, pkispawn
:
- Reads the default values from the
/usr/share/pki/server/etc/default.cfg
file. For further details, see the pki_default.cfg(5) man page.Important
Do not edit the/usr/share/pki/server/etc/default.cfg
file. Instead, create a configuration file and that overrides the defaults, and pass it to thepkispawn
utility. For details about using a configuration file, see Section 7.7, “Two-step Installation”. - Uses the passwords and other deployment-specific information provided depending on the setup mode:
- Interactive mode: The user is asked for the individual settings during the setup. Use this mode for simple deployments.
- Batch mode: The values are read from a configuration file the user provides. Parameters not set in the configuration file use the defaults.
- Performs the installation of the requested PKI subsystem.
- Passes the settings to a Java servlet that performs the configuration based on the settings.
pkispawn
utility to install:
- A root CA. For details, see Section 7.4, “Setting Up a Root Certificate Authority”.
- A subordinate CA or any other subsystem. For details, see Section 7.6, “Setting up Additional Subsystems”.
Note
pkispawn
utility. For a setup of a subordinate CA or non-CA subsystems, see Section 7.8, “Setting up Subsystems with an External CA”.
pkispawn
and examples, see the pkispawn(8) man page.
7.4. Setting Up a Root Certificate Authority
- Configuration file-based installation:Use this method for high-level customization. This installation method uses a configuration file that overrides the default installation parameters.You can install Certificate System using a configuration file in a single step or in two steps. For details and examples, see:
- The pkispawn(8) man page for the single-step installation.
- Section 7.7, “Two-step Installation” for the two-step installation.
- Interactive installation:
# pkispawn -s CA
Use the interactive installer if you only want to set the minimum of required configuration options.
7.5. Post-Installation
7.6. Setting up Additional Subsystems
Prerequisites
Installing the Subsystem
- Configuration file-based installation:Use this method for high-level customization. This installation method uses a configuration file that overrides the default installation parameters.You can install Certificate System using a configuration file in a single step or in two steps. For details and examples, see:
- The pkispawn(8) man page for the single-step installation.
- Section 7.7, “Two-step Installation” for the two-step installation.
- Interactive installation:Use the interactive installer if you only want to set the minimum of required configuration options.For example:
# pkispawn -s subsystem
Replace subsystem with one of the following subsystems:KRA
,OCSP
,TKS
, orTPS
.The interactive installer does not support installing a subordinate CA. To install a subordinate CA, use the two-step installation. See Section 7.7, “Two-step Installation”.
7.7. Two-step Installation
pkispawn
utility enables you to run the installation of a subsystem in two steps.
7.7.1. When to Use the Two-Step Installation
- Increasing security.
- Customizing subsystem certificates.
- Customizing the cipher list in the
sslRangeCiphers
parameter in the/etc/pki/instance_name/server.xml
file when installing a new Certificate System instance to be connected to an existing Certificate System. - Installing CA clones, KRA, OCSP, TKS and TPS in FIPS mode.
- Installing Certificate System with a Hardware Security Module (HSM) in FIPS mode.
7.7.2. The Two Major Parts of the Two-step Installation
- InstallationDuring this step,
pkispawn
copies configuration files from the/usr/share/pki/
directory to the instance-specific/etc/pki/instance_name/
directory. Additionally,pkispawn
sets the settings based on values defined in the deployment configuration file.This part of the installation contains the following substeps: - ConfigurationDuring this step,
pkispawn
continues the installation based on the configuration files in the instance-specific/etc/pki/instance_name/
directory.This part of the installation contains the following substeps:
7.7.3. Creating the Configuration File for the First Step of the Installation
/root/config.txt
, and fill it with the settings described below.
Important
Subsystem-independent Settings
- Set the passwords of the Certificate System
admin
user, the PKCS #12 file, and Directory Server:[DEFAULT] pki_admin_password=password pki_client_pkcs12_password=password pki_ds_password=password
- To use an LDAPS connection to Directory Server running on the same host, add the following parameters to the
[DEFAULT]
section in the configuration file:pki_ds_secure_connection=True pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate
Note
For security reasons, Red Hat recommends using an encrypted connection to Directory Server.If you use a self-signed certificate in Directory Server use the following command to export it from the Directory Server's Network Security Services (NSS) database:# certutil -L -d /etc/dirsrv/slapd-instance_name/ \ -n "server-cert" -a -o /root/ds.crt
Important
~/.dogtag/instance_name/subsystem/alias
client database after the installation. For security reasons, Red Hat recommends not enabling the pki_client_database_purge
parameter in the configuration file. If you manually set this parameter to True
, Certificate System does not remove the client database after the installation.
CA Settings
- To increase security, enable random serial numbers by adding the
[CA]
section with the following setting to the configuration file:[CA] pki_random_serial_numbers_enable=true
- Optionally, set the following parameters in the
[CA]
section to specify the data of theadmin
user, which will be automatically created during the installation:pki_admin_nickname=caadmin pki_admin_name=CA administrator account pki_admin_password=password pki_admin_uid=caadmin pki_admin_email=caadmin@example.com
Certificate System assigns administrator privileges to this account. Use this account after the installation to manage Certificate System and to create further user accounts. - To enable Certificate System to generate unique nicknames, set the following parameters in the
[DEFAULT]
section:pki_instance_name=instance_name pki_security_domain_name=example.com Security Domain pki_host=server.example.com
Important
If you install Certificate System with a network-shared Hardware Security Module (HSM), you must use unique certificate nicknames. - Optionally, to use Elliptic Curve Cryptography (ECC) instead of RSA when generating certificates:
- Add the following parameters to the
[DEFAULT]
section:pki_admin_key_algorithm=SHA256withEC pki_admin_key_size=nistp256 pki_admin_key_type=ecc pki_sslserver_key_algorithm=SHA256withEC pki_sslserver_key_size=nistp256 pki_sslserver_key_type=ecc pki_subsystem_key_algorithm=SHA256withEC pki_subsystem_key_size=nistp256 pki_subsystem_key_type=ecc
- Add the following parameters to the
[CA]
section:pki_ca_signing_key_algorithm=SHA256withEC pki_ca_signing_key_size=nistp256 pki_ca_signing_key_type=ecc pki_ca_signing_signing_algorithm=SHA256withEC pki_ocsp_signing_key_algorithm=SHA256withEC pki_ocsp_signing_key_size=nistp256 pki_ocsp_signing_key_type=ecc pki_ocsp_signing_signing_algorithm=SHA256withEC
- Add the following parameters to the
[CA]
section to override the RSA profiles with ECC profiles:pki_source_admincert_profile=/usr/share/pki/ca/conf/eccAdminCert.profile pki_source_servercert_profile=/usr/share/pki/ca/conf/eccServerCert.profile pki_source_subsystemcert_profile=/usr/share/pki/ca/conf/eccSubsystemCert.profile
Settings for Other Subsystems
- Add the following entry to
[DEFAULT]
section of your configuration file:pki_client_database_password=password
- If you are installing a TPS:
- Add the following section with the following section:
[TPS] pki_authdb_basedn=basedn_of_the_TPS_authentication_database
- Optionally, to configure that the TPS use server-side key generation utilizing a KRA that has already been installed in the shared CA instance, add the following entry to the
[TPS]
section:pki_enable_server_side_keygen=True
7.7.4. Starting the Installation Step
# pkispawn -f /root/config.txt -s subsystem --skip-configuration
CA
, KRA
, OCSP
, TKS
, or TPS
.
7.7.5. Customizing the Configuration Between the Installation Steps
7.7.5.1. Configuring Certificate Profiles
7.7.5.2. Enabling Signed Audit Logging
7.7.5.3. Updating the Ciphers List
- To secure the Certificate System instance
- To install a Certificate System instance and to add it to an existing site that supports only specific ciphers
Default FIPS Mode Enabled Ciphers for RSA Encryption
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA
- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA256
- TLS_RSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA256
Default FIPS Mode Enabled Ciphers for ECC Encryption
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA256
Required RSA Ciphers When Running an HSM on System with FIPS Mode Enabled
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
7.7.5.4. Configuring the PKI Console Timeout
7.7.5.5. Setting the KRA into Encryption Mode
7.7.5.6. Enabling OCSP
7.7.5.7. Configuring Ranges for Requests and Serial Numbers
7.7.6. Starting the Configuration Step
# pkispawn -f /root/config.txt -s subsystem --skip-installation
CA
, KRA
, OCSP
, TKS
, or TPS
.
pkispawn
utility displays an installation summary. For example:
================================================================ INSTALLATION SUMMARY ================================================================ Administrator's username: caadmin Administrator's PKCS #12 file: /root/.dogtag/instance_name/ca_admin_cert.p12 To check the status of the subsystem: systemctl status pki-tomcatd@instance_name.service To restart the subsystem: systemctl restart pki-tomcatd@instance_name.service The URL for the subsystem is: https://server.example.com:8443/ca/ PKI instances will be enabled upon system boot ================================================================
7.7.7. Post-Installation
7.8. Setting up Subsystems with an External CA
7.8.1. The Difference Between an Internal and External CA
pkispawn
utility sends subsystem Certificate Signing Requests (CSR) to a previously installed Certificate System, and the resulting issued certificates are received and used by pkispawn
, the CA the CSRs were sent to is called an Internal CA
.
External CA
, by contrast, can be one of the following:
- A non-Red Hat Certificate System CA that issues the signing certificate for a Certificate System subordinate CA.
- A previously installed Red Hat Certificate System CA that does not allow direct submission of CSRs. For example, this is the case if your environment requires CSRs from a subordinate CA, KRA, OCSP, TKS, or TPS to be in other formats than PKCS #10.
7.8.2. Installing a Subsystem with an External CA
Preparing the Configuration File for the External CA Installation
- If you install a subsystem which is integrated into an existing Certificate System installation but which uses a certificate signed by an external CA:
- Create the configuration file for the subsystem. See Section 7.7.3, “Creating the Configuration File for the First Step of the Installation”.
- Add the following settings to your configuration file in the respective [CA], [KRA], or [OCSP] sections:
- For a CA installation:
[CA] pki_external=True pki_external_step_two=False pki_ca_signing_csr_path=path/to/ca_signing.csr pki_ca_signing_cert_path=path/to/ca_signing.crt
- For a KRA installation:
[KRA] pki_external=True pki_external_step_two=False pki_storage_csr_path=/home/user_name/kra_storage.csr pki_transport_csr_path=/home/user_name/kra_transport.csr pki_subsystem_csr_path=/home/user_name/subsystem.csr pki_sslserver_csr_path=/home/user_name/sslserver.csr pki_audit_signing_csr_path=/home/user_name/kra_audit_signing.csr pki_admin_csr_path=/home/user_name/kra_admin.csr
- For an OCSP installation:
[OCSP] pki_external=True pki_external_step_two=False pki_ocsp_signing_csr_path=/home/user_name/ocsp_signing.csr pki_subsystem_csr_path=/home/user_name/subsystem.csr pki_sslserver_csr_path=/home/user_name/sslserver.csr pki_audit_signing_csr_path=/home/user_name/ocsp_audit_signing.csr pki_admin_csr_path=/home/user_name/ocsp_admin.csr
- If you install a standalone KRA or OCSP, which is not integrated into an existing Certificate System installation, execute the steps described in Section 7.9, “Setting up a Standalone KRA or OCSP”.
Starting the Installation of a Subsystem with an External CA
- Use the
pkispawn
utility to start the installation:# pkispawn -f /root/config.txt -s subsystem
Replace subsystem with the subsystem you want to install:CA
,KRA
, orOCSP
.During this step, the setup stores the CSRs in the files specified in the configuration. - Submit the CSRs to the external CA. Proceed after the CA has issued the corresponding certificates.In certain environments, if the external CA is also a Certificate System instance, the CSR in PKCS#10 format needs to be converted into CMC format before being submitted to the CA. See the Issuing Certificates Using CMC section in the Red Hat Certificate System Administration Guide for details about issuing the certificates.
- Optionally, customize the installation. For details, see Section 7.7.5, “Customizing the Configuration Between the Installation Steps”.
- After the external CA has issued the certificates, edit the deployment configuration file:
- Set the
pki_external_step_two
toTrue
:pki_external_step_two=True
- Add the following parameters, based on the subsystem you are installing:
- For a CA, set the path to the certificate file. For example:
pki_ca_signing_cert_path=/home/user_name/ca_signing.crt
If the specified file does not contain the certificate including the certificate chain, additionally specify the path to the certificate chain file and its nickname. For example:pki_cert_chain_path=/home/user_name/cert_chain.p7b pki_cert_chain_nickname=CA Signing Certificate
- For a KRA, set the paths to the certificate files. For example:
pki_storage_cert_path=/home/user_name/kra_storage.crt pki_transport_cert_path=/home/user_name/kra_transport.crt pki_subsystem_cert_path=/home/user_name/subsystem.crt pki_sslserver_cert_path=/home/user_namesslserver.crt pki_audit_signing_cert_path=/home/user_name/kra_audit_signing.crt pki_admin_cert_path=/home/user_name/kra_admin.crt
If the specified files do not contain the certificate including the certificate chain, additionally specify the paths to the signing certificate file and the certificate chain file together with their nicknames. For example:pki_ca_signing_nickname=CA Signing Certificate pki_ca_signing_cert_path=/home/user_name/ca_signing.crt pki_cert_chain_nickname=External Certificate Chain pki_cert_chain_path=/home/user_name/cert_chain.p7b
- For an OCSP, set the paths to the certificate files. For example:
pki_ocsp_signing_cert_path=/home/user_name/ocsp_signing.crt pki_subsystem_cert_path=/home/user_name/subsystem.crt pki_sslserver_cert_path=/home/user_name/sslserver.crt pki_audit_signing_cert_path=/home/user_name/ocsp_audit_signing.crt pki_admin_cert_path=/home/user_name/ocsp_admin.crt
If the specified files do not contain the certificate including the certificate chain, additionally specify the paths to the signing certificate file and the certificate chain file together with their nicknames. For example:pki_ca_signing_nickname=CA Signing Certificate pki_ca_signing_cert_path=/home/user_name/ca_signing.crt pki_cert_chain_nickname=External Certificate Chain pki_cert_chain_path=/home/user_name/cert_chain.p7b
- Optionally, customize the configuration files. For examples, see Section 7.7.5, “Customizing the Configuration Between the Installation Steps”.
- Start the configuration step:
# pkispawn -f /root/config.txt -s subsystem
Replace subsystem with the subsystem you want to install:CA
,KRA
, orOCSP
.
7.8.3. Post-Installation
7.9. Setting up a Standalone KRA or OCSP
- Create a configuration file, such as
/root/config.txt
, with the following content:[DEFAULT] pki_admin_password=password pki_client_database_password=password pki_client_pkcs12_password=password pki_ds_password=password pki_token_password=password pki_client_database_purge=False pki_security_domain_name=EXAMPLE pki_standalone=True pki_external_step_two=False
- For a standalone KRA, add the following section to the configuration file:
[KRA] pki_admin_email=kraadmin@example.com pki_ds_base_dn=dc=kra,dc=example,dc=com pki_ds_database=kra pki_admin_nickname=kraadmin pki_audit_signing_nickname=kra_audit_signing pki_sslserver_nickname=sslserver pki_storage_nickname=kra_storage pki_subsystem_nickname=subsystem pki_transport_nickname=kra_transport pki_standalone=True
- For a standalone OCSP, add the following section to the configuration file:
[OCSP] pki_admin_email=ocspadmin@example.com pki_ds_base_dn=dc=ocsp,dc=example,dc=com pki_ds_database=ocsp pki_admin_nickname=ocspadmin pki_audit_signing_nickname=ocsp_audit_signing pki_ocsp_signing_nickname=ocsp_signing pki_sslserver_nickname=sslserver pki_subsystem_nickname=subsystem pki_standalone=True
- To use an LDAPS connection to Directory Server running on the same host, add the following parameters to the
DEFAULT
section in the configuration file:pki_ds_secure_connection=True pki_ds_secure_connection_ca_pem_file=path_to_CA_or_self-signed_certificate
Note
For security reasons, Red Hat recommends using an encrypted connection to Directory Server.If you use a self-signed certificate in Directory Server, use the following command to export it from the Directory Server's Network Security Services (NSS) database:# certutil -L -d /etc/dirsrv/slapd-instance_name/ \ -n "server-cert" -a -o /root/ds.crt
- Proceed with the steps described in the section called “Starting the Installation of a Subsystem with an External CA”.
7.10. Post-installation Tasks
pkispawn
utility is complete, further steps could be taken to customize the configuration, depending on the site's preferences. These are described in Part III, “Configuring Certificate System”.
7.10.1. Setting Date/Time for RHCS
7.10.2. Replacing the Temporary Certificate
Note
- Obtain a new Directory Server server certificate. Submit the request for the new certificate signed by the CA. To get a new Directory Server certificate using the CMC method, see the Obtaining System and Server Certificates section in the Red Hat Certificate System Administration Guide.In the above section, follow the guidance to create a TLS server certificate. Once the certificate is created, it must be imported back into the Directory Server's certificate database.
- Stop the Directory Server instance before accessing the NSS database:
# systemctl stop dirsrv@instance_name
- Delete the old Directory Server certificate:
# certutil -F -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "DS Certificate"
- Import the CA certificate downloaded earlier:
# PKICertImport -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "CA Certificate" -t "CT,C,C" -a -i ca.crt -u L
- Import the new Directory Server certificate downloaded earlier:
# PKICertImport -d /etc/dirsrv/slapd-instance_name -f /etc/dirsrv/slapd-instance_name/password.txt -n "DS Certificate" -t ",," -a -i ds.crt -u V
- Start the Directory Server instance:
# systemctl start dirsrv@instance_name
- Remove the old Directory Server Certificate from PKI CA:
- Stop the Certificate System instance:
# systemctl stop pki-tomcatd@instance_name.service
- Remove the certificate:
# certutil -D -d /var/lib/pki/instance_name/alias/ -n "DS Certificate"
- Start the Certificate System instance:
# systemctl start pki-tomcatd@instance_name.service
- Verify that the new Directory Server certificate is signed by the CA installed in the NSS database:
- Display the Directory Server certificate
$ certutil -L -d /etc/dirsrv/slapd-instance_name -n "DS Certificate" Issuer: "CN=CA Signing Certificate,O=EXAMPLE" Subject: "CN=server.example.com"
- Verify the old Directory Server certificate no longer exists in the PKI NSS database:
$ certutil -L -d /var/lib/pki/instance_name/alias
- Verify Certificate System can connect to Directory Server using the new certificate:
$ pki cert-find
7.10.3. Enabling TLS Client Authentication
Note
pkispawn
already automatically created apkidbuser
on its internal directory server, where the CS instance's "subsystem certificate" (for examplesubsystemCert cert-pki-ca
) that is used for outbound TLS client authentication is stored in the user entry. Therefore, there is no need to create another LDAP user or another certificate for the TLS client-authentication.- When creating content for
/etc/dirsrv/slapd-instance_name/certmap.conf
, use the following format:certmap rhcs <certificate issuer DN> rhcs:CmapLdapAttr seeAlso rhcs:verifyCert on
For examplecertmap rhcs CN=CA Signing Certificate,OU=pki-tomcat-ca,O=pki-tomcat-ca-SD rhcs:CmapLdapAttr seeAlso rhcs:verifyCert on
- After configuring, restart the Directory Server.
CS.cfg
file located at <instance directory>/<subsystem type>/conf/CS.cfg
. For example /var/lib/pki/instance_name/ca/conf/CS.cfg
CS.cfg
, please add the RHCS instance's subsystem certificate nickname to internaldb.ldapauth.clientCertNickname
, and remove the two unused entries:
internaldb.ldapauth.bindDN internaldb.ldapauth.bindPWPrompt
internaldb._000=## internaldb._001=## Internal Database internaldb._002=## internaldb.basedn=o=pki-tomcat-ca-SD internaldb.database=pki-tomcat-ca internaldb.maxConns=15 internaldb.minConns=3 internaldb.ldapauth.authtype=SslClientAuth internaldb.ldapauth.clientCertNickname=HSM-A:subsystemCert pki-tomcat-ca internaldb.ldapconn.host=example.com internaldb.ldapconn.port=11636 internaldb.ldapconn.secureConn=true
Note
internaldb.basedn
and internaldb.database
parameters must be configured to match your specific LDAP instance.
internaldb.ldapauth.authtype=SslClientAuth
and internaldb.ldapconn.secureConn=true
must be set, and the value of the internaldb.ldapauth.clientCertNickname
must match the nickname of the TLS client certificate to authenticate against LDAP with in the NSS DB.
7.10.4. Configuring Session Timeout
7.10.5. CRL or Certificate Publishing
7.10.6. Configuring Certificate Enrollment Profiles (CA)
7.10.7. Enabling Access Banner
7.10.8. Enabling the Watchdog Service
nuxwdog
) service provides secure system password management. For details, see Section 14.3.2.1, “Enabling the Watchdog Service”.
7.10.9. Configuration for CMC Enrollment and Revocation (CA)
- For details about enabling the CMC Shared Token Feature, see Section 14.8.3, “Enabling the CMC Shared Secret Feature”.
- For details about enabling the
PopLinkWittness
feature, see Section 14.8.2, “Enabling thePopLinkWittnessV2
Feature”. - For details about enabling
CMCRevoke
for the web user interface, see Section 14.8.4, “Enabling CMCRevoke for the Web User Interface”.
7.10.10. TLS client-authentication for the Java Console
pkiconsole
to use TLS Client Certificate Authentication”.
Note
pkiconsole
is being deprecated.
7.10.11. Creating a Role User
7.10.12. Removing the Bootstrap User
7.10.13. Disabling Multi-role Support
7.10.14. KRA Configurations
7.10.14.1. Adding Requirement for Multiple Agent Approval for Key Recovery Authority (KRA)
7.10.14.2. Configuring KRA Encryption Settings
7.10.15. Setting up Users to use User Interfaces
Chapter 8. Using Hardware Security Modules for Subsystem Security Databases
8.1. Installing Certificate System with an HSM
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
8.2. Using Hardware Security Modules with Subsystems
pkcs11.txt
database with the modutil
command during the pre-configuration stage of the installation, if the PKCS #11 library modules are in the specified installation paths.
Important
8.2.1. Enabling the FIPS Mode on an HSM
Important
- nCipher HSM
- On a nCipher HSM, the FIPS mode can only be enabled when generating the Security World, this cannot be changed afterwards. While there is a variety of ways to generate the Security World, the preferred method is always to use the
new-world
command. For guidance on how to generate a FIPS-compliant Security World, please follow the nCipher HSM vendor's documentation. - LunaSA HSM
- Similarly, enabling the FIPS mode on a Luna HSM must be done during the initial configuration, since changing this policy zeroizes the HSM as a security measure. For details, please refer to the Luna HSM vendor's documentation.
8.2.2. Verifying if FIPS Mode is Enabled on an HSM
8.2.2.1. Verifying if FIPS Mode is Enabled on an nCipher HSM
Note
# /opt/nfast/bin/nfkminfo
StrictFIPS140
is listed in the state flag, the FIPS mode is enabled. In newer vesions, it is however better to check the new mode
line and look for fips1402level3
. In all cases, there should also be an hkfips
key present in the nfkminfo
output.
8.2.2.2. Verifying if FIPS Mode is Enabled on a Luna SA HSM
Note
- Open the
lunash
management console - Use the
hsm show
command and verify that the output contains the textThe HSM is in FIPS 140-2 approved operation mode.
:lunash:> hsm show ... FIPS 140-2 Operation: ===================== The HSM is in FIPS 140-2 approved operation mode. ...
8.2.3. Adding or Managing the HSM Entry for a Subsystem
pkispawn
command, the following parameter is added to the /var/lib/pki/instance_name/conf/password.conf
file for the HSM password:
hardware-HSM_token_name=HSM_token_password
8.2.4. Setting up SELinux for an HSM
enforcing
mode, certain HSMs require that you manually update SELinux settings before you can install Certificate System.
- nCipher nShield Connect XC
- After you installed the HSM and before you start installing Certificate System:
- Reset the context of files in the
/opt/nfast/
directory:# restorecon -R /opt/nfast/
- Restart the nfast software.
# /opt/nfast/sbin/init.d-ncipher restart
- Thales Luna HSM
- No SELinux-related actions are required before you start installing Certificate System.
8.2.5. Installing a Subsystem Using nCipher nShield Connect XC HSM
- Prepare an override file, which corresponds to your particular deployment. The following
default_hms.txt
file is an example of such an override file:Note
This file serves only as an example of an nCipher HSM override configuration file -- numerous other values can be overridden including default hashing algorithms. Also, only one of the [CA], [KRA], [OCSP], [TKS], or [TPS] sections will be utilized depending upon the subsystem invocation specified on thepkispawn
command-line.Example 8.1. An Override File Sample to Use with nCipher HSM
############################################################################### ############################################################################### ############################################################################### ## ## ## EXAMPLE: Configuration File used to override '/etc/pki/default.cfg' ## ## when using an nCipher Hardware Security Module (HSM): ## ## ## ## ## ## # modutil -dbdir . -list ## ## ## ## Listing of PKCS #11 Modules ## ## ----------------------------------------------------------- ## ## 1. NSS Internal PKCS #11 Module ## ## slots: 2 slots attached ## ## status: loaded ## ## ## ## slot: NSS Internal Cryptographic Services ## ## token: NSS Generic Crypto Services ## ## ## ## slot: NSS User Private Key and Certificate Services ## ## token: NSS Certificate DB ## ## ## ## 2. nfast ## ## library name: /opt/nfast/toolkits/pkcs11/libcknfast.so ## ## slots: 2 slots attached ## ## status: loaded ## ## ## ## slot: <serial_number> Rt1 ## ## token: accelerator ## ## ## ## slot: <serial_number> Rt1 slot 0 ## ## token: <HSM_token_name> ## ## ----------------------------------------------------------- ## ## ## ## ## ## Based on the example above, substitute all password values, ## ## as well as the following values: ## ## ## ## <hsm_libfile>=/opt/nfast/toolkits/pkcs11/libcknfast.so ## ## <hsm_modulename>=nfast ## ## <hsm_token_name>=NHSM-CONN-XC ## ## ## ############################################################################### ############################################################################### ############################################################################### [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> ################################## # Provide PKI-specific passwords # ################################## pki_admin_password=<pki_admin_password> pki_client_pkcs12_password=<pki_client_pkcs12_password> pki_ds_password=<pki_ds_password> ##################################### # Provide non-CA-specific passwords # ##################################### pki_client_database_password=<pki_client_database_password> ############################################################### # ONLY required if specifying a non-default PKI instance name # ############################################################### #pki_instance_name=<pki_instance_name> ############################################################## # ONLY required if specifying non-default PKI instance ports # ############################################################## #pki_http_port=<pki_http_port> #pki_https_port=<pki_https_port> ###################################################################### # ONLY required if specifying non-default 389 Directory Server ports # ###################################################################### #pki_ds_ldap_port=<pki_ds_ldap_port> #pki_ds_ldaps_port=<pki_ds_ldaps_port> ###################################################################### # ONLY required if PKI is using a Security Domain on a remote system # ###################################################################### #pki_ca_hostname=<pki_ca_hostname> #pki_issuing_ca_hostname=<pki_issuing_ca_hostname> #pki_issuing_ca_https_port=<pki_issuing_ca_https_port> #pki_security_domain_hostname=<pki_security_domain_hostname> #pki_security_domain_https_port=<pki_security_domain_https_port> ########################################################### # ONLY required for PKI using an existing Security Domain # ########################################################### # NOTE: pki_security_domain_password == pki_admin_password # of CA Security Domain Instance #pki_security_domain_password=<pki_admin_password> [Tomcat] ############################################################## # ONLY required if specifying non-default PKI instance ports # ############################################################## #pki_ajp_port=<pki_ajp_port> #pki_tomcat_server_port=<pki_tomcat_server_port> [CA] ####################################### # Provide CA-specific HSM token names # ####################################### pki_ca_signing_token=<hsm_token_name> pki_ocsp_signing_token=<hsm_token_name> ########################################################################### # ONLY required if 389 Directory Server for CA resides on a remote system # ########################################################################### #pki_ds_hostname=<389 hostname> [KRA] ######################################## # Provide KRA-specific HSM token names # ######################################## pki_storage_token=<hsm_token_name> pki_transport_token=<hsm_token_name> ############################################################################ # ONLY required if 389 Directory Server for KRA resides on a remote system # ############################################################################ #pki_ds_hostname=<389 hostname> [OCSP] ######################################### # Provide OCSP-specific HSM token names # ######################################### pki_ocsp_signing_token=<hsm_token_name> ############################################################################# # ONLY required if 389 Directory Server for OCSP resides on a remote system # ############################################################################# #pki_ds_hostname=<389 hostname> [TKS] ######################################## # Provide TKS-specific HSM token names # ######################################## ############################################################################ # ONLY required if 389 Directory Server for TKS resides on a remote system # ############################################################################ #pki_ds_hostname=<389 hostname> [TPS] ################################### # Provide TPS-specific parameters # ################################### pki_authdb_basedn=<dnsdomainname where hostname.b.c.d is dc=b,dc=c,dc=d> ######################################## # Provide TPS-specific HSM token names # ######################################## ############################################################################ # ONLY required if 389 Directory Server for TPS resides on a remote system # ############################################################################ #pki_ds_hostname=<389 hostname> ########################################################## # ONLY required if TPS requires a CA on a remote machine # ########################################################## #pki_ca_uri=https://<pki_ca_hostname>:<pki_ca_https_port> ####################################### # ONLY required if TPS requires a KRA # ####################################### #pki_enable_server_side_keygen=True ########################################################### # ONLY required if TPS requires a KRA on a remote machine # ########################################################### #pki_kra_uri=https://<pki_kra_hostname>:<pki_kra_https_port> ########################################################### # ONLY required if TPS requires a TKS on a remote machine # ########################################################### #pki_tks_uri=https://<pki_tks_hostname>:<pki_tks_https_port>
- Use the configuration file as described in Section 7.7, “Two-step Installation”.
# pkispawn -s CA -f ./
default_hsm.txt
-vvv# pkispawn -s KRA -f ./
default_hsm.txt
-vvv# pkispawn -s OCSP -f ./
default_hsm.txt
-vvv# pkispawn -s TKS -f ./
default_hsm.txt
-vvv# pkispawn -s TPS -f ./
default_hsm.txt
-vvv
- Verify that the HSM contains the following certificates:
$ certutil -L -d /etc/pki/pki-tomcat/alias -h token -f token.pwd
Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI token:ca_signing CTu,Cu,Cu token:ca_ocsp_signing u,u,u token:subsystem u,u,u token:ca_audit_signing u,u,Pu token:sslserver/pki.example.com u,u,u
8.2.6. Installing a Subsystem Using Thales Luna HSM
Example 8.2. A Sample of the LunaSA Override File Header
############################################################################### ############################################################################### ############################################################################### ## ## ## EXAMPLE: Configuration File used to override '/etc/pki/default.cfg' ## ## when using a LunaSA Hardware Security Module (HSM): ## ## ## ## ## ## # modutil -dbdir . -list ## ## ## ## Listing of PKCS #11 Modules ## ## ----------------------------------------------------------- ## ## 1. NSS Internal PKCS #11 Module ## ## slots: 2 slots attached ## ## status: loaded ## ## ## ## slot: NSS Internal Cryptographic Services ## ## token: NSS Generic Crypto Services ## ## ## ## slot: NSS User Private Key and Certificate Services ## ## token: NSS Certificate DB ## ## ## ## 2. lunasa ## ## library name: /usr/safenet/lunaclient/lib/libCryptoki2_64.so ## ## slots: 4 slots attached ## ## status: loaded ## ## ## ## slot: LunaNet Slot ## ## token: dev-intca ## ## ## ## slot: Luna UHD Slot ## ## token: ## ## ## ## slot: Luna UHD Slot ## ## token: ## ## ## ## slot: Luna UHD Slot ## ## token: ## ## ----------------------------------------------------------- ## ## ## ## ## ## Based on the example above, substitute all password values, ## ## as well as the following values: ## ## ## ## <hsm_libfile>=/usr/safenet/lunaclient/lib/libCryptoki2_64.so ## ## <hsm_modulename>=lunasa ## ## <hsm_token_name>=dev-intca ## ## ## ############################################################################### ############################################################################### ###############################################################################
8.3. Backing up Keys on Hardware Security Modules
.p12
file. If such an instance is to be backed-up, contact the manufacturer of your HSM for support.
8.4. Installing a Clone Subsystem Using an HSM
pki_backup_keys
to True
in the configuration file you use for the installation along with the defined value for the pki_backup_password
option, or by exporting the keys using the PKCS12Export
tool.
PKCS12Export
when using an HSM because the keys cannot be retrieved from the HSM. Instead, the clone subsystem should either be pointed to the HSM used by the master subsystem, so that it can access the same keys. Alternatively, if using a separate HSM, clone the keys to this HSM using the utilities provided by the HSM vendor. You must provide access to the master subsystem's key before running the pkispawn
utility.
[CA] pki_clone=True pki_clone_pkcs12_password=Secret123 pki_clone_pkcs12_path=<path_to_pkcs12_file> pki_clone_replicate_schema=True pki_clone_uri=https://<master_ca_host_name>:<master_ca_https_port>
[CA] pki_clone=True pki_clone_replicate_schema=True pki_clone_uri=https://<master_ca_host_name>:<master_ca_https_port>
Note
8.5. Viewing Tokens
modutil
utility.
- Change to the instance
alias
directory. For example:# cd /var/lib/pki/pki-tomcat/alias
- Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the
modutil
tool.# modutil -dbdir . -nocertdb -list
8.6. Detecting Tokens
TokenInfo
utility, pointing to the alias
directory for the subsystem instance. This is a Certificate System tool which is available after the Certificate System packages are installed.
# TokenInfo /var/lib/pki/pki-tomcat/alias
Chapter 9. Installing an Instance with ECC System Certificates
Important
enforcing
mode to permissive
mode to allow the module to function. Otherwise, any subsystem operations which require the ECC module will fail.
9.1. Loading a Third-Party ECC Module
9.2. Using ECC with an HSM
- Set up the HSM per manufacturer's instructions. If multiple hosts are sharing the HSM, make sure they can all access the same partition if needed and if the site policies allow it.
- Define the required parameters in the
pkispawn
utility configuration file and runpkispawn
. For example, to configure Certificate System to create an ECC CA, assuming the configuration file is