Red Hat SummitDieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.
Planning, Installation, and Deployment Guide
Planning and installing Certificate System subsystems
Abstract
Part I. Planning how to deploy Red Hat Certificate System
This part provides an overview of Certificate System, including general PKI principles and specific features of Certificate System and its subsystems. Planning a deployment is vital to designing a PKI infrastructure that adequately meets the needs of your organization.
Chapter 1. Introduction to public-key cryptography
Public-key cryptography and related standards underlie the security features of many products such as signed and encrypted email, single sign-on, and Transport Layer Security/Secure Sockets Layer (SSL/TLS) communications. This chapter covers the basic concepts of public-key cryptography.
Internet traffic, which passes information through intermediate computers, can be intercepted by a third party:
- 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.netor 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.netcan purport to be an on-line furniture store when it really receives credit-card payments but never sends any goods. Public-key cryptography provides protection against Internet-based attacks through:
-
Spoofing. A person can pretend to be someone else. For example, a person can pretend to have the email address
- 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
Encryption is the process of transforming information so it is unintelligible to anyone but the intended recipient. Decryption is the process of decoding encrypted information. A cryptographic algorithm, also called a cipher, is a mathematical function used for encryption or decryption. Usually, two related functions are used, one for encryption and the other for decryption.
With most modern cryptography, the ability to keep encrypted information secret is based not on the cryptographic algorithm, which is widely known, but on a number called a key that must be used with the algorithm to produce an encrypted result or to decrypt previously encrypted information. Decryption with the correct key is simple. Decryption without the correct key is very difficult, if not impossible.
1.1.1. Symmetric-key encryption
With symmetric-key encryption, the encryption key can be calculated from the decryption key and vice versa. With most symmetric algorithms, the same key is used for both encryption and decryption, as shown in Figure 1.1, “Symmetric-key encryption”.
Figure 1.1. Symmetric-key encryption
Implementations of symmetric-key encryption can be highly efficient, so that users do not experience any significant time delay as a result of the encryption and decryption.
Symmetric-key encryption is effective only if the symmetric key is kept secret by the two parties involved. If anyone else discovers the key, it affects both confidentiality and authentication. A person with an unauthorized symmetric key not only can decrypt messages sent with that key, but can encrypt new messages and send them as if they came from one of the legitimate parties using the key.
Symmetric-key encryption plays an important role in SSL/TLS communication, which is widely used for authentication, tamper detection, and encryption over TCP/IP networks. SSL/TLS also uses techniques of public-key encryption, which is described in the next section.
1.1.2. Public-key encryption
Public-key encryption (also called asymmetric encryption) involves a pair of keys, a public key and a private key, associated with an entity. Each public key is published, and the corresponding private key is kept secret. (For more information about the way public keys are published, see Section 1.3, “Certificates and authentication”.) Data encrypted with a public key can be decrypted only with the corresponding private key. Figure 1.2, “Public-key encryption” shows a simplified view of the way public-key encryption works.
Figure 1.2. Public-key encryption
The scheme shown in Figure 1.2, “Public-key encryption” allows public keys to be freely distributed, while only authorized people are able to read data encrypted using this key. In general, to send encrypted data, the data is encrypted with that person’s public key, and the person receiving the encrypted data decrypts it with the corresponding private key.
Compared with symmetric-key encryption, public-key encryption requires more processing and may not be feasible for encrypting and decrypting large amounts of data. However, it is possible to use public-key encryption to send a symmetric key, which can then be used to encrypt additional data. This is the approach used by the SSL/TLS protocols.
The reverse of the scheme shown in Figure 1.2, “Public-key encryption” also works: data encrypted with a private key can be decrypted only with the corresponding public key. This is not a recommended practice to encrypt sensitive data, however, because it means that anyone with the public key, which is by definition published, could decrypt the data. Nevertheless, private-key encryption is useful because it means the private key can be used to sign data with a digital signature, an important requirement for electronic commerce and other commercial applications of cryptography. Client software such as Mozilla Firefox can then use the public key to confirm that the message was signed with the appropriate private key and that it has not been tampered with since being signed. Section 1.2, “Digital signatures” illustrates how this confirmation process works.
1.1.3. Key length and encryption strength
Breaking an encryption algorithm is finding the key to the access the encrypted data in plain text. For symmetric algorithms, breaking the algorithm usually means trying to determine the key used to encrypt the text. For a public key algorithm, breaking the algorithm usually means acquiring the shared secret information between two recipients.
One method of breaking a symmetric algorithm is to simply try every key within the full algorithm until the right key is found. For public key algorithms, since half of the key pair is publicly known, the other half (private key) can be derived using published, though complex, mathematical calculations. Manually finding the key to break an algorithm is called a brute force attack.
Breaking an algorithm introduces the risk of intercepting, or even impersonating and fraudulently verifying, private information.
The key strength of an algorithm is determined by finding the fastest method to break the algorithm and comparing it to a brute force attack.
For symmetric keys, encryption strength is often described in terms of the size or length of the keys used to perform the encryption: longer keys generally provide stronger encryption. Key length is measured in bits.
An encryption key is considered full strength if the best known attack to break the key is no faster than a brute force attempt to test every key possibility.
Different types of algorithms -particularly public key algorithms -may require different key lengths to achieve the same level of encryption strength as a symmetric-key cipher. The RSA cipher can use only a subset of all possible values for a key of a given length, due to the nature of the mathematical problem on which it is based. Other ciphers, such as those used for symmetric-key encryption, can use all possible values for a key of a given length. More possible matching options means more security.
Because it is relatively trivial to break an RSA key, an RSA public-key encryption cipher must have a very long key -at least 2048 bits -to be considered cryptographically strong. On the other hand, symmetric-key ciphers are reckoned to be equivalently strong using a much shorter key length, as little as 80 bits for most algorithms. Similarly, public-key ciphers based on the elliptic curve cryptography (ECC), such as the Elliptic Curve Digital Signature Algorithm (ECDSA) ciphers, also require less bits than RSA ciphers.
1.2. Digital signatures
Tamper detection relies on a mathematical function called a one-way hash (also called a message digest). A one-way hash is a number of fixed length with the following characteristics:
- 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.
As mentioned in Section 1.1.2, “Public-key encryption”, it is possible to use a private key for encryption and the corresponding public key for decryption. Although not recommended when encrypting sensitive information, it is a crucial part of digitally signing any data. Instead of encrypting the data itself, the signing software creates a one-way hash of the data, then uses the private key to encrypt the hash. The encrypted hash, along with other information such as the hashing algorithm, is known as a digital signature.
Figure 1.3, “Using a digital signature to validate data integrity” illustrates the way a digital signature can be used to validate the integrity of signed data.
Figure 1.3. Using a digital signature to validate data integrity
Figure 1.3, “Using a digital signature to validate data integrity” shows two items transferred to the recipient of some signed data: the original data and the digital signature, which is a one-way hash of the original data encrypted with the signer’s private key. To validate the integrity of the data, the receiving software first uses the public key to decrypt the hash. It then uses the same hashing algorithm that generated the original hash to generate a new one-way hash of the same data. (Information about the hashing algorithm used is sent with the digital signature.) Finally, the receiving software compares the new hash against the original hash. If the two hashes match, the data has not changed since it was signed. If they do not match, the data may have been tampered with since it was signed, or the signature may have been created with a private key that does not correspond to the public key presented by the signer.
If the two hashes match, the recipient can be certain that the public key used to decrypt the digital signature corresponds to the private key used to create the digital signature. Confirming the identity of the signer also requires some way of confirming that the public key belongs to a particular entity. For more information on authenticating users, see Section 1.3, “Certificates and authentication”.
A digital signature is similar to a handwritten signature. Once data have been signed, it is difficult to deny doing so later, assuming the private key has not been compromised. This quality of digital signatures provides a high degree of nonrepudiation; digital signatures make it difficult for the signer to deny having signed the data. In some situations, a digital signature is as legally binding as a handwritten signature.
1.3. Certificates and authentication
1.3.1. A certificate identifies someone or something
A certificate is an electronic document used to identify an individual, a server, a company, or other entity and to associate that identity with a public key. Like a driver’s license or passport, a certificate provides generally recognized proof of a person’s identity. Public-key cryptography uses certificates to address the problem of impersonation.
To get personal ID such as a driver’s license, a person has to present some other form of identification which confirms that the person is who he claims to be. Certificates work much the same way. Certificate authorities (CAs) validate identities and issue certificates. CAs can be either independent third parties or organizations running their own certificate-issuing server software, such as Certificate System. The methods used to validate an identity vary depending on the policies of a given CA for the type of certificate being requested. Before issuing a certificate, a CA must confirm the user’s identity with its standard verification procedures.
The certificate issued by the CA binds a particular public key to the name of the entity the certificate identifies, such as the name of an employee or a server. Certificates help prevent the use of fake public keys for impersonation. Only the public key certified by the certificate will work with the corresponding private key possessed by the entity identified by the certificate.
In addition to a public key, a certificate always includes the name of the entity it identifies, an expiration date, the name of the CA that issued the certificate, and a serial number. Most importantly, a certificate always includes the digital signature of the issuing CA. The CA’s digital signature allows the certificate to serve as a valid credential for users who know and trust the CA but do not know the entity identified by the certificate.
For more information about the role of CAs, see Section 1.3.6, “How CA certificates establish trust”.
1.3.2. Authentication confirms an identity
Authentication is the process of confirming an identity. For network interactions, authentication involves the identification of one party by another party. There are many ways to use authentication over networks. Certificates are one of those way.
Network interactions typically take place between a client, such as a web browser, and a server. Client authentication refers to the identification of a client (the person assumed to be using the software) by a server. Server authentication refers to the identification of a server (the organization assumed to be running the server at the network address) by a client.
Client and server authentication are not the only forms of authentication that certificates support. For example, the digital signature on an email message, combined with the certificate that identifies the sender, can authenticate the sender of the message. Similarly, a digital signature on an HTML form, combined with a certificate that identifies the signer, can provide evidence that the person identified by that certificate agreed to the contents of the form. In addition to authentication, the digital signature in both cases ensures a degree of nonrepudiation; a digital signature makes it difficult for the signer to claim later not to have sent the email or the form.
Client authentication is an essential element of network security within most intranets or extranets. There are two main forms of client authentication:
- Password-based authentication
- Almost all server software permits client authentication by requiring a recognized name and password before granting access to the server.
- Certificate-based authentication
- Client authentication based on certificates is part of the SSL/TLS protocol. The client digitally signs a randomly generated piece of data and sends both the certificate and the signed data across the network. The server validates the signature and confirms the validity of the certificate.
1.3.2.1. Password-based authentication
Figure 1.4, “Using a password to authenticate a client to a server” shows the process of authenticating a user using a user name and password. This example assumes the following:
- 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
These are the steps in this authentication process:
- 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.
With this arrangement, the user must supply a new password for each server accessed, and the administrator must keep track of the name and password for each user.
1.3.2.2. Certificate-based authentication
One of the advantages of certificate-based authentication is that it can be used to replace the first three steps in authentication with a mechanism that allows the user to supply one password, which is not sent across the network, and allows the administrator to control user authentication centrally. This is called single sign-on.
Figure 1.5, “Using a certificate to authenticate a client to a server” shows how client authentication works using certificates and SSL/TLS. To authenticate a user to a server, a client digitally signs a randomly generated piece of data and sends both the certificate and the signed data across the network. The server authenticates the user’s identity based on the data in the certificate and signed data.
Like Figure 1.4, “Using a password to authenticate a client to a server”, Figure 1.5, “Using a certificate to authenticate a client to a server” assumes that the user has already trusted the server and requested a resource and that the server has requested client authentication before granting access to the requested resource.
Figure 1.5. Using a certificate to authenticate a client to a server
Unlike the authentication process in Figure 1.4, “Using a password to authenticate a client to a server”, the authentication process in Figure 1.5, “Using a certificate to authenticate a client to a server” requires SSL/TLS. Figure 1.5, “Using a certificate to authenticate a client to a server” also assumes that the client has a valid certificate that can be used to identify the client to the server. Certificate-based authentication is preferred to password-based authentication because it is based on the user both possessing the private key and knowing the password. However, these two assumptions are true only if unauthorized personnel have not gained access to the user’s machine or password, the password for the client software’s private key database has been set, and the software is set up to request the password at reasonably frequent intervals.
Neither password-based authentication nor certificate-based authentication address security issues related to physical access to individual machines or passwords. Public-key cryptography can only verify that a private key used to sign some data corresponds to the public key in a certificate. It is the user’s responsibility to protect a machine’s physical security and to keep the private-key password secret.
These are the authentication steps shown in Figure 1.5, “Using a certificate to authenticate a client to a server”:
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.
Certificates replace the authentication portion of the interaction between the client and the server. Instead of requiring a user to send passwords across the network continually, single sign-on requires the user to enter the private-key database password once, without sending it across the network. For the rest of the session, the client presents the user’s certificate to authenticate the user to each new server it encounters. Existing authorization mechanisms based on the authenticated user identity are not affected.
1.3.3. Uses for certificates
The purpose of certificates is to establish trust. Their usage varies depending on the kind of trust they are used to ensure. Some kinds of certificates are used to verify the identity of the presenter; others are used to verify that an object or item has not been tampered with.
1.3.3.1. SSL/TLS
The Transport Layer Security/Secure Sockets Layer (SSL/TLS) protocol governs server authentication, client authentication, and encrypted communication between servers and clients. SSL/TLS is widely used on the Internet, especially for interactions that involve exchanging confidential information such as credit card numbers.
SSL/TLS requires an SSL/TLS server certificate. As part of the initial SSL/TLS handshake, the server presents its certificate to the client to authenticate the server’s identity. The authentication uses public-key encryption and digital signatures to confirm that the server is the server it claims to be. Once the server has been authenticated, the client and server use symmetric-key encryption, which is very fast, to encrypt all the information exchanged for the remainder of the session and to detect any tampering.
Servers may be configured to require client authentication as well as server authentication. In this case, after server authentication is successfully completed, the client must also present its certificate to the server to authenticate the client’s identity before the encrypted SSL/TLS session can be established.
For an overview of client authentication over SSL/TLS and how it differs from password-based authentication, see Section 1.3.2, “Authentication confirms an identity”.
1.3.3.2. Signed and encrypted email
Some email programs support digitally signed and encrypted email using a widely accepted protocol known as Secure Multipurpose Internet Mail Extension (S/MIME). Using S/MIME to sign or encrypt email messages requires the sender of the message to have an S/MIME certificate.
An email message that includes a digital signature provides some assurance that it was sent by the person whose name appears in the message header, thus authenticating the sender. If the digital signature cannot be validated by the email software, the user is alerted.
The digital signature is unique to the message it accompanies. If the message received differs in any way from the message that was sent, even by adding or deleting a single character, the digital signature cannot be validated. Therefore, signed email also provides assurance that the email has not been tampered with. This kind of assurance is known as nonrepudiation, which makes it difficult for the sender to deny having sent the message. This is important for business communication. For information about the way digital signatures work, see Section 1.2, “Digital signatures”.
S/MIME also makes it possible to encrypt email messages, which is important for some business users. However, using encryption for email requires careful planning. If the recipient of encrypted email messages loses the private key and does not have access to a backup copy of the key, the encrypted messages can never be decrypted.
1.3.3.3. Single sign-on
Network users are frequently required to remember multiple passwords for the various services they use. For example, a user might have to type a different password to log into the network, collect email, use directory services, use the corporate calendar program, and access various servers. Multiple passwords are an ongoing headache for both users and system administrators. Users have difficulty keeping track of different passwords, tend to choose poor ones, and tend to write them down in obvious places. Administrators must keep track of a separate password database on each server and deal with potential security problems related to the fact that passwords are sent over the network routinely and frequently.
Solving this problem requires some way for a user to log in once, using a single password, and get authenticated access to all network resources that user is authorized to use-without sending any passwords over the network. This capability is known as single sign-on.
Both client SSL/TLS certificates and S/MIME certificates can play a significant role in a comprehensive single sign-on solution. For example, one form of single sign-on supported by Red Hat products relies on SSL/TLS client authentication. A user can log in once, using a single password to the local client’s private-key database, and get authenticated access to all SSL/TLS-enabled servers that user is authorized to use-without sending any passwords over the network. This approach simplifies access for users, because they do not need to enter passwords for each new server. It also simplifies network management, since administrators can control access by controlling lists of certificate authorities (CAs) rather than much longer lists of users and passwords.
In addition to using certificates, a complete single-sign on solution must address the need to interoperate with enterprise systems, such as the underlying operating system, that rely on passwords or other forms of authentication.
1.3.3.4. Object signing
Many software technologies support a set of tools called object signing. Object signing uses standard techniques of public-key cryptography to let users get reliable information about code they download in much the same way they can get reliable information about shrink-wrapped software.
Most important, object signing helps users and network administrators implement decisions about software distributed over intranets or the Internet-for example, whether to allow Java applets signed by a given entity to use specific computer capabilities on specific users' machines.
The objects signed with object signing technology can be applets or other Java code, JavaScript scripts, plug-ins, or any kind of file. The signature is a digital signature. Signed objects and their signatures are typically stored in a special file called a JAR file.
Software developers and others who wish to sign files using object-signing technology must first obtain an object-signing certificate.
1.3.4. Types of Certificates
The Certificate System is capable of generating different types of certificates for different uses and in different formats. Planning which certificates are required and planning how to manage them, including determining what formats are needed and how to plan for renewal, are important to manage both the PKI and the Certificate System instances.
This list is not exhaustive; there are certificate enrollment forms for dual-use certificates for LDAP directories, file-signing certificates, and other subsystem certificates. These forms are available through the Certificate Manager’s end-entities page, at ui`8443/ca/ee/ca`.
When the different Certificate System subsystems are installed, the basic required certificates and keys are generated; for example, configuring the Certificate Manager generates the CA signing certificate for the self-signed root CA and the internal OCSP signing, audit signing, SSL/TLS server, and agent user certificates. During the KRA configuration, the Certificate Manager generates the storage, transport, audit signing, and agent certificates. Additional certificates can be created and installed separately.
| 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
Every Certificate Manager has a CA signing certificate with a public/private key pair it uses to sign the certificates and certificate revocation lists (CRLs) it issues. This certificate is created and installed when the Certificate Manager is installed.
For more information about CRLs, see Section 2.4.4, “Revoking certificates and checking status”.
The Certificate Manager’s status as a root or subordinate CA is determined by whether its CA signing certificate is self-signed or is signed by another CA. Self-signed root CAs set the policies they use to issue certificates, such as the subject names, types of certificates that can be issued, and to whom certificates can be issued. A subordinate CA has a CA signing certificate signed by another CA, usually the one that is a level above in the CA hierarchy (which may or may not be a root CA). If the Certificate Manager is a subordinate CA in a CA hierarchy, the root CA’s signing certificate must be imported into individual clients and servers before the Certificate Manager can be used to issue certificates to them.
The CA certificate must be installed in a client if a server or user certificate issued by that CA is installed on that client. The CA certificate confirms that the server certificate can be trusted. Ideally, the certificate chain is installed.
1.3.4.2. Other signing certificates
Other services, such as the Online Certificate Status Protocol (OCSP) responder service and CRL publishing, can use signing certificates other than the CA certificate. For example, a separate CRL signing certificate can be used to sign the revocation lists that are published by a CA instead of using the CA signing certificate.
For more information about OCSP, see Section 2.4.4, “Revoking certificates and checking status”.
1.3.4.3. SSL/TLS server and client certificates
Server certificates are used for secure communications, such as SSL/TLS, and other secure functions. Server certificates are used to authenticate themselves during operations and to encrypt data; client certificates authenticate the client to the server.
CAs which have a signing certificate issued by a third-party may not be able to issue server certificates. The third-party CA may have rules in place which prohibit its subordinates from issuing server certificates.
1.3.4.4. User certificates
End user certificates are a subset of client certificates that are used to identify users to a server or system. Users can be assigned certificates to use for secure communications, such as SSL/TLS, and other functions such as encrypting email or for single sign-on. Special users, such as Certificate System agents, can be given client certificates to access special services.
1.3.4.5. Dual-key pairs
Dual-key pairs are a set of two private and public keys, where one set is used for signing and one for encryption. These dual keys are used to create dual certificates. The dual certificate enrollment form is one of the standard forms listed in the end-entities page of the Certificate Manager.
When generating dual-key pairs, set the certificate profiles to work correctly when generating separate certificates for signing and encryption.
1.3.4.6. Cross-pair certificates
The Certificate System can issue, import, and publish cross-pair CA certificates. With cross-pair certificates, one CA signs and issues a cross-pair certificate to a second CA, and the second CA signs and issues a cross-pair certificate to the first CA. Both CAs then store or publish both certificates as a crossCertificatePair entry.
Bridging certificates can be done to honor certificates issued by a CA that is not chained to the root CA. By establishing a trust between the Certificate System CA and another CA through a cross-pair CA certificate, the cross-pair certificate can be downloaded and used to trust the certificates issued by the other CA.
1.3.5. Contents of a certificate
The contents of certificates are organized according to the X.509 v3 certificate specification, which has been recommended by the International Telecommunications Union (ITU), an international standards body.
Users do not usually need to be concerned about the exact contents of a certificate. However, system administrators working with certificates may need some familiarity with the information contained in them.
1.3.5.1. Certificate data formats
Certificate requests and certificates can be created, stored, and installed in several different formats. All of these formats conform to X.509 standards.
1.3.5.1.1. Binary
The following binary formats are recognized:
- DER-encoded certificate. This is a single binary DER-encoded certificate.
-
PKCS #7 certificate chain. This is a PKCS #7
SignedDataobject. The only significant field in theSignedDataobject 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
ContentInfostructure, wrapping a sequence of certificates. The value of thecontentTypefield should benetscape-cert-sequence, while the content field has the following structure:CertificateSequence ::= SEQUENCE OF Certificate
CertificateSequence ::= SEQUENCE OF CertificateCopy to Clipboard Copied! Toggle word wrap Toggle overflow This format allows multiple certificates to be downloaded at the same time.
1.3.5.1.2. Text
Any of the binary formats can be imported in text form. The text form begins with the following line:
-----BEGIN CERTIFICATE-----
-----BEGIN CERTIFICATE-----Following this line is the certificate data, which can be in any of the binary formats described. This data should be base-64 encoded, as described by RFC 1113. The certificate information is followed by this line:
-----END CERTIFICATE-----
-----END CERTIFICATE-----1.3.5.2. Distinguished names
An X.509 v3 certificate binds a distinguished name (DN) to a public key. A DN is a series of name-value pairs, such as uid=doe, that uniquely identify an entity. This is also called the certificate subject name.
This is an example DN of an employee for Example Corp.:
uid=doe,cn=John Doe,o=Example Corp.,c=US
uid=doe,cn=John Doe,o=Example Corp.,c=US
In this DN, uid is the user name, cn is the user’s common name, o is the organization or company name, and c is the country.
DNs may include a variety of other name-value pairs. They are used to identify both certificate subjects and entries in directories that support the Lightweight Directory Access Protocol (LDAP).
The rules governing the construction of DNs can be complex; for comprehensive information about DNs, see A String Representation of Distinguished Names at http://www.ietf.org/rfc/rfc4514.txt.
1.3.5.3. A typical certificate
Every X.509 certificate consists of two sections:
- 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. Here are the data and signature sections of a certificate shown in the readable pretty-print format:
Here is the same certificate in the base-64 encoded format:
1.3.6. How CA certificates establish trust
CAs validate identities and issue certificates. They can be either independent third parties or organizations running their own certificate-issuing server software, such as the Certificate System.
Any client or server software that supports certificates maintains a collection of trusted CA certificates. These CA certificates determine which issuers of certificates the software can trust, or validate. In the simplest case, the software can validate only certificates issued by one of the CAs for which it has a certificate. It is also possible for a trusted CA certificate to be part of a chain of CA certificates, each issued by the CA above it in a certificate hierarchy.
The sections that follow explains how certificate hierarchies and certificate chains determine what certificates software can trust.
1.3.6.1. CA hierarchies
In large organizations, responsibility for issuing certificates can be delegated to several different CAs. For example, the number of certificates required may be too large for a single CA to maintain; different organizational units may have different policy requirements; or a CA may need to be physically located in the same geographic area as the people to whom it is issuing certificates.
These certificate-issuing responsibilities can be divided among subordinate CAs. The X.509 standard includes a model for setting up a hierarchy of CAs, shown in Figure 1.6, “Example of a hierarchy of certificate authorities”.
Figure 1.6. Example of a hierarchy of certificate authorities
The root CA is at the top of the hierarchy. The root CA’s certificate is a self-signed certificate; that is, the certificate is digitally signed by the same entity that the certificate identifies. The CAs that are directly subordinate to the root CA have CA certificates signed by the root CA. CAs under the subordinate CAs in the hierarchy have their CA certificates signed by the higher-level subordinate CAs.
Organizations have a great deal of flexibility in how CA hierarchies are set up; Figure 1.6, “Example of a hierarchy of certificate authorities” shows just one example.
1.3.6.2. Certificate chains
CA hierarchies are reflected in certificate chains. A certificate chain is series of certificates issued by successive CAs. Figure 1.7, “Example of a certificate chain” shows a certificate chain leading from a certificate that identifies an entity through two subordinate CA certificates to the CA certificate for the root CA, based on the CA hierarchy shown in Figure 1.6, “Example of a hierarchy of certificate authorities”.
Figure 1.7. Example of a certificate chain
A certificate chain traces a path of certificates from a branch in the hierarchy to the root of the hierarchy. In a certificate chain, the following occur:
- 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 CAcertificate 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 CAcan be used to verify theUSA CA's digital signature on the certificate for theEngineering CA.
1.3.6.3. Verifying a certificate chain
Certificate chain verification makes sure a given certificate chain is well-formed, valid, properly signed, and trustworthy. The following description of the process covers the most important steps of forming and verifying a certificate chain, starting with the certificate being presented for authentication:
- 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
Figure 1.8, “Verifying a certificate chain to the root CA” illustrates what happens when only the root CA is included in the verifier’s local database. If a certificate for one of the intermediate CAs, such as 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
Expired validity dates, an invalid signature, or the absence of a certificate for the issuing CA at any point in the certificate chain causes authentication to fail. Figure 1.10, “A certificate chain that cannot be verified” shows how verification fails if neither the root CA certificate nor any of the intermediate CA certificates are included in the verifier’s local database.
Figure 1.10. A certificate chain that cannot be verified
1.3.7. Certificate status
For more information on Certificate Revocation List (CRL), see Section 2.4.4.2.1, “CRLs”
For more information on Online Certificate Status Protocol (OCSP), see Section 2.4.4.2.2, “OCSP services”
1.4. Certificate life cycle
Certificates are used in many applications, from encrypting email to accessing websites. There are two major stages in the lifecycle of the certificate: the point when it is issued (issuance and enrollment) and the period when the certificates are no longer valid (renewal or revocation). There are also ways to manage the certificate during its cycle. Making information about the certificate available to other applications is publishing the certificate and then backing up the key pairs so that the certificate can be recovered if it is lost.
1.4.1. Certificate issuance
The process for issuing a certificate depends on the CA that issues it and the purpose for which it will be used. Issuing non-digital forms of identification varies in similar ways. The requirements to get a library card are different than the ones to get a driver’s license. Similarly, different CAs have different procedures for issuing different kinds of certificates. Requirements for receiving a certificate can be as simple as an email address or user name and password to notarized documents, a background check, and a personal interview.
Depending on an organization’s policies, the process of issuing certificates can range from being completely transparent for the user to requiring significant user participation and complex procedures. In general, processes for issuing certificates should be flexible, so organizations can tailor them to their changing needs.
1.4.2. Certificate expiration and renewal
Like a driver’s license, a certificate specifies a period of time during which it is valid. Attempts to use a certificate for authentication before or after its validity period will fail. Managing certificate expirations and renewals are an essential part of the certificate management strategy. For example, an administrator may wish to be notified automatically when a certificate is about to expire so that an appropriate renewal process can be completed without disrupting the system operation. The renewal process may involve reusing the same public-private key pair or issuing a new one.
Additionally, it may be necessary to revoke a certificate before it has expired, such as when an employee leaves a company or moves to a new job in a different unit within the company.
Certificate revocation can be handled in several different ways:
- 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.
For more information about renewing certificates, see Section 2.4.2, “Renewing certificates”. For more information about revoking certificates, including CRLs and OCSP, see Section 2.4.4, “Revoking certificates and checking status”.
1.5. Key management
Before a certificate can be issued, the public key it contains and the corresponding private key must be generated. Sometimes it may be useful to issue a single person one certificate and key pair for signing operations and another certificate and key pair for encryption operations. Separate signing and encryption certificates keep the private signing key only on the local machine, providing maximum nonrepudiation. This also aids in backing up the private encryption key in some central location where it can be retrieved in case the user loses the original key or leaves the company.
Keys can be generated by client software or generated centrally by the CA and distributed to users through an LDAP directory. There are costs associated with either method. Local key generation provides maximum nonrepudiation but may involve more participation by the user in the issuing process. Flexible key management capabilities are essential for most organizations.
Key recovery , or the ability to retrieve backups of encryption keys under carefully defined conditions, can be a crucial part of certificate management, depending on how an organization uses certificates. In some PKI setups, several authorized personnel must agree before an encryption key can be recovered to ensure that the key is only recovered to the legitimate owner in authorized circumstance. It can be necessary to recover a key when information is encrypted and can only be decrypted by the lost key.
Chapter 2. Introduction to Red Hat Certificate System
Every common PKI operation, such as issuing, renewing, and revoking certificates; archiving and recovering keys; publishing CRLs and verifying certificate status, is carried out by interoperating subsystems within Red Hat Certificate System. The functions of each individual subsystem and the way that they work together to establish a robust and local PKI is described in this chapter.
2.1. A review of Certificate System subsystems
Red Hat Certificate System provides five different subsystems, each focusing on different aspects of a PKI deployment:
- A certificate authority called Certificate Manager. The CA is the core of the PKI; it issues and revokes all certificates. The Certificate Manager is also the core of the Certificate System. By establishing a security domain of trusted subsystems, it establishes and manages relationships between the other subsystems.
A key recovery authority (KRA). Certificates are created based on a specific and unique key pair. If a private key is ever lost, then the data which that key was used to access (such as encrypted emails) is also lost because it is inaccessible. The KRA stores key pairs, so that a new, identical certificate can be generated based on recovered keys, and all of the encrypted data can be accessed even after a private key is lost or damaged.
NoteIn 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.
Even with all possible subsystems installed, the core of the Certificate System is still the CA (or CAs), since they ultimately process all certificate-related requests. The other subsystems connect to the CA or CAs likes spokes in a wheel. These subsystems work together, in tandem, to create a public key infrastructure (PKI). Depending on what subsystems are installed, a PKI can function in one (or both) of two ways:
- A token management system or TMS environment, which manages smart cards. This requires a CA, TKS, and TPS, with an optional KRA for server-side key generation.
- A traditional non token management system or non-TMS environment, which manages certificates used in an environment other than smart cards, usually in software databases. At a minimum, a non-TMS requires only a CA, but a non-TMS environment can use OCSP responders and KRA instances as well.
2.2. Overview of Certificate System subsystems
2.2.2. Instance installation prerequisites
2.2.2.1. Directory Server instance availability
Prior to installation of a Certificate System instance, a local or remote Red Hat Directory Server LDAP instance must be available. For instructions on installing Red Hat Directory Server, see the Red Hat Directory Server Installation Guide.
2.2.2.2. PKI packages
Red Hat Certificate System is composed of packages listed below:
- redhat-pki
- redhat-pki-base
- #redhat-pki-java
- #redhat-pki-javadoc
- python3-redhat-pki
- redhat-pki-tools
- redhat-pki-server
- redhat-pki-theme
- redhat-pki-ca
- redhat-pki-kra
- redhat-pki-ocsp
- redhat-pki-tks
- redhat-pki-tps
- redhat-pki-acme
- redhat-pki-est
- redhat-pki-console
- redhat-pki-console-theme
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.3.2.3, “Attaching a Red Hat subscription and enabling the Certificate System package repository”.
Use a Red Hat Enterprise Linux 8 system (optionally, use one that has been configured with a supported Hardware Security Module listed in Chapter 4, Supported platforms), and make sure that all packages are up to date before installing Red Hat Certificate System.
To install all Certificate System packages (with the exception of pki-javadoc), use dnf to install the redhat-pki metapackage:
dnf install redhat-pki
# dnf install redhat-pkiAlternatively, you can install one or more of the top level PKI subsystem packages as required; see the list above for exact package names. If you use this approach, make sure to also install the redhat-pki-server-theme package, and optionally redhat-pki-console-theme and pki-console to use the PKI Console.
Finally, developers and administrators may also want to install the JSS and PKI javadocs (the jss-javadoc and pki-javadoc).
The jss-javadoc package requires you to enable the Server-Optional repository in Subscription Manager.
2.2.2.3. Instance installation and configuration
The pkispawn command line tool is used to install and configure a new PKI instance. It eliminates the need for separate installation and configuration steps, and may be run either interactively, as a batch process, or a combination of both (batch process with prompts for passwords). The utility does not provide a way to install or configure the browser-based graphical interface. For details on how to use pkispawn, see Installing RHCS using the pkispawn utility.
2.2.2.4. Instance removal
To remove an existing PKI instance, use the pkidestroy command. It can be run interactively or as a batch process. Use pkidestroy -h to display detailed usage information on the command line.
The pkidestroy command reads in a PKI subsystem deployment configuration file which was stored when the subsystem was created (/var/lib/pki/instance_name/<subsystem>/registry/<subsystem>/deployment.cfg), uses the read-in file in order to remove the PKI subsystem, and then removes the PKI instance if it contains no additional subsystems. See the pkidestroy man page for more information.
An interactive removal procedure using pkidestroy may look similar to the following:
A non-interactive removal procedure may look similar to the following example:
Key pairs are not deleted when a hardware token or a hardware security module (HSM) is used because you can have clone instances. Key pairs are only deleted when a soft token is used.
This is important because you can easily recreate instances and fill up a HSM memory without realizing the tokens are left in the HSM.
In this case, your certutil command output can look similar to the following example, using an environment variable $nssdb to point to a local NSS DB already initialized to reach to the HSM, and different from the PKI’s NSS DBs:
Destroy an instance, for example:
pkidestroy -v -i 2023-10-03-0139-10.4-rootca1 -s CA 2>&1 | tee ~/pkidestroy.2023-10-03-0139-10.4-rootca1.out.1.txt
# pkidestroy -v -i 2023-10-03-0139-10.4-rootca1 -s CA 2>&1 | tee ~/pkidestroy.2023-10-03-0139-10.4-rootca1.out.1.txtVerify that the instance has been deleted, for example:
pki-server instance-find
pki-server instance-findVerify the private keys from the deleted PKI instance till exist on the hardware token:
If you really need to delete those private keys, either use the certutil -F commands or the manufacturer tool, for example Luna Client cmu list and cmu delete with some options.
Following is a certutil example, with an already initialized NSS db directory:
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:auditSigningCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:Server-Cert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:subsystemCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:ocspSigningCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:caSigningCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:auditSigningCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:Server-Cert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:subsystemCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:ocspSigningCert cert-2023-10-03-0139-10.4-rootca1 CA"
certutil -F -d ${nssdb} -f ${nssdb}/hsm.password.txt -h thalesLunaDEV -n "thalesLunaDEV:caSigningCert cert-2023-10-03-0139-10.4-rootca1 CA"Optional. Delete the system trust certificate or issuer or trust chain associated with a removed CA signing cert if there was one, for example:
2.2.3. Execution management (systemctl)
2.2.3.1. Starting, stopping, restarting, and obtaining status
Red Hat Certificate System subsystem instances can be stopped and started using the systemctl execution management system tool on Red Hat Enterprise Linux 8:
systemctl start <unit-file>@instance_name.service
# systemctl start <unit-file>@instance_name.servicesystemctl status <unit-file>@instance_name.service
# systemctl status <unit-file>@instance_name.servicesystemctl stop <unit-file>@instance_name.service
# systemctl stop <unit-file>@instance_name.servicesystemctl restart <unit-file>@instance_name.service
# systemctl restart <unit-file>@instance_name.service<unit-file> has one of the following values:
pki-tomcatd With watchdog disabled pki-tomcatd-nuxwdog With watchdog enabled
pki-tomcatd With watchdog disabled
pki-tomcatd-nuxwdog With watchdog enabled
For more details on the watchdog service, refer to the Section 2.3.9, “Passwords and watchdog (nuxwdog)” and Using the Certificate System Watchdog Service sections in the Red Hat Certificate System Administration Guide.
In RHCS 10, these systemctl actions support the pki-server alias: pki-server <command> subsystem_instance_name is the alias for systemctl <command> pki-tomcatd@<instance>.service.
2.2.3.2. Starting the instance automatically
The systemctl utility in Red Hat Enterprise Linux manages the automatic startup and shutdown settings for each process on the server. This means that when a system reboots, some services can be automatically restarted. System unit files control service startup to ensure that services are started in the correct order. The systemd service and systemctl utility are described in the Configuring basic system settings guide for Red Hat Enterprise Linux 8.
Certificate System instances can be managed by systemctl, so this utility can set whether to restart instances automatically. After a Certificate System instance is created, it is enabled on boot. This can be changed by using systemctl:
systemctl disable pki-tomcatd@instance_name.service
# systemctl disable pki-tomcatd@instance_name.serviceTo re-enable the instance:
systemctl enable pki-tomcatd@instance_name.service
# systemctl enable pki-tomcatd@instance_name.service
The systemctl enable and systemctl disable commands do not immediately start or stop Certificate System.
2.2.4. Process management (pki-server)
2.2.4.1. The pki-server command line tool
The primary process management tool for Red Hat Certificate System is pki-server. Use the pki-server --help command and see the pki-server man page for usage information.
The pki-server command-line interface (CLI) manages local server instances (for example server configuration or system certificates). Invoke the CLI as follows:
pki-server [CLI options] <command> [command parameters]
$ pki-server [CLI options] <command> [command parameters]The CLI uses the configuration files and NSS database of the server instance, therefore the CLI does not require any prior initialization. Since the CLI accesses the files directly, it can only be executed by the root user, and it does not require client certificate. Also, the CLI can run regardless of the status of the server; it does not require a running server.
The CLI supports a number of commands organized in a hierarchical structure. To list the top-level commands, execute the CLI without any additional commands or parameters:
pki-server
$ pki-serverSome commands have subcommands. To list them, execute the CLI with the command name and no additional options. For example:
pki-server ca pki-server ca-audit
$ pki-server ca
$ pki-server ca-auditTo view command usage information, use the --help option:
pki-server --help pki-server ca-audit-event-find --help
$ pki-server --help
$ pki-server ca-audit-event-find --help2.2.4.2. Enabling and disabling an installed subsystem using pki-server
To enable or disable an installed subsystem, use the pki-server utility.
pki-server subsystem-disable -i instance_id subsystem_id
# pki-server subsystem-disable -i instance_id subsystem_idpki-server subsystem-enable -i instance_id subsystem_id
# pki-server subsystem-enable -i instance_id subsystem_id
Replace subsystem_id with a valid subsystem identifier: ca, kra, tks, ocsp, or tps.
One instance can have only one of each type of subsystem.
For example, to disable the OCSP subsystem on an instance named pki-tomcat:
pki-server subsystem-disable -i pki-tomcat ocsp
# pki-server subsystem-disable -i pki-tomcat ocspTo list the installed subsystems for an instance:
pki-server subsystem-find -i instance_id
# pki-server subsystem-find -i instance_idTo show the status of a particular subsystem:
pki-server subsystem-find -i instance_id subsystem_id
# pki-server subsystem-find -i instance_id subsystem_id2.2.4.3. Finding the subsystem web services URLs
The CA, KRA, OCSP, TKS, and TPS subsystems have web services pages for agents, as well as regular users and administrators, when appropriate. These web services can be accessed by opening the URL to the subsystem host over the subsystem’s secure end user’s port. For example, for the CA:
https://server.example.com:8443/ca/services
https://server.example.com:8443/ca/servicesTo get a complete list of all of the interfaces, URLs, and ports for an instance, check the status of the service. For example:
pki-server status <instance_name>
pki-server status <instance_name>The main web services page for each subsystem has a list of available services pages; these are summarized in the below table. To access any service specifically, access the appropriate port and append the appropriate directory to the URL. For example, to access the CA’s end entities (regular users) web services:
https://server.example.com:8443/ca/ee/ca
https://server.example.com:8443/ca/ee/caIf DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the services pages. For example:
https://192.0.2.1:8443/ca/services https://[2001:DB8::1111]:8443/ca/services
https://192.0.2.1:8443/ca/services
https://[2001:DB8::1111]:8443/ca/servicesAnyone can access the end user pages for a subsystem. However, accessing agent or admin web services pages requires that an agent or administrator certificate be issued and installed in the web browser. Otherwise, authentication to the web services fails.
| Port | Used for SSL/TLS | Used for Client AuthenticationServices 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. | Web Services | Web Service Location |
|---|---|---|---|---|
|
| 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 |
| 8080 | No | |
| End Entities | kra/ee/kra | 8443 | Yes | No |
| End Entities | kra/ee/kra | 8443 | Yes | Yes |
| Agents | kra/agent/kra | 8443 | Yes | No |
| Services | kra/services | 8443 | Yes | No |
| Console | pkiconsole https://host:port/kra |
| 8080 | No |
| End Entities | ocsp/ee/ocsp | 8443 | Yes | |
| No | End Entities | ocsp/ee/ocsp | 8443 | Yes |
| Yes | Agents | ocsp/agent/ocsp | 8443 | Yes |
| No | Services | ocsp/services | 8443 | Yes |
| No | Console | pkiconsole https://host:port/ocsp |
| 8080 |
| No | End Entities | tks/ee/tks | 8443 | |
| Yes | No | End Entities | tks/ee/tks | 8443 |
| Yes | Yes | Agents | tks/agent/tks | 8443 |
| Yes | No | Services | tks/services | 8443 |
| Yes | No | Console | pkiconsole https://host:port/tks |
|
| 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 | tps/ui |
2.2.4.4. Starting the Certificate System console
This console is being deprecated.
The CA, KRA, OCSP, and TKS subsystems have a Java interface which can be accessed to perform administrative functions. For the KRA, OCSP, and TKS, this includes very basic tasks like configuring logging and managing users and groups. For the CA, this includes other configuration settings such as creating certificate profiles and configuring publishing.
The Console is opened by connecting to the subsystem instance over its SSL/TLS port using the pkiconsole utility. This utility uses the format:
pkiconsole https://server.example.com:admin_port/subsystem_type
pkiconsole https://server.example.com:admin_port/subsystem_type
The subsystem_type can be ca, kra, ocsp, or tks. For example, this opens the KRA console:
pkiconsole https://server.example.com:8443/kra
pkiconsole https://server.example.com:8443/kraIf DNS is not configured, then an IPv4 or IPv6 address can be used to connect to the console. For example:
https://192.0.2.1:8443/ca https://[2001:DB8::1111]:8443/ca
https://192.0.2.1:8443/ca
https://[2001:DB8::1111]:8443/ca2.3. Certificate System architecture overview
Although each provides a different service, all Red Hat Certificate System subsystems (CA, KRA, OCSP, TKS, TPS) share a common architecture. The following architectural diagram shows the common architecture shared by all of these subsystems.
2.3.1. Java application server
Java application server is a Java framework to run server applications. The Certificate System is designed to run within a Java application server. Currently the only Java application server supported is Tomcat. Support for other application servers may be added in the future.
Each Certificate System instance is a Tomcat server instance. Each Certificate System subsystem (such as CA or KRA) is deployed as a web application in Tomcat. The web application configuration is stored in a web.xml file, which is defined in Java Servlet 3.1 specification. See https://www.jcp.org/en/jsr/detail?id=340 for details.
The Certificate System configuration itself is stored in CS.cfg.
See Section 2.3.14, “Instance layout” for the actual locations of these files.
2.3.2. Java security manager
Java services have the option of having a Security Manager which defines unsafe and safe operations for applications to perform. When the subsystems are installed, they have the Security Manager enabled automatically, meaning each Tomcat instance starts with the Security Manager running.
The Security Manager is disabled if the instance is created by running pkispawn and using an override configuration file which specifies the pki_security_manager=false option under its own Tomcat section.
The Security Manager can be disabled from an installed instance using the following procedure:
First stop the instance:
pki-server stop instance_name
# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow or (if using the
nuxwdogwatchdog)systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Open the
/etc/sysconfig/instance_namefile, and setSECURITY_MANAGER="false" After saving, restart the instance:
pki-server start instance_name
# pki-server start instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow or (if using the
nuxwdogwatchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
When you start or restart an instance, a Java security policy is constructed or reconstructed 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
/usr/share/pki/server/conf/catalina.policy
/usr/share/tomcat/conf/catalina.policy
/var/lib/pki/$PKI_INSTANCE_NAME/conf/pki.policy
/var/lib/pki/$PKI_INSTANCE_NAME/conf/custom.policy
Then, it is saved into /var/lib/pki/ instance_name/conf/catalina.policy.
2.3.3. Interfaces
2.3.3.1. Servlet interface
Each subsystem contains interfaces allowing interaction with various portions of the subsystem. All subsystems share a common administrative interface and have an agent interface that allows for agents to perform the tasks assigned to them. A CA Subsystem has an end-entity interface that allows end-entities to enroll in the PKI. An OCSP Responder subsystem has an end-entity interface allowing end-entities and applications to check for current certificate revocation status. Finally, a TPS has an operator interface.
While the application server provides the connection entry points, Certificate System completes the interfaces by providing the servlets specific to each interface.
The servlets for each subsystem are defined in the corresponding web.xml file. The same file also defines the URL of each servlet and the security requirements to access the servlets. See Section 2.3.1, “Java application server” for more information.
2.3.3.2. Administrative interface
The agent interface provides Java servlets to process HTML form submissions coming from the agent entry point. Based on the information given in each form submission, the agent servlets allow agents to perform agent tasks, such as editing and approving requests for certificate approval, certificate renewal, and certificate revocation, approving certificate profiles. The agent interfaces for a KRA subsystem, or a TKS subsystem, or an OCSP Responder are specific to the subsystems.
In the non-TMS setup, the agent interface is also used for inter-CIMC boundary communication for the CA-to-KRA trusted connection. This connection is protected by SSL client-authentication and differentiated by separate trusted roles called Trusted Managers. Like the agent role, the Trusted Managers (pseudo-users created for inter-CIMC boundary connection only) are required to be SSL client-authenticated. However, unlike the agent role, they are not offered any agent capability.
In the TMS setup, inter-CIMC boundary communication goes from TPS-to-CA, TPS-to-KRA, and TPS-to-TKS.
2.3.3.3. End-entity interface
For the CA subsystem, the end-entity interface provides Java servlets to process HTML form submissions coming from the end-entity entry point. Based on the information received from the form submissions, the end-entity servlets allow end-entities to enroll, renew certificates, revoke their own certificates, and pick up issued certificates. The OCSP Responder subsystem’s End-Entity interface provides Java servlets to accept and process OCSP requests. The KRA, TKS, and TPS subsystems do not offer any End-Entity services.
2.3.3.4. Operator interface
The operator interface is only found in the TPS subsystem.
2.3.4. REST interface
Representational state transfer (REST) is a way to use HTTP to define and organize web services which will simplify interoperability with other applications. Red Hat Certificate System provides a REST interface to access various services on the server.
Each REST service is defined as a separate URL. For example:
-
CA certificate service:
https://<hostname>:<port>/ca/rest/certs/ -
KRA key service:
https://<hostname>:<port>/kra/rest/agent/keys/ -
TKS user service:
https://<hostname>:<port>/tks/rest/admin/users/ -
TPS group service:
https://<hostname>:<port>/tps/rest/admin/groups/
Some services can be accessed using plain HTTP connection, but some others may require HTTPS connection for security.
The REST operation is specified as HTTP method (for example, GET, PUT, POST, DELETE). For example, to get the CA users the client will send a GET /ca/rest/users request.
The REST request and response messages can be sent in XML or JSON format. For example:
The REST interface can be accessed using tools such as CLI, Web UI, or generic REST client. Certificate System also provides Java, Python, and JavaScript libraries to access the services programmatically.
The REST interface supports two types of authentication methods:
- user name and password
- client certificate
The authentication method required by each service is defined in /usr/share/pki/ca/conf/auth-method.properties.
The REST interface may require certain permissions to access the service. The permissions are defined in the ACL resources in LDAP. The REST interface are mapped to the ACL resources in the /usr/share/pki/<subsystem>/conf/acl.properties.
2.3.5. JSS
Java Security Services (JSS) provides a Java interface for cryptographic operations performed by NSS. JSS and higher levels of the Certificate System architecture are built with Java Native Interface (JNI), which provides access to native system libraries from within the Java Virtual Machine (JVM). This design allows us to use FIPS approved cryptographic providers such as NSS which are distributed as part of the system. JSS supports most of the security standards and encryption technologies supported by NSS. JSS also provides a pure Java interface for ASN.1 types and BER-DER encoding.
2.3.6. Tomcatjss
Java-based subsystems in Red Hat Certificate System use a single JAR file called tomcatjss as a bridge between the Tomcat Server HTTP engine and JSS, the Java interface for security operations performed by NSS. Tomcatjss is a Java Secure Socket Extension (JSSE) implementation using Java Security Services (JSS) for Tomcat.
Tomcatjss implements the interfaces needed to use TLS and to create TLS sockets. The socket factory, which tomcatjss implements, makes use of the various properties listed below to create a TLS server listening socket and return it to tomcat. Tomcatjss itself, makes use of our java JSS system to ultimately communicate with the native NSS cryptographic services on the machine.
Tomcatjss is loaded when the Tomcat server and the Certificate System classes are loaded. The load process is described below:
- The server is started.
- Tomcat gets to the point where it needs to create the listening sockets for the Certificate System installation.
-
The
server.xmlfile is processed. Configuration in this file tells the system to use a socket factory implemented by Tomcatjss. - For each requested socket, Tomcajss reads and processes the included attributes when it creates the socket. The resulting socket will behave as it has been asked to by those parameters.
- Once the server is running, we have the required set of listening sockets waiting for incoming connections to the Tomcat-based Certificate System.
Note that when the sockets are created at startup, Tomcatjss is the first entity in Certificate System that actually deals with the underlying JSS security services. Once the first listening socket is processed, an instance of JSS is created for use going forward.
For further details about the server.xml file, see Section 13.4, “Configuration files for the tomcat engine and web services”.
2.3.7. PKCS #11
Public-Key Cryptography Standard (PKCS) #11 specifies an API used to communicate with devices that hold cryptographic information and perform cryptographic operations. Because it supports PKCS #11, Certificate System is compatible with a wide range of hardware and software devices.
At least one PKCS #11 module must be available to any Certificate System subsystem instance. A PKCS #11 module (also called a cryptographic module or cryptographic service provider) manages cryptographic services such as encryption and decryption. PKCS #11 modules are analogous to drivers for cryptographic devices that can be implemented in either hardware or software. Certificate System contains a built-in PKCS #11 module and can support third-party modules.
A PKCS #11 module always has one or more slots which can be implemented as physical hardware slots in a physical reader such as smart cards or as conceptual slots in software. Each slot for a PKCS #11 module can in turn contain a token, which is a hardware or software device that actually provides cryptographic services and optionally stores certificates and keys.
The Certificate System defines two types of tokens, the internal and the external. The internal token is used for storing certificate trust anchors. The external token is used for storing key pairs and certificates that belong to the Certificate System subsystems.
2.3.7.1. NSS soft token (internal token)
Certificate System uses an NSS soft token for storing certificate trust anchors.
NSS Soft Token is also called an internal token or a software token. The software token consists of two files, which are usually called the certificate database (cert9.db) and key database (key4.db). The files are created during the Certificate System subsystem configuration. These security databases are located in the /var/lib/pki/ instance_name/alias directory.
Two cryptographic modules provided by the NSS soft token are included in the Certificate System:
The default internal PKCS #11 module, which comes with two tokens:
- The internal crypto services token, which performs all cryptographic operations such as encryption, decryption, and hashing.
- The internal key storage token ("Certificate DB token"), which handles all communication with the certificate and key database files that store certificates and keys.
- The FIPS 140 module. This module complies with the FIPS 140 government standard for cryptographic module implementations. The FIPS 140 module includes a single, built-in FIPS 140 certificate database token, which handles both cryptographic operations and communication with the certificate and key database files.
Specific instructions on how to import certificates onto the NSS soft token are in Chapter 14, Managing certificate/key crypto token.
For more information on the Network Security Services (NSS), see Mozilla Developer web pages of the same name.
2.3.7.2. Hardware security module (HSM, external token)
Certificate System uses an HSM for storing key pairs and certificates that belong to the Certificate System subsystems.
Any PKCS #11 module can be used with the Certificate System. To use an external hardware token with a subsystem, load its PKCS #11 module before the subsystem is configured, and the new token is available to the subsystem.
Available PKCS #11 modules are tracked in the pkcs11.txt database for the subsystem. The modutil utility is used to modify this file when there are changes to the system, such as installing a hardware accelerator to use for signing operations. For more information on modutil, see Network Security Services (NSS) at Mozilla Developer webpage.
PKCS #11 hardware devices also provide key backup and recovery features for the information stored on hardware tokens. Refer to the PKCS #11 vendor documentation for information on retrieving keys from the tokens.
Specific instructions on how to import certificates and to manage the HSM are in Chapter 14, Managing certificate/key crypto token.
Supported Hardware Security Modules are located in Section 4.4, “Supported Hardware Security Modules”.
2.3.8. Security domain
A security domain is a registry of PKI services. Services such as CAs register information about themselves in these domains so users of PKI services can find other services by inspecting the registry. The security domain service in RHCS manages both the registration of PKI services for Certificate System subsystems and a set of shared trust policies.
See Section 5.3, “Planning security domains” for further details.
2.3.9. Passwords and watchdog (nuxwdog)
In the default setup, an RHCS subsystem instance needs to act as a client and authenticate to some other services, such as an LDAP internal database (unless TLS client authentication is set up, where a certificate will be used for authentication instead), the NSS token database, or sometimes an HSM with a password. The administrator is prompted to set up this password at the time of installation configuration. This password is then written to the file <instance_dir>/conf/password.conf. At the same time, an identifying string is stored in the main configuration file CS.cfg as part of the parameter cms.passwordlist.
The configuration file, CS.cfg, is protected by Red Hat Enterprise Linux, and only accessible by the PKI administrators. No passwords are stored in CS.cfg.
During installation, the installer will select and log into either the internal software token or a hardware cryptographic token. The login passphrase to these tokens is also written to password.conf.
Configuration at a later time can also place passwords into password.conf. LDAP publishing is one example where the newly configured Directory Manager password for the publishing directory is entered into password.conf.
Nuxwdog (watchdog) is a lightweight auxiliary daemon process that is used to start, stop, monitor the status of, and reconfigure server programs. It is most useful when users need to be prompted for passwords to start a server, because it caches these passwords securely in the kernel keyring, so that restarts can be done automatically in the case of a server crash.
Nuxwdog is the only allowed watchdog service.
Once installation is complete, it is possible to remove the password.conf file altogether. On restart, the nuxwdog watchdog program will prompt the administrator for the required passwords, using the parameter cms.passwordlist (and cms.tokenList if an HSM is used) as a list of passwords for which to prompt. The passwords are then cached by nuxwdog in the kernel keyring to allow automated recovery from a server crash. This automated recovery (automatic subsystem restart) happens in case of uncontrolled shutdown (crash). In case of a controlled shutdown by the administrator, administrators are prompted for passwords again.
When using the watchdog service, starting and stopping an RHCS instance are done differently. For details, see Section 13.3.2, “Using the Certificate System watchdog service”.
For further information, see Section 13.3, “Managing system passwords”.
2.3.10. Internal LDAP database
Red Hat Certificate System employs Red Hat Directory Server (RHDS) as its internal database for storing information such as certificates, requests, users, roles, ACLs, as well as other miscellaneous internal information. Certificate System communicates with the internal LDAP database either with a password, or securely by means of SSL authentication.
If certificate-based authentication is required between a Certificate System instance and Directory Server, it is important to follow instruction to set up trust between these two entities. Proper pkispawn options will also be needed for installing such Certificate System instance.
For details, see Section 6.3.2, “Installing Red Hat Directory Server”.
2.3.11. Security-enhanced Linux (SELinux)
SELinux is a collection of mandatory access control rules which are enforced across a system to restrict unauthorized access and tampering. SELinux is described in more detail in Using SELinux guide for Red Hat Enterprise Linux 8.
Basically, SELinux identifies objects on a system, which can be files, directories, users, processes, sockets, or any other resource on a Linux host. These objects correspond to the Linux API objects. Each object is then mapped to a security context, which defines the type of object and how it is allowed to function on the Linux server.
Objects can be grouped into domains, and then each domain is assigned the proper rules. Each security context has rules which set restrictions on what operations it can perform, what resources it can access, and what permissions it has.
SELinux policies for the Certificate System are incorporated into the standard system SELinux policies. These SELinux policies apply to every subsystem and service used by Certificate System. By running Certificate System with SELinux in enforcing mode, the security of the information created and maintained by Certificate System is enhanced.
Figure 2.1. CA SELinux port policy
The Certificate System SELinux policies define the SELinux configuration for every subsystem instance:
- Files and directories for each subsystem instance are labeled with a specific SELinux context.
- The ports for each subsystem instance are labeled with a specific SELinux context.
- All Certificate System processes are constrained within a subsystem-specific domain.
- Each domain has specific rules that define what actions that are authorized for the domain.
- Any access not specified in the SELinux policy is denied to the Certificate System instance.
For Certificate System, each subsystem is treated as an SELinux object, and each subsystem has unique rules assigned to it. The defined SELinux policies allow Certificate System objects run with SELinux set in enforcing mode.
Every time pkispawn is run to configure a Certificate System subsystem, files and ports associated with that subsystem are labeled with the required SELinux contexts. These contexts are removed when the particular subsystems are removed using pkidestroy.
The central definition in an SELinux policy is the pki_tomcat_t domain. Certificate System instances are Tomcat servers, and the pki_tomcat_t domain extends the policies for a standard tomcat_t Tomcat domain. All Certificate System instances on a server share the same domain.
When each Certificate System process is started, it initially runs in an unconfined domain (unconfined_t) and then transitions into the pki_tomcat_t domain. This process then has certain access permissions, such as write access to log files labeled pki_tomcat_log_t, read and write access to configuration files labeled pki_tomcat_etc_rw_t, or the ability to open and write to http_port_t ports.
The SELinux mode can be changed from enforcing to permissive, or even off, though this is not recommended.
2.3.12. Self-tests
Red Hat Certificate System provides a Self-Test framework which allows the PKI system integrity to be checked during startup or on demand or both. In the event of a non-critical self test failure, the message will be stored in the log file, while in the event of a critical self test failure, the message will be stored in the log file, while the Certificate System subsystem will properly shut down. The administrator is expected to watch the self-test log during the startup of the subsystem if they wish to see the self-test report during startup. They can also view the log after startup.
When a subsystem is shut down due to a self-test failure, it will also be automatically disabled. This is done to ensure that the subsystem does not partially run and produce misleading responses. Once the issue is resolved, the subsystem can be re-enabled by running the following command on the server:
pki-server subsystem-enable <subsystem>
# pki-server subsystem-enable <subsystem>For details on how to configure self-tests, see Section 17.3.2, “Configuring self-tests”.
2.3.13. Logs
The Certificate System subsystems create log files that record events related to activities, such as administration, communications using any of the protocols the server supports, and various other processes employed by the subsystems. While a subsystem instance is running, it keeps a log of information and error messages on all the components it manages. Additionally, the Apache and Tomcat web servers generate error and access logs.
Each subsystem instance maintains its own log files for installation, audit, and other logged functions.
Log plug-in modules are listeners which are implemented as Java™ classes and are registered in the configuration framework.
All the log files and rotated log files, except for audit logs, are located in whatever directory was specified in pki_subsystem_log_path when the instance was created with pkispawn.
Regular audit logs are located in the log directory with other types of logs, while signed audit logs are written to /var/log/pki/ instance_name/subsystem_name/signedAudit. The default location for logs can be changed by modifying the configuration.
For details about log configuration during the installation and additional information, see Chapter 17, Configuring logs.
For details about log administration after the installation, see the Configuring Subsystem Logs section in the Red Hat Certificate System Administration Guide.
2.3.13.1. Audit log
The audit log contains records for selectable events that have been set up as recordable events. You can configure audit logs also to be signed for integrity-checking purposes.
Audit records should be kept according to the audit retention rules specified in -Section 17.4, “Audit retention”.
2.3.13.2. Debug logs
Debug logs, which are enabled by default, are maintained for all subsystems, with varying degrees and types of information.
Debug logs contain very specific information for every operation performed by the subsystem, including plug-ins and servlets which are run, connection information, and server request and response messages.
The general types of services which are recorded to the debug log are briefly discussed in Services That Are Logged. These services include authorization requests, processing certificate requests, certificate status checks, and archiving and recovering keys, and access to web services.
The debug logs for the CA, OCSP, KRA, and TKS record detailed information about the processes for the subsystem. Each log entry has the following format:
[date:time][processor]: servlet: message
[date:time][processor]: servlet: messageThe message can be a return message from the subsystem or contain values submitted to the subsystem.
For example, the TKS records this message for connecting to an LDAP server:
[10/Jun/{YEAR}:05:14:51][main]: Established LDAP connection using basic authentication to host localhost port 389 as cn=Directory Manager
[10/Jun/{YEAR}:05:14:51][main]: Established LDAP connection using basic authentication to host localhost port 389 as cn=Directory Manager
The processor is main, and the message is the message from the server about the LDAP connection, and there is no servlet.
The CA, on the other hand, records information about certificate operations as well as subsystem connections:
[06/Jun/{YEAR}:14:59:38][http-8443;-Processor24]:ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443
[06/Jun/{YEAR}:14:59:38][http-8443;-Processor24]:ProfileSubmitServlet: key=$request.requestowner$ value=KRA-server.example.com-8443In this case, the processor is the HTTP protocol over the CA’s agent port, while it specifies the servlet for handling profiles and contains a message giving a profile parameter (the subsystem owner of a request) and its value (that the KRA initiated the request).
Example 2.1. CA Certificate request log messages
Likewise, the OCSP shows OCSP request information:
[07/Jul/{YEAR}:06:25:40][http-11180-Processor25]: OCSPServlet: OCSP Request:
[07/Jul/{YEAR}:06:25:40][http-11180-Processor25]: OCSPServlet:MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU
[07/Jul/{YEAR}:06:25:40][http-11180-Processor25]: OCSPServlet: OCSP Request:
[07/Jul/{YEAR}:06:25:40][http-11180-Processor25]: OCSPServlet:MEUwQwIBADA+MDwwOjAJBgUrDgMCGgUABBSEWjCarLE6/BiSiENSsV9kHjqB3QQU2.3.13.3. Tomcat error and access logs
The CA, KRA, OCSP, TKS, and TPS subsystems use a Tomcat web server instance for their agent and end-entities' interfaces.
Error and access logs are created by the Tomcat web server, which are installed with the Certificate System and provide HTTP services. The error log contains the HTTP error messages the server has encountered. The access log lists access activity through the HTTP interface.
Logs created by Tomcat:
- admin.timestamp
- catalina.timestamp
- catalina.out
- host-manager.timestamp
- localhost.timestamp
- localhost_access_log.timestamp
- manager.timestamp
These logs are not available or configurable within the Certificate System; they are only configurable within Tomcat. See the Apache documentation for information about configuring these logs.
2.3.13.4. Self-tests log
The self-tests log records information obtained during the self-tests run when the server starts or when the self-tests are manually run. The tests can be viewed by opening this log. This log is not configurable through the Console. This log can only be configured by changing settings in the CS.cfg file. The information about logs in this section does not pertain to this log. See Section 2.6.5, “Self-tests” for more information about self-tests.
2.3.13.5. journalctl logs
When starting a Certificate System instance, there is a short period of time before the logging subsystem is set up and enabled. During this time, log contents are written to standard out, which is captured by systemd and exposed via the journalctl utility.
To view these logs, run the following command:
journalctl -u pki-tomcatd@instance_name.service
# journalctl -u pki-tomcatd@instance_name.service
If using the nuxwdog service:
journalctl -u pki-tomcatd-nuxwdog@instance_name.service
# journalctl -u pki-tomcatd-nuxwdog@instance_name.serviceOften it is helpful to watch these logs as the instance is starting (for example, in the event of a self-test failure on startup). To do this, run these commands in a separate console prior to starting the instance:
journalctl -f -u pki-tomcatd@instance_name.service
# journalctl -f -u pki-tomcatd@instance_name.service
If using the nuxwdog service:
journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service
# journalctl -f -u pki-tomcatd-nuxwdog@instance_name.service2.3.14. Instance layout
Each Certificate System instance depends on a number of files. Some of them are located in instance-specific folders, while some others are located in a common folder which is shared with other server instances.
For example, the server configuration files are stored in /etc/pki/ instance_name/server.xml, which is instance-specific, but the CA servlets are defined in /usr/share/pki/ca/webapps/ca/WEB-INF/web.xml, which is shared by all server instances on the system.
2.3.14.1. File and directory locations for Certificate System
Certificate System servers are Tomcat instances which consist of one or more Certificate System subsystems. Certificate System subsystems are web applications that provide specific type of PKI functions. General, shared subsystem information is contained in non-relocatable, RPM-defined shared libraries, Java archive files, binaries, and templates. These are stored in a fixed location.
The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.
The directories contain customized configuration files and templates, profiles, certificate databases, and other files for the subsystem.
| 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 |
| 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 |
The /var/lib/pki/ instance_name/conf/ directory is a symbolic link to the /etc/pki/ instance_name/ directory.
2.3.14.2. CA subsystem information
The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.
| 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 |
| 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.14.3. KRA subsystem information
The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.
| 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 |
| Web Services Files | /usr/share/pki/kra/webapps/kra/agent - Agent services /usr/share/pki/kra/webapps/kra/admin - Admin services |
2.3.14.4. OCSP subsystem information
The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.
| 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 |
| Web Services Files | /usr/share/pki/ocsp/webapps/ocsp/agent - Agent services /usr/share/pki/ocsp/webapps/ocsp/admin - Admin services |
2.3.14.5. TKS subsystem information
The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.
| 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 |
2.3.14.6. TPS subsystem information
The directories are instance specific, tied to the instance name. In these examples, the instance name is pki-tomcat; the true value is whatever is specified at the time the subsystem is created with pkispawn.
| 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 |
| Web Services Files | /usr/share/pki/tps/webapps/tps - TPS services |
2.3.14.7. Shared Certificate System subsystem file locations
There are some directories used by or common to all Certificate System subsystem instances for general server operations, listed in Table 2.8, “Subsystem file locations”.
| 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 |
| /usr/share/java/pki | Contains Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. |
2.4. PKI with Certificate System
The Certificate System is comprised of subsystems which each contribute different functions of a public key infrastructure. A PKI environment can be customized to fit individual needs by implementing different features and functions for the subsystems.
A conventional PKI environment provides the basic framework to manage certificates stored in software databases. This is a non-TMS environment, since it does not manage certificates on smart cards. A TMS environment manages the certificates on smart cards.
At a minimum, a non-TMS requires only a CA, but a non-TMS environment can use OCSP responders and KRA instances as well.
2.4.1. Issuing certificates
As stated, the Certificate Manager is the heart of the Certificate System. It manages certificates at every stage, from requests through enrollment (issuing), renewal, and revocation.
The Certificate System supports enrolling and issuing certificates and processing certificate requests from a variety of end entities, such as web browsers, servers, and virtual private network (VPN) clients. Issued certificates conform to X.509 version 3 standards.
For more information, see the About Enrolling and Renewing Certificates section in the Red Hat Certificate System Administration Guide.
2.4.1.1. The enrollment process
An end entity enrolls in the PKI environment by submitting an enrollment request through the end-entity interface. There can be many kinds of enrollment that use different enrollment methods or require different authentication methods. Different interfaces can also accept different types of Certificate Signing Requests (CSR).
The Certificate Manager supports different ways to submit CSRs, such as using the graphical interface and command-line tools.
2.4.1.1.1. Enrollment using the user interface
For each enrollment through the user interface, there is a separate enrollment page created that is specific to the type of enrollment, type of authentication, and the certificate profiles associated with the type of certificate. The forms associated with enrollment can be customized for both appearance and content. Alternatively, the enrollment process can be customized by creating certificate profiles for each enrollment type. Certificate profiles dynamically-generate forms which are customized by configuring the inputs associated with the certificate profile. Different interfaces can also accept different types of Certificate Signing Requests (CSR).
When an end entity enrolls in a PKI by requesting a certificate, the following events can occur, depending on the configuration of the PKI and the subsystems installed:
The end entity provides the information in one of the enrollment forms and submits a request.
The information gathered from the end entity is customizable in the form depending on the information collected to store in the certificate or to authenticate against the authentication method associated with the form. The form creates a request that is then submitted to the Certificate Manager.
- The enrollment form triggers the creation of the public and private keys or for dual-key pairs for the request.
- The end entity provides authentication credentials before submitting the request, depending on the authentication type. This can be LDAP authentication, PIN-based authentication, or certificate-based authentication.
The request is submitted either to an agent-approved enrollment process or an automated process.
The agent-approved process, which involves no end-entity authentication, sends the request to the request queue in the agent services interface, where an agent must processes the request. An agent can then modify parts of the request, change the status of the request, reject the request, or approve the request.
Automatic notification can be set up so an email is sent to an agent any time a request appears in the queue. Also, an automated job can be set to send a list of the contents of the queue to agents on a pre configured schedule.
- The automated process, which involves end-entity authentication, processes the certificate request as soon as the end entity successfully authenticates.
- The form collects information about the end entity from an LDAP directory when the form is submitted. For certificate profile-based enrollment, the defaults for the form can be used to collect the user LDAP ID and password.
- The certificate profile associated with the form determine aspects of the certificate that is issued. Depending on the certificate profile, the request is evaluated to determine if the request meets the constraints set, if the required information is provided, and the contents of the new certificate.
- The form can also request that the user export the private encryption key. If the KRA subsystem is set up with this CA, the end entity’s key is requested, and an archival request is sent to the KRA. This process generally requires no interaction from the end entity.
- The certificate request is either rejected because it did not meet the certificate profile or authentication requirements, or a certificate is issued.
The certificate is delivered to the end entity.
- In automated enrollment, the certificate is delivered to the user immediately. Since the enrollment is normally through an HTML page, the certificate is returned as a response on another HTML page.
- In agent-approved enrollment, the certificate can be retrieved by serial number or request Id in the end-entity interface.
- If the notification feature is set up, the link where the certificate can be obtained is sent to the end user.
- An automatic notice can be sent to the end entity when the certificate is issued or rejected.
- The new certificate is stored in the Certificate Manager’s internal database.
- If publishing is set up for the Certificate Manager, the certificate is published to a file or an LDAP directory.
- The internal OCSP service checks the status of certificates in the internal database when a certificate status request is received.
The end-entity interface has a search form for certificates that have been issued and for the CA certificate chain.
By default, the user interface supports CSR in the PKCS #10 and Certificate Request Message Format (CRMF).
2.4.1.1.2. Enrollment using the command line
This section describes the general workflows when enrolling certificates using the command line.
2.4.1.1.2.1. Enrolling using the pki utility
For details, see:
-
The
pki-cert(1)man page - The Command-Line Interfaces section in the Red Hat Certificate System Administration Guide.
2.4.1.1.2.2. Enrolling with CMC
To enroll a certificate with CMC, proceed as follows:
Generate a PKCS #10 or CRMF certificate signing request (CSR) using a utility, such as
PKCS10ClientorCRMFPopClient.NoteIf key archival is enabled in the Key Recovery Agent (KRA), use the
CRMFPopClientutility with the KRA’s transport certificate in Privacy Enhanced Mail (PEM) format set in thekra.transportfile.Use the
CMCRequestutility to convert the CSR into a CMC request. TheCMCRequestutility 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
HttpClientutility to send the CMC request to the CA.HttpClientuses a configuration file with settings, such as the path to the CMC request file and the servlet.If the
HttpClientcommand succeeds, the utility receives a PKCS #7 chain with CMC status controls from the CA.For details about what parameters the utility provides, enter the
HttpClientcommand without any parameters.Use the
CMCResponseutility to check the issuance result of the PKCS #7 file generated byHttpClient. If the request is successful,CMCResponsedisplays 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.
NoteThe certificate retrieved by
HttpClientis in PKCS #7 format. If the application supports only Base64-encoded certificates, use theBtoAutility 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
In situations when Proof Of Possession (POP) is missing, the HttpClient utility receives an EncryptedPOP CMC status, which is displayed by the CMCResponse command. In this case, enter the CMCRequest command again with different parameters in the configuration file.
For details, see the The CMC Enrollment Process section in the Red Hat Certificate System Administration Guide.
2.4.1.1.2.2.2. Signed CMC requests
CMC requests can either be signed by a user or a CA agent:
-
If an agent signs the request, set the authentication method in the profile to
CMCAuth. -
If a user signs the request, set the authentication method in the profile to
CMCUserSignedAuth.
For details, see the CMC Authentication Plug-ins section in the Red Hat Certificate System Administration Guide.
2.4.1.1.2.2.3. Unsigned CMC requests
When the CMCUserSignedAuth authentication plug-in is configured in the profile, you must use an unsigned CMC request in combination with the Shared Secret authentication mechanism.
Unsigned CMC requests are also called self-signed CMC requests.
For details, see the CMC Authentication Plug-ins section in the Red Hat Certificate System Administration Guide, and Section 13.7.8, “Enabling the CMC Shared Secret feature”.
2.4.1.1.2.2.5. Simple CMC requests
Certificate System allows simple CMC requests. However, this process does not support the same level of security requirements as full CMC requests and, therefore, must only be used in a secure environment.
When using simple CMC requests, set the following in the HttpClient utility’s configuration file:
servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert
servlet=/ca/ee/ca/profileSubmitCMCSimple?profileId=caECSimpleCMCUserCert2.4.1.2. Certificate profiles
The Certificate System uses certificate profiles to configure the content of the certificate, the constraints for issuing the certificate, the enrollment method used, and the input and output forms for that enrollment. A single certificate profile is associated with issuing a particular type of certificate.
A set of certificate profiles is included for the most common certificate types; the profile settings can be modified. Certificate profiles are configured by an administrator, and then sent to the agent services page for agent approval. Once a certificate profile is approved, it is enabled for use. In case of a UI-enrollment, a dynamically-generated HTML form for the certificate profile is used in the end-entities page for certificate enrollment, which calls on the certificate profile. In case of a command line-based enrollment, the certificate profile is called upon to perform the same processing, such as authentication, authorization, input, output, defaults, and constraints. The server verifies that the defaults and constraints set in the certificate profile are met before acting on the request and uses the certificate profile to determine the content of the issued certificate.
The Certificate Manager can issue certificates with any of the following characteristics, depending on the configuration in the profiles and the submitted certificate request:
- Certificates that are X.509 version 3-compliant
- Unicode support for the certificate subject name and issuer name
- Support for empty certificate subject names
- Support for customized subject name components
- Support for customized extensions
By default, the certificate enrollment profiles are stored in <instance directory>/ca/profiles/ca with names in the format of <profile id>.cfg. LDAP-based profiles are possible with proper pkispawn configuration parameters.
2.4.1.3. Authentication for certificate enrollment
Certificate System provides authentication options for certificate enrollment. These include agent-approved enrollment, in which an agent processes the request, and automated enrollment, in which an authentication method is used to authenticate the end entity and then the CA automatically issues a certificate. CMC enrollment is also supported, which automatically processes a request approved by an agent.
2.4.1.4. Cross-pair certificates
It is possible to create a trusted relationship between two separate CAs by issuing and storing cross-signed certificates between these two CAs. By using cross-signed certificate pairs, certificates issued outside the organization’s PKI can be trusted within the system.
2.4.2. Renewing certificates
When certificates reach their expiration date, they can either be allowed to lapse, or they can be renewed.
Renewal regenerates a certificate request using the existing key pairs for that certificate, and then resubmits the request to Certificate Manager. The renewed certificate is identical to the original (since it was created from the same profile using the same key material) with one exception - it has a different, later expiration date.
Renewal can make managing certificates and relationships between users and servers much smoother, because the renewed certificate functions precisely as the old one. For user certificates, renewal allows encrypted data to be accessed without any loss.
2.4.3. Publishing certificates and CRLs
Certificates can be published to files and an LDAP directory, and CRLs to files, an LDAP directory, and an OCSP responder. The publishing framework provides a robust set of tools to publish to all three places and to set rules to define with more detail which types of certificates or CRLs are published where.
2.4.4. Revoking certificates and checking status
End entities can request that their own certificates be revoked. When an end entity makes the request, the certificate has to be presented to the CA. If the certificate and the keys are available, the request is processed and sent to the Certificate Manager, and the certificate is revoked. The Certificate Manager marks the certificate as revoked in its database and adds it to any applicable CRLs.
An agent can revoke any certificate issued by the Certificate Manager by searching for the certificate in the agent services interface and then marking it revoked. Once a certificate is revoked, it is marked revoked in the database and in the publishing directory, if the Certificate is set up for publishing.
If the internal OCSP service has been configured, the service determines the status of certificates by looking them up in the internal database.
Automated notifications can be set to send email messages to end entities when their certificates are revoked by enabling and configuring the certificate revoked notification message.
2.4.4.1. Revoking certificates
Users can revoke their certificates using:
- The end-entity pages. For details, see the Certificate Revocation Pages section in the Red Hat Certificate System Administration Guide.
-
The
CMCRequestutility on the command line. For details, see the Performing a CMC Revocation section in the Red Hat Certificate System Administration Guide. -
The
pkiutility on the command line. For details, seepki-cert(1)man page.
2.4.4.2. Certificate status
2.4.4.2.1. CRLs
The Certificate System can create certificate revocation lists (CRLs) from a configurable framework which allows user-defined issuing points so a CRL can be created for each issuing point. Delta CRLs can also be created for any issuing point that is defined. CRLs can be issued for each type of certificate, for a specific subset of a type of certificate, or for certificates generated according to a profile or list of profiles. The extensions used and the frequency and intervals when CRLs are published can all be configured.
The Certificate Manager issues X.509-standard CRLs. A CRL can be automatically updated whenever a certificate is revoked or at specified intervals.
2.4.4.2.2. OCSP services
The Certificate System CA supports the Online Certificate Status Protocol (OCSP) as defined in PKIX standard RFC 2560. The OCSP protocol enables OCSP-compliant applications to determine the state of a certificate, including the revocation status, without having to directly check a CRL published by a CA to the validation authority. The validation authority, which is also called an OCSP responder, checks for the application.
- A CA is set up to issue certificates that include the Authority Information Access extension, which identifies an OCSP responder that can be queried for the status of the certificate.
- The CA periodically publishes CRLs to an OCSP responder.
- The OCSP responder maintains the CRL it receives from the CA.
- An OCSP-compliant client sends requests containing all the information required to identify the certificate to the OCSP responder for verification. The applications determine the location of the OCSP responder from the value of the Authority Information Access extension in the certificate being validated.
- The OCSP responder determines if the request contains all the information required to process it. If it does not or if it is not enabled for the requested service, a rejection notice is sent. If it does have enough information, it processes the request and sends back a report stating the status of the certificate.
2.4.4.2.2.1. OCSP response signing
Every response that the client receives, including a rejection notification, is digitally signed by the responder; the client is expected to verify the signature to ensure that the response came from the responder to which it submitted the request. The key the responder uses to sign the message depends on how the OCSP responder is deployed in a PKI setup. RFC 2560 recommends that the key used to sign the response belong to one of the following:
- The CA that issued the certificate whose status is being checked.
- A responder with a public key trusted by the client. Such a responder is called a trusted responder.
- A responder that holds a specially marked certificate issued to it directly by the CA that revokes the certificates and publishes the CRL. Possession of this certificate by a responder indicates that the CA has authorized the responder to issue OCSP responses for certificates revoked by the CA. Such a responder is called a CA-designated responder or a CA-authorized responder.
The end-entities page of a Certificate Manager includes a form for manually requesting a certificate for the OCSP responder. The default enrollment form includes all the attributes that identify the certificate as an OCSP responder certificate. The required certificate extensions, such as OCSPNoCheck and Extended Key Usage, can be added to the certificate when the certificate request is submitted.
2.4.4.2.2.2. OCSP responses
The OCSP response that the client receives indicates the current status of the certificate as determined by the OCSP responder. The response could be any of the following:
- Good or Verified . Specifies a positive response to the status inquiry, meaning the certificate has not been revoked. It does not necessarily mean that the certificate was issued or that it is within the certificate’s validity interval. Response extensions may be used to convey additional information on assertions made by the responder regarding the status of the certificate.
- Revoked . Specifies that the certificate has been revoked, either permanently or temporarily.
Based on the status, the client decides whether to validate the certificate.
The OCSP responder will never return a response of Unknown. The response will always be either Good or Revoked.
2.4.4.2.2.3. OCSP services
There are two ways to set up OCSP services:
- The OCSP built into the Certificate Manager
- The Online Certificate Status Manager subsystem
In addition to the built-in OCSP service, the Certificate Manager can publish CRLs to an OCSP-compliant validation authority. CAs can be configured to publish CRLs to the Certificate System Online Certificate Status Manager. The Online Certificate Status Manager stores each Certificate Manager’s CRL in its internal database and uses the appropriate CRL to verify the revocation status of a certificate when queried by an OCSP-compliant client.
The Certificate Manager can generate and publish CRLs whenever a certificate is revoked and at specified intervals. Because the purpose of an OCSP responder is to facilitate immediate verification of certificates, the Certificate Manager should publish the CRL to the Online Certificate Status Manager every time a certificate is revoked. Publishing only at intervals means that the OCSP service is checking an outdated CRL.
If the CRL is large, the Certificate Manager can take a considerable amount of time to publish the CRL.
The Online Certificate Status Manager stores each Certificate Manager’s CRL in its internal database and uses it as the CRL to verify certificates. The Online Certificate Status Manager can also use the CRL published to an LDAP directory, meaning the Certificate Manager does not have to update the CRLs directly to the Online Certificate Status Manager.
2.4.5. Archiving, recovering, and rotating keys
In the world of PKI, private key archival allows parties the possibility to recover the encrypted data in case the private key is lost. Private keys can be lost due to various reasons such as hardware failure, forgotten passwords, lost smartcards, incapacitated password holder, et caetera. Such archival and recovery feature is offered by the Key Recovery Authority (KRA) subsystem of RHCS.
Only keys that are used exclusively for encrypting data should be archived; signing keys in particular should never be archived. Having two copies of a signing key makes it impossible to identify with certainty who used the key; a second archived copy could be used to impersonate the digital identity of the original key owner.
2.4.5.1. Archiving keys
There are two types of key archival mechanisms provided by KRA:
- Client-side key generation: With this mechanism, clients are to generate CSRs in CRMF format, and submit the requests to the CA (with proper KRA setup) for enrollment and key archival. See 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.
The KRA automatically archives private encryption keys if archiving is configured.
The KRA stores private encryption keys in a secure key repository; each key is encrypted and stored as a key record and is given a unique key identifier.
The archived copy of the key remains wrapped with the KRA’s storage key. It can be decrypted, or unwrapped, only by using the corresponding private key pair of the storage certificate. A combination of one or more key recovery (or KRA) agents' certificates authorizes the KRA to complete the key recovery to retrieve its private storage key and use it to decrypt/recover an archived private key. See Section 16.3.1, “Configuring agent-approved key recovery in the command line”.
The KRA indexes stored keys by key number, owner name, and a hash of the public key, allowing for highly efficient searching. The key recovery agents have the privilege to insert, delete, and search for key records.
- When the key recovery agents search by the key ID, only the key that corresponds to that ID is returned.
- When the agents search by username, all stored keys belonging to that owner are returned.
- When the agents search by the public key in a certificate, only the corresponding private key is returned.
When a Certificate Manager receives a certificate request that contains the key archival option, it automatically forwards the request to the KRA to archive the encryption key. The private key is encrypted by the transport key, and the KRA receives the encrypted copy and stores the key in its key repository. To archive the key, the KRA uses two special key pairs:
- A transport key pair and corresponding certificate.
- A storage key pair.
Figure 2.2, “How the Key Archival Process works in client-side key generation” illustrates how the key archival process occurs when an end entity requests a certificate in the case of client-side key generation.
Figure 2.2. How the Key Archival Process works in client-side key generation
The client generates a CRMF request and submits it through the CA’s enrollment portal.
- The client’s private key is wrapped within the CRMF request and can only be unwrapped by the KRA.
- Detecting that it’s a CRMF request with key archival option, CA forwards the request to KRA for private key archival.
- The KRA decrypts / unwraps the user private key, and after confirming that the private key corresponds to the public key, the KRA encrypts / wraps it again before storing it in its internal LDAP database.
- Once the private encryption key has been successfully stored, the KRA responds to CA confirming that the key has been successfully archived.
- The CA sends the request down its Enrollment Profile Framework for certificate information content creation as well as validation. When everything passes, it then issues the certificate and sends it back to the end entity in its response.
2.4.5.2. Recovering keys
The KRA supports agent-initiated key recovery. Agent-initiated recovery is when designated recovery agents use the key recovery form on the KRA agent services portal to process and approve key recovery requests. With the approval of a specified number of agents, an organization can recover keys when the key’s owner is unavailable or when keys have been lost.
Through the KRA agent services portal, key recovery agents can collectively authorize and retrieve private encryption keys and associated certificates into a PKCS #12 package, which can then be imported into the client.
In key recovery authorization, one of the key recovery agents informs all required recovery agents about an impending key recovery. All recovery agents access the KRA key recovery portal. One of the agents initiates the key recovery process. The KRA returns a notification to the agent includes a recovery authorization reference number identifying the particular key recovery request that the agent is required to authorize. Each agent uses the reference number and authorizes key recovery separately.
KRA supports Asynchronous recovery, meaning that each step of the recovery process — the initial request and each subsequent approval or rejection — is stored in the KRA’s internal LDAP database, under the key entry. The status data for the recovery process can be retrieved even if the original browser session is closed or the KRA is shut down. Agents can search for the key to recover, without using a reference number.
This asynchronous recovery option is illustrated in Figure 2.3, “Asynchronous recovery”.
Figure 2.3. Asynchronous recovery
The KRA informs the agent who initiated the key recovery process of the status of the authorizations.
When all of the authorizations are entered, the KRA checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process.
The PKCS #12 package contains the encrypted private key. To minimize the risk of key compromise, the recovery agent must use a secure method to deliver the PKCS #12 package and password to the key recipient. The agent should use a good password to encrypt the PKCS #12 package and set up an appropriate delivery mechanism.
The key recovery agent scheme configures the KRA to recognize to which group the key recovery agents belong and specifies how many of these recovery agents are required to authorize a key recovery request before the archived key is restored.
The above information refers to using a web browser, such as Firefox. However, functionality critical to KRA usage is no longer newer versions of browsers. In such cases, it is necessary to use the pki utility to replicate this behavior. For more information, see the pki(1) and pki-key(1) man pages or run CRMFPopClient --help and man CMCRequest.
Apart from storing asymmetric keys, KRA can also store symmetric keys or secrets similar to symmetric keys, such as volume encryption secrets, or even passwords and passphrases. The pki utility supports options that enable storing and retrieving these other types of secrets.
2.4.5.3. KRA transport key rotation
KRA transport rotation allows for seamless transition between CA and KRA subsystem instances using a current and a new transport key. This allows KRA transport keys to be periodically rotated for enhanced security by allowing both old and new transport keys to operate during the time of the transition; individual subsystem instances take turns being configured while other clones continue to serve with no downtime.
In the KRA transport key rotation process, a new transport key pair is generated, a certificate request is submitted, and a new transport certificate is retrieved. The new transport key pair and certificate have to be included in the KRA configuration to provide support for the second transport key. Once KRA supports two transport keys, administrators can start transitioning CAs to the new transport key. KRA support for the old transport key can be removed once all CAs are moved to the new transport key.
To configure KRA transport key rotation:
- Generate a new KRA transport key and certificate
- Transfer the new transport key and certificate to KRA clones
- Update the CA configuration with the new KRA transport certificate
- Update the KRA configuration to use only the new transport key and certificate
After this, the rotation of KRA transport certificates is complete, and all the affected CAs and KRAs use the new KRA certificate only. For more information on how to perform the above steps, see the procedures below.
- Generating the new KRA transport key and certificate
Request the KRA transport certificate.
Stop the KRA:
pki-server stop pki-kra
# pki-server stop pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
# systemctl stop pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a subdirectory and save all the NSS database files into it. For example:
mkdir nss_db_backup cp *.db nss_db_backup
mkdir nss_db_backup cp *.db nss_db_backupCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a new request by using the
PKCS10Clientutility. For example:PKCS10Client -p password -d '.' -o 'req.txt' -n 'CN=KRA Transport 2 Certificate,O=example.com Security Domain'
PKCS10Client -p password -d '.' -o 'req.txt' -n 'CN=KRA Transport 2 Certificate,O=example.com Security Domain'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Alternatively, use the
certutilutility. 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
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-fileCopy to Clipboard Copied! Toggle word wrap Toggle overflow - 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
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow - 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
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow 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
# certutil -d . -A -n 'transportCert-serial_number cert-pki-kra KRA' -t 'u,u,u' -a -i cert-serial_number.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Update the KRA transport certificate configuration.
Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the new KRA transport certificate is imported:
certutil -d . -L certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfgfile and add the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
- Propagating the new transport key and certificate to KRA clones
- Start the KRA:
pki-server start pki-kra
# pki-server start pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@pki-kra.service
# systemctl start pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Extract the new transport key and certificate for propagation to clones.
Go to the KRA NSS database directory:
cd /etc/pki/pki-kra/alias
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the KRA:
pki-server stop pki-kra
# pki-server stop pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
# systemctl stop pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the new KRA transport certificate is present:
certutil -d . -L certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Export the KRA new transport key and certificate:
pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'
# pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the exported KRA transport key and certificate:
pk12util -l transport.p12
# pk12util -l transport.p12Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Perform these steps on each KRA clone:
-
Copy the
transport.p12file, including the transport key and certificate, to the KRA clone location. Go to the clone NSS database directory:
cd /etc/pki/pki-kra/alias
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the KRA clone:
pki-server stop pki-kra
# pki-server stop pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
# systemctl stop pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Check the content of the clone NSS database:
certutil -d . -L
# certutil -d . -LCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the new transport key and certificate of the clone:
pk12util -i transport.p12 -d .
# pk12util -i transport.p12 -d .Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add the following line to the
/var/lib/pki/pki-kra/kra/conf/CS.cfgfile on the clone:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the KRA clone:
pki-server start pki-kra
# pki-server start pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@pki-kra.service
# systemctl start pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
Copy the
- 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.txtKRA transport certificate file created when retrieving the KRA transport certificate in the previous procedure. Convert the Base64-encoded certificate included in
cert-serial_number.txtto a single-line file:tr -d '\n' < cert-serial_number.txt > cert-one-line-serial_number.txt
# tr -d '\n' < cert-serial_number.txt > cert-one-line-serial_number.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
Obtain the
Do the following for the CA and all its clones corresponding to the KRA above:
Stop the CA:
pki-server stop pki-ca
# pki-server stop pki-caCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@pki-ca.service
# systemctl stop pki-tomcatd-nuxwdog@pki-ca.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow In the
/var/lib/pki/pki-ca/ca/conf/CS.cfgfile, locate the certificate included in the following line:ca.connector.KRA.transportCert=certificate
ca.connector.KRA.transportCert=certificateCopy to Clipboard Copied! Toggle word wrap Toggle overflow Replace that certificate with the one contained in
cert-one-line-serial_number.txt.Start the CA:
pki-server start pki-ca
# pki-server start pki-caCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@pki-ca.service
# systemctl start pki-tomcatd-nuxwdog@pki-ca.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
NoteWhile 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
# cd /etc/pki/pki-kra/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the KRA:
pki-server stop pki-kra
# pki-server stop pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
# systemctl stop pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the new KRA transport certificate is imported:
certutil -d . -L certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfgfile, and look for thenickNamevalue included in the following line:kra.transportUnit.nickName=transportCert cert-pki-kra KRA
kra.transportUnit.nickName=transportCert cert-pki-kra KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow Replace the
nickNamevalue with thenewNickNamevalue included in the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow As a result, the
CS.cfgfile includes this line:kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow Remove the following line from
/var/lib/pki/pki-kra/kra/conf/CS.cfg:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the KRA:
pki-server start pki-kra
# pki-server start pki-kraCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using the
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@pki-kra.service
# systemctl start pki-tomcatd-nuxwdog@pki-kra.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.5. Smart card token management with Certificate System
A smart card is a hardware cryptographic device containing cryptographic certificates and keys. It can be employed by the user to participate in operations such as secure website access and secure mail. It can also serve as an authentication device to log in to various operating systems such as Red Hat Enterprise Linux. The management of these cards or tokens throughout their entire lifetime in service is accomplished by the Token Management System (TMS).
A TMS environment requires a Certificate Authority (CA), Token Key Service (TKS), and Token Processing System (TPS), with an optional Key Recovery Authority (KRA) for server-side key generation and key archival and recovery. Online Certificate Status Protocol (OCSP) can also be used to work with the CA to serve online certificate status requests. This chapter provides an overview of the TKS and TPS systems, which provide the smart card management functions of Red Hat Certificate System, as well as Enterprise Security Client (ESC), that works with TMS from the user end.
Figure 2.4. How the TMS manages smart cards
2.5.1. Token Key Service (TKS)
The Token Key Service (TKS) is responsible for managing one or more master keys. It maintains the master keys and is the only entity within the TMS that has access to the key materials. In an operational environment, each valid smart card token contains a set of symmetric keys that are derived from both the master key and the ID that is unique to the card (CUID).
Initially, a default (unique only per manufacturer master key) set of symmetric keys is initialized on each smart card by the manufacturer. This default set should be changed at the deployment site by going through a Key Changeover operation to generate the new master key on TKS. As the sole owner to the master key, when given the CUID of a smart card, TKS is capable of deriving the set of symmetric keys residing on that particular smart card, which would then allow TKS to establish a session-based Secure Channel for secure communication between TMS and each individual smart card.
Because of the sensitivity of the data that the TKS manages, the TKS should be set behind the firewall with restricted access.
2.5.1.1. Master keys and key sets
The TKS supports multiple smart card key sets. Each smart card vendor creates different default (developer) static key sets for their smart card token stocks, and the TKS is equipped with the static key set (per manufacturer) to kickstart the format process of a blank token.
During the format process of a blank smart card token, a Java applet and the uniquely derived symmetric key set are injected into the token. Each master key (in some cases referred to as keySet) that the TKS supports is to have a set of entries in the TKS configuration file (CS.cfg). Each TPS profile contains a configuration to direct its enrollment to the proper TKS keySet for the matching key derivation process that would essentially be responsible for establishing the Secure Channel secured by a set of session-specific keys between TMS and the smart card token.
On TKS, master keys are defined by named keySets for references by TPS. On TPS, depending on the enrollment type (internal or external registration), The keySet is either specified in the TPS profile, or determined by the keySet Mapping Resolver.
2.5.1.3. Key update (key changeover)
When Global Platform-compliant smart cards are created at the factory, the manufacturer will burn a set of default symmetric keys onto the token. The TKS is initially configured to use these symmetric keys (one KeySet entry per vendor in the TKS configuration). However, since these symmetric keys are not unique to the smart cards from the same stock, and because these are well-known keys, it is strongly encouraged to replace these symmetric keys with a set that is unique per token, not shared by the manufacturer, to restrict the set of entities that can manipulate the token.
The changing over of the keys takes place with the assistance of the Token Key Service subsystem. One of the functions of the TKS is to oversee the Master Keys from which the previously discussed smart card token keys are derived. There can be more than one master key residing under the control of the TKS.
When this key changeover process is done on a token, the token may become unusable in the future since it no longer has the default key set enabled. The key is essentially only as good as long as the TPS and TKS system that provisioned the token is valid. Because of this, it is essential to keep all the master keys, even if any of them are outdated.
You can disable the old master keys in TKS for better control, but do not delete them unless disabled tokens are part of your plan. There is support to revert the token keys back to the original key set, which is viable if the token is to be reused again in some sort of a testing scenario.
2.5.1.4. APDUs and secure channels
The Red Hat Certificate System Token Management System (TMS) supports the GlobalPlatform smart card specification, in which the Secure Channel implementation is done with the Token Key System (TKS) managing the master key and the Token Processing System (TPS) communicating with the smart card (tokens) with Application Protocol Data Units (APDUs).
There are two types of APDUs:
- Command APDUs, sent by the TPS to smart cards
- Response APDUs, sent by smart cards to the TPS as response to command APDUs
The initiation of the APDU commands may be triggered when clients take action and connect to the Certificate System server for requests. A secure channel begins with an InitializeUpdate APDU sent from TPS to the smart card token, and is fully established with the ExternalAuthenticate APDU. Then, both the token and TMS would have established a set of shared secrets, called session keys, which are used to encrypt and authenticate the communication. This authenticated and encrypted communication channel is called Secure Channel.
Because TKS is the only entity that has access to the master key which is capable of deriving the set of unique symmetric on-token smart card keys, the Secure Channel provides the adequately safeguarded communication between TMS and each individual token. Any disconnection of the channel will require reestablishment of new session keys for a new channel.
2.5.2. Token Processing System (TPS)
The Token Processing System (TPS) is a registration authority for smart card certificate enrollment. It acts as a conduit between the user-centered Enterprise Security Client (ESC), which interacts with client side smart card tokens, and the Certificate System back end subsystems, such as the Certificate Authority (CA) and the Key Recovery Authority (KRA).
In TMS, the TPS is required in order to manage smart cards, as it is the only TMS entity that understands the APDU commands and responses. TPS sends commands to the smart cards to help them generate and store keys and certificates for a specific entity, such as a user or device. Smart card operations go through the TPS and are forwarded to the appropriate subsystem for action, such as the CA to generate certificates or the KRA to generate, archive, or recover keys.
2.5.2.1. Coolkey applet
Red Hat Certificate System includes the Coolkey Java applet, written specifically to run on TMS-supported smart card tokens. The Coolkey applet connects to a PKCS#11 module that handles the certificate and key related operations. During a token format operation, this applet is injected onto the smart card token using the Secure Channel protocol, and can be updated per configuration.
2.5.2.2. Token operations
The TPS in Red Hat Certificate System is available to provision smart cards on the behalf of end users of the smart cards. The Token Processing System provides support for the following major token operations:
- Token Format - The format operation is responsible for installing the proper Coolkey applet onto the token. The applet provides a platform where subsequent cryptographic keys and certificates can be later placed.
Token Enrollment - The enrollment operation results in a smart card populated with required cryptographic keys and cryptographic certificates. This material allows the user of the smart card to participate in operations such as secure web site access and secure mail. Two types of enrollments are supported, which is configured globally:
- Internal Registration - Enrollment by TPS profiles determined by the profile Mapping Resolver.
- External Registration - Enrollment by TPS profiles determined by the entries in the user’s LDAP record.
- Token PIN Reset - The token PIN reset operation allows the user of the token to specify a new PIN that is used to log into the token, making it available for performing cryptographic operations.
The following other operations can be considered supplementary or inherent operations to the main ones listed above. They can be triggered per relevant configuration or by the state of the token.
Key Generation - Each PKI certificate is comprised of a public/private key pair. In Red Hat Certificate System, the generation of the keys can be done in two ways, depending on the TPS profile configuration:
- Token Side Key Generation - The PKI key pairs are generated on the smart card token. Generating the key pairs on the token side does not allow for key archival.
- Server Side Key Generation - The PKI key pairs are generated on the TMS server side. The key pairs are then sent back to the token using Secure Channel. Generating the key pairs on the server side allows for key archival.
- Certificate Renewal - This operation allows a previously enrolled token to have the certificates currently on the token reissued while reusing the same keys. This is useful in situations where the old certificates are due to expire and you want to create new ones but maintain the original key material.
Certificate Revocation - Certificate revocation can be triggered based on TPS profile configuration or based on token state.
Normally, only the CA which issued a certificate can revoke it, which could mean that retiring a CA would make it impossible to revoke certain certificates. However, it is possible to route revocation requests for tokens to the retired CA while still routing all other requests such as enrollment to a new, active CA. This mechanism is called Revocation Routing.
- Token Key Changeover - The key changeover operation, triggered by a format operation, results in the ability to change the internal keys of the token from the default developer key set to a new key set controlled by the deployer of the Token Processing System. This is usually done in any real deployment scenario since the developer key set is better suited to testing situations.
- Applet Update - During the course of a TMS deployment, the Coolkey smart card applet can be updated or downgraded if required.
2.5.2.3. TPS profiles
The Certificate System Token Processing System subsystem facilitates the management of smart card tokens. Tokens are provisioned by the TPS such that they are taken from a blank state to either a Formatted or Enrolled condition. A Formatted token is one that contains the CoolKey applet supported by TPS, while an Enrolled token is personalized (a process called binding) to an individual with the requisite certificates and cryptographic keys. This fully provisioned token is ready to use for crytptographic operations.
The TPS can also manage Profiles. The notion of a token Profile is related to:
- The steps taken to Format or Enroll a token.
- The attributes contained within the finished token after the operation has been successfully completed.
The following list contains some of the quantities that make up a unique token profile:
- How does the TPS connect to the user’s authentication LDAP database?
- Will user authentication be required for this token operation? If so, what authentication manager will be used?
- How does the TPS connect to a Certificate System CA from which it will obtain certificates?
- How are the private and public keys generated on this token? Are they generated on the token side or on the server side?
- What key size (in bits) is to be used when generating private and public keys?
Which certificate enrollment profile (provisioned by the CA) is to be used to generate the certificates on this token?
NoteThis setting will determine the final structure of the certificates to be written to the token. Different certificates can be created for different uses, based on extensions included in the certificate. For example, one certificate can specialize in data encryption, and another one can be used for signature operations.
- What version of the Coolkey applet will be required on the token?
- How many certificates will be placed on this token for an enrollment operation?
These above and many others can be configured for each token type or profile. A full list of available configuration options is available in the Red Hat Certificate System Administration Guide.
Another question to consider is how a given token being provisioned by a user will be mapped to an individual token profile. There are two types of registration:
-
Internal Registration - In this case, the TPS profile (
tokenType) is determined by the profile Mapping Resolver. This filter-based resolver can be configured to take any of the data provided by the token into account and determine the target profile. External Registration - When using external registration, the profile (in name only - actual profiles are still defined in the TPS in the same fashion as those used by the internal registration) is specified in each user’s LDAP record, which is obtained during authentication. This allows the TPS to obtain key enrollment and recovery information from an external registration Directory Server where user information is stored. This gives you the control to override the enrollment, revocation, and recovery policies that are inherent to the TPS internal registration mechanism. The user LDAP record attribute names relevant to external registration are configurable.
External registration can be useful when the concept of a "group certificate" is required. In that case, all users within a group can have a special record configured in their LDAP profiles for downloading a shared certificate and keys.
The registration to be used is configured globally per TPS instance.
2.5.2.4. Token database
The Token Processing System makes use of the LDAP token database store, which is used to keep a list of active tokens and their respective certificates, and to keep track of the current state of each token. A brand new token is considered Uninitialized, while a fully enrolled token is Enrolled. This data store is constantly updated and consulted by the TPS when processing tokens.
2.5.2.4.1. Token states and transitions
The Token Processing System stores states in its internal database in order to determine the current token status as well as actions which can be performed on the token.
2.5.2.4.1.1. Token states
The following table lists all possible token states:
| Name | Code | Label |
|---|---|---|
| FORMATTED | 0 | Formatted (uninitialized) |
| DAMAGED | 1 | Physically damaged |
| PERM_LOST | 2 | Permanently lost |
| SUSPENDED | 3 | Suspended (temporarily lost) |
| ACTIVE | 4 | Active |
| TERMINATED | 6 | Terminated |
| UNFORMATTED | 7 | Unformatted |
The command line interface displays token states using the Name listed above. The graphical interface uses the Label instead.
The above table contains no state with code 5, which previously belonged to a state that was removed.
2.5.2.4.1.2. Token state transitions done using the graphical or command line interface
Each token state has a limited amount of next states it can transition into. For example, a token can change state from FORMATTED to ACTIVE or DAMAGED, but it can never transition from FORMATTED to UNFORMATTED.
Furthermore, the list of states a token can transition into is different depending on whether the transition is triggered manually using a command line or the graphical interface, or automatically using a token operation. The list of allowed manual transitions is stored in the tokendb.allowedTransitions property, and the tps.operations.allowedTransitions property controls allowed transitions triggered by token operations.
The default configurations for both manual and token operation-based transitions are stored in the /usr/share/pki/tps/conf/CS.cfg configuration file.
2.5.2.4.1.2.1. Token state transitions using the command line or graphical interface
All possible transitions allowed in the command line or graphical interface are described in the TPS configuration file using the tokendb.allowedTransitions property:
tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7
tokendb.allowedTransitions=0:1,0:2,0:3,0:6,3:2,3:6,4:1,4:2,4:3,4:6,6:7
The property contains a comma-separated list of transitions. Each transition is written in the format of <current code>:_<new code>_. The codes are described in Table 2.10, “Possible manual token state transitions”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg.
The following table describes each possible transition in more detail:
| 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. |
The following transitions are generated automatically depending on the token’s original state. If a token was originally FORMATTED and then became SUSPENDED, it can only return to the FORMATTED state. If a token was originally ACTIVE and then became SUSPENDED, it can only return to the ACTIVE state.
| 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
All possible transitions that can be done using token operations are described in the TPS configuration file using the tokendb.allowedTransitions property:
tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0
tps.operations.allowedTransitions=0:0,0:4,4:4,4:0,7:0
The property contains a comma-separated list of transitions. Each transition is written in the format of <current code>:_<new code>_. The codes are described in Table 2.10, “Possible manual token state transitions”. The default configuration is preserved in /usr/share/pki/tps/conf/CS.cfg.
The following table describes each possible transition in more detail:
| 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
The default labels for token states and transitions are stored in the /usr/share/pki/tps/conf/token-states.properties configuration file. By default, the file has the following contents:
2.5.2.4.1.5. Customizing allowed token state transitions
To customize the list of token state transition, edit the following properties in /var/lib/pki/ instance_name/tps/conf/CS.cfg:
-
tokendb.allowedTransitionsto customize the list of allowed transitions performed using the command line or graphical interface -
tps.operations.allowedTransitionsto customize the list of allowed transitions using token operations
Transitions can be removed from the default list if necessary, but new transitions cannot be added unless they were in the default list. The defaults are stored in /usr/share/pki/tps/conf/CS.cfg.
2.5.2.4.1.6. Customizing token state and transition labels
To customize token state and transition labels, copy the default /usr/share/pki/tps/conf/token-states.properties into your instance folder (/var/lib/pki/ instance_name/tps/conf/CS.cfg), and change the labels listed inside as needed.
Changes will be effective immediately, the server does not need to be restarted. The TPS user interface may require a reload.
To revert to default state and label names, delete the edited token-states.properties file from your instance folder.
2.5.2.4.1.7. Token activity log
Certain TPS activities are logged. Possible events in the log file are listed in the table below.
| Activity | Description |
|---|---|
| add | A token was added. |
| format | A token was formatted. |
| enrollment | A token was enrolled. |
| recovery | A token was recovered. |
| renewal | A token was renewed. |
| pin_reset | A token PIN was reset. |
| token_status_change | A token status was changed using the command line or graphical interface. |
| token_modify | A token was modified. |
| delete | A token was deleted. |
| cert_revocation | A token certificate was revoked. |
| cert_unrevocation | A token certificate was unrevoked. |
2.5.2.4.2. Token policies
In case of internal registration, each token can be governed by a set of token policies. The default policies are:
RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YES
RE_ENROLL=YES;RENEW=NO;FORCE_FORMAT=NO;PIN_RESET=NO;RESET_PIN_RESET_TO_NO=NO;RENEW_KEEP_OLD_ENC_CERTS=YESAll TPS operations under internal registration are subject to the policies specified in the token’s record. If no policies are specified for a token, the TPS uses the default set of policies.
2.5.2.5. Mapping resolver
The Mapping Resolver is an extensible mechanism used by the TPS to determine which token profile to assign to a specific token based on configurable criteria. Each mapping resolver instance can be uniquely defined in the configuration, and each operation can point to various defined mapping resolver instance.
The mapping resolver framework provides a platform for writing custom plug-ins. However instructions on how to write a plug-in is outside the scope of this document.
FilterMappingResolver is the only mapping resolver implementation provided with the TPS by default. It allows you to define a set of mappings and a target result for each mapping. Each mapping contains a set of filters, where:
-
If the input filter parameters pass all filters within a mapping, the
targetvalue 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.
The input filter parameters are information received from the smart card token with or without extensions. They are run against the FilterMappingResolver according to the above rules. The following input filter parameters are supported by FilterMappingResolver:
-
appletMajorVersion- The major version of the Coolkey applet on the token. -
appletMinorVersion- The minor version of the Coolkey applet on the token. keySetortokenType-
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. ThekeySetMappingResolverhelps solve the issue by allowing the keySet to be resolved before authentication. -
tokenType- okenType can be set as an extension in the client request. It must match the value in the filter if the extension is specified. tokenType (also referred to as TPS Profile) is determined at this time for the internal registration environment.
-
-
tokenATR- The token’s Answer to Reset (ATR). -
tokenCUID- "start" and "end" define the range the Card Unique IDs (CUID) of the token must fall in to pass this filter.
2.5.2.6. TPS roles
The TPS supports the following roles by default:
TPS Administrator - this role is allowed to:
- Manage TPS tokens
- View TPS certificates and activities
- Manage TPS users and groups
- Change general TPS configuration
- Manage TPS authenticators and connectors
- Configure TPS profiles and profile mappings
- Configure TPS audit logging
TPS Agent - this role is allowed to:
- Configure TPS tokens
- View TPS certificates and activities
- Change the status of TPS profiles
TPS Operator - this role is allowed to:
- View TPS tokens, certificates, and activities
2.5.4. Enterprise Security Client (ESC)
The Enterprise Security Client is an HTTP client application, similar to a web browser, that communicates with the TPS and handles smart card tokens from the client side. While an HTTPS connection is established between the ESC and the TPS, an underlying Secure Channel is also established between the token and the TMS within each TLS session.
2.6. Red Hat Certificate System services
Certificate System has a number of different features for administrators to use which makes it easier to maintain the individual subsystems and the PKI as a whole.
2.6.1. Notifications
When a particular event occurs, such as when a certificate is issued or revoked, then a notification can be sent directly to a specified email address. The notification framework comes with default modules that can be enabled and configured.
2.6.2. Jobs
Automated jobs run at defined intervals.
2.6.3. Logging
The Certificate System and each subsystem produce extensive system and error logs that record system events so that the systems can be monitored and debugged. All log records are stored in the local file system for quick retrieval. Logs are configurable, so logs can be created for specific types of events and at the required logging level.
Certificate System allows logs to be signed digitally before archiving them or distributing them for auditing. This feature enables log files to be checked for tampering after being signed.
2.6.4. Auditing
The Certificate System maintains audit logs for all events, such as requesting, issuing and revoking certificates and publishing CRLs. These logs are then signed. This allows authorized access or activity to be detected. An outside auditor can then audit the system if required. The assigned auditor user account is the only account which can view the signed audit logs. This user’s certificate is used to sign and encrypt the logs. Audit logging is configured to specify the events that are logged.
2.6.5. Self-tests
The Certificate System provides the framework for system self-tests that are automatically run at startup and can be run on demand. A set of configurable self-tests are already included with the Certificate System.
2.6.6. Users, authorization, and access controls
Certificate System users can be assigned to groups, which are also known as roles, and they then have the privileges of whichever group they are members. A user only has privileges for the instance of the subsystem in which the user is created and the privileges of the group to which the user is a member.
Authentication is the means that Certificate System subsystems use to verify the identity of clients, whether they are authenticating to a certificate profile or to one of the services interfaces. There are a number of different ways for a client to perform authentication, including simple user name/password, SSL/TLS client authentication, LDAP authentication, NIS authentication, or CMC. Authentication can be performed for any access to the subsystem; for certificate enrollments, for example, the profile defines how the requestor authenticates to the CA.
Once the client is identified and authenticated, then the subsystems perform an authorization check to determine what level of access to the subsystem that particular user is allowed.
Authorization is tied to group, or role, permissions, rather than directly to individual users. The Certificate System provides an authorization framework for creating groups and assigning access control to those groups. The default access control on preexisting groups can be modified, and access control can be assigned to individual users and IP addresses. Access points for authorization have been created for the major portions of the system, and access control rules can be set for each point.
2.6.6.1. Default administrative roles
Red Hat Certificate System uses the words roles and groups interchangeably in the context of the permissions given to users.
The Certificate System is configured by default with three user types with different access levels to the system:
- Administrators, who can perform any administrative or configuration task for a subsystem.
- Agents, who perform PKI management tasks, like approving certificate requests, managing token enrollments, or recovering keys.
- Auditors, who can view and configure audit logs.
By default, for bootstrapping purposes, an administrative user processing both Administrator and Agent privileges is created during the Red Hat Certificate System instance creation, when running the pkispawn utility. This bootstrap administrator uses the caadmin user name by default but can be overridden by the pki_admin_uid parameter in the configuration file passed to the pkispawn command. The purpose of the bootstrap administrator is to create the first administrator and agent user. This operation requires the administrator privilege to mange user and groups, and the agent privilege to issue certificates.
2.6.6.2. Built-in subsystem trust roles
Additionally, when a security domain is created, the CA subsystem which hosts the domain is automatically granted the special role of Security Domain Administrator, which gives the subsystem the ability to manage the security domain and the subsystem instances within it. Other security domain administrator roles can be created for the different subsystem instances. These special roles should not have actual users as members.
2.7. Cloning
2.7.1. About cloning
Planning for high availability reduces unplanned outages and other problems by making one or more subsystem clones available. When a host machine goes down, the cloned subsystems can handle requests and perform services, taking over from the master (original) subsystem seamlessly and keeping uninterrupted service.
Using cloned subsystems also allows systems to be taken offline for repair, troubleshooting, or other administrative tasks without interrupting the services of the overall PKI system.
All of the subsystems except the TPS can be cloned.
Cloning is one method of providing scalability to the PKI by assigning the same task, such as handling certificate requests, to separate instances on different machines. The internal databases for the master and its clones are replicated between each other, so the information about certificate requests or archived keys on one subsystem is available on all the others.
Typically, master and cloned instances are installed on different machines, and those machines are placed behind a load balancer. The load balancer accepts HTTP and HTTPS requests made to the Certificate System subsystems and directs those requests appropriately between the master and cloned instances. In the event that one machine fails, the load balancer transparently redirects all requests to the machine that is still running until the other machine is brought back online.
Figure 2.5. Cloning example
The load balancer in front of a Certificate System subsystem is what provides the actual failover support in a high availability system. A load balancer can also provide the following advantages as part of a Certificate System subsystem:
- 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.
Normally, when a system is cloned, the configuration servlet sets up the replication agreements between the internal LDAP databases. However, some users may want to establish and manage their own replication agreements. The pkispawn executable has been modified to allow this by adding a [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
[Tomcat]
pki_clone_setup_replication=False
pki_clone_reindex_data=False
Data must be replicated before pkispawn is invoked when specifying this kind of installation.
2.7.2. Preparing clones
You need to export certificates to a 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.
Exporting Subsystem Certificates
You can verify that the exported p12 file contains the certificates. In the following example, the output of the pki pkcs12-cert-find returns four certificates:
With the exported p12 file, you can now set up a clone subsystem.
2.7.3. Cloning for CAs
Cloned instances have the exact same private keys as the master, so their certificates are identical. For CAs, that means that the CA signing certificates are identical for the original master CA and its cloned CAs. From the perspectives of clients, these look like a single CA.
Every CA, both cloned and master, can issue certificates and process revocation requests.
Only one replicated CA can generate, cache, and publish CRLs; this is the CRL CA. CRL requests submitted to other replicated CAs are immediately redirected to the CRL CA. While other replicated CAs can revoke, display, import, and download CRLs previously generated by the CRL CA, synchronization problems might occur if they generate new CRLs. For instructions on how to move CRL generation to a different replicated CA, see Section 9.5.1, “Converting CA clones and masters”.
Master CAs also manage the relationships and information sharing between the cloned CAs by monitoring replication changes to the internal databases.
If a CA which is a security domain master is cloned, then that cloned CA is also a security domain master. In that case, both the original CA and its clone share the same security domain configuration.
As covered in Section 2.7.9, “Custom configuration and clones”, the data within the LDAP database is replicated among a master and clones, but the configuration files for the different instances are not replicated. This means that any changes which affect the 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.
Any changes to the CA configuration should either be made to the master before any clones are created (so the custom changes are included in the cloning process) or any configuration changes must be copied over manually to the clone instances after they are created.
2.7.4. Cloning for KRAs
With KRAs, all keys archived in one KRA are replicated to the internal databases of the other KRAs. This allows a key recovery to be initiated on any clone KRA, regardless of which KRA the key was originally archived on.
After a key recovery is processed, the record of the recovery is stored in the internal database of all of the cloned KRAs.
With synchronous key recovery, although the recovery process can be initiated on any clone, it must be completed on the same single KRA on which it was initiated. This is because a recovery operation is recorded in the replicated database only after the appropriate number of approvals have been obtained from the KRA agents. Until then, the KRA on which the recovery is initiated is the only one which knows about the recovery operation.
There exists a synchronous key recovery mechanism that has been deprecated starting with Red Hat Certificate System 9 and is not discussed in this documentation. Red Hat recommends the use of asynchronous key recovery instead.
2.7.5. Cloning for other subsystems
There is no real operational difference between replicated TKSs; the information created or maintained on one is replicated along the other servers.
For OCSPs, only one replicated OCSP receives CRL updates, and then the published CRLs are replicated to the clones.
2.7.6. Cloning and key stores
Cloning a subsystem creates two server processes performing the same functions: another new instance of the subsystem is created and configured to use the same keys and certificates to perform its operations. Depending on where the keys are stored for the master clone, the method for the clone to access the keys is very different.
If the keys and certificates are stored in the internal software token, then they must be exported from the master subsystem when it is first configured. When configuring the master instance, it is possible to backup the system keys and certificates to a PKCS #12 file by specifying the 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.
If the keys were not backed up during the initial configuration, you can extract them to a PKCS #12 file using the PKCS12Export utility, as described in Section 9.1, “Backing up subsystem keys from a software database”.
Then copy the PKCS #12 file over to the host machine of the clone subsystem, and define its location and password in the 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.
If the keys and certificates are stored on a hardware token, then the keys and certificates must be copied using hardware token specific utilities or referenced directly in the token:
- 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
As mentioned in Section 2.7, “Cloning”, part of the behavior of cloning is to replicate information between replicated subsystems, so that they work from an identical set of data and records. This means that the LDAP servers for the replicated subsystems need to be able to communicate.
If the Directory Server instances are on different hosts, then make sure that there is appropriate firewall access to allow the Directory Server instances to connect with each other.
Cloned subsystems and their masters must use separate LDAP servers while they replicate data between common suffixes.
A subsystem can connect to its internal database using either SSL/TLS over an LDAPS port or over a standard connection over an LDAP port. When a subsystem is cloned, the clone instance uses the same connection method (SSL/TLS or standard) as its master to connect to the database. With cloning, there is an additional database connection though: the master Directory Server database to the clone Directory Server database. For that connection, there are three connection options:
- 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.
NoteTo 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.
Whatever connection method (secure or standard) used by the master must be used by the clone and must be properly configured for the Directory Server databases prior to configuring the clone.
Even if the clone connects to the master over a secure connection, the standard LDAP port (389 by default) must still be open and enabled on the LDAP server while cloning is configured.
For secure environments, the standard LDAP port can be disabled on the master’s Directory Server instance once the clone is configured.
2.7.8. Replica ID numbers
Cloning is based on setting up a replication agreement between the Directory Server for the master instance and the Directory Server for the cloned instance.
Servers involved together with replication are in the same replication topology. Every time a subsystem instance is cloned, it is added to the overall topology. Directory Server discerns between different servers in the topology based on their replica ID number. This replica ID must be unique among all of the servers in the topology.
Every subsystem is assigned a range of allowed replica IDs. When the subsystem is cloned, it assigns one of the replica IDs from its range to the new clone instance.
dbs.beginReplicaNumber=1 dbs.endReplicaNumber=95
dbs.beginReplicaNumber=1
dbs.endReplicaNumber=95The replica ID range can be refreshed with new numbers if an instance begins to exhaust its current range.
2.7.9. Custom configuration and clones
After a clone is created, configuration changes are not replicated between clones or between a master and a clone. The instance configuration is in the CS.cfg file - outside the replicated database.
For example, there are two CAs, a master and a clone. A new KRA is installed which is associated, at its configuration, with the master CA. The CA-KRA connector information is stored in the master CA’s 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.
Changes made to the configuration of a master server or to a clone server are not replicated to other cloned instances. Any critical settings must be added manually to clones.
You can set all required, custom configuration for a master server before configuring any clones. For example, install all KRAs so that all the connector information is in the master CA configuration file, create any custom profiles, or configure all publishing points for a master OCSP responder. Note that if the LDAP profiles are stored in the Directory Server, they are replicated and kept in sync across servers.
Any custom settings in the master instance will be included in the cloned instance at the time they are cloned (but not after).
Chapter 3. Supported standards and protocols
Red Hat Certificate System is based on many public and standard protocols and RFCs, to ensure the best possible performance and interoperability. The major standards and protocols used or supported by Certificate System {VER} are outlined in this chapter, to help administrators plan their client services effectively.
3.1. TLS, ECC, and RSA
The Transport Layer Security (TLS) protocol is an universally accepted standard for authenticated and encrypted communication between clients and servers. Both client and server authentication occur over TLS.
TLS uses a combination of public-key and symmetric-key encryption. Symmetric-key encryption is much faster than public-key encryption, but public-key encryption provides better authentication techniques. An TLS session always begins with an exchange of messages called handshake, initial communication between the server and client. The handshake allows the server to authenticate itself to the client using public-key techniques, optionally allows the client to authenticate to the server, then allows the client and the server to cooperate in the creation of symmetric keys used for rapid encryption, decryption, and integrity verification during the session that follows.
TLS supports a variety of different cryptographic algorithms, or ciphers, for operations such as authenticating the server and client, transmitting certificates, and establishing session keys. Clients and servers may support different cipher suites, or sets of ciphers. Among other functions, the handshake determines how the server and client negotiate which cipher suite is used to authenticate each other, to transmit certificates, and to establish session keys.
Key-exchange algorithms like RSA and Elliptic Curve Diffie-Hellman (ECDH) govern the way the server and client determine the symmetric keys to use during an TLS session. TLS supports ECC (Elliptic Curve Cryptography) cipher suites, as well as RSA. The Certificate System supports both RSA and ECC public-key cryptographic systems natively.
In more recent practise, key-exchange algorithms are being superseded by key-agreement protocols where each of the two or more parties can influence the outcome when establishing a common key for secure communication. Key agreement is preferrable to key exchange because it allows for Perfect Forward Secrecy (PFS) to be implemented. When PFS is used, random public keys (also called temporary cipher parameters or ephemeral keys) are generated for each session by a non-deterministic algorithm for the purposes of key agreement. As a result, there is no single secret value which could lead to the compromise of multiple messages, protecting past and future communication alike.
Longer RSA keys are required to provide security as computing capabilities increase. The recommended RSA key-length is 2048 bits. Though many servers continue to use 1024-bit keys, servers should migrate to at least 2048 bits. For 64-bit machines, consider using stronger keys. All CAs should use at least 2048-bit keys, and stronger keys (such as 3072 or 4096 bits) if possible.
3.1.1. Supported cipher suites
Cipher and hashing algorithms are in a constant flux with regard to various vulnerabilities and security strength. As a general rule, Red Hat Certificate System follows the NIST guideline and supports TLS 1.1 and TLS 1.2 cipher suites pertaining to the server keys.
3.1.2. Recommended TLS cipher suites
The Transport Layer Security (TLS) protocol is a universally accepted standard for authenticated and encrypted communication between clients and servers. Red Hat Certificate System supports TLS 1.1 and 1.2.
Red Hat Certificate System supports the following cipher suites when the server is acting either as a server or as a client:
- 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
Red Hat Certificate System supports the following key algorithms and sizes if they are provided by the underlying PKCS #11 module.
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
The following keyed hash messages authentication (HMAC) are allowed:
- SHA-256
- SHA-384
- SHA-512
The following cryptographic hashing functions are allowed:
- SHA-256
- SHA-384
- SHA-512
3.4. IPv4 and IPv6 addresses
Certificate System supports both IPv4 addresses and IPv6 addresses. In a very wide variety of circumstances, Certificate System subsystems or operations reference a host name or IP address; supporting both IPv4- and IPv6-style addresses ensures forward compatibility with network protocols. The operations that support IPv6 connections include the following:
- 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
pkiutility, the Subject Alt Name Extension tool, HttpClient, and the Bulk Issuance Tool -
Client communications, including both the
pkiconsoleutility 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
Any time a host name or URL is referenced, an IP address can be used:
-
An IPv4 address must be in the format
n.n.n.norn.n.n.n,m.m.m.m. For example,128.21.39.40or128.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.
If DNS is properly configured, then an IPv4 or IPv6 address can be used to connect to the web services pages and to the subsystem Java consoles. The most common method is to use fully-qualified domain names:
https://ipv6host.example.com:8443/ca/services pkiconsole https://ipv6host.example.com:8443/ca
https://ipv6host.example.com:8443/ca/services
pkiconsole https://ipv6host.example.com:8443/ca
To use IPv6 numeric addresses, replace the fully-qualified domain name in the URL with the IPv6 address, enclosed in brackets: [<IPv6_address>]. 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
https://[00:00:00:00:123:456:789:00:]:8443/ca/services
pkiconsole https://[00:00:00:00:123:456:789:00:]:8443/ca3.5. Supported PKIX formats and protocols
The Certificate System supports many of the protocols and formats defined in Public-Key Infrastructure (X.509) by the IETF. In addition to the PKIX standards listed here, other PKIX-listed standards are available at the IETF Datatracker website.
| 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. |
| Automated Certificate Management Environment (ACME) | RFC 8555 | A protocol for automated identifier validation and certificate issuance. |
| Enrollment over Secure Transport (EST) | RFC 7030 | A cryptographic protocol designed to provide secure certificate enrollment for devices. |
Chapter 4. Supported platforms
This section describes the different server platforms, hardware, tokens, and software supported by Red Hat Certificate System 10.
4.1. General requirements
For details, see the corresponding section in the Red Hat Certificate System 10 Release Notes.
4.2. Server support
Running the Certificate Authority (CA), Key Recovery Authority (KRA), Online Certificate Status Protocol (OCSP), Token Key Service (TKS), Token Processing System (TPS), Automated Certificate Management Environment (ACME), and Enrollment over Secure Transport (EST) subsystems of Certificate System 10.8 is supported on Red Hat Enterprise Linux 8.10 and later. The supported Red Hat Directory Server version is 11.9 and later.
Certificate System 10.8 is supported running on a Red Hat Enterprise Linux 8.10 virtual guest on a certified hypervisor. For details, see the Which hypervisors are certified to run Red Hat Enterprise Linux? solution article.
4.3. Supported web browsers
Red Hat Certificate System 10 supports the following browsers:
| Platform | Agent Services | End User Pages |
|---|---|---|
| Red Hat Enterprise Linux | Firefox 60 and later [a] | Firefox 60 and later |
[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.
| ||
The only fully-supported browser for the HTML-based instance configuration is Mozilla Firefox.
4.4. Supported Hardware Security Modules
The following table lists Hardware Security Modules (HSM) supported by Red Hat Certificate System:
| 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
Each Red Hat Certificate System subsystem can be installed on the same server machine, installed on separate servers, or have multiple instances installed across an organization. Before installing any subsystem, it is important to plan the deployment out: what kind of PKI services do you need? What are the network requirements? What people need to access the Certificate System, what are their roles, and what are their physical locations? What kinds of certificates do you want to issue and what constraints or rules need to be set for them?
This chapter covers some basic questions for planning a Certificate System deployment. Many of these decisions are interrelated; one choice impacts another, like deciding whether to use smart cards determines whether to install the TPS and TKS subsystems.
5.1. Deciding on the required subsystems
The Certificate System subsystems cover different aspects of managing certificates. Planning which subsystems to install is one way of defining what PKI operations the deployment needs to perform.
Certificates, like software or equipment, have a lifecycle with defined stages. At its most basic, there are three steps:
- It is requested and issued.
- It is valid.
- It expires.
However, this simplified scenario does not cover a lot of common issues with certificates:
- 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?
This introduces three other considerations for managing certificates: revocation, renewal, and replacements.
Other considerations are the loads on the certificate authority. Are there a lot of issuance or renewal requests? Is there a lot of traffic from clients trying to validate whether certificates are valid? How are people requesting certificates supposed to authenticate their identity, and does that process slow down the issuance process?
5.1.1. Using a single Certificate Manager
The core of the Certificate System PKI is the Certificate Manager, a certificate authority. The CA receives certificate requests and issues all certificates.
Figure 5.1. CA only Certificate System
All of the basic processing for requests and issuing certificates can be handled by the Certificate Manager, and it is the only required subsystem. There can be a single Certificate Manager or many Certificate Managers, arranged in many different relationships, depending on the demands of the organization.
Along with issuing certificates, a Certificate Manager can also revoke certificates. One question for administrators is how to handle certificates if they are lost, compromised, or if the person or equipment for which they are issued leaves the company. Revoking a certificate invalidates it before its expiration date, and a list of revoked certificates is compiled and published by the issuing CA so that clients can verify the certificate status.
5.1.2. Planning for lost keys: key archival and recovery
One operation the CA cannot perform, though, is key archival and recovery. A very real scenario is that a user is going to lose his private key -for instance, the keys could be deleted from a browser database or a smart card could be left at home. Many common business operations use encrypted data, like encrypted email, and losing the keys which unlock that data means the data itself is lost. Depending on the policies in the company, there probably has to be a way to recover the keys in order to regenerate or reimport a replacement certificate, and both operations require the private key.
That requires a KRA, the subsystem which specially archives and retrieves keys.
Figure 5.2. CA and KRA
The Key Recovery Authority stores encryption keys (key archival) and can retrieve those keys so that the CA can reissue a certificate (key recovery). A KRA can store keys for any certificate generated by Certificate System, whether it is done for a regular certificate or when enrolling a smart card.
The key archival and recovery process is explained in more detail in Section 2.4.5, “Archiving, recovering, and rotating keys”.
The KRA is intended for archival and recovery of private encryption keys only. Therefore, end users must use a browser that supports dual-key generation to store their public-private key pairs.
5.1.3. Balancing certificate request processing
Another aspect of how the subsystems work together is load balancing. If a site has high traffic, then it is possible to simply install a lot of CAs, as clones of each other or in a flat hierarchy (where each CA is independent) or in a tree hierarchy (where some CAs are subordinate to other CAs); this is covered more in Section 5.2, “Defining the Certificate Authority hierarchy”.
5.1.4. Balancing client OCSP requests
If a certificate is within its validity period but needs be invalidated, it can be revoked. A Certificate Manager can publish lists of revoked certificates, so that when a client needs to verify that a certificate is still valid, it can check the list. These requests are online certificate status protocol requests, meaning that they have a specific request and response format. The Certificate Manager has a built-in OCSP responder so that it can verify OCSP requests by itself.
However, as with certificate request traffic, a site may have a significant number of client requests to verify certificate status. Example Corp. has a large web store, and each customer’s browser tries to verify the validity of their SSL/TLS certificates. Again, the CA can handle issuing the number of certificates, but the high request traffic affects its performance. In this case, Example Corp. uses the external OCSP Manager subsystem to verify certificate statuses, and the Certificate Manager only has to publish updated CRLs every so often.
Figure 5.3. CA and OCSP
5.1.5. Using smart cards
Smart cards usually require in-person enrollment and approval processes, since they use a physical medium to store key and certificate data. That means that multiple agents need to have access to the TPS and, possibly, multiple TPS subsystems in different offices or geographic locations.
The token management system is very scalable. Multiple TPSs can be configured to work with a single CA, TKS, or KRA instance, while multiple Enterprise Security Clients can communicate with a single TPS. As additional clients are installed, they can point back to the TPS instance without having to reconfigure the TPS; likewise, as TPSs are added, they can point to the same CA, TKS, and KRA instances without having to reconfigure those subsystems.
After installation, the TPS configuration can be edited to use additional CA, KRA, and TKS instances for failover support, so if the primary subsystem is unavailable, the TPS can switch to the next available system without interrupting its token services.
5.2. Defining the Certificate Authority hierarchy
The CA is the center of the PKI, so the relationship of CA systems, both to each other (CA hierarchy) and to other subsystems (security domain) is vital to planning a Certificate System PKI.
When there are multiple CAs in a PKI, the CAs are structured in a hierarchy or chain. The CA above another CA in a chain is called an root CA; a CA below another CA in the chain is called a subordinate CA. A CA can also be subordinate to a root outside of the Certificate System deployment; for example, a CA which functions as a root CA within the Certificate System deployment can be subordinate to a third-party CA.
A Certificate Manager (or CA) is subordinate to another CA because its CA signing certificate, the certificate that allows it to issue certificates, is issued by another CA. The CA that issued the subordinate CA signing certificate controls the CA through the contents of the CA signing certificate. The CA can constrain the subordinate CA through the kinds of certificates that it can issue, the extensions that it is allowed to include in certificates, the number of levels of subordinate CAs the subordinate CA can create, and the validity period of certificates it can issue, as well as the validity period of the subordinate CAs signing certificate.
Although a subordinate CA can create certificates that violate these constraints, a client authenticating a certificate that violates those constraints will not accept that certificate.
A self-signed root CA signs its own CA signing certificate and sets its own constraints as well as setting constraints on the subordinate CA signing certificates it issues.
A Certificate Manager can be configured as either a root CA or a subordinate CA. It is easiest to make the first CA installed a self-signed root, so that it is not necessary to apply to a third party and wait for the certificate to be issued. Before deploying the full PKI, however, consider whether to have a root CA, how many to have, and where both root and subordinate CAs will be located.
5.2.1. Subordination to a public CA
Chaining the Certificate System CA to a third-party public CA introduces the restrictions that public CAs place on the kinds of certificates the subordinate CA can issue and the nature of the certificate chain. For example, a CA that chains to a third-party CA might be restricted to issuing only Secure Multipurpose Internet Mail Extensions (S/MIME) and SSL/TLS client authentication certificates, but not SSL/TLS server certificates. There are other possible restrictions with using a public CA. This may not be acceptable for some PKI deployments.
One benefit of chaining to a public CA is that the third party is responsible for submitting the root CA certificate to a web browser or other client software. This can be a major advantage for an extranet with certificates that are accessed by different companies with browsers that cannot be controlled by the administrator. Creating a root CA in the CA hierarchy means that the local organization must get the root certificate into all the browsers which will use the certificates issued by the Certificate System. There are tools to do this within an intranet, but it can be difficult to accomplish with an extranet.
5.2.2. Subordination to a Certificate System CA
The Certificate System CA can function as a root CA, meaning that the server signs its own CA signing certificate as well as other CA signing certificates, creating an organization-specific CA hierarchy. The server can alternatively be configured as a subordinate CA, meaning the server’s CA signing key is signed by another CA in an existing CA hierarchy.
Setting up a Certificate System CA as the root CA means that the Certificate System administrator has control over all subordinate CAs by setting policies that control the contents of the CA signing certificates issued. A subordinate CA issues certificates by evaluating its own authentication and certificate profile configuration, without regard for the root CA’s configuration.
5.2.3. Linked CA
The Certificate System Certificate Manager can function as a linked CA, chaining up to many third-party or public CAs for validation; this provides cross-company trust, so applications can verify certificate chains outside the company certificate hierarchy. A Certificate Manager is chained to a third-party CA by requesting the Certificate Manager’s CA signing certificate from the third-party CA.
Related to this, the Certificate Manager also can issue cross-pair or cross-signed certificates. Cross-pair certificates create a trusted relationship between two separate CAs by issuing and storing cross-signed certificates between these two CAs. By using cross-signed certificate pairs, certificates issued outside the organization’s PKI can be trusted within the system.
These are also called bridge certificates, related to the Federal Bridge Certification Authority (FBCA) definition.
5.2.4. CA cloning
Instead of creating a hierarchy of root and subordinate CAs, it is possible to create multiple clones of a Certificate Manager and configure each clone to issue certificates within a range of serial numbers.
A cloned Certificate Manager uses the same CA signing key and certificate as another Certificate Manager, the master Certificate Manager.
If there is a chance that a subsystem will be cloned, then it is easiest to export its key pairs during the configuration process and save them to a secure location. The key pairs for the original Certificate Manager have to be available when the clone instance is configured, so that the clone can generate its certificates from the original Certificate Manager’s keys.
It is also possible to export the keys from the security databases at a later time, using the pk12util or the PKCS12Export commands.
Because clone CAs and original CAs use the same CA signing key and certificate to sign the certificates they issue, the issuer name in all the certificates is the same. Clone CAs and the original Certificate Managers issue certificates as if they are a single CA. These servers can be placed on different hosts for high availability failover support.
The advantage of cloning is that it distributes the Certificate Manager’s load across several processes or even several physical machines. For a CA with a high enrollment demand, the distribution gained from cloning allows more certificates to be signed and issued in a given time interval.
A cloned Certificate Manager has the same features, such as agent and end-entity gateway functions, of a regular Certificate Manager.
Each clone is assigned a unique replica ID from the range assigned to the subsystem that’s being cloned, see Replica ID numbers.
5.3. Planning security domains
A security domain is a registry of PKI services. PKI services, such as CAs, register information about themselves in these domains so users of PKI services can find other services by inspecting the registry. The security domain service in Certificate System manages both the registration of PKI services for Certificate System subsystems and a set of shared trust policies.
The registry provides a complete view of all PKI services provided by the subsystems within that domain. Each Certificate System subsystem must be either a host or a member of a security domain.
A CA subsystem is the only subsystem which can host a security domain. The security domain shares the CA internal database for privileged user and group information to determine which users can update the security domain, register new PKI services, and issue certificates.
A security domain is created during CA configuration, which automatically creates an entry in the security domain CA’s LDAP directory. Each entry contains all the important information about the domain. Every subsystem within the domain, including the CA registering the security domain, is recorded under the security domain container entry.
The URL to the CA uniquely identifies the security domain. The security domain is also given a friendly name, such as 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.
Each subsystem within the security domain shares the same trust policies and trusted roots which can be retrieved from different servers and browsers. The information available in the security domain is used during configuration of a new subsystem, which makes the configuration process streamlined and automated. For example, when a TPS needs to connect to a CA, it can consult the security domain to get a list of available CAs.
Each CA has its own LDAP entry. The security domain is an organizational group underneath that CA entry:
ou=Security Domain,dc=server.example.com-pki-ca
ou=Security Domain,dc=server.example.com-pki-ca
Then there is a list of each subsystem type beneath the security domain organizational group, with a special object class (pkiSecurityGroup) to identify the group type:
cn=KRAList,ou=Security Domain,o=pki-tomcat-CA objectClass: top objectClass: pkiSecurityGroup cn: KRAList
cn=KRAList,ou=Security Domain,o=pki-tomcat-CA
objectClass: top
objectClass: pkiSecurityGroup
cn: KRAList
Each subsystem instance is then stored as a member of that group, with a special pkiSubsystem object class to identify the entry type:
If a subsystem needs to contact another subsystem to perform an operation, it contacts the CA which hosts the security domain (by invoking a servlet which connects over the administrative port of the CA). The security domain CA then retrieves the information about the subsystem from its LDAP database, and returns that information to the requesting subsystem.
The subsystem authenticates to the security domain using a subsystem certificate.
Consider the following when planning the security domain:
- 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
The CA configuration determines many of the characteristics of the certificates which it issues, regardless of the actual type of certificate being issued. Constraints on the CA’s own validity period, distinguished name, and allowed encryption algorithms impact the same characteristics in their issued certificates. Additionally, the Certificate Managers have predefined profiles that set rules for different kinds of certificates that they issue, and additional profiles can be added or modified. These profile configurations also impact issued certificates.
5.4.1. Determining which certificates to install
When a Certificate System subsystem is first installed and configured, the certificates necessary to access and administer it are automatically created. These include an agent’s certificate, server certificate, and subsystem-specific certificates. These initial certificates are shown in Table 5.1, “Initial subsystem certificates”.
| Subsystem | Certificates |
|---|---|
| Certificate Manager |
|
| OCSP |
|
| KRA |
|
| TKS |
|
| TPS |
|
There are some cautionary considerations about replacing existing subsystem certificates.
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.transportCertparameter. - 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
The core elements of a CA are a signing unit and the Certificate Manager identity. The signing unit digitally signs certificates requested by end entities. A Certificate Manager must have its own distinguished name (DN), which is listed in every certificate it issues.
Like any other certificate, a CA certificate binds a DN to a public key. A DN is a series of name-value pairs that in combination uniquely identify an entity. For example, the following DN identifies a Certificate Manager for the Engineering department of a corporation named Example Corporation:
cn=demoCA, o=Example Corporation, ou=Engineering, c=US
cn=demoCA, o=Example Corporation, ou=Engineering, c=USMany combinations of name-value pairs are possible for the Certificate Manager’s DN. The DN must be unique and readily identifiable, since any end entity can examine it.
5.4.3. Setting the CA signing certificate validity period
Every certificate, including a Certificate Manager signing certificate, must have a validity period. The Certificate System does not restrict the validity period that can be specified. Set as long a validity period as possible, depending on the requirements for certificate renewal, the place of the CA in the certificate hierarchy, and the requirements of any public CAs that are included in the PKI.
A Certificate Manager cannot issue a certificate that has a validity period longer than the validity period of its CA signing certificate. If a request is made for a period longer than the CA certificate’s validity period, the requested validity date is ignored and the CA signing certificate validity period is used.
5.4.4. Choosing the signing key type and length
A signing key is used by a subsystem to verify and "seal" something. CAs use a CA signing certificate to sign certificates or CRLs that it issues; OCSPs use signing certificates to verify their responses to certificate status requests; all subsystems use log file signing certificates to sign their audit logs.
The signing key must be cryptographically strong to provide protection and security for its signing operations. The following signing algorithms are considered secure:
- SHA256withRSA
- SHA512withRSA
- SHA256withEC
- SHA512withEC
Certificate System includes native ECC support. It is also possible to load and use a third-party PKCS #11 module with ECC-enabled. This is covered in Section 7.2, “Installing RHCS using the pkispawn utility”.
Along with a key type, each key has a specific bit length. Longer keys are considered cryptographically stronger than shorter keys. However, longer keys require more time for signing operations.
The default RSA key length in the configuration wizard is 2048 bits; for certificates that provide access to highly sensitive data or services, consider increasing the length to 4096 bits. ECC keys are much stronger than RSA keys, so the recommended length for ECC keys is 256 bits, which is equivalent in strength to a 2048-bit RSA key.
5.4.5. Using certificate extensions
An X.509 v3 certificate contains an extension field that permits any number of additional fields to be added to the certificate. Certificate extensions provide a way of adding information such as alternative subject names and usage restrictions to certificates. Older Netscape servers, such as Red Hat Directory Server and Red Hat Certificate System, require Netscape-specific extensions because they were developed before PKIX part 1 standards were defined.
The X.509 v1 certificate specification was originally designed to bind public keys to names in an X.500 directory. As certificates began to be used on the Internet and extranets and directory lookups could not always be performed, problem areas emerged that were not covered by the original specification.
- 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.
The X.509 v3 specification addressed these issues by altering the certificate format to include additional information within a certificate by defining a general format for certificate extensions and specifying extensions that can be included in the certificate. The extensions defined for X.509 v3 certificates enable additional attributes to be associated with users or public keys and manage the certification hierarchy. The Internet X.509 Public Key Infrastructure Certificate and CRL Profile recommends a set of extensions to use for Internet certificates and standard locations for certificate or CA information. These extensions are called standard extensions.
The X.509 v3 standard for certificates allows organizations to define custom extensions and include them in certificates. These extensions are called private, proprietary, or custom extensions, and they carry information unique to an organization or business. Applications may not able to validate certificates that contain private critical extensions, so it not recommended that these be used in wide-spread situations.
The X.500 and X.509 specifications are controlled by the International Telecommunication Union (ITU), an international organization that primarily serves large telecommunication companies, government organizations, and other entities concerned with the international telecommunications network. The Internet Engineering Task Force (IETF), which controls many of the standards that underlie the Internet, is currently developing public-key infrastructure X.509 (PKIX) standards. These proposed standards further refine the X.509 v3 approach to extensions for use on the Internet. The recommendations for certificates and CRLs have reached proposed standard status and are in a document referred to as PKIX Part 1.
Two other standards, Abstract Syntax Notation One (ASN.1) and Distinguished Encoding Rules (DER), are used with Certificate System and certificates in general. These are specified in the CCITT Recommendations X.208 and X.209. For a quick summary of ASN.1 and DER, see A Layman’s Guide to a Subset of ASN.1, BER, and DER, which is available at RSA Laboratories' web site, http://www.rsa.com.
5.4.5.1. Structure of certificate extensions
In RFC 3280, an X.509 certificate extension is defined as follows:
Extension ::= SEQUENCE {
extnID OBJECT IDENTIFIER,
critical BOOLEAN DEFAULT FALSE,
extnValue OCTET STRING }
Extension ::= SEQUENCE {
extnID OBJECT IDENTIFIER,
critical BOOLEAN DEFAULT FALSE,
extnValue OCTET STRING }The means a certificate extension consists of the following:
-
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 either
trueorfalse, 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.
Typically, the application receiving the certificate checks the extension ID to determine if it can recognize the ID. If it can, it uses the extension ID to determine the type of value used.
Some of the standard extensions defined in the X.509 v3 standard include the following:
- 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.
Not all applications support certificates with version 3 extensions. Applications that do support these extensions may not be able to interpret some or all of these specific extensions.
5.4.6. Using and customizing certificate profiles
Certificates have different types and different applications. They can be used to establish a single sign-on environment for a corporate network, to set up VPNs, to encrypt email, or to authenticate to a website. The requirements for all of these certificates can be different, just as there may also be different requirements for the same type of certificate for different kinds of users. These certificate characteristics are set in certificate profiles. The Certificate Manager defines a set of certificate profiles that it uses as enrollment forms when users or machines request certificates.
Certificate profiles
A certificate profile defines everything associated with issuing a particular type of certificate, including the authentication method, the certificate content (defaults), constraints for the values of the content, and the contents of the input and output for the certificate profile. Enrollment requests are submitted to a certificate profile and are then subject to the defaults and constraints set in that certificate profile. These constraints are in place whether the request is submitted through the input form associated with the certificate profile or through other means. The certificate that is issued from a certificate profile request contains the content required by the defaults with the information required by the default parameters. The constraints provide rules for what content is allowed in the certificate.
For example, a certificate profile for user certificates defines all aspects of that certificate, including the validity period of the certificate. The default validity period can be set to two years, and a constraint can be set on the profile that the validity period for certificates requested through this certificate profile cannot exceed two years. When a user requests a certificate using the input form associated with this certificate profile, the issued certificate contains the information specified in the defaults and will be valid for two years. If the user submits a pre-formatted request for a certificate with a validity period of four years, the request is rejected since the constraints allow a maximum of two years validity period for this type of certificate.
A set of certificate profiles have been predefined for the most common certificates issued. These certificate profiles define defaults and constraints, associate the authentication method, and define the needed inputs and outputs for the certificate profile.
Modifying the certificate profile parameters
The parameters of the default certificate profiles can be modified; this includes the authentication method, the defaults, the constraints used in each profile, the values assigned to any of the parameters in a profile, the input, and the output. It is also possible to create new certificate profiles for other types of certificates or for creating more than one certificate profile for a certificate type. There can be multiple certificate profiles for a particular type of certificate to issue the same type of certificate with a different authentication method or different definitions for the defaults and constraints. For example, there can be two certificate profiles for enrollment of SSL/TLS server certificates where one certificate profile issues certificates with a validity period of six months and another certificate profile issues certificates with a validity period of two years.
An input sets a text field in the enrollment form and what kind of information needs gathered from the end entity; this includes setting the text area for a certificate request to be pasted, which allows a request to be created outside the input form with any of the request information required. The input values are set as values in the certificate. The default inputs are not configurable in the Certificate System.
An output specifies how the response page to a successful enrollment is presented. It usually displays the certificate in a user-readable format. The default output shows a printable version of the resultant certificate; other outputs set the type of information generated at the end of the enrollment, such as PKCS #7.
Policy sets are sets of constraints and default extensions attached to every certificate processed through the profile. The extensions define certificate content such as validity periods and subject name requirements. A profile handles one certificate request, but a single request can contain information for multiple certificates. A PKCS#10 request contains a single public key. One CRMF request can contain multiple public keys, meaning multiple certificate requests. A profile may contain multiple sets of policies, with each set specifying how to handle one certificate request within a CRMF request.
Certificate Profile Administration
An administrator sets up a certificate profile by associating an existing authentication plug-in, or method, with the certificate profile; enabling and configuring defaults and constraints; and defining inputs and outputs. The administrator can use the existing certificate profiles, modify the existing certificate profiles, create new certificate profiles, and delete any certificate profile that will not be used in this PKI.
Once a certificate profile is set up, it appears on the Manage Certificate Profiles page of the agent services page where an agent can approve, and thus enable, a certificate profile. Once the certificate profile is enabled, it appears on the Certificate Profile tab of the end-entities page where end entities can enroll for a certificate using the certificate profile.
The certificate profile enrollment page in the end-entities interface contains links to each certificate profile that has been enabled by the agents. When an end entity selects one of those links, an enrollment page appears containing an enrollment form specific to that certificate profile. The enrollment page is dynamically generated from the inputs defined for the profile. If an authentication plug-in is configured, additional fields may be added to authenticate the user.
When an end entity submits a certificate profile request that is associated with an agent-approved (manual) enrollment, an enrollment where no authentication plug-in is configured, the certificate request is queued in the agent services interface. The agent can change some aspects of the enrollment, request, validate it, cancel it, reject it, update it, or approve it. The agent is able to update the request without submitting it or validate that the request adheres to the profile’s defaults and constraints. This validation procedure is only for verification and does not result in the request being submitted. The agent is bound by the constraints set; they cannot change the request in such a way that a constraint is violated. The signed approval is immediately processed, and a certificate is issued.
When a certificate profile is associated with an authentication method, the request is approved immediately and generates a certificate automatically if the user successfully authenticates, all the information required is provided, and the request does not violate any of the constraints set up for the certificate profile. There are profile policies which allow user-supplied settings like subject names or validity periods. The certificate profile framework can also preserve user-defined content set in the original certificate request in the issued certificate.
The issued certificate contains the content defined in the defaults for this certificate profile, such as the extensions and validity period for the certificate. The content of the certificate is constrained by the constraints set for each default. Multiple policies (defaults and constraints) can be set for one profile, distinguishing each set by using the same value in the policy set ID. This is particularly useful for dealing with dual keys enrollment where encryption keys and signing keys are submitted to the same profile. The server evaluates each set with each request it receives. When a single certificate is issued, one set is evaluated, and any other sets are ignored. When dual-key pairs are issued, the first set is evaluated with the first certificate request, and the second set is evaluated with the second certificate request. There is no need for more than one set for issuing a single certificate or more than two sets for issuing dual-key pairs.
Guidelines for customizing certificate profiles
Tailor the profiles for the organization to the real needs and anticipated certificate types used by the organization:
- 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
Certificate System enables adding Subject Alternative Name (SAN) extensions to the SSL server certificate during the installation of non-root CA or other Certificate System instances. To do so, follow the instructions in the /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 (,).
For example:
pki_san_inject=True pki_san_for_server_cert=intca01.example.com,intca02.example.com,intca.example.com
pki_san_inject=True
pki_san_for_server_cert=intca01.example.com,intca02.example.com,intca.example.com5.4.7. Planning authentication methods
As implied in Section 5.4.6, “Using and customizing certificate profiles”, authentication for the certificate process means the way that a user or entity requesting a certificate proves that they are who they say they are. There are three ways that the Certificate System can authenticate an entity:
- 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.
A Certificate Manager is initially configured for agent-approved enrollment and for CMC authentication. Automated enrollment is enabled by configuring one of the authentication plug-in modules. More than one authentication method can be configured in a single instance of a subsystem. The HTML registration pages contain hidden values specifying the method used. With certificate profiles, the end-entity enrollment pages are dynamically-generated for each enabled profile. The authentication method associated with this certificate profile is specified in the dynamically-generated enrollment page.
The authentication process is simple.
- 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.
The requirements for how a certificate request is authenticated can have a direct impact on the necessary subsystems and profile settings. For example, if an agent-approved enrollment requires that an agent meet the requester in person and verify their identity through supported documentation, the authentication process can be time-intensive, as well as constrained by the physical availability of both the agent and the requester.
5.4.8. Publishing certificates and CRLs
A CA can publish both certificates and CRLs. Certificates can be published to a plain file or to an LDAP directory; CRLs can be published to file or an LDAP directory, as well, and can also be published to an OCSP responder to handle certificate verification.
Configuring publishing is fairly straightforward and is easily adjusted. For continuity and accessibility, though, it is good to plan out where certificates and CRLs need to be published and what clients need to be able to access them.
Publishing to an LDAP directory requires special configuration in the directory for publishing to work:
- 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
When a CA signing certificate expires, all certificates signed with the CA’s corresponding signing key become invalid. End entities use information in the CA certificate to verify the certificate’s authenticity. If the CA certificate itself has expired, applications cannot chain the certificate to a trusted CA.
There are two ways of resolving CA certificate expiration:
- 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.
There are problems and advantages with either renewing or reissuing a CA certificate. Begin planning the CA certificate renewal or re-issuance before installing any Certificate Managers, and consider the ramifications the planned procedures may have for extensions, policies, and other aspects of the PKI deployment.
Correct use of extensions, for example the authorityKeyIdentifier extension, can affect the transition from an old CA certificate to a new one.
5.5. Planning for network and physical security
When deploying any Certificate System subsystem, the physical and network security of the subsystem instance has to be considered because of the sensitivity of the data generated and stored by the subsystems.
5.5.1. Considering firewalls
There are two considerations about using firewalls with Certificate System subsystems:
- Protecting sensitive subsystems from unauthorized access
- Allowing appropriate access to other subsystems and clients outside of the firewall
The CA, KRA, and TKS are always placed inside a firewall because they contain critical information that can cause devastating security consequences if they are compromised.
The TPS and OCSP can be placed outside the firewall. Likewise, other services and clients used by the Certificate System can be on a different machine outside the firewall. In that case, the local networks have to be configured to allow access between the subsystems behind the firewall and the services outside it.
The LDAP database can be on a different server, even on a different network, than the subsystem which uses it. In this case, all LDAP ports (389 for LDAP and 636 for LDAPS, by default) need to be open in the firewall to allow traffic to the directory service. Without access to the LDAP database, all subsystem operations can fail.
As part of configuring the firewalls, if iptables is enabled, then it must have configured policies to allow communication over the appropriate Certificate System ports. Configuring iptables is described in the Using and configuring firewalld guide.
5.5.2. Considering physical security and location
Because of the sensitive data they hold, consider keeping the CA, KRA, and TKS in a secure facility with adequate physical access restrictions. Just as network access to the systems needs to be restricted, the physical access also needs to be restricted.
Along with finding a secure location, consider the proximity to the subsystem agents and administrators. Key recovery, for example, can require multiple agents to give approval; if these agents are spread out over a large geographical area, then the time differences may negatively impact the ability to retrieve keys. Plan the physical locations of the subsystems, then according to the locations of the agents and administrators who will manage the subsystem.
5.5.3. Planning ports
Each Certificate System server uses up to four 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
All of the service pages and interfaces described in the Red Hat Certificate System User Interfaces chapter in the Red Hat Certificate System Administration Guide are connected to using the instance’s URL and the corresponding port number. For example:
https://server.example.com:8443/ca/ee/ca
https://server.example.com:8443/ca/ee/caTo access the admin console, the URL specifies the admin port:
pkiconsole https://server.example.com:8443/ca
pkiconsole https://server.example.com:8443/caAll agent and admin functions require SSL/TLS client authentication. For requests from end entities, the Certificate System listens on both the SSL/TLS (encrypted) port and non-SSL/TLS ports.
The ports are defined in the server.xml file. If a port is not used, it can be disabled in that file. For example:
<Service name="Catalina">
<!--Connector port="8080" ... /--> unused standard port
<Connector port="8443" ... />
<Service name="Catalina">
<!--Connector port="8080" ... /--> unused standard port
<Connector port="8443" ... />Whenever a new instance in installed, make sure that the new ports are unique on the host system.
To verify that a port is available for use, check the appropriate file for the operating system. Port numbers for network-accessible services are usually maintained in a file named services. On Red Hat Enterprise Linux, it is also helpful to confirm that a port is not assigned by SELinux, by running the command semanage port -l to list all ports which currently have an SELinux context.
When a new subsystem instance is created, any number between 1 and 65535 can be specified as the secure port number.
5.6. Tokens for storing Certificate System subsystem keys and certificates
A token is a hardware or software device that performs cryptographic functions and stores public-key certificates, cryptographic keys, and other data. The Certificate System defines two types of tokens, internal and external, for storing key pairs and certificates that belong to the Certificate System subsystems.
An internal (software) token is a pair of files, usually called the certificate database (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.
These security databases are located in the /var/lib/pki/ instance_name/alias directory.
An external token refers to an external hardware device, such as a smart card or hardware security module (HSM), that the Certificate System uses to generate and store its key pairs and certificates. The Certificate System supports any hardware tokens that are compliant with PKCS #11.
PKCS #11 is a standard set of APIs and shared libraries which isolate an application from the details of the cryptographic device. This enables the application to provide a unified interface for PKCS #11-compliant cryptographic devices.
The PKCS #11 module implemented in the Certificate System supports cryptographic devices supplied by many different manufacturers. This module allows the Certificate System to plug in shared libraries supplied by manufacturers of external encryption devices and use them for generating and storing keys and certificates for the Certificate System managers.
Consider using external tokens for generating and storing the key pairs and certificates used by Certificate System. These devices are another security measure to safeguard private keys because hardware tokens are sometimes considered more secure than software tokens.
Before using external tokens, plan how the external token is going to be used with the subsystem:
- 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.
The Certificate System can also use hardware cryptographic accelerators with external tokens. Many of the accelerators provide the following security features:
- 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.
The Certificate System supports the nCipher nShield hardware security module (HSM), by default. Certificate System-supported HSMs are automatically added to the 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.
During configuration, the Security Modules panel displays the supported modules, along with the NSS internal software PKCS#11 module. All supported modules that are detected show a status of Found and is individually marked as either Logged in or Not logged in. If a token is found but not logged in, it is possible to log in using the under Operations. If the administrator can log into a token successfully, the password is stored in a configuration file. At the next start or restart of the Certificate System instance, the passwords in the password store are used to attempt a login for each corresponding token.
Administrators are allowed to select any of the tokens that are logged in as the default token, which is used to generate system keys.
5.7. A Checklist for planning the PKI
- How many security domains will be created, and what subsystem instances will be placed in each domain?
- A subsystem can only communicate with another subsystem if they have a trusted relationship. Because the subsystems within a security domain have automatic trusted relationships with each other, it is important what domain a subsystem joins. Security domains can have different certificate issuing policies, different kinds of subsystems within them, or a different Directory Server database. Map out where (both on the physical machine and in relation to each other) each subsystem belongs, and assign it to the security domain accordingly.
- 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?
- The most secure solution is to use separate ports for each SSL/TLS interface. However, the feasibility of implementing multiple ports may depends on your network setup, firewall rules, and other network conditions.
- 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?
The location to install a subsystem depends on the network design. The OCSP subsystem is specifically designed to operate outside a firewall for user convenience, while the CA, KRA, and TPS should all be secured behind a firewall for increased security.
When deciding the location of the subsystems, it is critical to plan what other subsystems or services that server needs to access (including the internal database, a CA, or external users) and look at firewall, subnet, and VPN configuration.
- What subsystems need to be physically secured? How will access be granted, and who will be granted access?
- The CA, TKS, and KRA all store extremely sensitive key and certificate information. For some deployments, it may be necessary to limit physical access to the machines these subsystems run on. In that case, both the subsystems and their host machines must be included in the larger infrastructure inventory and security design.
- 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?
- The physical location of Certificate System users may impact things like request approval and token enrollment, as well as system performance because of network lag time. The importance of response time for processing certificate operations should be taken into account when deciding where and how many subsystems to install.
- How many subsystems do you need to install?
The primary consideration is the expected load for each subsystem and then, secondarily, geographical or departmental divisions. Subsystems with fairly low loads (like the KRA or TKS) may only require a single instance for the entire PKI. Systems with high load (the CA) or which may benefit from local instances for local agents (like the TPS) may require multiple instances.
Subsystems can be cloned, meaning they essentially are clustered, operating as a single unit, which is good for load balancing and high availability. Cloning is especially good for CAs and KRAs, where the same key and certificate data may need to be accessed by larger numbers of users or to have reliable failover.
When planning for multiple subsystem instances, keep in mind how the subsystems fit within the established security domains. Security domains create trusted relationships between subsystems, allowing them to work together to find available subsystems to respond to immediate needs. Multiple security domains can be used in a single PKI, with multiple instances of any kind of subsystem, or a single security domain can be used for all subsystems.
- Will any subsystems need to be cloned and, if so, what are the methods for securely storing their key materials?
- Cloned subsystems work together, essentially as a single instance. This can be good for high demand systems, failover, or load balancing.
- Will the subsystem certificates and keys be stored on the internal software token in Certificate System or on an external hardware token?
- Certificate System supports two hardware security modules (HSM): nCipher nShield and Safenet LunaSA. Using a hardware token can require additional setup and configuration before installing the subsystems, but it also adds another layer of security.
- 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?
The real question here is, will the CA bee a root CA which sets its own rules on issuing certificates or will it be a subordinate CA where another CA (another CA in your PKI or even an external CA) sets restrictions on what kind of certificates it can issue.
A Certificate Manager can be configured as either a root CA or a subordinate CA. The difference between a root CA and a subordinate CA is who signs the CA signing certificate. A root CA signs its own certificate. A subordinate CA has another CA (either internal or external) sign its certificate.
A self-signing root CA issues and signs its own CA signing certificate. This allows the CA to set its own configuration rules, like validity periods and the number of allowed subordinate CAs.
A subordinate CA has its certificates issued by a public CA or another Certificate System root CA. This CA is subordinate to the other CA’s rules about its certificate settings and how the certificate can be used, such as the kinds of certificates that it can issue, the extensions that it is allowed to include in certificates, and the levels of subordinate CAs the subordinate CA can create.
One option is to have the Certificate manager subordinate to a public CA. This can be very restrictive, since it introduces the restrictions that public CAs place on the kinds of certificates the subordinate CA can issue and the nature of the certificate chain. On the other hand, one benefit of chaining to a public CA is that the third party is responsible for submitting the root CA certificate to a web browser or other client software, which is a major advantage for certificates that are accessed by different companies with browsers that cannot be controlled by the administrator.
The other option is make the CA subordinate to a Certificate System CA. Setting up a Certificate System CA as the root CA means that the Certificate System administrator has control over all subordinate CAs by setting policies that control the contents of the CA signing certificates issued.
It is easiest to make the first CA installed a self-signed root, so that it is not necessary to apply to a third party and wait for the certificate to be issued. Make sure that you determine how many root CAs to have and where both root and subordinate CAs will be located.
- 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?
- As touched on in Section 5.4.6, “Using and customizing certificate profiles”, the profiles (the forms which configure each type of certificate issued by a CA) can be customized. This means that the subject DN, the validity period, the type of SSL/TLS client, and other elements can be defined by an administrator for a specific purpose. For security, profiles should provide only the functionality that is required by the PKI. Any unnecessary profiles should be disabled.
- 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?
The request approval process directly impacts the security of the certificate. Automated processes are much faster but are less secure since the identity of the requester is only superficially verified. Likewise, agent-approved enrollments are more secure (since, in the most secure scenario they can require an in-person verification and supporting identification) but they can also be the most time-consuming.
First determine how secure the identity verification process needs to be, then determine what authentication (approval) mechanism is required to validate that identity.
- Will many external clients need to validate certificate status? Can the internal OCSP in the Certificate Manager handle the load?
- Publishing CRLs and validating certificates is critical. Determine what kinds of clients will be checking the certificate status (will it mainly be internal clients? external clients? will they be validating user certificates or server certificates?) and also try to determine how many OCSP checks will be run. The CA has an internal OCSP which can be used for internal checks or infrequent checks, but a large number of OCSP checks could slow down the CA performance. For a larger number of OCSP checks and especially for large CRLs, consider using a separate OCSP Manager to take the load off the CA.
- Will the PKI allow replacement keys? Will it require key archival and recovery?
- If lost certificates or tokens are simply revoked and replaced, then there does not need to be a mechanism to recover them. However, when certificates are used to sign or encrypt data such as emails, files, or harddrives, then the key must always be available so that the data can be recovered. In that case, use a KRA to archive the keys so the data can always be accessed.
- Will the organization use smart cards? If so, will temporary smart cards be allowed if smart cards are mislaid, requiring key archival and recovery?
- If no smart cards are used, then it is never necessary to configure the TPS or TKS, since those subsystems are only used for token management. However, if smart cards are used, then the TPS and TKS are required. If tokens can be lost and replaced, then it is also necessary to have a KRA to archive the keys so that the token’s certificates can be regenerated.
- 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?
- The important thing to determine is what clients need to be able to access the certificate or CRL information and how that access is allowed. From there, you can define the publishing policy.
Part II. Installing Red Hat Certificate System
This part describes the requirements and procedures for installing Red Hat Certificate System.
Chapter 6. Prerequisites and Preparation for Installation
The Red Hat Certificate System installation process requires some preparation of the environment. This chapter describes the requirements, dependencies, and other prerequisites when installing Certificate System subsystems.
6.1. Installing Red Hat Enterprise Linux
Red Hat Certificate System 10.8 requires the Red Hat Enterprise Linux 8.10 version. For details about installing Red Hat Enterprise Linux, see Performing a standard RHEL installation.
To enable the Federal Information Processing Standard (FIPS) on Red Hat Enterprise Linux, see the Red Hat Security Hardening Guide.
It is strongly recommended that FIPS mode is enabled on the RHEL host before you install Certificate System.
Enable FIPS:
fips-mode-setup --enable
# fips-mode-setup --enableCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Restart the system.
Verify FIPS mode is enabled:
sysctl crypto.fips_enabled
# sysctl crypto.fips_enabledCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the returned value is
1, FIPS mode is enabled.
When FIPS mode is enabled for RHEL, the attached HSM used by Certificate System must also be in FIPS mode. See Section 6.2.1, “Enabling FIPS mode on an HSM”.
6.1.1. Securing the system using SELinux
Security-Enhanced Linux (SELinux) is an implementation of a mandatory access control mechanism in the Linux kernel, checking for allowed operations after standard discretionary access controls are checked. SELinux can enforce rules on files and processes in a Linux system, and on their actions, based on defined policies.
In most cases, no actions are required to run Certificate System with SELinux in 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.
By default, after installing Red Hat Enterprise Linux, SELinux is enabled and running in enforcing mode and no further actions are required.
To verify the current SELinux mode, enter:
getenforce
# getenforceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
For further details about SELinux, see the Using SELinux Guide.
6.1.2. Configuring the firewall
The following table lists the default ports used by Certificate System subsystems:
| Service | Port | Protocol |
|---|---|---|
| HTTP | 8080 | TCP |
| HTTPS | 8443 | TCP |
| Tomcat Management | 8005 | TCP |
When you set up Certificate System using the 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 Opening the required ports in the firewall. For further details about ports, see Section 5.5.3, “Planning ports”.
For ports required to access Directory Server, see the corresponding section in the DirectoryServer Installation Guide.
Opening the required ports in the firewall
To enable communication between the clients and Certificate System, open the required ports in your firewall:
Make sure the
firewalldservice is running.systemctl status firewalld
# systemctl status firewalldCopy to Clipboard Copied! Toggle word wrap Toggle overflow To start
firewalldand configure it to start automatically when the system boots:systemctl start firewalld systemctl enable firewalld
# systemctl start firewalld # systemctl enable firewalldCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the required ports using the
firewall-cmdutility. 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}# firewall-cmd --permanent --add-port={8080/tcp,8443/tcp,8009/tcp,8005/tcp}Copy to Clipboard Copied! Toggle word wrap Toggle overflow For details on using
firewall-cmdto open ports on a system, see Securing Networks or the firewall-cmd(1) man page.Reload the firewall configuration to ensure that the change takes place immediately:
firewall-cmd --reload
# firewall-cmd --reloadCopy to Clipboard Copied! Toggle word wrap Toggle overflow
6.2. Hardware Security Module
To use a Hardware Security Module (HSM), a Federal Information Processing Standard (FIPS) 140-2 validated HSM is required. The Certificate System supports the nCipher nShield hardware security module (HSM) and Gemalto Safenet LunaSA HSM by default. Certificate System-supported HSMs are automatically added to the 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.
6.2.1. Enabling FIPS mode on an HSM
Certain deployments require to setup their HSM to use FIPS mode. To enable FIPS Mode on HSMs, please refer to your HSM vendor’s documentation for specific instructions.
- 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-worldcommand. 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.2.2. Verifying if FIPS mode is enabled on an HSM
This section describes how to verify if FIPS mode is enabled for certain HSMs. For other HSMs, see the hardware manufacturer’s documentation.
6.2.2.1. Verifying if FIPS mode is enabled on an nCipher HSM
Please refer to your HSM vendor’s documentation for the complete procedure.
To verify if the FIPS mode is enabled on an nCipher HSM, enter:
/opt/nfast/bin/nfkminfo
# /opt/nfast/bin/nfkminfo
With older versions of the software, if the StrictFIPS140 is listed in the state flag, the FIPS mode is enabled. In newer 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.2.2.2. Verifying if FIPS mode is enabled on a Luna SA HSM
Please refer to your HSM vendor’s documentation for the complete procedure.
To verify if the FIPS mode is enabled on a Luna SA HSM:
-
Open the
lunashmanagement console Use the
hsm showcommand and verify that the output contains the textThe HSM is in FIPS 140-2 approved operation mode.:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
6.2.3. Setting up SELinux for an HSM
Certain HSMs require that you manually update SELinux settings before you can install Certificate System.
The following section describes the required actions for supported HSMs:
- 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/
# restorecon -R /opt/nfast/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the
nfastsoftware./opt/nfast/sbin/init.d-ncipher restart
# /opt/nfast/sbin/init.d-ncipher restartCopy to Clipboard Copied! Toggle word wrap Toggle overflow
- Gemalto Safenet LunaSA HSM
- No SELinux-related actions are required before you start installing Certificate System.
For details about the supported HSMs, see Section 4.4, “Supported Hardware Security Modules”.
6.2.4. Preparing for installing Certificate System with an HSM
In Section 7.2, “Installing RHCS using the 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:
-
The values of the
pki_hsm_libfileandpki_token_nameparameter depend on your specific HSM installation. These values allow thepkispawnutility to set up your HSM and enable Certificate System to connect to it. -
The value of the
pki_token_passworddepends upon your particular HSM token’s password. The password gives thepkispawnutility read and write permissions to create new keys on the HSM. -
The value of the
pki_hsm_modulenameis a name used in laterpkispawnoperations to identify the HSM. The string is an identifier you can set as whatever you like. It allowspkispawnand Certificate System to refer to the HSM and configuration information by name in later operations.
The following section provides settings for individual HSMs. If your HSM is not listed, consult your HSM manufacturer’s documentation.
For more information on using an HSM, see Using hardware security modules with subsystems.
6.2.4.1. nCipher HSM parameters
For an nCipher HSM, set the following parameters:
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so pki_hsm_modulename=nfast
pki_hsm_libfile=/opt/nfast/toolkits/pkcs11/libcknfast.so
pki_hsm_modulename=nfast
Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.
Example 6.1. Identifying the token name
To identify the token name, run the following command as the root user:
The value of the name field in the Cardset section lists the token name.
Set the token name as follows:
pki_token_name=NHSM-CONN-XC
pki_token_name=NHSM-CONN-XC6.2.4.2. SafeNet / Luna SA HSM parameters
For a SafeNet / Luna SA HSM, such as a SafeNet Luna Network HSM, specify the following parameters:
pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so pki_hsm_modulename=lunasa
pki_hsm_libfile=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
pki_hsm_modulename=lunasa
Note that you can set the value of pki_hsm_modulename to any value. The above is a suggested value.
Example 6.2. Identifying the token name
To identify the token name, run the following command as the root user:
The value in the label column lists the token name.
Set the token name as follows:
pki_token_name=lunasaQE
pki_token_name=lunasaQE6.3. Red Hat Directory Server installation prerequisites
You must ensure certain prerequisites are met prior to installing PKI subsystems. Every system must have a correctly configured fully qualified domain name (FQDN)
Additionally, for every Certificate System instance installation, you must install a Directory Server instance and it is likely to be on a separate host from the Certificate System instance, you must ensure the hostname is configured correctly and recognized by the Certificate System instance hosts.
6.3.1. FQDN configuration
In order to have a properly functioning PKI system, each machine in the system must have a correct fully qualified domain name.
Follow this process to configure the fully qualified domain name on each machine.
6.3.1.1. Verifying FQDN
To verify the current FQDN, execute the following command:
hostname
# hostname
pki.example.com6.3.1.2. Configuring FQDN
If the host name is not what you expect it to be, run hostnamectl to set the hostname. For example,
Set the hostname of your pki machine as follows:
hostnamectl set-hostname pki.example.com
# hostnamectl set-hostname pki.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set the hostname of your DS machine as follows:
hostnamectl set-hostname dir.example.com
# hostnamectl set-hostname dir.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add both the CS and DS machine IP addresses and new hostnames as entries in
/etc/hostsof both machines:127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 10.1.111.111 pki.example.com 10.2.222.222 dir.example.com
127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 10.1.111.111 pki.example.com 10.2.222.222 dir.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the FQDN again after the change:
hostname
# hostnameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
6.3.2. Installing Red Hat Directory Server
Red Hat Certificate System uses Red Hat Directory Server to store system certificates and user data. You can install both Directory Server and Certificate System on the same host or on different hosts in the network.
If you are enabling FIPS mode on the RHEL system that is hosting the Directory Server, FIPS mode must be enabled on the RHEL host before you install the Directory Server.
To ensure FIPS mode is enabled:
sysctl crypto.fips_enabled
# sysctl crypto.fips_enabled
If the returned value is 1, FIPS mode is enabled.
6.3.2.1. Installing the Directory Server packages
Perform the following steps to install the Red Hat Directory Server packages:
Pin the RHEL version to 8.10 by using the
subscription-manager release --setcommand. For example:subscription-manager release --list subscription-manager release --set 8.10
# subscription-manager release --list # subscription-manager release --set 8.10Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verification:
subscription-manager release --show
subscription-manager release --showCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Make sure you have attached a subscription that provides Directory Server to the host.
Enable the Directory Server packages repository:
subscription-manager repos --enable=dirsrv-11.9-for-rhel-8-x86_64-rpms
# subscription-manager repos --enable=dirsrv-11.9-for-rhel-8-x86_64-rpmsCopy to Clipboard Copied! Toggle word wrap Toggle overflow Install the Directory Server and the openldap-clients packages:
dnf module install redhat-ds:11
# dnf module install redhat-ds:11Copy to Clipboard Copied! Toggle word wrap Toggle overflow
6.3.2.2. Directory Server instance creation
Note: Prior to installing DS instances, make sure the following procedures are done:
- Installing DS packages - done on the DS host system
- Setting the FQDN of the host system - done on the host systems of DS and PKI
Follow this process to prepare a local DS instance for PKI server.
Note: The DS installation automatically generates a bootstrap self-signed signing certificate which issues a bootstrap server certificate for SSL connection. The PKI installation takes advantage of this security offer to complete its installation. The bootstrap server certificate could be replaced by a server certificate issued by an actual CA at a later step after the installation.
If you wish to disable bootstrap certificate generation and SSL connection, set self_sign_cert = False in the sed command below. You can still enable SSL later by following Enabling SSL Connection in DS with Bootstrap Cert.
6.3.2.2.1. Creating a DS Instance
6.3.2.2.1.1. Generating a DS configuration file, for example ds.inf:
dscreate create-template ds.inf
$ dscreate create-template ds.infCustomize the DS configuration file as follows:
+ where
-
instance_name specifies the name of the DS instance. In this example it’s set to
localhost. -
root_password specifies the password for DS admin, that is
cn=Directory Manager. In this example it is set toSecret.123. -
suffix specifies the namespace for the DS instance. In this example it is set to
dc=example,dc=com. self_sign_cert specifies whether to create self-signed certificates for SSL connection. In this example it is set to
True. The SSL connection is enabled.For more information see the parameter descriptions in the DS configuration file itself, that is,
ds.inf, and in DS documentation.
For more information see the parameter descriptions in the DS configuration file itself (i.e. ds.inf) and in DS documentation.
6.3.2.2.1.2. Creating an instance
Finally, create the instance:
dscreate from-file ds.inf
$ dscreate from-file ds.inf6.3.2.2.2. Creating PKI subtree
Note: The dc=pki,dc=example,dc=com subtree is not mandatory, but it is highly recommended in order to avoid conflicts with other applications sharing the same DS instance.
Initially the DS instance is empty. Use an LDAP client to add a root entry and PKI base entry, for example:
ldapadd -H ldap://$HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 << EOF dn: dc=pki,dc=example,dc=com objectClass: domain dc: pki EOF
$ ldapadd -H ldap://$HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 << EOF
dn: dc=pki,dc=example,dc=com
objectClass: domain
dc: pki
EOFThe subtree for each PKI subsystem is created when the subsystem is installed. When all PKI subsystems are created, the LDAP tree looks like the following:
6.3.2.2.3. Enabling SSL connection
If you set self_sign_cert = False earlier, and now decide to create bootstrap certs so that your PKI can be installed using SSL connection to DS, follow Enabling SSL Connection in DS
Note: The bootstrap server certificate could be replaced by a server certificate issued by an actual CA at a later step after the installation.
6.3.2.2.4. Configuring replication
6.3.2.2.5. Removing DS instance
To remove DS instance:
dsctl localhost remove --do-it
$ dsctl localhost remove --do-it6.3.2.2.6. Log Files
DS log files are available in /var/log/dirsrv/slapd-localhost:
- access
- audit
- errors
6.3.2.2.7. See Also
6.3.2.3. Attaching a Red Hat subscription and enabling the Certificate System package repository
Before you can install and update Certificate System, you must enable the corresponding repository:
Pin the RHEL version to 8.10 by using the
subscription-manager release --setcommand. For example:subscription-manager release --list subscription-manager release --set 8.10
# subscription-manager release --list # subscription-manager release --set 8.10Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verification:
subscription-manager release --show
subscription-manager release --showCopy to Clipboard Copied! Toggle word wrap Toggle overflow Attach the Red Hat subscriptions to the system:
Skip this step, if your system is already registered or has a subscription that provides Certificate System attached.
Register the system to the Red Hat subscription management service.
You can use the
--auto-attachoption to automatically apply an available subscription for the operating system.Copy to Clipboard Copied! Toggle word wrap Toggle overflow List the available subscriptions and note the pool ID providing the Red Hat Certificate System. For example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 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
# subscription-manager list --available --all > /root/subscriptions.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Attach the Certificate System subscription to the system using the pool ID from the previous step:
subscription-manager attach --pool=7aba89677a6a38fc0bba7dac673f7993
# subscription-manager attach --pool=7aba89677a6a38fc0bba7dac673f7993 Successfully attached a subscription for: Red Hat Enterprise Linux Developer SuiteCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Enable the Certificate System repository:
subscription-manager repos --enable certsys-10.x-for-rhel-8-x86_64-rpms
# subscription-manager repos --enable certsys-10.x-for-rhel-8-x86_64-rpms Repository 'certsys-10-for-rhel-8-x86_64-rpms' is enabled for this system.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the Certificate System module stream:
dnf module enable redhat-pki
# dnf module enable redhat-pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Installing the required packages is described in the Chapter 7, Installing and configuring Red Hat Certificate System.
For compliance, only enable Red Hat approved repositories. Only Red Hat approved repositories can be enabled through subscription-manager utility.
6.4. Certificate System packages
When installing the Certificate System packages you can either install them for each subsystem individually or all at once.
To install and update Certificate System packages, you must enable the corresponding repository. For details, see Section 6.3.2.3, “Attaching a Red Hat subscription and enabling the Certificate System package repository”.
The following subsystem packages and components are available in Red Hat Certificate System:
- 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
- pki-acme: Provides Automatic Certificate Management Environment (ACME).
- pki-est: Provides Enrollment over Secure Transport (EST).
6.4.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 which include CA, KRA, OCSP, TKS, TPS, ACME, and EST.
dnf install redhat-pki
# dnf install redhat-pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Alternatively, you can install packages separately. For example, to install the CA subsystem and the optional web interface:
dnf install pki-ca redhat-pki-server-theme
# dnf install pki-ca redhat-pki-server-themeCopy to Clipboard Copied! Toggle word wrap Toggle overflow 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:
dnf install pki-console redhat-pki-console-theme
# dnf install pki-console redhat-pki-console-themeCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteThe
pkiconsoletool will be deprecated.If you are installing the PKI CLI on a machine that does not have a PKI server, execute the following command:
dnf install redhat-pki-tools
# dnf install redhat-pki-toolsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
6.4.2. Updating Certificate System packages
To update Certificate System and operating system packages, use the following procedure:
- Follow instructions in Section 6.4.3, “Determining Certificate System product version” to check the product version.
Execute \# dnf update
The command above updates the whole system including the RHCS packages.
NoteWe suggest scheduling a maintenance window during which you can take the PKI infrastructure offline to install the update.
ImportantUpdating Certificate System requires the PKI infrastructure to be restarted.
Then check version again by following Section 6.4.3, “Determining Certificate System product version”.
The version number should confirm that the update was successfully installed.
To optionally download updates without installing, use the --downloadonly option in the above procedure:
dnf update --downloadonly
dnf update --downloadonly
The downloaded packages are stored in the /var/cache/dnf/ directory. The dnf update will later use the packages if they are the latest versions.
6.4.3. Determining Certificate System product version
The Red Hat Certificate System product version is stored in the /usr/share/pki/CS`SERVER_VERSION file. To display the version:
cat /usr/share/pki/CS_SERVER_VERSION
Red Hat Certificate System {Version} (Batch Update 1)
# cat /usr/share/pki/CS_SERVER_VERSION
Red Hat Certificate System {Version} (Batch Update 1)To find the product version of a running server, access the following URLs from your browser:
-
http://<hostname>:<port_number>/ca/admin/ca/getStatus -
http://<hostname>:<port_number>/kra/admin/kra/getStatus -
http://<hostname>:<port_number>/ocsp/admin/ocsp/getStatus -
http://<hostname>:<port_number>/tks/admin/tks/getStatus -
http://<hostname>:<port_number>/tps/admin/tps/getStatus
Note that each component is a separate package and thus could have a separate version number. The above will show the version number for each currently running component.
6.5. Certificate System operating system users and groups
When installing Certificate System, the pkiuser account and the corresponding pkiuser group are automatically created. Certificate System uses this account and group to start services.
As part of a post-installation procedure, you will later be instructed to create an operating system user for each Certificate System administrator who should be able to start and stop or directly configure the instance on the operating system. For details, see Section 7.5, “Post-installation tasks”.
Chapter 7. Installing and configuring Red Hat Certificate System
Red Hat Certificate System provides different subsystems that can be installed individually. For example, you can install multiple subsystem instances on a single server or you can run them independently on different hosts. This enables you to adapt the installation to your environment to provide a higher availability, scalability, and fail-over support. This chapter describes the package installation and how to set up the individual subsystems.
The Certificate System includes the following subsystems:
- Certificate Authority (CA)
- Key Recovery Authority (KRA)
- Online Certificate Status Protocol (OCSP) Responder
- Token Key Service (TKS)
- Token Processing System (TPS)
Each subsystem is installed and configured individually as a standalone Tomcat web server instance. However, Red Hat Certificate System additionally supports running a single shared Tomcat web server instance that can contain up to one of each subsystem.
7.1. Subsystem configuration order
The order in which the individual subsystems are set up is important because of relationships between the different subsystems:
- 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.
In certain situations, administrators want to install a standalone KRA or OCSP which do not require a CA running as a security domain. For details, see Section 7.4, “Installing PKI subsystems”.
7.2. Installing RHCS using the pkispawn utility
If you are already familiar with pkispawn, you can go directly to Section 7.4, “Installing PKI subsystems”.
In Red Hat Certificate System, administrators set up the individual subsystems using the pkispawn utility. This section gives you an overall understanding of how installing using pkispawn works. Read it carefully to ensure that you make the right choices when following the installation procedures in Section 7.4, “Installing PKI subsystems”.
pkispawn provides two different modes of operation:
- 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 (details below).
In the remainder of this chapter, batch mode is assumed unless stated otherwise.
7.2.1. Creating the pkispawn configuration file
The pkispawn utility requires a configuration file. This file contains parameters that are grouped into sections. These sections are stacked, so that parameters defined in earlier sections can be overridden by parameters defined in later sections. The sections are read in the following order:
- [DEFAULT] - subsystem-independent settings
- [Tomcat]
- [CA], [KRA], [OCSP], [TKS], [TPS], [ACME], or [EST] - the subsystem-specific sections
When it runs, pkispawn:
Reads the default values from the
/usr/share/pki/server/etc/default.cfgfile. For further details, see thepki_default.cfg(5)man page.ImportantDo not edit the
/usr/share/pki/server/etc/default.cfgfile. Instead, you are instructed to create a configuration file that overrides the defaults. For details about using a configuration file, see the examplepkispawnconfiguration files in the following sections that correspond to each different type of subsystem.- Reads the administrator-provided configuration file mentioned above to override the default values.
- Performs the installation of the requested subsystem.
- Passes the settings to a Java servlet that performs the configuration based on the settings.
pkispawn settings
The following provides information on how to create a configuration file for pkispawn along with some of the major parameters. Please see the pkispawn(8) and pki_default.cfg(5) man pages, specifically /usr/share/pki/server/etc/default.cfg on details such as which [ ] section a parameter belongs to or the exact spelling of a parameter.
Create a text file for the pkispawn configuration settings, such as /root/pki/config.subsystem.txt, and fill it with the settings described below. You must add every setting under the corresponding [ ] section. You can refer to the /usr/share/pki/server/etc/default.cfg file to confirm the proper placement.
This section describes a general minimum configuration. Depending on your environment, additional parameters may be necessary (see /usr/share/pki/server/etc/default.cfg). For additional examples, see the EXAMPLES section in the pkispawn(8) man page.
For descriptions about the parameters covered in this section, see the pki_default.cfg(5) man page.
Subsystem-independent settings
Both shared and separate PKI instances for subsystems are supported. A separate PKI instance runs as a standalone Java-based Apache Tomcat instance that contains a single PKI subsystem (CA, KRA, OCSP, TKS, or TPS), and must utilize a unique instance name and ports if co-located on the same machine. Whereas a shared instance runs as a single Java-based Apache Tomcat instance sharing the same instance name and ports, but may contain any combination of up to one of each type of PKI subsystem.
Independently of the subsystem you install, the following settings can be specified in the configuration file in the [DEFAULT] section:
Set a unique instance name:
pki_instance_name=instance_name
# pki_instance_name=instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set the host name:
pki_hostname=server.example.com
# pki_hostname=server.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteCertificate System creates unique certificate nicknames based on these parameters and the instance name. The uniqueness of certificate nicknames is very important in keeping the HSM token shared by multiple PKI instances functional.
Set the port numbers for the HTTP and HTTPS protocols:
pki_https_port=port_number pki_http_port=port_number
pki_https_port=port_number pki_http_port=port_numberCopy to Clipboard Copied! Toggle word wrap Toggle overflow ImportantTo run more than one Certificate System instance on the same host, you must set unique ports in the
pki_https_portandpki_http_portparameters that are not used by any other service on the host. By default, Certificate System uses port 8080 for HTTP and 8443 for HTTPS.Set the HSM-specific parameters:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For further details, see Section 6.2.4, “Preparing for installing Certificate System with an HSM”.
If building an RSA Certificate System instance, use the following configuration:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Allowed choices for the key_algorithm parameters are:
SHA256withRSA SHA384withRSA SHA512withRSA
SHA256withRSA SHA384withRSA SHA512withRSACopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteYou can set these algorithm parameters to a value specified in the
ca.profiles.defaultSigningAlgsAllowedparameter in the CA’sCS.cfgfile. For details, see the B.2.10 Signing Algorithm Constraint appendix in the Administration Guide. Signature algorithm must matchkey_type.To use Elliptic Curve Cryptography (ECC) instead of RSA when creating certificates, set:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Allowed choices for the
key_algorithmparameters are:SHA256withEC SHA384withEC SHA512withEC
SHA256withEC SHA384withEC SHA512withECCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteYou can set these algorithm parameters to a value specified in the
ca.profiles.defaultSigningAlgsAllowedparameter in the CA’sCS.cfgfile. For details, see the For details, see the Signing Algorithm Constraint appendix in the Administration Guide. The signature algorithm must match withkey_type.For ECC, the allowed choices for
key_sizeare:nistp256 nistp384 nistp521
nistp256 nistp384 nistp521Copy to Clipboard Copied! Toggle word wrap Toggle overflow For ECC, the allowed choice for
key_typeisecc.Set the client directory of the bootstrap admin user:
pki_client_dir=bootstrap_admin_directory
pki_client_dir=bootstrap_admin_directoryCopy to Clipboard Copied! Toggle word wrap Toggle overflow By default, the path is set to
~/.dogtag/instance_name/ImportantThe
pki_admin_*andpki_client_*parameters belong to the bootstrap user that is automatically created by the installation process. For further information about default roles (privileges) and the bootstrap user, see Section 2.6.6, “Users, authorization, and access controls”. For descriptions about the parameters covered in this section, see thepki_default.cfg(5)man page.Set various passwords for the bootstrap admin user:
pki_admin_password=password pki_client_database_password=password pki_client_pkcs12_password=password
pki_admin_password=password pki_client_database_password=password pki_client_pkcs12_password=passwordCopy to Clipboard Copied! Toggle word wrap Toggle overflow If you chose to set up TLS between Certificate System and Directory Server, use the following parameters in the configuration file:
NoteWe need to first create a basic TLS server authentication connection. At the end, during post-installation, we will return and make the connection require a client authentication certificate to be presented to Directory Server. At that time, once client authentication is set up, the
pki_ds_passwordwould no longer be relevant.Copy to Clipboard Copied! Toggle word wrap Toggle overflow The value of the
pki_ds_databaseparameter is a name used by thepkispawnutility to create the corresponding subsystem database on the Directory Server instance.The value of the
pki_ds_hostnameparameter depends on the install location of the Directory Server instance. This depends on the values used in Section 6.3.2.1, “Installing the Directory Server packages”.When you set
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 topkispawnbeing able to utilize it. -
pki_ds_ldaps_port: Sets the value of the secure LDAPS port Directory Server is listening to. The default is636.
-
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
# certutil -L -d /etc/dirsrv/slapd-instance_name/ -n "Server-Cert" -a -o /root/ds.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow For the CA that will act as a security domain, set the proper parameters:
for a CA that acts as a security domain
# for a CA that acts as a security domain pki_security_domain_hostname= pki_security_domain_name=example.com Security Domain pki_security_domain_user=caadmin pki_security_domain_password=SD passwordCopy to Clipboard Copied! Toggle word wrap Toggle overflow
[Tomcat] section:
Set the Tomcat JServ Protocol (AJP) port:
pki_ajp_port=Tomcat_AJP_port
pki_ajp_port=Tomcat_AJP_portCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set the Tomcat server port:
pki_tomcat_server_port=Tomcat_server_port
pki_tomcat_server_port=Tomcat_server_portCopy to Clipboard Copied! Toggle word wrap Toggle overflow
To run more than one PKI subsystem instance on the same host, you must set ports in the pki_ajp_port and pki_tomcat_server_port parameters that are not used by any other service on the host. By default, the pki_ajp_port is set to 8009 and pki_tomcat_server_port to 8005.
Subsystem-specific settings
After you have created the initial configuration file, add the subsystem-specific settings to it. Search for a list of the suitable parameters for each subsystem ([CA], [OCSP], [KRA], [TKS], [TPS], [ACME], or [EST]) in the /usr/share/pki/server/etc/default.cfg file.
7.2.2. Installation methods (single-step or two-step)
You can run pkispawn in either single-step installation or two-step installation:
Unless overwritten by the <pki_instance_name> parameter, by default pkispawn installs the subsystem in a PKI server instance called pki-tomcat under the /var/lib/pki/pki-tomcat directory. Multiple subsystems can be installed in the same instance.
Sample deployment configuration files can be found in Appendix XXX [NEEDS UPDATING].
7.2.2.1. Single-step installation
In a single-step installation process, an administrator first creates a pkispawn configuration file and then runs pkispawn against this file as follows:
pkispawn -s [CA, OCSP, KRA, TKS, TPS, ACME, EST] -f cs_inst.cfg –debug
# pkispawn -s [CA, OCSP, KRA, TKS, TPS, ACME, EST] -f cs_inst.cfg –debug
Before starting the installation, it is good practice to first run the pkispawn command with the --precheck option to validate the configuration file.
For example, for the CA:
pkispawn -s CA -f rootca_inst.cfg --precheck --debug pkispawn -s CA -f rootca_inst.cfg --debug
# pkispawn -s CA -f rootca_inst.cfg --precheck --debug
# pkispawn -s CA -f rootca_inst.cfg --debug
For a complete example, see Section 7.3.1, “Installing a root CA using the pkispawn single-step method”.
7.2.2.2. Two-step installation
In a two-step installation, an administrator first creates a pkispawn configuration file and then runs pkispawn twice against the same pkispawn configuration file. In between the execution of the pkispawn utility, the administrator is allowed to manually update various configuration files, for example enrollment profiles, cs.cfg etc. This method allows for better customization.
These two distinct stages of the two-step installation method are outlined below:
First step (installation)
-
Create
pkispawnconfiguration file. -
Run
pkispawn(installation)
-
Create
Second step (configuration)
- Customization of the configuration
-
Run
pkispawn(configuration)
First step (installation)
During this step, when run, 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 requires the following two substeps by the administrators:
-
Creating the
pkispawnconfiguration file. See Section 7.2.1, “Creating thepkispawnconfiguration file”. Run
pkispawnas follows:pkispawn -s [CA, OCSP, KRA, TKS, TPS] -f cs_inst.cfg --skip-configuration –debug
# pkispawn -s [CA, OCSP, KRA, TKS, TPS] -f cs_inst.cfg --skip-configuration –debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteBefore starting the installation, it is good practice to first run the
pkispawncommand with the--precheckoption to validate the configuration file.For example, for the CA:
pkispawn -s CA -f rootca_inst.cfg --skip-configuration --precheck --debug pkispawn -s CA -f rootca_inst.cfg --skip-configuration --debug
# pkispawn -s CA -f rootca_inst.cfg --skip-configuration --precheck --debug # pkispawn -s CA -f rootca_inst.cfg --skip-configuration --debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Second step (configuration)
During the second step, pkispawn continues the installation based on the configuration files in the instance-specific /etc/pki/instance_name/ directory.
This part of the installation requires the following two substeps by the administrators:
Customization: This is an opportunity to manually update some instance-specific configuration files before the next substep. Parameters you customize at this point are in general things that you cannot configure in the
pkispawnconfiguration file but would affect the outcome or behavior of the system. For example, modifying system certificate enrollment profiles (*.profile) under/var/lib/pki/<CA instance name>/ca/conf/(see Chapter 15, Configuring certificate profiles). For example:- Adding a desired certificate extension (which is not in the default profile) to a system certificate by editing the corresponding system certificate profile
- Changing the validity period of a system certificate by editing the corresponding system certificate profile
Run
pkispawnagainst the samepkispawnfile as the first step but in a different manner as the following:pkispawn -s [CA, OCSP, KRA, TKS, TPS] -f cs_inst.cfg --skip-installation –debug
# pkispawn -s [CA, OCSP, KRA, TKS, TPS] -f cs_inst.cfg --skip-installation –debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Before starting the installation, it is good practice to first run a precheck using the configuration file.
For example, for the CA:
pkispawn -s CA -f rootca_inst.cfg --skip-installation --precheck --debug pkispawn -s CA -f rootca_inst.cfg --skip-installation --debug
# pkispawn -s CA -f rootca_inst.cfg --skip-installation --precheck --debug
# pkispawn -s CA -f rootca_inst.cfg --skip-installation --debug
For a complete example, see Section 7.3.2, “Installing a root CA using the pkispawn two-step method”.
7.3. Setting Up a Root Certificate Authority (examples)
If you are already familiar with pkispawn, you can go directly to Section 7.4, “Installing PKI subsystems”)
This section provides two examples on how to install a root CA:
-
Installing a root CA using the
pkispawnsingle-step method. -
Installing a root CA using the
pkispawntwo-step method.
7.3.1. Installing a root CA using the pkispawn single-step method
Configuring a RootCA instance using the single-step method requires creating a configuration file and running the pkispawn tool once.
In this example, the RootCA is installed on pki.example.com (as well as other instances), with its internal directory server on dir.example.com.
Prerequisites
- You are logged in to pki.example.com as root user.
- You have followed the steps in Section 6.3.2.2, “Directory Server instance creation”. In our example, CC-RSA-RootCA-LDAP is the RootCA’s internal database.
Procedure
Create a CA installation file at a chosen location (e.g.
/root/pki_rsa) on the machine that will host the RHCS instance (pki.example.com).cd /root/pki_rsa vi rootca_inst.cfg
# cd /root/pki_rsa # vi rootca_inst.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteUnless explicitly specified, system certificate nicknames are automatically named bearing the value specified for
pki_instance_name. To avoid certificate nickname conflicts on a shared HSM, use a unique instance name for each instance creation.The values specified in the installation file below are examples. In addition to changing the HSM password, edit the values accordingly, for example ports, directories, nicknames, domains…
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run the pkispawn tool to install the RHCS CA instance:
pkispawn -s CA -f rootca_inst.cfg --debug
pkispawn -s CA -f rootca_inst.cfg --debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification steps
Show the status of the installed CA:
pki-server status rhcs10-RSA-RootCA
pki-server status rhcs10-RSA-RootCACopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the sanity of the CA by running the following command. It should display certificates:
pki -p 8443 -h pki.example.com ca-cert-find
pki -p 8443 -h pki.example.com ca-cert-findCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteAn untrusted issuer warning for the CA signing certificate will display when connecting to the RootCA with a pki command for the first time, as seen below:
WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' indicates a non-trusted CA cert 'CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' Trust this certificate (y/N)?
WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' indicates a non-trusted CA cert 'CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' Trust this certificate (y/N)?Copy to Clipboard Copied! Toggle word wrap Toggle overflow Select
yto trust the CA signing cert if the Subject DN matches the hostname as expected. The warning will not display again.
7.3.2. Installing a root CA using the pkispawn two-step method
Configuring a RootCA instance using the two-step method requires creating a configuration file and running the pkispawn tool twice.
In this example, the RootCA is installed on pki.example.com.
Prerequisites
- You are logged in to pki.example.com as root user.
- You have run the steps in Section 6.3.2, “Set up a DS instance” [NEEDS UPDATING]. In our example, CC-RSA-RootCA-LDAP is the RootCA’s internal database.
7.3.2.1. First step of RootCA installation
Create a CA installation file at a chosen location, for example,
/root/pki_rsa, on the machine that will host the RHCS instance, pki.example.com.cd /root/pki_rsa vi rootca_inst.cfg
cd /root/pki_rsa vi rootca_inst.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteUnless explicitly specified, system certificate nicknames are automatically named bearing the value specified for
pki_instance_name. To avoid certificate nickname conflicts on a shared HSM, use a unique instance name for each instance creation. However, in a two-step installation, thepki_instance_namevalue of both files should match. The following values are just examples.Run the
pkispawntool the first time to install the RHCS CA instance:pkispawn -s CA -f rootca_inst.cfg --skip-configuration --debug
pkispawn -s CA -f rootca_inst.cfg --skip-configuration --debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.3.2.2. Second step of RootCA configuration
As explained in Section 7.2.2, “Installation methods (single-step or two-step)”, there are two substeps in the second step of the two-step installation method.
Customization
In this substep, you can customize certain things, such as the certificate profile of a system certificate.
Setting the Subject Key Identifier extension message digest algorithm for the CA signing certificate:
Open the enrollment profile for this CA’s signing certificate:
vi /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/caCert.profile
# vi /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/caCert.profileCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the following parameter:
7.default.params.messageDigest=SHA-256
7.default.params.messageDigest=SHA-256Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Save the file.
Likewise, do the same for the CA signing cert that this CA will be issuing in the future:
Open the enrollment profile for the CA signing certificate:
vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caInstallCACert.cfg vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCcaCert.cfg
# vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caInstallCACert.cfg # vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCcaCert.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the following parameter:
policyset.caCertSet.8.default.params.messageDigest=SHA-256
policyset.caCertSet.8.default.params.messageDigest=SHA-256Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Save the file.
Other customization changes can take place here too. For example, if you wish to extend the validity period of the audit signing certificate of this subsystem:
Open the corresponding configuration file:
vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caInternalAuthAuditSigningCert.cfg
# vi /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caInternalAuthAuditSigningCert.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Change the following range parameters to the desired values:
policyset.auditSigningCertSet.2.constraint.params.range=720 policyset.auditSigningCertSet.2.default.params.range=720
policyset.auditSigningCertSet.2.constraint.params.range=720 policyset.auditSigningCertSet.2.default.params.range=720Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Save the file. Once you have done the second step of
pkispawnin the next section, you should expect the validity of the audit signing certificate of this subsystem to match the values you have changed to.
Running pkispawn the second time (Configuration)
The second step of pkispawn in this case involves running the tool against the same file in a different manner to configure the RHCS CA instance.
Run the
pkispawntool to configure the CA:pkispawn -s CA -f rootca_inst.cfg --skip-installation --debug
# pkispawn -s CA -f rootca_inst.cfg --skip-installation --debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Verification steps
Show the status of the installed CA:
pki-server status rhcs10-RSA-RootCA
# pki-server status rhcs10-RSA-RootCACopy to Clipboard Copied! Toggle word wrap Toggle overflow Note down the Unsecure EE, Secure EE, Agent, Admin and pkiconsole URLs.
Verify the sanity of the CA by running the following command. It should display certificates:
pki -p 8443 -h pki.example.com ca-cert-find
# pki -p 8443 -h pki.example.com ca-cert-findCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteAn untrusted issuer warning for the CA signing certificate will display when connecting to the RootCA with a pki command for the first time, as seen below:
WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' indicates a non-trusted CA cert 'CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' Trust this certificate (y/N)?
WARNING: UNTRUSTED ISSUER encountered on 'CN=pki.example.com,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' indicates a non-trusted CA cert 'CN=CA Signing Certificate,OU=rhcs10-RSA-RootCA,O=Example-rhcs10-RSA-RootCA' Trust this certificate (y/N)?Copy to Clipboard Copied! Toggle word wrap Toggle overflow Select
yto trust the CA signing cert if the Subject DN matches the hostname as expected. The warning will not display again.
7.4. Installing PKI subsystems
Red Hat Certificate System provides different subsystems that can be installed individually. For example, you can install multiple subsystem instances on a single server or you can run them independently on different hosts. This enables you to adapt the installation to your environment to provide a higher availability, scalability, and fail-over support.
Refer to the required RHCS subsystem guide below for installation guidance.
If you are not familiar with pkispawn, refer to Section 7.2, “Installing RHCS using the pkispawn utility” for a better understanding of the choices presented for each subsystem installation.
Once completed, refer to Section 7.5, “Post-installation tasks” and follow the sections pertaining to the subsystem you are installing.
7.4.1. Installing the CA subsystem
- Installing CA
- Installing CA Clone
- Installing CA Clone with HSM
- Installing CA Clone with LDAPS Connection
- Installing CA Clone with LDAPS Using Bootstrap DS Certs
- Installing CA with Custom CA Signing Key
- Installing CA with ECC
- Installing CA with Existing Keys in HSM
- Installing CA with Existing Keys in Internal Token
- Installing CA with External CA Signing Certificate
- Installing CA with HSM
- Installing CA with LDAPS Connection
- Installing Subordinate CA
7.4.1.1. Installing a CA
Follow this process to install a CA subsystem instance with a self-signed CA signing certificate. It is also known as a "root CA".
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.1.1. Installing the CA subsystem
Prepare a deployment configuration, for example ca.cfg, to deploy CA subsystem. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca.cfg.
To start the installation execute the following command:
pkispawn -f ca.cfg -s CA
$ pkispawn -f ca.cfg -s CA7.4.1.1.2. CA system certificates
After installation, the CA system certificates and keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias):
If necessary, the certificates can be exported into PEM files by using the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid certificate IDs for CA are:
-
ca_signing -
ca_ocsp_signing -
ca_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate ID.
7.4.1.1.3. Admin certificate
After installation the admin certificate and key are stored in ~/.dogtag/pki-tomcat/ca_admin_cert.p12.
The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.
To use the admin certificate, do the following.
Export the CA signing certificate from the server NSS database:
pki-server cert-export ca_signing --cert-file ca_signing.crt
$ pki-server cert-export ca_signing --cert-file ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --password Secret.123$ pki pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.2. Installing CA clone
Follow this process to install a CA subsystem as a clone of an existing CA subsystem.
Prior to installation, ensure that the Installation Prerequisites are configured.
Additional useful tips:
- Ensure that the firewall on the master allows external access to LDAP from the clone.
- Ensure that the firewall on the clone allows external access to LDAP from the master.
7.4.1.2.1. Exporting existing CA system certificates
On the existing system, export the CA system certificates with the following command:
pki-server ca-clone-prepare \
--pkcs12-file ca-certs.p12 \
--pkcs12-password Secret.123
$ pki-server ca-clone-prepare \
--pkcs12-file ca-certs.p12 \
--pkcs12-password Secret.123The command exports the following certificates (including the certificate chain) and their keys into a PKCS #12 file:
- CA signing certificate
- OCSP signing certificate
- audit signing certificate
- subsystem certificate
Note that the existing SSL server certificate is not exported.
If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command:
pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
pkcs12-cert-import <nickname> \
--pkcs12-file ca-certs.p12 \
--pkcs12-password Secret.123 \
--append
$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
pkcs12-cert-import <nickname> \
--pkcs12-file ca-certs.p12 \
--pkcs12-password Secret.123 \
--appendOptionally, the CSRs for the above certificates can be exported as well with the following commands:
7.4.1.2.2. SELinux permissions
After copying the ca-certs.p12 to the clone machine, ensure that appropriate SELinux rules are added:
semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12 restorecon -R -v ca-certs.p12
$ semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12
$ restorecon -R -v ca-certs.p12
Ensure that the ca-certs.p12 file is owned by the pkiuser
chown pkiuser:pkiuser ca-certs.p12
$ chown pkiuser:pkiuser ca-certs.p127.4.1.2.3. Installing the CA subsystem
Prepare a deployment configuration, for example ca-clone-w-p12.cfg, to deploy a CA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-clone-w-p12.cfg.
It assumes that the:
-
The CA subsystem clone is running on a different machine than the primary CA subsystem. Note: In a test environment, if creating the clone on the same machine, the
pki_instance_nameand the port values (for PKI and DS) must be different. -
CA signing certificate has been exported into
ca_signing.crt -
admin certificate and key have been exported into
ca_admin_cert.p12 -
PKCS #12 password is specified in the
pki_client_pkcs12_passwordparameter. - The CA is not using an HSM (which is a different installation case covered in section Installing CA clone with HSM).
See Installing CA for details.
If the CSRs are available, they can be specified with the following parameters:
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csr pki_subsystem_csr_path=subsystem.csr
pki_ca_signing_csr_path=ca_signing.csr
pki_ocsp_signing_csr_path=ca_ocsp_signing.csr
pki_audit_signing_csr_path=ca_audit_signing.csr
pki_subsystem_csr_path=subsystem.csrTo start the installation, execute the following command:
pkispawn -f ca-clone-w-p12.cfg -s CA
$ pkispawn -f ca-clone-w-p12.cfg -s CA7.4.1.2.4. CA system certificates
After installation the existing CA system certificates (including the certificate chain) and their keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias), and a new SSL server certificate is created for the new instance:
If necessary, the certificates can be exported into PEM files with the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid certificate IDs for CA are:
-
ca_signing -
ca_ocsp_signing -
ca_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.
7.4.1.2.5. Admin certificate
To use the admin certificate, do the following.
Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow To verify that the admin certificate can be used to access the CA subsystem clone, execute the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.3. Installing CA clone with HSM
Follow this process to install a CA subsystem as a clone of an existing CA subsystem where the system certificates and their keys are stored on a HSM.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.3.1. Exporting existing system certificates
Since the system certificates and the keys are already on a HSM, it is not necessary to export them into a PKCS #12 file to create a clone.
However, the CSRs for the system certificates are stored in CS.cfg instead of HSM.
They can optionally be exported with the following commands:
7.4.1.3.2. CA subsystem installation
Note: It is assumed that the CA signing certificate has been exported into ca_signing.crt
Prepare a file, for example
ca.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the CSRs are available, they can be specified with the following parameters:
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csr pki_subsystem_csr_path=subsystem.csr
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csr pki_subsystem_csr_path=subsystem.csrCopy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ca.cfg -s CA
$ pkispawn -f ca.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
7.4.1.3.3. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.3.4. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the master’s admin key and certificate:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA clone by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.4. Installing CA clone with LDAPS connection
Follow this process to install a CA subsystem as clone of an existing CA subsystem with a secure database connection.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.4.1. DS configuration
Once the prerequisites listed above are completed on the clone system, follow the procedure in enable SSL Connection with DS so that the CA clone’s DS is running with SSL enabled with a real server certificate issued by the CA.
Some useful tips:
- Ensure the firewall on the master allows external access to LDAP from the clone.
- Ensure the firewall on the clone allows external access to LDAP from the master.
7.4.1.4.2. Exporting existing CA system certificates
On the existing system, export the CA system certificates and copy them to the clone system with the following command:
pki-server ca-clone-prepare --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 pki-server cert-export ca_signing --cert-file ca_signing.crt
$ pki-server ca-clone-prepare --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123
$ pki-server cert-export ca_signing --cert-file ca_signing.crtThe following certificates (including the certificate chain) and their keys are exported into a PKCS #12 file:
- CA signing certificate
- OCSP signing certificate
- audit signing certificate
- subsystem certificate
Note that the existing SSL server certificate is not exported.
If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command:
pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
pkcs12-cert-import <nickname> \
--pkcs12-file ca-certs.p12 \
--pkcs12-password Secret.123 \
--append
$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
pkcs12-cert-import <nickname> \
--pkcs12-file ca-certs.p12 \
--pkcs12-password Secret.123 \
--append7.4.1.4.3. SELinux permissions
After copying the ca-certs.p12 to the clone machine, ensure that appropriate SELinux rules are added:
semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12 restorecon -R -v ca-certs.p12
$ semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12
$ restorecon -R -v ca-certs.p12
Ensure that the ca-certs.p12 file is owned by the pkiuser
chown pkiuser:pkiuser ca-certs.p12
$ chown pkiuser:pkiuser ca-certs.p127.4.1.4.4. Installing the CA subsystem
Prepare a deployment configuration, for example ca-secure-ds-secondary.cfg, to deploy a CA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
The sample pkispawn config file referenced below expects the DS server certificate’s signing certificate to be in a file named ds_signing.crt. Since the existing CA is being used as the signing certificate, copy the CA’s signing certificate into ds_signing.crt:
cp ca_signing.crt ds_signing.crt
$ cp ca_signing.crt ds_signing.crtA sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-secure-ds-secondary.cfg.
It assumes that:
-
The existing CA and DS instances are running on
primary.example.com. -
The new CA and DS clones are being installed on
secondary.example.com. -
The CA signing certificate has been exported into
ca_signing.crt. -
The admin certificate and key have been exported into
ca_admin_cert.p12. -
The PKCS #12 password is specified in the
pki_client_pkcs12_passwordparameter.
To start the installation, execute the following command:
pkispawn -f ca-secure-ds-secondary.cfg -s CA
$ pkispawn -f ca-secure-ds-secondary.cfg -s CA7.4.1.4.5. CA system certificates
After installation the existing CA system certificates (including the certificate chain) and their keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias), and a new SSL server certificate is created for the new instance. Note that if the ds_signing certificate is the same certificate as ca_signing, it does not show in the following certutil listing:
If necessary, the clone CA system certificates can be exported into PEM files with the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid certificate IDs for CA are:
-
ca_signing -
ca_ocsp_signing -
ca_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.
7.4.1.4.6. Admin certificate
To use the admin certificate, do the following.
Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key from the master CA into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem clone by running the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.5. Installing CA clone with LDAPS using bootstrap DS certificates
Follow this process to install a CA subsystem as a clone of an existing CA subsystem that runs with a bootstrap SSL server certificate. It is assumed that the DS clone was created with self_sign_cert = False.
Prior to installation, please ensure that the Installation Prerequisites are configured.
7.4.1.5.1. DS configuration
Once the prerequisites listed above are completed on the clone system, go on the existing system and export the DS signing certificate into
ds_signing.p12and copy the certificate into clone system with the following command:pki -d /etc/dirsrv/slapd-localhost \ -C /etc/dirsrv/slapd-localhost/pwdfile.txt \ pkcs12-export --pkcs12-file ds_signing.p12 \ --pkcs12-password Secret.123 Self-Signed-CA
$ pki -d /etc/dirsrv/slapd-localhost \ -C /etc/dirsrv/slapd-localhost/pwdfile.txt \ pkcs12-export --pkcs12-file ds_signing.p12 \ --pkcs12-password Secret.123 Self-Signed-CACopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the
ds_signing.p12into the clone DS instance with the following command:pki -d /etc/dirsrv/slapd-localhost \ -C /etc/dirsrv/slapd-localhost/pwdfile.txt \ pkcs12-import --pkcs12-file ds_signing.p12 \ --pkcs12-password Secret.123
$ pki -d /etc/dirsrv/slapd-localhost \ -C /etc/dirsrv/slapd-localhost/pwdfile.txt \ pkcs12-import --pkcs12-file ds_signing.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow On the DS clone, create a bootstrap DS server certificate as described in Creating DS Server Certificate.
Note that the certificate subject DN should match the clone’s hostname, that is,
--subject "CN=secondary.example.com".- Enable the SSL connection as described in Enabling SSL Connection.
After the successful DS restart, export the DS Signing Certificate into 'ds_signing.crt' as follows:
certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Some useful tips:
- Ensure the DS firewall allows access from PKI server and other DS instances.
7.4.1.5.2. Exporting existing CA system certificates
On the existing system, export the CA system certificates and copy to clone system with the following command:
pki-server ca-clone-prepare --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 pki-server cert-export ca_signing --cert-file ca_signing.crt
$ pki-server ca-clone-prepare --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 $ pki-server cert-export ca_signing --cert-file ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow The following certificates (including the certificate chain) and their keys are exported into a PKCS #12 file:
- CA signing certificate
- OCSP signing certificate
- audit signing certificate
- subsystem certificate
Note that the existing SSL server certificate is not exported.
If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command:
pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \ pkcs12-cert-import <nickname> \ --pkcs12-file ca-certs.p12 \ --pkcs12-password Secret.123 \ --append$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \ pkcs12-cert-import <nickname> \ --pkcs12-file ca-certs.p12 \ --pkcs12-password Secret.123 \ --appendCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.5.3. SELinux permissions
After copying the
ca-certs.p12to the clone machine, ensure that appropriate SELinux rules are added:semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12 restorecon -R -v ca-certs.p12
$ semanage fcontext -a -t pki_tomcat_cert_t ca-certs.p12 $ restorecon -R -v ca-certs.p12Copy to Clipboard Copied! Toggle word wrap Toggle overflow Ensure that the
ca-certs.p12file is owned by thepkiuser:chown pkiuser:pkiuser ca-certs.p12
$ chown pkiuser:pkiuser ca-certs.p12Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.5.4. Installing a CA subsystem
Prepare a deployment configuration, for example ca-secure-ds-secondary.cfg, to deploy CA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-secure-ds-secondary.cfg.
It assumes that:
-
The existing CA and DS instances are running on
primary.example.com. -
The new CA and DS clones are being installed on
secondary.example.com. -
The CA signing certificate has been exported into
ca_signing.crt. -
The admin certificate and key have been exported into
ca_admin_cert.p12. -
The PKCS #12 password is specified in the
pki_client_pkcs12_passwordparameter.
To start the installation execute the following command:
pkispawn -f ca-secure-ds-secondary.cfg -s CA
$ pkispawn -f ca-secure-ds-secondary.cfg -s CA7.4.1.5.5. CA system certificates
After installation, the existing CA system certificates (including the certificate chain) and their keys are stored in the server NSS database, that is, /var/lib/pki/pki-tomcat/conf/alias) and a new SSL server certificate is created for the new instance:
If necessary, the clone CA system certificates can be exported into PEM files with the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid certificate IDs for CA are:
-
ca_signing -
ca_ocsp_signing -
ca_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.
7.4.1.5.6. Admin certificate
To use the admin certificate, do the following.
Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem clone, execute the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.6. Installing CA with custom CA signing key
Follow this process to install a CA subsystem with a custom CA signing key, CSR, and certificate.
Prior to installation, please ensure that the Installation Prerequisites are configured.
7.4.1.6.1. Starting the CA subsystem installation
Prepare a file, for example
ca-step1.cfg, that contains the deployment configuration for step 1:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ca-step1.cfg -s CA
$ pkispawn -f ca-step1.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
Since there is no CSR path parameter specified, it does not generate the CA signing key by default.
7.4.1.6.2. Generating CA signing key, CSR, and certificate
Generate a custom CA signing key in the server NSS database, then generate a CSR and store it in a file, for example ca_signing.csr.
Use the CSR to issue the CA signing certificate:
- For root CA installation, generate a self-signed CA signing certificate.
- For subordinate CA installation, submit the CSR to an external CA to issue the CA signing certificate.
Store the CA signing certificate in a file, for example ca_signing.crt. The CA signing certificate can be specified as a single certificate or a PKCS #7 certificate chain in PEM format.
If the CA signing certificate was issued by an external CA, store the external CA certificate chain in a file, for example external.crt. The certificate chain can be specified as a single certificate or a PKCS #7 certificate chain in PEM format. The certificate chain should include all CA certificates from the root CA to the external CA that issued the CA signing certificate, but it should not include the CA signing certificate itself.
7.4.1.6.3. Finishing the CA subsystem installation
Prepare another file, for example ca-step2.cfg, that contains the deployment configuration for step 2. The file can be copied from step 1, that is ca-step1.cfg, with additional changes below.
Specify step 2 with the following parameter:
pki_external_step_two=True
pki_external_step_two=TrueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the custom CA signing CSR with the following parameter:
pki_ca_signing_csr_path=ca_signing.csr
pki_ca_signing_csr_path=ca_signing.csrCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the custom CA signing certificate with the following parameter:
pki_ca_signing_cert_path=ca_signing.crt
pki_ca_signing_cert_path=ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the CA signing certificate was issued by an external CA, specify the external CA certificate chain with the following parameters:
pki_cert_chain_nickname=external pki_cert_chain_path=external.crt
pki_cert_chain_nickname=external pki_cert_chain_path=external.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ca-step2.cfg -s CA
$ pkispawn -f ca-step2.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.6.4. Verifying the system certificates
Verify that the server NSS database contains the following certificates:
7.4.1.6.5. Verifying admin certificate
Import the external CA certificate chain:
pki -c Secret.123 client-cert-import --ca-cert external.crt
$ pki -c Secret.123 client-cert-import --ca-cert external.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.7. Installing CA with ECC
Follow this process to install a CA subsystem with ECC self-signed CA signing certificate.
Supported ECC curves:
- nistp256
- nistp384
- nistp521
Supported ECC key algorithms:
- SHA256withEC
- SHA384withEC
- SHA512withEC
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.7.1. Installing a CA subsystem
Prepare a deployment configuration, for example ca-ecc.cfg, to deploy CA subsystem. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-ecc.cfg.
To start the installation execute the following command:
pkispawn -f ca-ecc.cfg -s CA
$ pkispawn -f ca-ecc.cfg -s CA7.4.1.7.2. CA system certificates
After installation the CA system certificates and keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias):
If necessary, the certificates can be exported into PEM files with the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid certificate IDs for CA are:
-
ca_signing -
ca_ocsp_signing -
ca_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate ID.
7.4.1.7.3. Admin certificate
After installation, the admin certificate and key are stored in ~/.dogtag/pki-tomcat/ca_admin_cert.p12. The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.
To use the admin certificate, do the following.
Export the CA signing certificate from the server NSS database:
pki-server cert-export ca_signing --cert-file ca_signing.crt
$ pki-server cert-export ca_signing --cert-file ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow To verify that the admin certificate can be used to access the CA subsystem, execute the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.8. Installing CA with existing keys in HSM
Follow this process to install a CA subsystem with the system keys, CSRs, and certificates from an existing CA where the keys are stored on a HSM.
To avoid conflicts with the existing CA subsystem, the new CA subsystem uses new SSL server and subsystem certificates, so they will not be included in the installation process.
Prior to installation, please ensure that the Installation Prerequisites are configured.
7.4.1.8.1. Starting a CA subsystem
Prepare a file, for example
ca-step1.cfg, that contains the deployment configuration in step 1:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ca-step1.cfg -s CA
$ pkispawn -f ca-step1.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
Since there are no CSR path parameters specified, it does not generate CA system and admin keys.
7.4.1.8.2. Exporting existing system certificates and CSRs
Export the system certificates from the existing CA with the following commands:
certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_signing" -a > ca_signing.crt certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_ocsp_signing" -a > ca_ocsp_signing.crt certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_audit_signing" -a > ca_audit_signing.crt
$ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_signing" -a > ca_signing.crt $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_ocsp_signing" -a > ca_ocsp_signing.crt $ certutil -L -d /var/lib/pki/pki-tomcat/conf/alias -h HSM -f HSM.pwd -n "HSM:ca_audit_signing" -a > ca_audit_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Export the CSRs from the existing CA with the following commands:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.8.3. Finishing a CA subsystem installation
Prepare another file, for example ca-step2.cfg, that contains the deployment configuration for step 2. The file can be copied from step 1, that is ca-step1.cfg, with additional changes below.
Specify step 2 with the following parameter:
pki_external_step_two=True
pki_external_step_two=TrueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the existing certificates with the following parameters:
pki_ca_signing_cert_path=ca_signing.crt pki_ocsp_signing_cert_path=ca_ocsp_signing.crt pki_audit_signing_cert_path=ca_audit_signing.crt
pki_ca_signing_cert_path=ca_signing.crt pki_ocsp_signing_cert_path=ca_ocsp_signing.crt pki_audit_signing_cert_path=ca_audit_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the existing CSRs with the following parameters:
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csr
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csrCopy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ca-step2.cfg -s CA
$ pkispawn -f ca-step2.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.8.4. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.8.5. Verifying the admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.9. Installing CA with existing keys in internal token
Follow this process to install a CA subsystem with the system keys, CSRs, and certificates from an existing CA where the keys are stored on an internal token.
This method of installation could be useful for situations such as restoring an independent instance from a backup where the original server might not be available anymore.
To avoid conflicts with the existing CA subsystem, the new CA subsystem uses new SSL server and subsystem certificates, so they are not included in the installation process.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.9.1. Starting a CA subsystem installation
Prepare a file, for example ca-existing-certs-step1.cfg, that contains the first deployment configuration.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-existing-certs-step1.cfg.
Execute the following command:
pkispawn -f ca-existing-certs-step1.cfg -s CA
$ pkispawn -f ca-existing-certs-step1.cfg -s CAIt installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
Since there are no CSR path parameters specified, it does not generate CA system and admin keys.
7.4.1.9.2. Exporting existing system keys, CSRs, certificates
Export the system keys and certificates from the existing CA into a PKCS #12 file with the following command:
pki -d /var/lib/pki/pki-tomcat/conf/alias -c Secret.123 pkcs12-export \ --pkcs12 ca-certs.p12 \ --password Secret.123 pki pkcs12-cert-del --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 sslserver pki pkcs12-cert-del --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 subsystem
$ pki -d /var/lib/pki/pki-tomcat/conf/alias -c Secret.123 pkcs12-export \ --pkcs12 ca-certs.p12 \ --password Secret.123 $ pki pkcs12-cert-del --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 sslserver $ pki pkcs12-cert-del --pkcs12-file ca-certs.p12 --pkcs12-password Secret.123 subsystemCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy the CSRs from the existing CA to the pkispawn directory on the host where the new CA is being created, for example:
cp /etc/pki/pki-tomcat/certs/* /root
cp /etc/pki/pki-tomcat/certs/* /rootCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.9.3. Finishing a CA subsystem installation
Prepare another file, for example
ca-existing-certs-step2.cfg, that contains the second deployment configuration.The file can be created from the first file, that is
ca-existing-certs-step1.cfg, with the following changes:pki_external_step_two=True
pki_external_step_two=TrueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the existing keys and certificates in the PKCS #12 file with the following parameters:
pki_pkcs12_path=ca-certs.p12 pki_pkcs12_password=Secret.123
pki_pkcs12_path=ca-certs.p12 pki_pkcs12_password=Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the existing CSRs with the following parameters:
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csr
pki_ca_signing_csr_path=ca_signing.csr pki_ocsp_signing_csr_path=ca_ocsp_signing.csr pki_audit_signing_csr_path=ca_audit_signing.csrCopy to Clipboard Copied! Toggle word wrap Toggle overflow A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-existing-certs-step2.cfg.
Execute the following command:
pkispawn -f ca-existing-certs-step2.cfg -s CA
$ pkispawn -f ca-existing-certs-step2.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.9.4. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.1.9.5. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.10. Installing CA with external CA signing certificate
An external CA is a CA that is not in the same security domain as that of the PKI subsystem that is being installed.
Follow this process to install a CA subsystem with an external CA signing certificate.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.10.1. Starting a CA subsystem installation
Prepare a file, for example ca-external-cert-step1.cfg, that contains the first deployment configuration.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-external-cert-step1.cfg
Execute the following command:
pkispawn -f ca-external-cert-step1.cfg -s CA
$ pkispawn -f ca-external-cert-step1.cfg -s CAIt installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
It also generates the CA signing key in the server NSS database and the CSR in the specified path.
7.4.1.10.2. Generating a CA signing certificate
Use the CSR to issue the CA signing certificate:
- For root CA installation, generate a self-signed CA signing certificate.
- For subordinate CA installation, submit the CSR to an external CA to issue the CA signing certificate.
Store the CA signing certificate in a file, for example ca_signing.crt. The CA signing certificate can be specified as a single certificate or a PKCS #7 certificate chain in PEM format.
If the CA signing certificate was issued by an external CA, store the external CA certificate chain in a file, for example root-ca_signing.crt.
The certificate chain can be specified as a single certificate or a PKCS #7 certificate chain in PEM format.
The certificate chain should include all CA certificates from the root CA to the external CA that issued the CA signing certificate, but it should not include the CA signing certificate itself.
7.4.1.10.3. Finishing the CA subsystem installation
Prepare another file, for example
ca-external-cert-step2.cfg, that contains the second deployment configuration. The file can be created from the first file, that isca-external-cert-step1.cfg, with the following changes:pki_external_step_two=True
pki_external_step_two=TrueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the custom CA signing certificate with the following parameter:
pki_ca_signing_cert_path=ca_signing.crt
pki_ca_signing_cert_path=ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the CA signing certificate was issued by an external CA, specify the external CA certificate chain with the following parameters:
pki_cert_chain_nickname=root-ca_signing pki_cert_chain_path=root-ca_signing.crt
pki_cert_chain_nickname=root-ca_signing pki_cert_chain_path=root-ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-external-cert-step2.cfg.
Execute the following command:
pkispawn -f ca-external-cert-step2.cfg -s CA
$ pkispawn -f ca-external-cert-step2.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.10.4. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.1.10.5. Verifying admin certificate
Import the external CA certificate chain:
pki -c Secret.123 client-cert-import --ca-cert root-ca_signing.crt
$ pki -c Secret.123 client-cert-import --ca-cert root-ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.11. Installing a CA with HSM
Follow this process to install a CA subsystem with a self-signed CA signing certificate where the system certificates and their keys are stored on a HSM.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.11.1. Installing a CA subsystem
Prepare a file, for example
ca.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ca.cfg -s CA
$ pkispawn -f ca.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
7.4.1.11.2. Verifying the system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.11.3. Verifying the Admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.12. Installing CA with LDAPS connection
Follow this process to install a CA subsystem with a secure database connection.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.12.1. DS configuration
Once the prerequisites listed above are completed, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows:
certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt7.4.1.12.2. CA subsystem installation
Prepare a deployment configuration, for example ca-secure-ds.cfg, to deploy CA subsystem. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ca-secure-ds.cfg.
To start the installation, execute the following command:
pkispawn -f ca-secure-ds.cfg -s CA
$ pkispawn -f ca-secure-ds.cfg -s CA7.4.1.12.3. CA system certificates
After installation the CA system certificates with their keys are generated and stored in the server NSS database, that is /var/lib/pki/pki-tomcat/conf/alias, and the DS signing certificate is imported into the same NSS database:
If necessary, the CA system certificates can be exported into PEM files with the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid IDs for CA system certificates are:
-
ca_signing -
ca_ocsp_signing -
ca_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate ID.
7.4.1.12.4. CA database configuration
The CA database configuration can be displayed with the following command:
7.4.1.12.5. Admin certificate
After installation the admin certificate and key are stored in ~/.dogtag/pki-tomcat/ca_admin_cert.p12. The PKCS #12 password is specified in the pki_client_pkcs12_password parameter.
To use the admin certificate, do the following.
Export the CA signing certificate from the server NSS database:
pki-server cert-export ca_signing --cert-file ca_signing.crt
$ pki-server cert-export ca_signing --cert-file ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ~/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow To verify that the admin certificate can be used to access the CA subsystem, execute the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.1.12.6. Getting real DS certificate from the CA
If desired, follow this procedure to get real DS certificate issued by the CA.
7.4.1.13. Installing a subordinate CA
Follow this process to install a subordinate CA subsystem with a signing certificate issued by a root CA.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.1.13.1. Installing a subordinate CA subsystem
Prepare a file, for example
subca.cfg, that contains the deployment configuration.A sample deployment configuration is available at /usr/share/pki/server/examples/installation/subca.cfg.
It assumes that the root CA is already running at https://root.example.com:8443 and the root CA signing certificate has been exported into
root-ca_signing.crt.Execute the following command:
pkispawn -f subca.cfg -s CA
$ pkispawn -f subca.cfg -s CACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a CA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ca/alias
7.4.1.13.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.1.13.3. Verifying admin certificate
Import the root CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 /root/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 /root/.dogtag/pki-tomcat/ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the subordinate CA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2. Installing the KRA subsystem
7.4.2.1. Installing KRA
Follow this process to install a KRA subsystem.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.2.1.1. Installing KRA subsystem installation
-
Prepare a file, for example
kra.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra.cfg. Execute the following command:
pkispawn -f kra.cfg -s KRA
$ pkispawn -f kra.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
When KRA is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only!) to the system prior to KRA installation.
7.4.2.1.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.2.1.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the KRA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.1.4. Verifying KRA connector
Verify that the KRA connector is configured in the CA subsystem:
7.4.2.2. Installing KRA clone
Follow this process to install a KRA subsystem as a clone of an existing KRA subsystem.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.2.2.1. Exporting existing KRA system certificates
On the existing system, export the KRA system certificates with the following command:
pki-server kra-clone-prepare \
--pkcs12-file kra-certs.p12 \
--pkcs12-password Secret.123
$ pki-server kra-clone-prepare \
--pkcs12-file kra-certs.p12 \
--pkcs12-password Secret.123The command exports the following certificates (including the certificate chain) and their keys into a PKCS #12 file:
- KRA storage certificate
- KRA transport certificate
- audit signing certificate
- subsystem certificate
Note that the existing SSL server certificate is not exported.
If necessary, third-party certificates, for example trust anchors, can be added into the same PKCS #12 file with the following command:
pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
pkcs12-cert-import <nickname> \
--pkcs12-file kra-certs.p12 \
--pkcs12-password Secret.123 \
--append
$ pki -d /var/lib/pki/pki-tomcat/conf/alias -f /var/lib/pki/pki-tomcat/conf/password.conf \
pkcs12-cert-import <nickname> \
--pkcs12-file kra-certs.p12 \
--pkcs12-password Secret.123 \
--append7.4.2.2.2. Installing KRA subsystem
Prepare a deployment configuration, for example kra-clone.cfg, to deploy KRA subsystem clone. By default the subsystem is deployed into a Tomcat instance called pki-tomcat.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra-clone.cfg.
It assumes that the:
- Primary CA and KRA subsystems are running at https://primary.example.com:8443.
-
CA signing certificate has been exported into
ca_signing.crt. -
Admin certificate and key have been exported into
ca_admin_cert.p12. -
The PKCS #12 password is specified in the
pki_client_pkcs12_passwordparameter.
See Installing CA for details.
To start the installation execute the following command:
pkispawn -f kra-clone.cfg -s KRA
$ pkispawn -f kra-clone.cfg -s KRA7.4.2.2.3. KRA system certificates
After installation, the existing KRA system certificates (including the certificate chain) and their keys are stored in the server NSS database (i.e. /var/lib/pki/pki-tomcat/conf/alias), and a new SSL server certificate is created for the new instance:
If necessary, the certificates can be exported into PEM files with the following command:
pki-server cert-export <cert ID> --cert-file <filename>
$ pki-server cert-export <cert ID> --cert-file <filename>The valid certificate IDs for KRA are:
-
kra_storage_signing -
kra_transport_signing -
kra_audit_signing -
subsystem -
sslserver
Note that the pki-server cert-export command takes a certificate ID instead of a nickname. For simplicity the nicknames in this example are configured to be the same as the certificate IDs.
7.4.2.2.4. Admin certificate
To use the admin certificate, do the following.
Import the CA signing certificate into the client NSS database:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow To verify that the admin certificate can be used to access the KRA subsystem clone, execute the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.3. Installing KRA clone with HSM
Follow this process to install a KRA subsystem as a clone of an existing KRA subsystem where the system certificates and their keys are stored on a HSM.
Since the certificates and the keys are already on the HSM, it is not necessary to export them into a PKCS #12 file to create a clone.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.2.3.1. Installing KRA subsystem
Note: It is assumed that the CA signing certificate has been exported into ca_signing.crt.
Prepare a file, for example
kra.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f kra.cfg -s KRA
$ pkispawn -f kra.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.3.2. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.3.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the KRA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.3.4. Verifying KRA connector
Verify that the KRA connector is configured in the CA subsystem:
7.4.2.4. Installing KRA with ECC
Follow this process to install a KRA subsystem with ECC.
Supported ECC curves:
- nistp256
- nistp384
- nistp521
Supported ECC key algorithms:
- SHA256withEC
- SHA384withEC
- SHA512withEC
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.2.4.1. Installing KRA subsystem
Prepare a file, for example
kra.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f kra.cfg -s KRA
$ pkispawn -f kra.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.4.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.2.4.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the KRA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.5. Installing KRA with HSM
Follow this process to install a KRA subsystem where the system certificates and their keys are stored on a HSM.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.2.5.1. Installing KRA subsystem
Prepare a file, for example
kra.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f kra.cfg -s KRA
$ pkispawn -f kra.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.5.2. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.5.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the KRA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.5.4. Verifying KRA connector
Verify that the KRA connector is configured in the CA subsystem:
7.4.2.6. Installing KRA with LDAPS connection
Follow this process to install a KRA subsystem with a secure database connection.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.2.6.1. DS configuration
Once the prerequisites listed above are configured, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows:
certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt7.4.2.6.2. Installing KRA subsystem
Prepare a file, for example
kra.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f kra.cfg -s KRA
$ pkispawn -f kra.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a KRA subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.2.6.3. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.2.6.4. Verifying database configuration
Verify that the KRA database is configured with a secure connection:
7.4.2.6.5. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the KRA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.6.6. Verifying KRA connector
Verify that the KRA connector is configured in the CA subsystem:
7.4.2.6.7. Getting real DS certificate from the CA
If desired, follow this procedure to get the real DS certificate issued by the CA.
7.4.2.7. Installing standalone KRA
Follow this process to install a standalone KRA subsystem.
In regular KRA installation the KRA certificates are issued automatically by the CA and the KRA will join the CA’s security domain.
In standalone KRA installation, the KRA certificates are issued manually and the KRA has its own security domain.
The installation process consists multiple steps:
- Generating certificate requests
- Issuing the certificates
- Completing installation with the certificates
7.4.2.7.1. Generating certificate requests
Prepare a file, for example
kra-standalone-step1.cfg, that contains the first deployment configuration.A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra-standalone-step1.cfg.
Execute the following command:
pkispawn -f kra-standalone-step1.cfg -s KRA
$ pkispawn -f kra-standalone-step1.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
It creates an NSS database in /var/lib/pki/pki-tomcat/alias and generate CSRs in the specified paths.
7.4.2.7.2. Issuing certificates
Use the CSRs to obtain KRA certificates by submitting the CSRs to an external CA to issue the KRA system certificates. In the section that follows, it is assumed that the KRA system certificates are stored in the following files:
- kra_storage.crt
- kra_transport.crt
- subsystem.crt
- sslserver.crt
- kra_audit_signing.crt
- kra_admin.crt
7.4.2.7.3. Completing the installation
Prepare another file, for example
kra-standalone-step2.cfg, that contains the second deployment configuration. The file can be created from the first file, that iskra-standalone-step1.cfg, with the following changes:pki_external_step_two=True
pki_external_step_two=TrueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the certificate files with the following parameters:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Each certificate file can contain either a single PEM certificate or a PKCS #7 certificate chain.
Specify the CA certificate chain with the following parameters:
pki_cert_chain_nickname=ca_signing pki_cert_chain_path=ca_signing.crt
pki_cert_chain_nickname=ca_signing pki_cert_chain_path=ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow The CA certificate chain file can contain either a single PEM certificate or a PKCS #7 certificate chain as well.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/kra-standalone-step2.cfg.
Execute the following command:
pkispawn -f kra-standalone-step2.cfg -s KRA
$ pkispawn -f kra-standalone-step2.cfg -s KRACopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.2.7.4. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 kra_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 kra_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the KRA subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3. Installing the OCSP subsystem
7.4.3.1. Installing OCSP
Follow this process to install an OCSP subsystem.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.3.1.1. Installing OCSP subsystem
-
Prepare a file, for example
ocsp.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ocsp.cfg. Execute the following command:
pkispawn -f ocsp.cfg -s OCSP
$ pkispawn -f ocsp.cfg -s OCSPCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias
When OCSP is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only) to the system prior to OCSP installation.
7.4.3.1.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.3.1.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.1.4. Verifying OCSP client
Publish the CRL in CA to the directory server as follows:
- Go to CA Agent UI (https://pki.example.com:8443/ca/agent/ca/).
- Click Update Directory Server.
- Select Update the certificate revocation list to the directory.
- Click Update Directory.
Verify that the OCSPClient can be used to validate a certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.2. Installing OCSP with ECC
Follow this process to install an OCSP subsystem with ECC.
Supported ECC curves:
- nistp256
- nistp384
- nistp521
Supported ECC key algorithms:
- SHA256withEC
- SHA384withEC
- SHA512withEC
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.3.2.1. Installing OCSP subsystem
Prepare a file, for example
ocsp.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ocsp.cfg -s OCSP
$ pkispawn -f ocsp.cfg -s OCSPCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/kra/alias
7.4.3.2.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.3.2.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.3. Installing OCSP with HSM
Follow this process to install an OCSP subsystem where the system certificates and their keys are stored on a HSM.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.3.3.1. Installing OCSP subsystem
Prepare a file, for example
ocsp.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ocsp.cfg -s OCSP
$ pkispawn -f ocsp.cfg -s OCSPCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias
7.4.3.3.2. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.3.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.3.4. Verifying OCSP client
Publish the CRL in CA to the directory server as follows:
- Go to CA Agent UI (https://pki.example.com:8443/ca/agent/ca/).
- Click Update Directory Server.
- Select Update the certificate revocation list to the directory.
- Click Update Directory.
Verify that the OCSPClient can be used to validate a certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.4. Installing OCSP with LDAPS connection
Follow this process to install an OCSP subsystem with a secure database connection.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.3.4.1. DS configuration
Once the prerequisites listed above are completed, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows
certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt7.4.3.4.2. Installing OCSP subsystem
Prepare a file, for example
ocsp.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f ocsp.cfg -s OCSP
$ pkispawn -f ocsp.cfg -s OCSPCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a OCSP subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/ocsp/alias
7.4.3.4.3. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.3.4.4. Verifying database configuration
Verify that the OCSP database is configured with a secure connection:
7.4.3.4.5. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.4.6. Verifying OCSP client
Publish the CRL in CA to the directory server as follows:
- Go to CA Agent UI (https://pki.example.com:8443/ca/agent/ca/).
- Click Update Directory Server.
- Select Update the certificate revocation list to the directory.
- Click Update Directory.
Verify that the OCSPClient can be used to validate a certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.4.7. Getting real DS Certificate from the CA
If desired, follow this procedure to get real DS certificate issued by the CA.
7.4.3.5. Installing standalone OCSP
Follow this process to install a standalone OCSP subsystem.
In regular OCSP installation the OCSP certificates are issued automatically by the CA and the OCSP will join the CA’s security domain.
In standalone OCSP installation, the OCSP certificates are issued manually and the OCSP has its own security domain.
The installation process consists multiple steps:
- Generating certificate requests
- Issuing the certificates
- Completing installation with the certificates
7.4.3.5.1. Generating certificate requests
Prepare a file, for example
ocsp-standalone-step1.cfg, that contains the first deployment configuration.A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ocsp-standalone-step1.cfg.
Execute the following command:
pkispawn -f ocsp-standalone-step1.cfg -s OCSP
$ pkispawn -f ocsp-standalone-step1.cfg -s OCSPCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It creates an NSS database in /var/lib/pki/pki-tomcat/alias and generates CSRs in the specified paths.
7.4.3.5.2. Issuing certificates
Use the CSRs to obtain OCSP certificates by submitting the CSRs to an external CA to issue the KRA system certificates. In the section that follows, it is assumed that the KRA system certificates are stored in the following files:
- ocsp_signing.crt
- subsystem.crt
- sslserver.crt
- ocsp_audit_signing.crt
- ocsp_admin.crt
7.4.3.5.3. Completing installation
Prepare another file, for example
ocsp-standalone-step2.cfg, that contains the second deployment configuration. The file can be created from the first file, that isocsp-standalone-step1.cfg, with the following changes:pki_external_step_two=True
pki_external_step_two=TrueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Specify the certificate files with the following parameters:
pki_ocsp_signing_cert_path=ocsp_signing.crt pki_subsystem_cert_path=subsystem.crt pki_sslserver_cert_path=sslserver.crt pki_audit_signing_cert_path=ocsp_audit_signing.crt pki_admin_cert_path=ocsp_admin.crt
pki_ocsp_signing_cert_path=ocsp_signing.crt pki_subsystem_cert_path=subsystem.crt pki_sslserver_cert_path=sslserver.crt pki_audit_signing_cert_path=ocsp_audit_signing.crt pki_admin_cert_path=ocsp_admin.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Each certificate file can contain either a single PEM certificate or a PKCS #7 certificate chain.
Specify the CA certificate chain with the following parameters:
pki_cert_chain_nickname=ca_signing pki_cert_chain_path=ca_signing.crt
pki_cert_chain_nickname=ca_signing pki_cert_chain_path=ca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow The CA certificate chain file can contain either a single PEM certificate or a PKCS #7 certificate chain as well.
A sample deployment configuration is available at /usr/share/pki/server/examples/installation/ocsp-standalone-step2.cfg.
Execute the following command:
pkispawn -f ocsp-standalone-step2.cfg -s OCSP
$ pkispawn -f ocsp-standalone-step2.cfg -s OCSPCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.3.5.4. Verifying Admin Certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki pkcs12-import \ --pkcs12 ocsp_admin_cert.p12 \ --pkcs12-password Secret.123$ pki pkcs12-import \ --pkcs12 ocsp_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the OCSP subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.4. Installing the TKS subsystem
7.4.4.1. Installing TKS
Follow this process to install a TKS subsystem.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.4.1.1. Installing TKS subsystem
-
Prepare a file, for example
tks.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/tks.cfg. Execute the following command:
pkispawn -f tks.cfg -s TKS
$ pkispawn -f tks.cfg -s TKSCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a TKS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/tks/alias
When TKS is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only!) to the system prior to TKS installation.
7.4.4.1.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.4.1.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the TKS subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.4.2. Installing TKS with HSM
Follow this process to install a TKS subsystem where the system certificates and their keys are stored on a HSM.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.4.2.1. Installing TKS subsystem
Prepare a file, for example
tks.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f tks.cfg -s TKS
$ pkispawn -f tks.cfg -s TKSCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a TKS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/tks/alias
7.4.4.2.2. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.4.2.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the TKS subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.4.3. Installing TKS with LDAPS connection
Follow this process to install a TKS subsystem with a secure database connection.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.4.3.1. DS configuration
Once the prerequisites listed above are completed, if you chose to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows:
certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt7.4.4.3.2. Installing TKS subsystem
Prepare a file, for example
tks.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f tks.cfg -s TKS
$ pkispawn -f tks.cfg -s TKSCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a TKS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/tks/alias
7.4.4.3.3. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.4.3.4. Verifying database configuration
Verify that the TKS database is configured with a secure connection:
7.4.4.3.5. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the TKS subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.4.3.6. Getting real DS Certificate from the CA
If desired, follow this procedure to get real DS certificate issued by the CA.
7.4.5. Installing the TPS subsystem
7.4.5.1. Installing TPS
Follow this process to install a TPS subsystem.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.5.1.1. Installing TPS subsystem
-
Prepare a file, for example
tps.cfg, that contains the deployment configuration. A sample deployment configuration is available at /usr/share/pki/server/examples/installation/tps.cfg. Execute the following command:
pkispawn -f tps.cfg -s TPS
$ pkispawn -f tps.cfg -s TPSCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a TPS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/tps/alias
When TPS is installed on a new system without any other subsystems, it is necessary to provide the CA’s root certificate. Specify the path to the CA PKCS#7 PEM file in the pki_cert_chain_path. This allows the server to verify the CA’s SSL server certificate when contacting the security domain. It is up to the administrator to securely transport the CA root certificate (public key only) to the system prior to TPS installation.
7.4.5.1.2. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.5.1.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the TPS subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.5.2. Installing TPS with HSM
Follow this process to install a TPS subsystem where the system certificates and their keys are stored on a HSM.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.5.2.1. Installing TPS subsystem
Prepare a file, for example
tps.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f tps.cfg -s TPS
$ pkispawn -f tps.cfg -s TPSCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a TPS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/tps/alias
7.4.5.2.2. Verifying system certificates
Verify that the internal token contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the HSM contains the following certificates:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.5.2.3. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the TPS subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.5.3. Installing TPS with LDAPS connection
Follow this process to install a TPS subsystem a secure database connection.
Prior to installation, ensure that the Installation Prerequisites are configured.
7.4.5.3.1. DS configuration
Once the prerequisites listed above are completed, if you had chosen to use the DS bootstrap certificates during DS instance creation, then export the bootstrap self-signed certificate into ds_signing.crt as follows:
certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt
$ certutil -L -d /etc/dirsrv/slapd-localhost -n Self-Signed-CA -a > ds_signing.crt7.4.5.3.2. Installing TPS subsystem
Prepare a file, for example
tps.cfg, that contains the deployment configuration:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the following command:
pkispawn -f tps.cfg -s TPS
$ pkispawn -f tps.cfg -s TPSCopy to Clipboard Copied! Toggle word wrap Toggle overflow
It installs a TPS subsystem in a Tomcat instance (default is pki-tomcat) and creates the following NSS databases:
- server NSS database: /var/lib/pki/pki-tomcat/conf/alias
- admin NSS database: ~/.dogtag/pki-tomcat/tps/alias
7.4.5.3.3. Verifying system certificates
Verify that the server NSS database contains the following certificates:
7.4.5.3.4. Verifying database configuration
Verify that the TPS database is configured with a secure connection:
7.4.5.3.5. Verifying admin certificate
Import the CA signing certificate:
pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signing
$ pki nss-cert-import --cert ca_signing.crt --trust CT,C,C ca_signingCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import admin certificate and key into the client NSS database (by default ~/.dogtag/nssdb) with the following command:
pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123$ pki -c Secret.123 pkcs12-import \ --pkcs12 ca_admin_cert.p12 \ --pkcs12-password Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the admin certificate can be used to access the TPS subsystem by executing the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.4.5.3.6. Getting real DS certificate from the CA
If desired, follow this procedure to get real DS certificate issued by the CA.
7.4.6. Installing the EST subsystem
7.4.6.1. Installing EST
Follow this process to install an EST subsystem.
The EST subsystem requires the package dogtag-pki-est installed on the server where the instance is run:
dnf install dogtag-pki-est
# dnf install dogtag-pki-est7.4.6.1.1. Prerequisites
On the CA, create a user group for EST RA accounts (EST RA Agents), and an EST RA account (est-ra-1). The EST subsystem uses this account to authenticate to the CA subsystem and issue certificates on behalf of EST clients.
Note: The commands below assume that the CA is running on the same host with the default port and the nssdb is located in ~/.dogtag/nssdb. To point to a CA on a different host or with a different port use the options -h <hostname>, -p <port_number> or -U <CA_uri. To use a different nssdb use the option -d <nssdb_path>.
Add and enable the EST enrollment profile estServiceCert.cfg, which is available in /usr/share/pki/ca/profiles/ca if the dogtag-pki-ca package is installed:
Note: Before enabling the profile, verify if the options satisfy the requirement for the deployment.
EST subsystem has its own realm authentication with a separate user DB. LDAP, PostreSQL and file based DB are supported. The DB has to be prepared in advance for authentication to work. Instructions to set up the user DB are available in Configure EST Realm DB.
7.4.6.1.2. Installing EST subsystem
There are two options for the installation:
-
Basic installation with
pkispawn. See Installing EST pkispawn; -
Advanced installation with
pki-server. See Installing EST pki-server. It requires more manual configuration but provides more control over the installation process since each step can be verified and eventually customized and repeated.
7.4.6.1.3. Verifying EST
Before enrolling certificates, EST users must be added in the user database. The user management is not part of EST commands and has to be done outside of EST. Information on how to add users on each database platform can be found in the Administration Guide.
Use curl to verify that the EST subsystem is deployed and is able to communicate with the CA subsystem.
The following command prints the CA signing certificate obtained from the server:
curl --cacert ./ca_signing.crt https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/cacerts | openssl base64 -d | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout
$ curl --cacert ./ca_signing.crt https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/cacerts | openssl base64 -d | openssl pkcs7 -inform der -print_certs | openssl x509 -text -noout
Replace $EST_HOSTNAME and $EST_PORT with the hostname and port of the EST subsystem, respectively.
If successful, the server CA certificate chain is printed on standard output and the command will exit with status 0 (success).
To test the enrollment using curl, generate a CSR and submit using a user from the EST user DB associated with the realm. The following commands will perform the enrollment and print the final certificate:
Note: The testServer.p10 file is a base64 encoded pkcs10 DER without header/footer.
In case the enrollment is done using mutual TLS authentication in the curl command above, the credentials have to be replaced with the certificate and related key as follows:
curl --cacert ./ca_signing.crt --cert cert.pem --key key-x-x.pem \
--data-binary @testServer.p10 -H "Content-Type: application/pkcs10"
$ curl --cacert ./ca_signing.crt --cert cert.pem --key key-x-x.pem \
--data-binary @testServer.p10 -H "Content-Type: application/pkcs10"
-o newCert.p7 https://<EST_HOSTNAME>:<EST_PORT>/.well-known/est/simpleenroll
When mutual TLS authentication is performed, the CSR subject and SAN has to match with the subject and SAN of the certificate used for the authentication in order to get authorized. Differently, using the basic authentication the CSR subject and SAN will be verified with user full name or user id. This check can be disabled for the simpleenroll operation. To disable this check add the following option to the file /etc/pki/<instance_name>/est/authorizer.conf:
enrollMatchTLSSubjSAN=false
enrollMatchTLSSubjSAN=false7.4.6.2. EST installation using pkispawn
Once the prerequisites in Installing EST are configured, it is possible to install EST.
7.4.6.2.1. Installation
An example pkispawn installation configuration is provided in /usr/share/pki/server/examples/installation/est.cfg with the following content:
The following commands install an EST subsystem on a PKI server instance that already has a CA subsystem in it. By default the PKI server instance is called pki-tomcat and it uses HTTP port 8080 and HTTPS port 8443. To use a different instance name or port numbers refer to the command’s manual page.
To install EST in the same instance of the CA and with the DS realm, run the command:
pkispawn \
-f /usr/share/pki/server/examples/installation/est.cfg \
-s EST \
-D est_realm_url=ldap://estds.example.com:389 \
-v
# pkispawn \
-f /usr/share/pki/server/examples/installation/est.cfg \
-s EST \
-D est_realm_url=ldap://estds.example.com:389 \
-v
Note that the est_realm_url points to the user DB. The other configurations that could be modified according to the deployment are:
The est_ca_* provides information related to the user and profile configured in the CA for the EST subsystem.
The est_authorizer_exec_path is the path to the executable responsible for verifying the authorization. The default script estauthz is a simple authorization example that checks only that the user has the role estclient.
The est_realm_* options allow one to customize the realm. Possible types are: ds, postgresql and in-memory.
As an example, to install EST with PostgreSQL the command is:
The est_realm_custom is a path to a custom realm configuration for Tomcat and if provided it will overwrite all other realm related configurations.
7.4.6.2.1.1. Installation on separate instance with certificates
EST can also be installed on a Tomcat instance that is separate from the CA.
In addition to the configuration above, installing EST in a separate instance requires some extra steps to configure the certificates.
Note: The commands below assume that the CA is running on the same host with the default port and the nssdb is located in ~/.dogtag/nssdb. To point to a CA on a different host or with a different port use the options -h <hostname>, -p <port_number> or -U <CA_uri. To use a different nssdb use the option -d <nssdb_path>.
The EST server cert (and a subsystem certificate to connect with the CA) has to be pre-issued and provided to pkispawn with its full chain in a PKCS#12 bundle supplied via the pki_server_pkcs12_* parameters on the pkispawn command line as shown below.
It is important that the certificate aliases in the PKCS#12 matches with the nickname used by EST. For the SSL certificate the nickname configured in est.cfg is sslserver but can be modified.
To create the PKCS12 with the certificate it is possible to request a server certificate for EST from the CA (and later the RA user certificate) and then export them as shown below:
Similarly, to generate a subsystem certificate for EST, associate to the EST RA user (est-ra-1) previously configured in the CA, and add in the same PKCS12 of the SSL server certificate:
Using the generated PKCS#12 bundle, the command to deploy EST is:
7.4.6.2.1.2. Installation on separate instance without certificates
If the PKCS#12 bundle certificates are not provided to pkispawn, during the installation, the EST server cert is issued automatically using the profile configured for EST. The connection with the CA uses the credentials (username/password) provided in the configuration file. In such a case the CA signing certificate is needed. Retrieving the certificate can be done in the CA server with the command:
pki-server cert-export ca_signing --cert-file ca_signing.crt
# pki-server cert-export ca_signing --cert-file ca_signing.crtIt is possible to install EST with the following command:
After the installation it is possible to update the EST server certificates with a new certificate using a different profile if the EST released certificates are not meant for the server. Additionally, a certificate for TLS authentication could be added in the EST nssdb and configured in the file /var/lib/pki/pki-tomcat/conf/est/backend.conf.
7.4.6.2.2. Removing EST
To remove the EST subsystem, it is possible to use the pkidestroy command as follows:
pkidestroy -s EST -v
# pkidestroy -s EST -v
Note: the configuration and log folders are not removed. To remove everything add the the options: --remove-conf --remove-logs.
7.4.6.3. EST installation using pki-server
Once the prerequisite in Installing EST are configured, it is possible to install EST.
A PKI Tomcat instance has to be already available, if it is not present then it is possible to create a new one with pki-server create (see more details here).
Create the EST subsystem inside the pki server instance:
pki-server est-create
# pki-server est-create
Configure the issuance backend. The class org.dogtagpki.est.DogtagRABackend is used for the EST instance to communicate with the CA. This requires:
- The url parameter pointing to the CA subsystem;
Credentials of an EST RA account using either of the following methods that authorizes the account to request certificate issuance using the configured enrollment profile:
- username and password if the EST RA account;
- TLS client certificate that belongs to the EST RA account.
- The enrollment profile.
Note: To use TLS mutual authentication instead of username/password, one needs to:
- Get issuance for a TLS client certificate from the CA, using the EST instance’s crypto token for generating keys and CSR in the instance alias directory;
- Import the certificate into the EST instance’s crypto token;
- Assign the nickname to the parameter nickname (leave out username and password);
- Add the certificate to the EST RA user account on the CA.
An example on how to get the certificate and configure EST with TLS mutual configuration is provided in the pkispawn installation guide here.
Configure request authorization. The class org.dogtagpki.est.ExternalProcessRequestAuthorizer allows to delegate the authorization to an external process configured with the parameter executable:
cat >/var/lib/pki/pki-tomcat/conf/est/authorizer.conf <<EOF class=org.dogtagpki.est.ExternalProcessRequestAuthorizer executable=/usr/share/pki/est/bin/estauthz EOF
# cat >/var/lib/pki/pki-tomcat/conf/est/authorizer.conf <<EOF
class=org.dogtagpki.est.ExternalProcessRequestAuthorizer
executable=/usr/share/pki/est/bin/estauthz
EOF
The executable script in this example performs a simple check of the user role and it is available at /usr/share/pki/est/bin/estauthz. It can be replaced if a more sophisticated authorization framework has to be adopted.
Deploy the EST application:
pki-server est-deploy
# pki-server est-deployConfigure the authentication. The authentication allows one to use realms from Tomcat or developed for dogtag. As an example we use an in memory realm:
Finally, restart the server:
pki-server restart --wait
# pki-server restart --wait7.4.6.4. Configure EST Realm DB
7.4.6.4.1. Preparing DS DB
If you have chosen to use an LDAP instance for user management, before adding users, ensure that you have configured the directory server and added base entries. Directory server setup instructions can be found in the Installation Prerequisites.
The user DB requires a group node for the people and one for the groups. A simple ldif file is available in /usr/share/pki/est/conf/realm/ds/create.ldif. The base DN in this is dc=pki,dc=example,dc=com but it can be modified and the new value specified during the following EST installation. The file can be imported with the following command:
ldapadd -x -H ldap://<ds_server_hostname>:<ds_server_port> \
-D "cn=Directory Manager" -w Secret.123 \
-f /usr/share/pki/est/conf/realm/ds/create.ldif
ldapadd -x -H ldap://<ds_server_hostname>:<ds_server_port> \
-D "cn=Directory Manager" -w Secret.123 \
-f /usr/share/pki/est/conf/realm/ds/create.ldif
The command creates also the group EST Users and it is used as default group for users to access EST. Using a different group requires you to modify the authorization script /usr/share/pki/est/bin/estauthz.
7.4.6.4.2. Preparaing PostgreSQL DB
If you have chosen to use PostgreSQL for user management, you first need to prepare a database, for example est, to access the database. Installation instructions can be found here.
After the installation, verify the database connection with the following command:
psql -U est -d est
$ psql -U est -d est
To use the PostreSQL DB, the user tables should be created with the sql file provided in /usr/share/pki/est/conf/realm/postgresql/create.sql and then filled with the user information. The tables can be created with the command:
psql -U est -t -A -f /usr/share/pki/est/conf/realm/postgresql/create.sql
$ psql -U est -t -A -f /usr/share/pki/est/conf/realm/postgresql/create.sql
The command creates also the group EST Users and it is used as default group for user to access EST. Using a different group requires you to modify the authorization script /usr/share/pki/est/bin/estauthz.
It is possible to use different schemas but in this case a custom statements.conf file (provided in the same folder) has to be provided in order to retrieve the user information from the DB.
Additionally, a Java driver for PostgreSQL needs to be installed in the EST server and linked into library folder of pki:
7.5. Post-installation tasks
Once installation using the 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”.
This section provides a list of operations from Part III, “Configuring Certificate System” which are suggested for improving the security for the deployment.
7.5.1. Setting date/time for Red Hat Certificate System
It is important to have the time set up correctly for running RHCS; see the Setting time and date section in the Red Hat Certificate System Administration Guide.
7.5.2. Getting DS certificate issued by actual CA
Follow this process using pki CLI (run man pki-client) commands to get DS certificate issued by the actual CA.
This section assumes that a DS instance named localhost already exists,
Two conditions are covered by this section:
- The DS instance does not already have any SSL server certificate, bootstrap or otherwise, and it is time to create an actual server cert for it.
- The DS instance has a bootstrap SSL server certificate, and you wish to replace it.
It is assumed that an actual trusted CA is available for issuing certificates.
7.5.2.1. Export the CA signing certificate
pki-server cert-export ca_signing --cert-file ca_signing.crt
pki-server cert-export ca_signing --cert-file ca_signing.crt7.5.2.2. Creating DS server certificate
7.5.2.2.1. Generate DS server CSR
As a DS administrator:
Note: Make sure the certificate subject DN and SAN match the system hostname.
7.5.2.2.2. Submit DS server certificate request:
As a DS admin:
pki ca-cert-request-submit --profile caServerCert --csr-file ds_server.csr
$ pki ca-cert-request-submit --profile caServerCert --csr-file ds_server.csr7.5.2.2.3. Approve the certificate request:
As a PKI agent:
pki -n caadmin ca-cert-request-approve <request ID>
$ pki -n caadmin ca-cert-request-approve <request ID>7.5.2.3. Retrieve the certificate
Retrieve the cert as the DS admin user:
pki ca-cert-export <certificate ID> --output-file ds_server.crt
$ pki ca-cert-export <certificate ID> --output-file ds_server.crt7.5.2.4. Stop the DS instance
Stop the DS instance prior to changing the NSS database.
dsctl localhost stop
$ dsctl localhost stop7.5.2.5. Import the CA signing certificate
As a DS administrator, import the CA signing cert into the nssdb of the DS instance.
7.5.2.6. Delete DS bootstrap certificates
If you already had boostrap DS certificates, delete them:
7.5.2.7. Import DS server certificate:
To verify the DS server certificate:
7.5.2.8. Enabling SSL Connection
This section only applies if you did not enable SSL in your DS earlier.
To enable SSL connection in the DS instance:
dsconf localhost config replace nsslapd-security=on
$ dsconf localhost config replace nsslapd-security=onCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the DS instance:
dsctl localhost start
$ dsctl localhost startCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the SSL connection:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.2.9. Delete DS bootstrap signing certificate from PKI instance
If you are replacing the DS bootstrap certs, as a PKI administrator, stop the PKI then delete the DS bootstrap signing cert from the PKI nssdb as follows.
certutil -F -d /var/lib/pki/pki-tomcat/conf/alias \
-f /var/lib/pki/pki-tomcat/conf/alias/pwdfile.txt \
-n ds_signing
$ certutil -F -d /var/lib/pki/pki-tomcat/conf/alias \
-f /var/lib/pki/pki-tomcat/conf/alias/pwdfile.txt \
-n ds_signingStart the PKI.
7.5.2.10. See Also
7.5.3. Enabling SSL connection in DS using bootstrap certs
If you already have an active trusted CA, and you wish to issue a server cert for your DS, follow this section instead.
Follow this process using pki CLI (run man pki-client) commands to enable SSL connection in DS by creating a bootstrap DS self-signed signing certificate and the bootstrap server certificate issued by it.
This section assumes that a DS instance named localhost already exists, it does not have certificates, and the SSL connection is disabled.
Note: In newer DS versions the certificates are created and the SSL connection is enabled by default, so in general it is not necessary to follow this procedure.
7.5.3.1. Creating DS signing certificate
Generate DS signing CSR with the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Issue DS signing certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Import DS signing certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the DS signing certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.3.2. Creating DS Server Certificate
Generate DS server CSR with the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Issue DS server certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Import DS server certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the DS server certificate:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.3.3. Enabling SSL Connection
To enable SSL connection in the DS instance:
dsconf localhost config replace nsslapd-security=on
$ dsconf localhost config replace nsslapd-security=onCopy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the DS instance:
dsctl localhost restart
$ dsctl localhost restartCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the SSL connection:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.3.4. See Also
7.5.4. Enabling TLS mutual authentication from CS to DS
This section requires a root CA installed and running. If you used a bootstrap self-signed LDAP server certificate, replace it first by following Section 7.5.2, “Getting DS certificate issued by actual CA”. These steps are to be performed once the installation is complete.
If you choose to enable TLS client authentication, once the basic TLS server authentication has been configured and running when installing the CS subsystem, we can now double back and attempt to enable client authentication from a given subsystem to the LDAP server.
There are two parts to setting up client authentication. The first part is configuring the LDAP directory to require TLS mutual authentication. This procedure is detailed in Using certificate-based client authentication in the Red Hat Directory Server Administration Guide.
Note the following:
-
pkispawnalready automatically created apkidbuseron 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
certmap rhcs <certificate issuer DN> rhcs:CmapLdapAttr seeAlso rhcs:verifyCert onCopy to Clipboard Copied! Toggle word wrap Toggle overflow For example
certmap rhcs CN=CA Signing Certificate,OU=pki-tomcat-ca,O=pki-tomcat-ca-SD rhcs:CmapLdapAttr seeAlso rhcs:verifyCert on
certmap rhcs CN=CA Signing Certificate,OU=pki-tomcat-ca,O=pki-tomcat-ca-SD rhcs:CmapLdapAttr seeAlso rhcs:verifyCert onCopy to Clipboard Copied! Toggle word wrap Toggle overflow - After configuring, restart the Directory Server.
The second part is adding configuration to the Red Hat Certificate System instance so that it knows which port and certificate is to be used to communicate with its internal LDAP server using TLS mutual authentication. This involves editing the RHCS instance’s CS.cfg file located at <instance directory>/<subsystem type>/conf/CS.cfg. For example /var/lib/pki/ instance_name/ca/conf/CS.cfg
In the 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.ldapauth.bindDN
internaldb.ldapauth.bindPWPromptAs shown below:
Restart the CS instance at the end of the post-installation step.
The internaldb.basedn and internaldb.database parameters must be configured to match your specific LDAP instance.
For compliance, 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.
All other values can be changed as desired to reflect your environment or availability needs.
7.5.5. Configuring session timeout
Various timeout configurations exist on the system that could affect how long a TLS session is allowed to remain idle before termination. For details, see Section 13.4.2, “Session timeout”.
7.5.6. CRL or certificate publishing
CRL publishing is critical in providing OCSP service. Certificate publishing is optional but often desired by sites. For details, see the Publishing Certificates and CRLs section in the Red Hat Certificate System Administration Guide.
7.5.7. Configuring certificate enrollment profiles (CA)
RHCS has a rich profile framework that allows for customization of the certificate enrollment profiles. It is very common for a site to enable/disable default profiles that come with the system, or modify existing profiles, or create their own profiles. For details, see Chapter 15, Configuring certificate profiles.
7.5.8. CA’s enrollment profile configuration with CRL Distribution Points
Enable the desired profile(s) to include the CRL Distribution Points. These are the profiles corresponding to the configuration in the sections above.
Open the
caCMCserverCertWithCRLDP.cfgprofile (for enrollments with RSA keys) in the/var/lib/pki/<ca instance directory/ca/profiles/ca/directory and update as follows:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Open the
caCMCECserverCertWithCRLDP.cfg(for enrollments with ECC keys) in the/var/lib/pki/<ca instance directory/ca/profiles/ca/directory and update as follows:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set user:group ownership:
chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Register a new profile in the CA’s
CS.cfg:Add the following lines for each profile:
profile.caCMCserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg profile.caCMCECserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCECserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
profile.caCMCserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg profile.caCMCECserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCECserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
profile.listentry to add the two new profiles. For example::profile.list=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP,acmeServerCert,caCMCserverCert,caCMCECserverCert, …
profile.list=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP,acmeServerCert,caCMCserverCert,caCMCECserverCert, …Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.9. Configure support for CRL Distribution Point
For more information on CRL Distribution Points, why they are needed and where they are best suited, see Enabling automatic revocation checking on the CA.
To configure support for CRL Distribution Points, as an example, we describe how to set up a file-based CRL publisher as well as the partitioning of the CRL. You will also learn how to enable a certificate enrollment profile to issue certificates with the CRL Distribution Point extension. Finally, we describe how to replace the temporary Server-Cert of the CA’s LDAP server with a certificate issued from the CRL Distribution Point profiles.
Before proceeding with the following changes, stop the RootCA instance:
pki-server stop rhcs10-RSA-RootCA
pki-server stop rhcs10-RSA-RootCA7.5.9.1. CA setup to support Server Cert CRL File Publishing
Before proceeding, save a copy of the configuration file before editing:
cp /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/CS.cfg /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/CS.cfg.bak.<date>
cp /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/CS.cfg /var/lib/pki/rhcs10-RSA-RootCA/ca/conf/CS.cfg.bak.<date>7.5.9.1.1. Set up the file-based publisher: crlFilePublisher
The configuration in this section creates a file-based CRL publisher called crlFilePublisher. When set up correctly, the CRL is stored under directory /var/lib/pki/rhcs10-RSA-RootCA/crl in DER format.
Create the CRL directory for publishing the file-based partitioned CRL:
mkdir /var/lib/pki/rhcs10-RSA-RootCA/crl chown pkiuser.pkiuser /var/lib/pki/rhcs10-RSA-RootCA/crl
mkdir /var/lib/pki/rhcs10-RSA-RootCA/crl chown pkiuser.pkiuser /var/lib/pki/rhcs10-RSA-RootCA/crlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the following to the CA’s CS.cfg:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.9.1.2. Set up the file-based publishing rule: FileCrlRule
The configuration in this section creates a file-based publishing rule called FileCrlRule. The predicate specifies the issuing point to a partitioned CRL called ServerCertCRL(defined in Set up the CRL-partitioning for certificates issued via a profile.
-
Add the following to the CA’s
CS.cfg:
7.5.9.1.3. Modify the LDAP-based publishing rule: LdapCrlRule
This configuration explicitly sets the LdapCrlRule predicate to the master (full) CRL. The master CRL is continuously supplied to the OCSP responder for proper OCSP support.
Modify the following in the CA’s CS.cfg:
ca.publish.rule.instance.LdapCrlRule.predicate=issuingPointId==MasterCRL
ca.publish.rule.instance.LdapCrlRule.predicate=issuingPointId==MasterCRL7.5.9.1.4. Set up the CRL-partitioning for certificates issued via a profile
The configuration in this section demonstrates how to partition a CRL to a smaller subset that could be utilized in the FileCrlRule defined above. The CRL is partitioned by the certificate enrollment profile(s) specified in the profileList parameter. A comma-separated list can be used for multiple profiles (for example, caCMCserverCertWithCRLDP.cfg and caCMCECserverCertWithCRLDP.cfg).
Add the following to the CA’s CS.cfg:
For an ECC CA, set the following to SHA512withEC:
ca.crl.ServerCertCRL.signingAlgorithm=SHA512withEC
ca.crl.ServerCertCRL.signingAlgorithm=SHA512withEC7.5.9.2. Set up CRL HTTP service in the CA
The CRL served by the CRL Distribution Point is published to a file (see sections above). This file is served by a non-SSL Tomcat service that we are adding to the CA’s server.xml as shown below:
Add the following CRL service before the Catalina service in the file
/var/lib/pki/rhcs10-RSA-RootCA/conf/server.xml:Copy to Clipboard Copied! Toggle word wrap Toggle overflow In the above CRL service, choose a connector port number that has not been used. For example, if the root CA’s HTTP port is 8080, then pick 8085. Ensure that the port is added for SELinux and firewall, for example:
semanage port -a -t http_port_t -p tcp 8085 firewall-cmd --permanent --add-port=8085/tcp firewall-cmd --reload
semanage port -a -t http_port_t -p tcp 8085 firewall-cmd --permanent --add-port=8085/tcp firewall-cmd --reloadCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteIf your selected port has been pre-assigned with another SELinux context, you will see an error message that looks like the following:
ValueError: Port tcp/8085 already defined
ValueError: Port tcp/8085 already definedCopy to Clipboard Copied! Toggle word wrap Toggle overflow You can also search and find out whether the CRL HTTP port is pre-assigned by using the following command:
semanage port -l | grep <port>
# semanage port -l | grep <port>Copy to Clipboard Copied! Toggle word wrap Toggle overflow We recommend that you select another port. However, if you wish to use the same port, you could do the following:
semanage port -m -t http_port_t -p tcp 8085
# semanage port -m -t http_port_t -p tcp 8085Copy to Clipboard Copied! Toggle word wrap Toggle overflow When the server is restarted, the directory CRL/localhost is created under the CA’s conf directory if it does not exist. However, to prepare for the addition of the
crl.xmlfile, do the following:mkdir -p /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost
mkdir -p /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhostCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a
crl.xmlfile under/var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost, and add the following content:<Context docBase="/var/lib/pki/rhcs10-RSA-RootCA/crl"> <Resources allowLinking="true" cachingAllowed="false" /> </Context>
<Context docBase="/var/lib/pki/rhcs10-RSA-RootCA/crl"> <Resources allowLinking="true" cachingAllowed="false" /> </Context>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set the
user:groupownership for thecrl.xmlfile:chown pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost/crl.xml
chown pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/conf/CRL/localhost/crl.xmlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
The CRL Distribution Point set in the enrollment profile looks like this (see next section for full example): http://rhcs10.example.com:8085/crl/ServerCertCRL.crl
File-based CRL publisher is only recommended for smaller CRLs with less frequently issued or revoked certificates. It is only recommended if necessary, such as in the case of CA startup setup described in this section.
7.5.9.3. CA’s enrollment profile configuration with CRL Distribution Points
Enable the desired profile(s) to include the CRL Distribution Points. These are the profiles corresponding to the configuration in the sections above.
Open the
caCMCserverCertWithCRLDP.cfgprofile (for enrollments with RSA keys) in the/var/lib/pki/<ca instance directory/ca/profiles/ca/ directoryand update as follows:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Open the caCMCECserverCertWithCRLDP.cfg (for enrollments with ECC keys) in the /var/lib/pki/<ca instance directory/ca/profiles/ca/ directory and update as follows:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set user:group ownership:
chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg chown -R pkiuser:pkiuser /var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Register a new profile in the CA’s CS.cfg:
Add the following lines for each profile:
profile.caCMCserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg profile.caCMCECserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCECserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfg
profile.caCMCserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCserverCertWithCRLDP.cfg profile.caCMCECserverCertWithCRLDP.class_id=caEnrollImpl profile.caCMCECserverCertWithCRLDP.config=/var/lib/pki/rhcs10-RSA-RootCA/ca/profiles/ca/caCMCECserverCertWithCRLDP.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the profile.list entry to add the two new profiles. For example::
profile.list=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP,acmeServerCert,caCMCserverCert,caCMCECserverCert, …
profile.list=caCMCserverCertWithCRLDP,caCMCECserverCertWithCRLDP,acmeServerCert,caCMCserverCert,caCMCECserverCert, …Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.9.4. Set up for more immediate CRL update
Since server certs do not often get revoked, it is reasonable to update the CRL as soon as there is a revocation. Edit the CA’s CS.cfg:
ca.crl.ServerCertCRL.alwaysUpdate=true
ca.crl.ServerCertCRL.alwaysUpdate=true7.5.9.5. Restart the CA once the CA’s configuration is updated
Once configuration is complete, restart the CA:
pki-server restart rhcs10-RSA-RootCA
pki-server restart rhcs10-RSA-RootCATo verify that the CRL Distribution Point is working, follow Verifying the CRL Distribution Point.
7.5.10. Verifying the CRL Distribution Point
If you have replaced the server-cert of the root CA’s directory server using the profile caCMCserverCertWithCRLDP, this effectively triggers the CRL distribution point to be referenced by the CA during startup when initiating a connection with its internal directory server.
This section provides a rudimentary method to verify the CRL Distribution Point setup in the CA (see Configure support for CRL Distribution Point):
Prior to verification, you need to enable revocation checks as follows:
To enable certificate revocation checks, in the respective
/var/lib/pki/rhcs10-RSA-RootCA/conf/server.xmlfile:Set
enableOCSPorenableRevocationCheckto true:enableOCSP=true or enableRevocationCheck=true
enableOCSP=true or enableRevocationCheck=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Additionally, remove these two parameters and their assigned values:
ocspResponderURL ocspResponderCertNickname
ocspResponderURL ocspResponderCertNicknameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Disable the legacy revocation check method by editing the CA’s CS.cfg file and setting the following to false:
auths.revocationChecking.enabled=false
auths.revocationChecking.enabled=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the RootCA instance:
pki-server start rhcs10-RSA-RootCA
pki-server start rhcs10-RSA-RootCACopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.10.1. Verification of the CRL Distribution Point
To verify the CRL Distribution Point:
Check the publishing of the file-based CRL:
ls -l /var/lib/pki/rhcs10-RSA-RootCA/crl
# ls -l /var/lib/pki/rhcs10-RSA-RootCA/crl total 8 -rw-r--r--. 1 pkiuser pkiuser 574 Jun 20 18:08 ServerCertCRL-20240620-180859.der -rw-r--r--. 1 pkiuser pkiuser 613 Jun 20 18:09 ServerCertCRL-20240620-180938.der lrwxrwxrwx. 1 pkiuser pkiuser 68 Jun 20 18:09 ServerCertCRL.crl -> /var/lib/pki/rhcs10-RSA-RootCA/crl/ServerCertCRL-20240620-180938.derCopy to Clipboard Copied! Toggle word wrap Toggle overflow Display and verify the content of the CRL
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Do not remove the CRL file (soft link file ServerCertCRL.crl, and its associated der file).
If you encounter a situation where the CRL file is missing or has been accidentally deleted from /var/lib/pki/rhcs10-RSA-RootCA/crl/, preventing the CA from starting, follow the steps below to regenerate the CRL file:
Stop the CA service.
pki-server stop rhcs10-RSA-RootCA
pki-server stop rhcs10-RSA-RootCACopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Set the
enableRevocationCheckorenableOCSPparameter tofalse(if it is currently set totrue) in CA’sserver.xml. -
Set the
ca.crl.ServerCertCRL.publishOnStart=parameter to true in CA’sCS.cfg. Start the CA service to regenerate the missing CRL file:
pki-server start rhcs10-RSA-RootCA
pki-server start rhcs10-RSA-RootCACopy to Clipboard Copied! Toggle word wrap Toggle overflow - After the CRL file has been recovered, stop the CA service once again.
-
Revert the
ca.crl.ServerCertCRL.publishOnStart=parameter to false in CA’sCS.cfg. -
Set the
enableRevocationCheckorenableOCSPparameter totruein CA’sserver.xml. - Start the CA service again to apply the changes.
By following these steps, you successfully recover the missing CRL file and ensure the CA can start correctly.
7.5.11. Enabling access banner
To enable user interface banners, refer to Section 13.7.1, “Enabling an access banner”.
7.5.12. Enabling the watchdog service
The watchdog (nuxwdog) service provides secure system password management. For details, see Section 13.3.2.1, “Enabling the watchdog service”.
7.5.13. Configuration for CMc enrollment and revocation (CA)
Certificate enrollments and revocation can be done via CMC.
- For details about enabling the CMC Shared Token Feature, see Section 13.7.8, “Enabling the CMC Shared Secret feature”.
-
For details about enabling the
PopLinkWittnessfeature, see Section 13.7.7, “Enabling thePopLinkWittnessV2feature”. -
For details about enabling
CMCRevokefor the web user interface, see Section 13.7.9, “Enabling CMCRevoke for the Web User Interface”.
7.5.14. TLS client-authentication for the Java console
To require Certificate System administrators to present a user TLS client certificate when logging into the Java console, see Section 13.2.3.14, “Setting requirement for pkiconsole to use TLS client certificate authentication”.
pkiconsole is being deprecated.
7.5.15. Creating a role user
Create real role users so that you can remove the bootstrap user.
To create users and assign them to different privileged roles to manage Certificate System, see Chapter 18, Creating a role user.
7.5.16. Removing the bootstrap user
Once the real role users are created, the bootstrap user that was created automatically during the installation is not needed anymore. To delete this account, see Chapter 19, Deleting the Bootstrap User after making sure you created a new administrator account assigned to an individual person.
7.5.17. Disabling multi-role support
To disable the multi-role support once the bootstrap user is removed, see Section 19.1, “Disabling multi-roles support”.
7.5.18. KRA configurations
7.5.18.1. Adding requirement for multiple agent approval for Key Recovery Authority (KRA)
To set up a requirement for multiple KRA agents to approve key recovery, see the Configuring agent-approved key recovery in the command line section in the Red Hat Certificate System Administration Guide.
7.5.18.2. Configuring KRA encryption settings
To configure key encryption/wrapping algorithms, see Section 16.2, “Encryption of KRA operations”.
7.5.19. Setting up users to use user interfaces
Before a user could use an approved user interface, initialization needs to be performed. Users (administrative roles or otherwise) are required to setup their clients for accessing the user interface. See the Client NSS database initialization section in the Red Hat Certificate System Administration Guide.
7.5.20. Enabling signed audit logging
By default, audit logging is enabled upon installation. However, log signing needs to be enabled manually after installation.
To display the current audit logging configuration:
To enable signed audit logging:
Use the
pki-serverutility to set the --logSigning option totrue:pki-server subsystem-audit-config-mod --logSigning True
# pki-server subsystem-audit-config-mod --logSigning True ... Log Signing: True ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the instance:
systemctl restart pki-tomcatd@instance_name.service
# systemctl restart pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.21. Update the ciphers list
Red Hat Certificate System allows to set restrictions on acceptable ciphers when acting as a server or as a client. These cipher controls are configured at different locations.
An RHCS instance is acting as a server when it is accepting requests from another entity. For example:
- When a RHCS cli talks to a CA for certificate enrollment (in this case, the CA is the server)
- When a RHCS administrator uses the pkiconsole to talk to a CA (in this case, the CA is the server)
- When a CA talks to a KRA for key archival (in this case, the KRA is the server, and the CA is the client)
An RHCS instance is acting as a client when it attempts to reach out to another server. For example:
- When a CA talks to a KRA for key archival (in this case, the CA is the client while the KRA is the server)
- When a CA talks to its internal LDAP database (in this case, the CA is the client while Directory Server is the server)
The following sections provide instructions on how to configure the ciphers for these different scenarios.
7.5.21.1. Configuring the ciphers for a CS instance acting as a server
The desired set of ciphers for a given instance is defined by the SSLHostConfig element in the <CS instance directory>/conf/server.xml file.
Follow the instructions below to configure each CS instance.
Back up the original server.xml file before editing, for example to server.xml.orig.
-
Edit the
server.xmlfile, navigate to the main SSL port’s Connector declaration and find the SSLHostConfig element. Modify the SSLHostConfig element with the following configuration:
<SSLHostConfig sslProtocol="TLS" protocols="TLSv1.2" certificateVerification="optional" ciphers="ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384">
<SSLHostConfig sslProtocol="TLS" protocols="TLSv1.2" certificateVerification="optional" ciphers="ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384">Copy to Clipboard Copied! Toggle word wrap Toggle overflow
The above cipher list represents the set of ciphers claimed in this RHCS release in OpenSSL format, where:
-
ciphers=" … ": establishes the restricted ciphers desired (for example TLS). In this format, cipher names are separated by a colon. -
protocols=" … ": establishes which TLS version you want (for example, 1.2).
7.5.21.2. Configuring the ciphers for a CS instance acting as a client
When a CS instance acts as a client, add the desired list of ciphers in the instance’s CS.cfg configuration file. Configure all the client instances as relevant based on their roles.
Back up the original CS.cfg file before editing, for example to CS.cfg.orig.
When a CS instance is acting as a client to its internal LDAP database.
Add the following line to the
<instance directory>/<instance type>/conf/CS.cfgfile:tcp.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
tcp.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteTo ensure that the internal LDAP database has the desired ciphers enabled, please follow Configuring the ciphers for a DS instance.
When a CA instance is acting as a client to the KRA.
Add the following line to the
<instance directory>/ca/conf/CS.cfgfile:ca.connector.KRA.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ca.connector.KRA.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384Copy to Clipboard Copied! Toggle word wrap Toggle overflow When a TPS instance is acting as a client to the CA, KRA, or TKS.
Add the following line to the
<instance directory>/tps/conf/CS.cfgfile:tps.connector.<ca|kra|tks id>.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
tps.connector.<ca|kra|tks id>.clientCiphers=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384Copy to Clipboard Copied! Toggle word wrap Toggle overflow
You must restart each server instance for the modifications to take effect, for example:
pki-server restart rhcs10-RSA-RootCA pki-server restart rhcs10-RSA-SubCA pki-server restart rhcs10-RSA-OCSP-rootca pki-server restart rhcs10-RSA-OCSP-subca pki-server restart rhcs10-RSA-KRA
# pki-server restart rhcs10-RSA-RootCA
# pki-server restart rhcs10-RSA-SubCA
# pki-server restart rhcs10-RSA-OCSP-rootca
# pki-server restart rhcs10-RSA-OCSP-subca
# pki-server restart rhcs10-RSA-KRAOR if using the Nuxwdog watchdog:
systemctl restart rhcs10-RSA-RootCA systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-SubCA.service systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-OCSP-rootca.service systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-OCSP-subca.service systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-KRA.service
# systemctl restart rhcs10-RSA-RootCA
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-SubCA.service
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-OCSP-rootca.service
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-OCSP-subca.service
# systemctl restart pki-tomcatd-nuxwdog@rhcs10-RSA-KRA.service7.5.21.3. Configuring the ciphers for a DS instance
By default, a Directory Server instance inherits the ciphers enabled on the OS. If you wish to set it so that the cipher list matches that of the Certificate System, proceed with the following steps for each DS instance:
On the DS host dir.example.com:
Enable the intended ciphers (use the non-SSL port of the DS instance):
dsconf -D "cn=Directory Manager" ldap://dir.example.com:7389 security ciphers set "+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
# dsconf -D "cn=Directory Manager" ldap://dir.example.com:7389 security ciphers set "+TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,+TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,+TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,+TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the DS instance:
dsctl slapd-CC-RSA-SubCA-LDAP stop
# dsctl slapd-CC-RSA-SubCA-LDAP stopCopy to Clipboard Copied! Toggle word wrap Toggle overflow dsctl slapd-CC-RSA-SubCA-LDAP start
# dsctl slapd-CC-RSA-SubCA-LDAP startCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify by listing the enabled ciphers:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.22. Enabling OAEP support for KRA, TKS, AND TPS
The Optimal Asymmetric Encryption Padding (OAEP) key wrapping algorithm is now supported in RHCS in favor of the older PKCS#1 algorithm. Newer HSM devices and later FIPS-enabled versions of NSS often require this algorithm for use. This operation mainly comes into play when there is an ultimate interaction with the KRA. The KRA’s transport certificate is used to perform a public key wrap of some other key, such as an AES symmetric key. When OAEP is utilized, OAEP must be used on both ends of the wrapping and unwrapping sequence, with the wrapping taking part on perhaps a client and the unwrapping taking place on a server such as the RHCS KRA or other subsystems.
There are two scenarios where OAEP is most often used:
- Within our RHCS subsystems such as the KRA, TPS, and TKS.
- Use through various command line tools that interact with one of the RHCS subsystems.
The client to server interaction requires that both ends use OAEP wrapping or not at all. For instance, if the KRA is configured for OAEP, command line tools that interact with the KRA must use OAEP when using the transport certificate to wrap keys.
Due to the fact that our JSS crypto bindings component has supported OAEP for some time, it is now a simple matter to configure clients or servers to make use of OAEP. The choice for Certificate System subsystems is binary in nature, meaning we must chose to do everything in OAEP (when called for) or do nothing in OAEP in similar scenarios. Once the user of client programs knows if the server is configured for OAEP or not, a decision on how to operate the client in question can be made based on command line parameters utilized or not utilized if defaults exist.
This section deals with the configuration of subsystems for OAEP. This configuration of the subsystems is performed after pkispawn has successfully created the RHCS subsystem instance.
Limited support for Thales Luna: Red Hat is not able to confirm that the Thales HSM unit supports AES key wrapping/unwrapping via OAEP. Be aware that those features requiring support of this algorithm will not function without such support. These features include: KRA: key archival and recovery CMC SharedToken authentication mechanism for enrollments TKS → TPS shared secret automatic transport during installation
Note: For examples of using the command line interface with OAEP, refer to the administration guide.
7.5.22.1. KRA
The KRA is one of the main Certificate System subsystems to make use of OAEP. This is due to the fact that the KRA transport certificate is often used by client programs to wrap keys which are subsequently unwrapped by the KRA itself.
This section contains settings other than OAEP to appease HSM devices that supports the AES key wrapping/unwrapping operations, such as an Entrust nShield Connect XC unit with firmware v12.72.1.
Perform the following (as root) on the host containing the subsystem:
Stop the kra
pki-server stop <subsystem instance name>
pki-server stop <subsystem instance name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
/var/lib/pki/<subsystem instance name>/CS.cfgconfiguration file and add the following three lines:keyWrap.useOAEP=true kra.legacyPKCS12=false kra.nonLegacyAlg=AES/None/PKCS5Padding/Kwp/256
keyWrap.useOAEP=true kra.legacyPKCS12=false kra.nonLegacyAlg=AES/None/PKCS5Padding/Kwp/256Copy to Clipboard Copied! Toggle word wrap Toggle overflow The first line above relates to OAEP while the final two settings are complimentary settings that allow for proper KRA operation under the OAEP scenario. The AES based “KWP” algorithm is used in the situation above.
Start the KRA:
pki-server start <subsystem instance name>
pki-server start <subsystem instance name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.22.2. TKS
Perform the following (as root) on the host containing the subsystem:
Stop the TKS
pki-server stop <subsystem instance name>
pki-server stop <subsystem instance name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
/var/lib/pki/<subsystem instance name>/CS.cfgconfiguration file and add the following entry:keyWrap.useOAEP=true
keyWrap.useOAEP=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the TKS:
pki-server start <subsystem instance name>
pki-server start <subsystem instance name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
7.5.22.3. TPS
The TPS and TKS work together when using the Token Management System. OAEP needs to be enabled on both subsystems for normal operation. The normal sequence of installation of TKS and TPS has TKS installed first, followed by TPS. The following instructions apply when it is known that the TKS has been configured for OAEP.
Perform the following (as root) on the host containing the subsystem:
Stop the TKS
pki-server stop <subsystem instance name>
pki-server stop <subsystem instance name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the /var/lib/pki/<subsystem instance name>/CS.cfg configuration file and add the following entry:
keyWrap.useOAEP=true
keyWrap.useOAEP=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the TKS:
pki-server start <subsystem instance name>
pki-server start <subsystem instance name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 8. Using hardware security modules with subsystems
A subsystem instance generates and stores its key information in a key store, called a security module or a token. A subsystem instance can be configured for the keys to be generated and stored using the internal NSS token or on a separate cryptographic device, a hardware token.
8.1. Adding or managing the HSM entry for a subsystem
During installation, when an HSM is selected as the default token where appropriate HSM-specific parameters are set in the configuration file passed to the 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
hardware-HSM_token_name=HSM_token_password8.2. Installing a subsystem using an HSM
To install a Certificate System instance using an HSM, follow the procedure in Preparing for installing Certificate System with an HSM to prepare a pkispawn file for installation of a Certificate System instance using one of the supported HSMs.
You can find full installation examples using an HSM, such as the following, in Installing the CA subsystem:
8.3. Viewing Tokens
To view a list of the tokens currently installed for a Certificate System instance, use the modutil utility.
Change to the instance
aliasdirectory. For example:cd /var/lib/pki/pki-tomcat/alias
# cd /var/lib/pki/pki-tomcat/aliasCopy to Clipboard Copied! Toggle word wrap Toggle overflow Show the information about the installed PKCS #11 modules installed as well as information on the corresponding tokens using the
modutiltool.modutil -dbdir . -nocertdb -list
# modutil -dbdir . -nocertdb -listCopy to Clipboard Copied! Toggle word wrap Toggle overflow
8.4. Detecting Tokens
To see if a token can be detected by Certificate System, use the 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.
For example:
TokenInfo /var/lib/pki/pki-tomcat/alias
# TokenInfo /var/lib/pki/pki-tomcat/aliasThis utility returns all tokens which can be detected by the Certificate System, not only tokens which are installed in the Certificate System.
8.5. Failover and resilience
Failover means setting up multiple units, and configuring them so that if one unit fails, another one will take over and continue the service without interruption.
Resilience ensures that when the network connection to a unit is interrupted and then reconnected, the service is not interrupted within a reasonable timeframe.
Some Hardware Security Module (HSM) models offer failover or resilience of varying degrees. For detail on the exact make and models and the features that they offer, consult your HSM manual, or contact the manufacturer. The HSMs described in the following sections have been tested with Red Hat Certificate System.
8.5.1. nCipher nShield HSM
The failover and resilience tests were conducted on the older Entrust HSMS model, nShield Connect 6000, however, according to the Entrust website, failover and resilience are also supported in the newer model of nShield Connect HSMs, such as the XC. They are expected to work in a similar manner.
Failover
With nShield Connect 6000, failover has been tested in the scenario where there are two HSM modules, nShield1, and nShield2, both running and configured for failover.
If one of nShield units goes down, the other exhibits ability to continue the provision of cryptographic services to Certificate System with no known issues, without restarting of the RHCS instance.
When the above situation happens (one HSM unit goes down), the administrator is expected to schedule a downtime for all the connected Certificate System instances and fix the down hsm unit and bring it back up and restart the instances. This means that if one unit goes down, Certificate System is expected to continue functioning; however, if the down hsm is brought back up without restarting the instances, the newly brought up HSM unit is not expected to be part of the failover scheme as originally planned.
Resilience
With nShield Connect 6000, testing has shown that when the network cable is pulled off the HSM unit, and replugged in within up to 90 minutes, the service continues. There is no data for any time period longer than 90 minutes.
8.5.2. Gemalto Safenet LunaSA HSM
Failover
The Gemalto Safenet LunaSA Cloning model offers Failover. However, we have no data on this model.
8.6. Backing up keys on Hardware Security modules
It is not possible to export keys and certificates stored on an HSM to a .p12 file. If such an instance is to be backed-up, contact the manufacturer of your HSM for support.
Chapter 9. Cloning subsystems
When a new subsystem instance is first configured, the Red Hat Certificate System allows subsystems to be cloned, or duplicated, for high availability of the Certificate System. The cloned instances run on different machines to avoid a single point of failure and their databases are synchronized through replication.
The master CA and its clones are functionally identical, they only differ in serial number assignments and CRL generation. Therefore, this chapter refers to master or any of its clones as replicated CAs.
9.1. Backing up subsystem keys from a software database
Ideally, the keys for the master instance are backed up when the instance is first created. If the keys were not backed up then or if the backup file is lost, then it is possible to extract the keys from the internal software database for the subsystem instance using the PKCS12Export utility. For example:
PKCS12Export -debug -d /var/lib/pki/ instance_name/alias -w p12pwd.txt -p internal.txt -o master.p12
PKCS12Export -debug -d /var/lib/pki/ instance_name/alias -w p12pwd.txt -p internal.txt -o master.p12Then copy the PKCS #12 file to the clone machine to be used in the clone instance configuration. For more details, see Section 2.7.6, “Cloning and key stores”.
Keys cannot be exported from an HSM. However, in a typical deployment, HSMs support networked access, as long as the clone instance is installed using the same HSM as the master. If both instances use the same key store, then the keys are naturally available to the clone.
If backing up keys from the HSM is required, contact the HSM manufacturer for assistance.
9.2. Cloning a CA
- Configure the master CA, and back up the keys.
In the
CS.cfgfile for the master CA, enable the master CA to monitor replication database changes by adding theca.listenToCloneModificationsparameter:ca.listenToCloneModifications=true
ca.listenToCloneModifications=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create the clone subsystem instance.
For examples of the configuration file required by
pkispawnwhen cloning CA subsystems, see theInstalling a CA cloneandInstalling a CA clone on the same hostsections of thepkispawn(8)man page.Restart the Directory Server instance used by the clone.
systemctl restart pki-tomcatd@kra-clone-ds-instance.service
# systemctl restart pki-tomcatd@kra-clone-ds-instance.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteRestarting the Directory Server reloads the updated schema, which is required for proper performance.
Restart the clone instance.
pki-server restart instance_name
# pki-server restart instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
After configuring the clone, test to make sure that the master-clone relationship is functioning:
- Request a certificate from the cloned CA.
- Approve the request.
- Download the certificate to the browser.
- Revoke the certificate.
Check master CA’s CRL for the revoked certificate. In the master Certificate Manager’s agent services page, click Update Certificate Revocation List. Find the CRL in the list.
The CRL should show the certificate revoked by the cloned Certificate Manager. If that certificate is not listed, check logs to resolve the problem.
9.3. Updating CA-KRA connector information after cloning
As covered in Section 2.7.9, “Custom configuration and clones”, configuration information is not updated in clone instances if it is made after the clone is created. Likewise, changes made to a clone are not copied back to the master instance.
If a new KRA is installed or cloned after a clone CA is created, then the clone CA does not have the new KRA connector information in its configuration. This means that the clone CA is not able to send any archival requests to the KRA.
Whenever a new KRA is created or cloned, copy its connector information into all of the cloned CAs in the deployment. To do this, use the pki ca-kraconnector-add command.
If it is required to do this manually, follow these steps:
On the master clone machine, open the master CA’s
CS.cfgfile, and copy all of theca.connector.KRA.*lines for the new KRA connector.vim /var/lib/pki/ instance_name/ca/conf/CS.cfg
[root@master ~]# vim /var/lib/pki/ instance_name/ca/conf/CS.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the clone CA instance. For example:
pki-server stop instance_name
[root@clone-ca ~]# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the clone CA’s
CS.cfgfile.vim /var/lib/pki/ instance_name/ca/conf/CS.cfg
[root@clone-ca ~]# vim /var/lib/pki/ instance_name/ca/conf/CS.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy in the connector information for the new KRA instance or clone.
ca.connector.KRA.enable=true ca.connector.KRA.host=server-kra.example.com ca.connector.KRA.local=false ca.connector.KRA.nickName=subsystemCert cert-pki-ca ca.connector.KRA.port=10444 ca.connector.KRA.timeout=30 ca.connector.KRA.transportCert=MIIDbD...ZR0Y2zA== ca.connector.KRA.uri=/kra/agent/kra/connector
ca.connector.KRA.enable=true ca.connector.KRA.host=server-kra.example.com ca.connector.KRA.local=false ca.connector.KRA.nickName=subsystemCert cert-pki-ca ca.connector.KRA.port=10444 ca.connector.KRA.timeout=30 ca.connector.KRA.transportCert=MIIDbD...ZR0Y2zA== ca.connector.KRA.uri=/kra/agent/kra/connectorCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the clone CA.
pki-server start instance_name
[root@clone-ca ~]# pki-server start instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
9.4. Cloning subsystems
9.4.1. Cloning OCSP subsystems
- Configure the master OCSP, and back up the keys.
In the
CS.cfgfile for the master OCSP, set theOCSP.Responder.store.defStore.refreshInSecparameter to any non-zero number other than 21600; 21600 is the setting for a clone.vim /etc/ instance_name/CS.cfg
# vim /etc/ instance_name/CS.cfg OCSP.Responder.store.defStore.refreshInSec=15000Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create the clone subsystem instance using the
pkispawnutility.For examples of the configuration file required by
pkispawnwhen cloning OCSP subsystems, see thepkispawn(8)man page.Restart the Directory Server instance used by the clone.
systemctl dirsrv@instance_name.service
# systemctl dirsrv@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteRestarting the Directory Server reloads the updated schema, which is required for proper performance.
Restart the clone instance.
pki-server restart instance_name
# pki-server restart instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
After configuring the clone, test to make sure that the master-clone relationship is functioning:
- Set up OCSP publishing in the master CA so that the CRL is published to the master OCSP.
- Once the CRL is successfully published, check both the master and cloned OCSP’s List Certificate Authorities link in the agent pages. The list should be identical.
-
Use the
OCSPClienttool to submit OCSP requests to the master and the cloned Online Certificate Status Manager. The tool should receive identical OCSP responses from both managers.
9.4.2. Cloning KRA subsystems
- Configure the master subsystem, and back up the keys.
Create the clone subsystem instance using the
pkispawnutility.For examples of the configuration file required by
pkispawnwhen cloning KRA subsystems, see theInstalling a KRA or TPS clonesection of thepkispawn(8)man page.Restart the Directory Server instance used by the clone.
systemctl dirsrv@instance_name.service
# systemctl dirsrv@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteRestarting the Directory Server reloads the updated schema, which is required for proper performance.
Restart the clone instance.
pki-server restart instance_name
# pki-server restart instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
For the KRA clone, test to make sure that the master-clone relationship is functioning:
- Go to the KRA agent’s page.
- Click List Requests.
- Select Show all requests for the request type and status.
- Click .
- Compare the results from the cloned KRA and the master KRA. The results ought to be identical.
9.4.3. Cloning TKS subsystems
- Configure the master subsystem, and back up the keys.
Create the clone subsystem instance using the
pkispawnutility.For examples of the configuration file required by
pkispawnwhen cloning TKS subsystems, see theInstalling a KRA or TKS clonesection of thepkispawn(8)man page.Restart the clone instance.
pki-server restart instance_name
# pki-server restart instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
For the TKS, enroll a smart card and then run an ldapsearch to make sure that the same key information is contained in both databases.
9.5. Converting masters and clones
Only one single active CA generating CRLs can exist within the same topology. Similarly, only one OCSP receiving CRLs can exist within the same topology. As such, there can be any number of clones, but there can only be a single configured master for CA and OCSP.
For KRAs and TKSs, there is no configuration difference between masters and clones, but CAs and OCSPs do have some configuration differences. This means that when a master is taken offline -because of a failure or for maintenance or to change the function of the subsystem in the PKI -then the existing master must be reconfigured to be a clone, and one of the clones promoted to be the master.
9.5.1. Converting CA clones and masters
- Stop the master CA if it is still running.
Open the existing master CA configuration directory:
cd /var/lib/pki/ instance_name/ca/conf
# cd /var/lib/pki/ instance_name/ca/confCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
CS.cfgfile for the master, and change the CRL and maintenance thread settings so that it is set as a clone:Disable control of the database maintenance thread:
ca.certStatusUpdateInterval=0
ca.certStatusUpdateInterval=0Copy to Clipboard Copied! Toggle word wrap Toggle overflow Disable monitoring database replication changes:
ca.listenToCloneModifications=false
ca.listenToCloneModifications=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Disable maintenance of the CRL cache:
ca.crl.IssuingPointId.enableCRLCache=false
ca.crl.IssuingPointId.enableCRLCache=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Disable CRL generation:
ca.crl.IssuingPointId.enableCRLUpdates=false
ca.crl.IssuingPointId.enableCRLUpdates=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set the CA to redirect CRL requests to the new master:
master.ca.agent.host=new_master_hostname master.ca.agent.port=new_master_port
master.ca.agent.host=new_master_hostname master.ca.agent.port=new_master_portCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Stop the cloned CA server.
pki-server stop instance_name
# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the cloned CA’s configuration directory.
cd /etc/instance_name
# cd /etc/instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
CS.cfgfile to configure the clone as the new master.-
Delete each line which begins with the
ca.crl.prefix. -
Copy each line beginning with the
ca.crl.prefix from the former master CACS.cfgfile into the cloned CA’sCS.cfgfile. Enable control of the database maintenance thread; the default value for a master CA is
600.ca.certStatusUpdateInterval=600
ca.certStatusUpdateInterval=600Copy to Clipboard Copied! Toggle word wrap Toggle overflow Enable monitoring database replication:
ca.listenToCloneModifications=true
ca.listenToCloneModifications=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Enable maintenance of the CRL cache:
ca.crl.IssuingPointId.enableCRLCache=true
ca.crl.IssuingPointId.enableCRLCache=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Enable CRL generation:
ca.crl.IssuingPointId.enableCRLUpdates=true
ca.crl.IssuingPointId.enableCRLUpdates=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Disable the redirect settings for CRL generation requests:
master.ca.agent.host=hostname master.ca.agent.port=port number
master.ca.agent.host=hostname master.ca.agent.port=port numberCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
Delete each line which begins with the
Start the new master CA server.
pki-server start instance_name
# pki-server start instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
9.5.2. Converting OCSP clones
- Stop the OCSP master, if it is still running.
Open the existing master OCSP configuration directory.
cd /etc/instance_name
# cd /etc/instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
CS.cfg, and reset theOCSP.Responder.store.defStore.refreshInSecparameter to21600:OCSP.Responder.store.defStore.refreshInSec=21600
OCSP.Responder.store.defStore.refreshInSec=21600Copy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the online cloned OCSP server.
pki-server stop instance_name
# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the cloned OCSP responder’s configuration directory.
cd /etc/instance_name
# cd /etc/instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the
CS.cfgfile, and delete theOCSP.Responder.store.defStore.refreshInSecparameter or change its value to any non-zero number:OCSP.Responder.store.defStore.refreshInSec=15000
OCSP.Responder.store.defStore.refreshInSec=15000Copy to Clipboard Copied! Toggle word wrap Toggle overflow Start the new master OCSP responder server.
pki-server start instance_name
# pki-server start instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
9.6. Cloning a CA that has been re-keyed
When a certificate expires, it has to be replaced. This can either be done by renewing the certificate, which re-uses the original keypair to generate a new certificate, or it can be done by generating a new keypair and certificate. The second method is called re-keying.
When a CA is re-keyed, new keypairs are stored in its certificate database, and these are the keys references for normal operations. However, for cloning a subsystem, the cloning process checks for the CA private key IDs as stored in its CS.cfg configuration file - and those key IDs are not updated when the certificate database keys change.
If a CA has been re-keyed and then an administrator attempts to clone it, the cloned CA fails to generate any certificates for the certificates which were re-keyed, and it shows up in the error logs with this error:
CertUtil::createSelfSignedCert() - CA private key is null!
CertUtil::createSelfSignedCert() - CA private key is null!To clone a CA that has been re-keyed:
Find all of the private key IDs in the
CS.cfgfile.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Print all of the current private key IDs stored in the NSS database and compare them to the private key IDs stored in the
CS.cfgfile:Copy to Clipboard Copied! Toggle word wrap Toggle overflow In this example, only the audit signing key is the same; the others have been changed.
Take the keys returned in the previous step and convert them from unsigned values (which is what
certutilreturns) to signed Java BigIntegers (which is how the keys are stored in the Certificate System database).This can be done with a calculator or by using the script in Example 9.1, “Certutil to BigInteger conversion program”.
Copy the new key values into the
CS.cfgfile.Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Clone the CA as described in Section 9.2, “Cloning a CA”.
Example 9.1. Certutil to BigInteger conversion program
This Java program can convert the key output from certutil to the required BigInteger format.
Save this as a .java file, such as Test.java.
Then, compile the file:
javac Test.java
# javac Test.javaChapter 10. Setting up PKI ACME responder
This chapter describes the installation and initial configuration on an ACME responder on a PKI server that already has a CA subsystem.
The following assumes you installed the CA with the default instance name (i.e. pki-tomcat).
For information on how to manage PKI ACME Responder, see the Managing PKI ACME Responder chapter in the Red Hat Certificate System Administration Guide.
10.1. Installing PKI ACME Responder
To install PKI ACME Responder on your PKI server,
First download and install the
pki-acmeRPM package:dnf install pki-acme
$ dnf install pki-acmeCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create an ACME responder in a PKI server instance using the following command:
pki-server acme-create
$ pki-server acme-createCopy to Clipboard Copied! Toggle word wrap Toggle overflow
This creates the initial configuration files in the /etc/pki/pki-tomcat/acme directory.
For more information, see the pki-server-acme manpage.
10.2. Configuring an ACME database
This section describes how to configure a database for the ACME responder. The database configuration is located at /etc/pki/pki-tomcat/acme/database.conf.
You can configure the database via command-line using the
pki-server acme-database-modcommand. Invoking this command without any parameters launches an interactive mode, for example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Invoking the command with the
--typeparameter creates a new configuration based on the specified type. - Invoking the command with other parameters updates the specified parameters.
Certain ACME configuration properties are stored in the database, enabling you to configure all ACME responders in the cluster consistently. By default, the ACME responder directly accesses the database when retrieving or updating the ACME configuration properties, which may increase the load on the database. Some databases might provide an ACME configuration monitor to reduce this load.
10.2.1. Configuring a DS database
You can configure the ACME responder to use a DS database. A sample DS database configuration is available at /usr/share/pki/acme/database/ds/database.conf.
To configure a DS database:
First add the ACME DS schema by importing the
/usr/share/pki/acme/database/ds/schema.ldiffile with the following command:ldapmodify -h $HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 \ -f /usr/share/pki/acme/database/ds/schema.ldif$ ldapmodify -h $HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 \ -f /usr/share/pki/acme/database/ds/schema.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Next, prepare an LDIF file to create the ACME subtree. A sample LDIF file is available at
usr/share/pki/acme/database/ds/create.ldif. This example usesdc=acme,dc=pki,dc=example,dc=comas the base DN. Import the LDIF file using the
ldapaddcommand:ldapadd -h $HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 \ -f /usr/share/pki/acme/database/ds/create.ldif$ ldapadd -h $HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 \ -f /usr/share/pki/acme/database/ds/create.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy the sample database configuration file from
/usr/share/pki/acme/database/ds/database.confinto the/etc/pki/pki-tomcat/acmedirectory, or execute the following command to customize some of the parameters:pki-server acme-database-mod --type ds \ -DbindPassword=Secret.123$ pki-server acme-database-mod --type ds \ -DbindPassword=Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Customize the configuration as needed:
In a standalone ACME deployment, the
database.confshould look like the following:Copy to Clipboard Copied! Toggle word wrap Toggle overflow In a shared CA and ACME deployment, the database.conf should look like the following:
class=org.example.acme.database.DSDatabase configFile=conf/ca/CS.cfg baseDN=dc=acme,dc=pki,dc=example,dc=comclass=org.example.acme.database.DSDatabase configFile=conf/ca/CS.cfg baseDN=dc=acme,dc=pki,dc=example,dc=comCopy to Clipboard Copied! Toggle word wrap Toggle overflow
The DS database provides an ACME configuration monitor using search persistence. You can enable it by enabling setting the following parameter: monitor.enabled=true
10.3. Configuring ACME Issuer
This section describes how to configure an issuer for PKI ACME Responder. The configuration for ACME Issuer is located at /etc/pki/pki-tomcat/acme/issuer.conf.
You can configure the issuer via command-line using the pki-server acme-issuer-mod command.
Invoking this command without any parameters launches an interactive mode, for example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Invoking the command with the
--typeparameter creates a new configuration based on the specified type. - Invoking the command with other parameters updates the specified parameters.
10.3.1. Configuring PKI Issuer
You can configure PKI ACME Responder to issue certificates using PKI Issuer. A sample configuration is available at /usr/share/pki/acme/issuer/pki/issuer.conf.
To configure a PKI issuer, copy this sample
issuer.confinto the/etc/pki/pki-tomcat/acmedirectory or execute the following command to customize some of the parameters:pki-server acme-issuer-mod --type pki \ -Dusername=caadmin \ -Dpassword=Secret.123$ pki-server acme-issuer-mod --type pki \ -Dusername=caadmin \ -Dpassword=Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Customize the configuration as needed. The
issuer.conffile should look like the following:class=org.example.acme.issuer.PKIIssuer url=https://localhost.localdomain:8443 profile=acmeServerCert username=caadmin password=Secret.123
class=org.example.acme.issuer.PKIIssuer url=https://localhost.localdomain:8443 profile=acmeServerCert username=caadmin password=Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow - The url parameter specifies the PKI issuer location.
- The profile parameter specifies the certificate profile to use.
- To use client certificate authentication, specify the client certificate nickname in the nickname parameter.
- To use basic authentication, specify the username in the username parameter as well as the password in the password parameter.
10.4. Configuring ACME Realm
This section describes how to configure a realm for PKI ACME responder. The realm configuration is located at /etc/pki/pki-tomcat/acme/realm.conf.
You can configure ACME Realm via command line using the pki-server acme-realm-mod command.
Invoking this command without any parameters launches an interactive mode, for example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Invoking the command with the
--typeparameter creates a new configuration based on the specified type. - Invoking the command with other parameters updates the specified parameters.
10.4.1. Configuring DS Realm
You can configure PKI ACME Responder to use a Directory Server realm. A sample configuration for DS Realm is available at /usr/share/pki/acme/realm/ds/realm.conf.
To configure a Directory Server realm:
-
Prepare subtrees for ACME users and groups in DS. A sample LDIF file is available at
/usr/share/pki/acme/realm/ds/create.ldif]. This example usesdc=acme,dc=pki,dc=example,dc=comas the base DN. Import the LDIF file using the
ldapaddcommand:ldapadd -h $HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 \ -f /usr/share/pki/acme/realm/ds/create.ldif$ ldapadd -h $HOSTNAME -x -D "cn=Directory Manager" -w Secret.123 \ -f /usr/share/pki/acme/realm/ds/create.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy the sample configuration file from
/usr/share/pki/acme/realm/ds/realm.confinto the/etc/pki/pki-tomcat/acmedirectory, or run the following command to customize some of the parameters:pki-server acme-realm-mod --type ds \ -DbindPassword=Secret.123$ pki-server acme-realm-mod --type ds \ -DbindPassword=Secret.123Copy to Clipboard Copied! Toggle word wrap Toggle overflow Customize the configuration as needed:
In a standalone ACME deployment, the
realm.conffile should look like the following:Copy to Clipboard Copied! Toggle word wrap Toggle overflow In a shared CA and ACME deployment, the
realm.conffile should look like the following:class=org.example.acme.realm.DSRealm configFile=conf/ca/CS.cfg usersDN=ou=people,dc=ca,dc=pki,dc=example,dc=com groupsDN=ou=groups,dc=ca,dc=pki,dc=example,dc=com
class=org.example.acme.realm.DSRealm configFile=conf/ca/CS.cfg usersDN=ou=people,dc=ca,dc=pki,dc=example,dc=com groupsDN=ou=groups,dc=ca,dc=pki,dc=example,dc=comCopy to Clipboard Copied! Toggle word wrap Toggle overflow
10.5. Deploying ACME Responder
Once you have configured the ACME responder, deploy it using the following command:
pki-server acme-deploy
$ pki-server acme-deployCopy to Clipboard Copied! Toggle word wrap Toggle overflow This creates a deployment descriptor at
/etc/pki/pki-tomcat/Catalina/localhost/acme.xml.The PKI server starts ACME Responder automatically after a few seconds, you do not need to restart the server.
To verify that ACME Responder is running, use the following command:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
For more information, see the pki-server-acme manpage.
Chapter 11. Additional installation options
All Red Hat Certificate System instances created with pkispawn make certain assumptions about the instances being installed, such as the default signing algorithm to use for CA signing certificates and whether to allow IPv6 addresses for hosts.
This chapter describes additional configuration options that impact the installation and configuration for new instances, so many of these procedures occur before the instance is created.
11.1. Lightweight sub-CAs
Using the default settings, you are able to create lightweight sub-CAs. They enable you to configure services, like virtual private network (VPN) gateways, to accept only certificates issued by one sub-CA. At the same time, you can configure other services to accept only certificates issued by a different sub-CA or the root CA.
If you revoke the intermediate certificate of a sub-CA, all certificates issued by this sub-CA are automatically invalid.
If you set up the CA subsystem in Certificate System, it is automatically the root CA. All sub-CAs you create, are subordinated to this root CA.
11.1.1. Setting up a lightweight sub-CA
Depending on your environment, the installation of a sub-CA differs between Internal CAs and External CAs. For more information, see example in Installing CA with external CA signing certificate.
11.1.2. Disabling the creation of lightweight sub-CAs
In certain situations, administrators want to disable lightweight sub-CAs. To prevent adding, modifying, or removing sub-CAs, enter the following command on the Directory Server instance used by Certificate System:
This command removes the default Access Control List (ACL) entries, which grant the permissions to manage sub-CAs.
If any ACLs related to lightweight sub-CA creation have been modified or added, remove the relevant values.
11.1.3. Re-enabling the creation of lightweight sub-CAs
If you previously disabled the creation of lightweight sub-CAs, you can re-enable the feature by entering the following command on the Directory Server instance used by Certificate System:
This command adds the Access Control List (ACL) entries, which grant the permissions to manage sub-CAs.
11.2. Enabling IPv6 for a subsystem
Certificate System automatically configures and manages connections between subsystems. Every subsystem must interact with a CA as members of a security domain and to perform their PKI operations.
For these connections, Certificate System subsystems can be recognized by their host’s fully-qualified domain name or an IP address. By default, Certificate System resolves IPv4 addresses and host names automatically, but Certificate System can also use IPv6 for their connections. IPv6 is supported for all server connections: to other subsystems, to the administrative console (pkiconsole), or through command-line scripts such as tpsclient:
op=var_set name=ca_host value=IPv6 address
op=var_set name=ca_host value=IPv6 address- Install the Red Hat Certificate System packages.
Set the IPv4 and IPv6 addresses in the
/etc/hostsfile. For example:vim /etc/hosts
# vim /etc/hosts 192.0.0.0 server.example.com IPv4 address 3ffe:1234:2222:2000:202:55ff:fe67:f527 server6.example.com IPv6 addressCopy to Clipboard Copied! Toggle word wrap Toggle overflow Then, export the environment variable to use the IPv6 address for the server. For example:
export PKI_HOSTNAME=server6.example.com
export PKI_HOSTNAME=server6.example.comCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Run
pkispawnto create the new instance. The values for the server host name in theCS.cfgfile will be set to the IPv6 address.
11.3. Enabling LDAP-based enrollment profiles
-
To install with LDAP-based profiles, set the pki_profile_in_ldap=True option in the
[CA]section of thepkispawnconfiguration file.
In this case, profile files will still appear in /var/lib/pki/ instance_name/ca/profiles/ca/, but will be ignored.
To enable LDAP-based profiles on an existing instance, change the following in the instance’s
CS.cfg:subsystem.1.class=com.netscape.cmscore.profile.LDAPProfileSubsystem
subsystem.1.class=com.netscape.cmscore.profile.LDAPProfileSubsystemCopy to Clipboard Copied! Toggle word wrap Toggle overflow Then, import profiles manually into the database using either the
pkicommand line utility or a custom script.
Chapter 12. Troubleshooting installation and cloning
This chapter covers some of the more common installation and migration issues that are encountered when installing Certificate System.
12.1. Installation
- Q: I cannot see any Certificate System packages or updates.
- Q: The init script returned an OK status, but my CA instance does not respond. Why?
- Q: I want to customize the subject name for the CA signing certificate, but do not see a way to do this using the pkispawn interactive install mode.
- Q: I want to set different certificate validity periods and extensions for my root certificate authority -but I do not see a way to set it using pkispawn.
- Q: I am seeing an HTTP 500 error code when I try to connect to the web services pages after configuring my subsystem instance.
I cannot see any Certificate System packages or updates.
Verify that your system is correctly registered to the Red Hat subscription management service, a valid subscription is assigned, and the Certificate System repository is enabled. For details, see Section 6.3.2.3, “Attaching a Red Hat subscription and enabling the Certificate System package repository”.
The init script returned an OK status, but my CA instance does not respond. Why?
This should not happen. Usually (but not always), this indicates a listener problem with the CA, but it can have many different causes. To see what errors have occurred, examine the journal log by running the following command:
journalctl -u pki-tomcatd@instance_name.service
journalctl -u pki-tomcatd@instance_name.service
Alternatively, examine the debug log files at /var/log/pki/ instance_name/subsystem_type/debug.
One situation is when there is a PID for the CA, indicating the process is running, but that no listeners have been opened for the server. This would return Java invocation class errors in the catalina.out file:
This could mean that you have the wrong version of JSS or NSS. The process requires libnss3.so in the path. Check this with this command:
ldd /usr/lib64/libjss4.so
ldd /usr/lib64/libjss4.so
If libnss3.so is not found, set the correct classpath in the /etc/sysconfig/instance_name configuration file. Then restart the CA using the systemctl restart pki-tomcatd@instance_name.service command.
I want to customize the subject name for the CA signing certificate, but do not see a way to do this using the pkispawn interactive install mode.
To do this, a configuration file representing delta links to the /usr/share/pki/server/etc/default.cfg file is required. See the pkispawn(8) and pki_default.cfg(5) man pages.
I want to set different certificate validity periods and extensions for my root certificate authority -but I do not see a way to set it using pkispawn.
You cannot currently do this using pkispawn. However, there is a way to edit the certificate profiles used by pkispawn to generate the root CA certificates.
You must do this before running pkispawn to create a new CA instance.
Back up the original CA certificate profile used by
pkispawn.cp -p /usr/share/pki/ca/conf/caCert.profile /usr/share/pki/ca/conf/caCert.profile.orig
# cp -p /usr/share/pki/ca/conf/caCert.profile /usr/share/pki/ca/conf/caCert.profile.origCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the CA certificate profile used by the configuration wizard.
vim /usr/share/pki/ca/conf/caCert.profile
# vim /usr/share/pki/ca/conf/caCert.profileCopy to Clipboard Copied! Toggle word wrap Toggle overflow Reset the validity period in the Validity Default to whatever you want. For example, to change the period to two years:
2.default.class=com.netscape.cms.profile.def.ValidityDefault 2.default.name=Validity Default 2.default.params.range=7200
2.default.class=com.netscape.cms.profile.def.ValidityDefault 2.default.name=Validity Default 2.default.params.range=7200Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add any extensions by creating a new default entry in the profile and adding it to the list. For example, to add the Basic Constraint Extension, add the default (which, in this example, is default #9):
9.default.class=com.netscape.cms.profile.def.BasicConstraintsExtDefault 9.default.name=Basic Constraint Extension Constraint 9.default.params.basicConstraintsCritical=true 9.default.params.basicConstraintsIsCA=true 9.default.params.basicConstraintsPathLen=2
9.default.class=com.netscape.cms.profile.def.BasicConstraintsExtDefault 9.default.name=Basic Constraint Extension Constraint 9.default.params.basicConstraintsCritical=true 9.default.params.basicConstraintsIsCA=true 9.default.params.basicConstraintsPathLen=2Copy to Clipboard Copied! Toggle word wrap Toggle overflow Then, add the default number to the list of defaults to use the new default:
list=2,4,5,6,7,8,9
list=2,4,5,6,7,8,9Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Once the new profile is set up, then run
pkispawnto create the new CA instance and go through the configuration wizard.
I am seeing an HTTP 500 error code when I try to connect to the web services pages after configuring my subsystem instance.
This is an unexpected generic error which can have many different causes. Check in the journal, system, and debug log files for the instance to see what errors have occurred. This lists a couple of common errors, but there are many other possibilities.
Error #1: The LDAP database is not running.
If the Red Hat Directory Server instance use for the internal database is not running, then you cannot connect to the instance. This will be apparent in exceptions in the journal file that the instance is not ready:
java.io.IOException: CS server is not ready to serve.
com.netscape.cms.servlet.base.CMSServlet.service(CMSServlet.java:409)
javax.servlet.http.HttpServlet.service(HttpServlet.java:688)
java.io.IOException: CS server is not ready to serve.
com.netscape.cms.servlet.base.CMSServlet.service(CMSServlet.java:409)
javax.servlet.http.HttpServlet.service(HttpServlet.java:688)The Tomcat logs will specifically identify the problem with the LDAP connection:
5558.main - [29/Oct/2010:11:13:40 PDT] [8] [3] In Ldap (bound) connection pool to host ca1 port 389, Cannot connect to LDAP server. Error: netscape.ldap.LDAPException: failed to connect to server ldap://ca1.example.com:389 (91)
5558.main - [29/Oct/2010:11:13:40 PDT] [8] [3] In Ldap (bound) connection pool
to host ca1 port 389, Cannot connect to LDAP server. Error:
netscape.ldap.LDAPException: failed to connect to server
ldap://ca1.example.com:389 (91)
As will the instance’s debug log:
[29/Oct/2010:11:39:10][main]: CMS:Caught EBaseException
Internal Database Error encountered: Could not connect to LDAP server host
ca1 port 389 Error netscape.ldap.LDAPException: failed to connect to
server ldap://ca1:389 (91)
at com.netscape.cmscore.dbs.DBSubsystem.init(DBSubsystem.java:262)
[29/Oct/2010:11:39:10][main]: CMS:Caught EBaseException
Internal Database Error encountered: Could not connect to LDAP server host
ca1 port 389 Error netscape.ldap.LDAPException: failed to connect to
server ldap://ca1:389 (91)
at com.netscape.cmscore.dbs.DBSubsystem.init(DBSubsystem.java:262)Error #2: A VPN is blocking access.
Another possibility is that you are connecting to the subsystem over a VPN. The VPN must have a configuration option like Use this connection only for resources on its network enabled. If that option is not enabled, then the journal log file for the instance’s Tomcat service shows a series of connection errors that result in the HTTP 500 error:
12.2. Java Console
- Q: I cannot open the pkiconsole and I am seeing Java exceptions in stdout.
- Q: I tried to run pkiconsole, and I got Socket exceptions in stdout. Why?
- Q: I attempt to start the console, and the system prompts me for my user name and password. After I enter these credentials, the console fails to appear.
I cannot open the pkiconsole and I am seeing Java exceptions in stdout.
This probably means that you have the wrong JRE installed or the wrong JRE set as the default. Run alternatives --config java to see what JRE is selected. Red Hat Certificate System requires OpenJDK 1.7.
I tried to run pkiconsole, and I got Socket exceptions in stdout. Why?
This means that there is a port problem. Either there are incorrect SSL/TLS settings for the administrative port (meaning there is bad configuration in the server.xml) or the wrong port was given to access the admin interface.
Port errors will look like the following:
I attempt to start the console, and the system prompts me for my user name and password. After I enter these credentials, the console fails to appear.
Make sure the user name and password you entered are valid. If so, enable the debug output and examine it.
To enable the debug output, open the /usr/bin/pkiconsole file, and add the following lines:
============================================
${JAVA} ${JAVA_OPTIONS} -cp ${CP} -Djava.util.prefs.systemRoot=/tmp/.java -Djava.util.prefs.userRoot=/tmp/java com.netscape.admin.certsrv.Console -s instanceID -D 9:all -a $1
----------
note: "-D 9:all" is for verbose output on the console.
============================================
============================================
${JAVA} ${JAVA_OPTIONS} -cp ${CP} -Djava.util.prefs.systemRoot=/tmp/.java -Djava.util.prefs.userRoot=/tmp/java com.netscape.admin.certsrv.Console -s instanceID -D 9:all -a $1
----------
note: "-D 9:all" is for verbose output on the console.
============================================Part III. Configuring Certificate System
This part describes the initial configuration of Red Hat Certificate System.
Chapter 13. The Certificate System Configuration Files
The primary configuration file for every subsystem is its CS.cfg file. This chapter covers basic information about and rules for editing the CS.cfg file. This chapter also describes some other useful configuration files used by the subsystems, such as password and web services files.
13.1. File and directory locations for Certificate System subsystems
Certificate System servers consist of an Apache Tomcat instance, which contains one or more subsystems. Each subsystem consists of a web application, which handles requests for a specific type of PKI function.
The available subsystems are: CA, KRA, OCSP, TKS, and TPS. Each instance can contain only one of each type of a PKI subsystem.
A subsystem can be installed within a particular instance using the pkispawn command.
13.1.1. Instance-specific information
For instance information for the default instance (pki-tomcat), see Table 2.2, “Tomcat instance information”
| Port Type | Port Number | Notes |
|---|---|---|
| Secure port | 8443 | Main port used to access PKI services by end-users, agents, and admins over HTTPS. |
| Insecure port | 8080 | Used to access the server insecurely for some end-entity functions over HTTP. Used for instance to provide CRLs, which are already signed and therefore need not be encrypted. |
| AJP port | 8009 | Used to access the server from a front end Apache proxy server through an AJP connection. Redirects to the HTTPS port. |
| Tomcat port | 8005 | Used by the web server. |
13.1.2. CA subsystem information
This section contains details about the CA subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.
| Setting | Value |
|---|---|
| Main directory | /var/lib/pki/pki-tomcat/ca/ |
| Configuration directory | /var/lib/pki/pki-tomcat/ca/conf/ |
| Configuration file | /var/lib/pki/pki-tomcat/ca/conf/CS.cfg |
| Subsystem certificates | CA signing certificate |
| OCSP signing certificate (for the CA’s internal OCSP service) | TLS server certificate |
| Audit log signing certificate | Subsystem certificate |
| Security databases | /var/lib/pki/pki-tomcat/alias/ |
| Log files | /var/lib/pki/pki-tomcat/ca/logs/ |
| Install log | /var/log/pki/pki-ca-spawn.date.log |
| Uninstall log | /var/log/pki/pki-ca-destroy.date.log |
| Audit logs | /var/log/pki/pki-tomcat/ca/signedAudit/ |
| Profile files | /var/lib/pki/pki-tomcat/ca/profiles/ca/ |
| Email notification templates | /var/lib/pki/pki-tomcat/ca/emails/ |
| Web services files | Agent services: /var/lib/pki/pki-tomcat/ca/webapps/ca/agent/ |
| Admin services: /var/lib/pki/pki-tomcat/ca/webapps/ca/admin/ | End user services: /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/ |
13.1.3. KRA subsystem information
This section contains details about the KRA subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.
| Setting | Value |
|---|---|
| Main directory | /var/lib/pki/pki-tomcat/kra/ |
| Configuration directory | /var/lib/pki/pki-tomcat/kra/conf/ |
| Configuration file | /var/lib/pki/pki-tomcat/kra/conf/CS.cfg |
| Subsystem certificates | Transport certificate |
| Storage certificate | TLS server certificate |
| Audit log signing certificate | Subsystem certificate |
| Security databases | /var/lib/pki/pki-tomcat/alias/ |
| Log files | /var/lib/pki/pki-tomcat/kra/logs/ |
| Install log | /var/log/pki/pki-kra-spawn-date.log |
| Uninstall log | /var/log/pki/pki-kra-destroy-date.log |
| Audit logs | /var/log/pki/pki-tomcat/kra/signedAudit/ |
| Web services files | Agent services: /var/lib/pki/pki-tomcat/kra/webapps/kra/agent/ |
13.1.4. OCSP subsystem information
This section contains details about the OCSP subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.
| Setting | Value |
|---|---|
| Main directory | /var/lib/pki/pki-tomcat/ocsp/ |
| Configuration directory | /var/lib/pki/pki-tomcat/ocsp/conf/ |
| Configuration file | /var/lib/pki/pki-tomcat/ocsp/conf/CS.cfg |
| Subsystem certificates | Transport certificate |
| Storage certificate | TLS server certificate |
| Audit log signing certificate | Subsystem certificate |
| Security databases | /var/lib/pki/pki-tomcat/alias/ |
| Log files | /var/lib/pki/pki-tomcat/ocsp/logs/ |
| Install log | /var/log/pki/pki-ocsp-spawn-date.log |
| Uninstall log | /var/log/pki/pki-ocsp-destroy-date.log |
| Audit logs | /var/log/pki/pki-tomcat/ocsp/signedAudit/ |
| Web services files | Agent services: /var/lib/pki/pki-tomcat/ocsp/webapps/ocsp/agent/ |
13.1.5. TKS subsystem information
This section contains details about the TKS subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.
| Setting | Value |
|---|---|
| Main directory | /var/lib/pki/pki-tomcat/tks/ |
| Configuration directory | /var/lib/pki/pki-tomcat/tks/conf/ |
| Configuration file | /var/lib/pki/pki-tomcat/tks/conf/CS.cfg |
| Subsystem certificates | Transport certificate |
| Storage certificate | TLS server certificate |
| Audit log signing certificate | Subsystem certificate |
| Security databases | /var/lib/pki/pki-tomcat/alias/ |
| Log files | /var/lib/pki/pki-tomcat/tks/logs/ |
| Install log | /var/log/pki/pki-tks-spawn-date.log |
| Uninstall log | /var/log/pki/pki-tks-destroy-date.log |
| Audit logs | /var/log/pki/pki-tomcat/tks/signedAudit/ |
| Web services files | Agent services: /var/lib/pki/pki-tomcat/tks/webapps/tks/agent/ |
13.1.6. TPS subsystem information
This section contains details about the TPS subsystem, which is one of the possible subsystems that can be installed as a web application in a Certificate Server instance.
| Setting | Value |
|---|---|
| Main directory | /var/lib/pki/pki-tomcat/tps |
| Configuration directory | /var/lib/pki/pki-tomcat/tps/conf/ |
| Configuration file | /var/lib/pki/pki-tomcat/tps/conf/CS.cfg |
| Subsystem certificates | Transport certificate |
| Storage certificate | TLS server certificate |
| Audit log signing certificate | Subsystem certificate |
| Security databases | /var/lib/pki/pki-tomcat/alias/ |
| Log files | /var/lib/pki/pki-tomcat/tps/logs/ |
| Install log | /var/log/pki/pki-tps-spawn-date.log |
| Uninstall log | /var/log/pki/pki-tps-destroy-date.log |
| Audit logs | /var/log/pki/pki-tomcat/tps/signedAudit/ |
| Web services files | Agent services: /var/lib/pki/pki-tomcat/tps/webapps/tps/agent/ |
13.1.7. Shared Certificate System subsystem file locations
There are some directories used by or common to all Certificate System subsystem instances for general server operations, listed in Table 13.7, “Subsystem file locations”.
| Directory Location | Contents |
|---|---|
| /var/lib/instance_name | Contains the main instance directory, which is the location for user-specific directory locations and customized configuration files, profiles, certificate databases, web files, and other files for the subsystem instance. |
| /usr/share/java/pki | Contains Java archive files shared by the Certificate System subsystems. Along with shared files for all subsystems, there are subsystem-specific files in subfolders:
|
| /usr/share/pki | Contains common files and templates used to create Certificate System instances. Along with shared files for all subsystems, there are subsystem-specific files in subfolders:
|
| /usr/bin |
Contains the |
| /var/lib/tomcat5/common/lib | Contains links to Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. Not used by the TPS subsystem. |
| /var/lib/tomcat5/server/lib | Contains links to Java archive files used by the local Tomcat web server and shared by the Certificate System subsystems. Not used by the TPS subsystem. |
| /usr/shared/pki | Contains the Java archive files used by the Tomcat server and applications used by the Certificate System instances. Not used by the TPS subsystem. |
| Contains Apache modules used by the TPS subsystem. Not used by the CA, KRA, OCSP, or TKS subsystems. |
| Mozilla LDAP SDK tools used by the TPS subsystem. Not used by the CA, KRA, OCSP, or TKS subsystems. |
13.2. CS.cfg files
The runtime properties of a Certificate System subsystem are governed by a set of configuration parameters. These parameters are stored in a file that is read by the server during startup, CS.cfg.
The CS.cfg, an ASCII file, is created and populated with the appropriate configuration parameters when a subsystem is first installed. The way the instance functions are modified is by making changes through the subsystem console, which is the recommended method. The changes made in the administrative console are reflected in the configuration file.
It is also possible to edit the CS.cfg configuration file directly, and in some cases this is the easiest way to manage the subsystem.
13.2.1. Locating the CS.cfg file
Each instance of a Certificate System subsystem has its own configuration file, CS.cfg. The contents of the file for each subsystem instance is different depending on the way the subsystem was configured, additional settings and configuration (like adding new profiles or enabling self-tests), and the type of subsystem.
The CS.cfg file is located in the configuration directory for the instance.
/var/lib/pki/ instance_name/subsystem_type/conf
/var/lib/pki/ instance_name/subsystem_type/confFor example:
/var/lib/pki/ instance_name/ca/conf
/var/lib/pki/ instance_name/ca/conf13.2.2. Editing the configuration file
Do not edit the configuration file directly without being familiar with the configuration parameters or without being sure that the changes are acceptable to the server. The Certificate System fails to start if the configuration file is modified incorrectly. Incorrect configuration can also result in data loss.
To modify the CS.cfg file:
Stop the subsystem instance.
pki-server stop instance_name
# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow The configuration file is stored in the cache when the instance is started. Any changes made to the instance through the Console are changed in the cached version of the file. When the server is stopped or restarted, the configuration file stored in the cache is written to disk. Stop the server before editing the configuration file or the changes will be overwritten by the cached version when the server is stopped.
-
Open the
/var/lib/pki/ instance_name/subsystem_type/confdirectory. -
Open the
CS.cfgfile in a text editor. - Edit the parameters in the file, and save the changes.
Start the subsystem instance.
pki-server start instance_name
# pki-server start instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
13.2.3. Overview of the CS.cfg configuration file
Each subsystem instances has its own main configuration file, CS.cfg, which contains all of the settings for the instance, such as plug-ins and Java classes for configuration. The parameters and specific settings are different depending on the type of subsystem, but, in a general sense, the CS.cfg file defines these parts of the subsystem instance:
- Basic subsystem instance information, like its name, port assignments, instance directory, and hostname
- Logging
- Plug-ins and methods to authenticate to the instance’s user directory (authorization)
- The security domain to which the instance belongs
- Subsystem certificates
- Other subsystems used by the subsystem instance
- Database types and instances used by the subsystem
- Settings for PKI-related tasks, like the key profiles in the TKS, the certificate profiles in the CA, and the required agents for key recovery in the KRA
Many of the configuration parameters (aside from the ones for PKI tasks) are very much the same between the CA, OCSP, KRA, and TKS because they all use a Java-based console, so configuration settings which can be managed in the console have similar parameters.
The CS.cfg file a basic parameter=value format.
#comment parameter=value
#comment
parameter=value
In the CS.cfg file, many of the parameter blocks have descriptive comments, commented out with a pound (#) character. Comments, blank lines, unknown parameters, or misspelled parameters are ignored by the server.
A bug in the TPS prevents it from ignoring lines which are commented out in the CS.cfg file. Rather than commenting out lines in the TPS CS.cfg file, simply delete those lines.
Parameters that configure the same area of the instance tend to be grouped together into the same block.
Example 13.1. Logging settings in the CS.cfg file
Some areas of functionality are implemented through plug-ins, such as self-tests, jobs, and authorization to access the subsystem. For those parameters, the plug-in instance has a unique identifier (since there can be multiple instances of even the same plug-in called for a subsystem), the implementation plug-in name, and the Java class.
Example 13.2. Subsystem authorization settings
authz.impl._000=## authz.impl._001=## authorization manager implementations authz.impl._002=## authz.impl.BasicAclAuthz.class=com.netscape.cms.authorization.BasicAclAuthz authz.instance.BasicAclAuthz.pluginName=BasicAclAuthz
authz.impl._000=##
authz.impl._001=## authorization manager implementations
authz.impl._002=##
authz.impl.BasicAclAuthz.class=com.netscape.cms.authorization.BasicAclAuthz
authz.instance.BasicAclAuthz.pluginName=BasicAclAuthzThe values for configuration parameters must be properly formatted, so they must obey two rules:
- The values that need to be localized must be in UTF8 characters.
-
The
CS.cfgfile supports forward slashes (/) in parameter values. If a back slash (\) is required in a value, it must be escaped with a back slash, meaning that two back slashes in a row must be used.
The following sections are snapshots of CS.cfg file settings and parameters. These are not exhaustive references or examples of CS.cfg file parameters. Also, the parameters available and used in each subsystem configuration file is very different, although there are similarities.
13.2.3.1. Basic subsystem settings
Basic settings are specific to the instance itself, without directly relating to the functionality or behavior of the subsystem. This includes settings for the instance name, root directory, the user ID for the process, and port numbers. Many of the settings assigned when the instance is first installed or configured are prefaced with pkispawn.
Example 13.3. Basic Instance Parameters for the CA: pkispawn file ca.cfg
While information like the port settings is included in the CS.cfg file, it is not set in the CS.cfg. The server configuration is set in the server.xml file.
The ports in CS.cfg and server.xml must match for a working RHCS instance.
13.2.3.2. Logging settings
There are several different types of logs that can be configured, depending on the type of subsystem. Each type of log has its own configuration entry in the CS.cfg file.
For example, the CA has this entry for transaction logs, which allows log rotation, buffered logging, and log levels, among other settings:
For more information about these parameters and their values, see Section 17.1, “Certificate System log settings”. As long as audit logging is enabled, these values do not affect compliance.
13.2.3.3. Authentication and authorization settings
The CS.cfg file sets how users are identified to access a subsystem instance (authentication) and what actions are approved (authorization) for each authenticated user.
A CS subsystem uses authentication plug-ins to define the method for logging into the subsystem.
The following example shows an authentication instance named SharedToken that instantiates a JAVA plug-in named SharedSecret.
For some authorization settings, it is possible to select an authorization method that uses an LDAP database to store user entries, in which case the database settings are configured along with the plug-in as shown below.
For more information on securely configuring LDAP and an explanation of parameters, refer to Section 7.5.4, “Enabling TLS mutual authentication from CS to DS”. The parameters paths differ than what is shown there, but the same names and values are allowed in both places.
The CA also has to have a mechanism for approving user requests. As with configuring authorization, this is done by identifying the appropriate authentication plug-in and configuring an instance for it:
auths.impl.AgentCertAuth.class=com.netscape.cms.authentication.AgentCertAuthentication auths.instance.AgentCertAuth.agentGroup=Certificate Manager Agents auths.instance.AgentCertAuth.pluginName=AgentCertAuth
auths.impl.AgentCertAuth.class=com.netscape.cms.authentication.AgentCertAuthentication
auths.instance.AgentCertAuth.agentGroup=Certificate Manager Agents
auths.instance.AgentCertAuth.pluginName=AgentCertAuth13.2.3.4. Subsystem certificate settings
Several of the subsystems have entries for each subsystem certificate in the configuration file.
ca.sslserver.cert=MIIDmDCCAoCgAwIBAgIBAzANBgkqhkiG9w0BAQUFADBAMR4wHAYDVQQKExVSZWR... ca.sslserver.certreq=MIICizCCAXMCAQAwRjEeMBwGA1UEChMVUmVkYnVkY29tcHV0ZXIgRG9tYWluMSQwIgYDV... ca.sslserver.nickname=Server-Cert cert-pki-ca ca.sslserver.tokenname=Internal Key Storage Token
ca.sslserver.cert=MIIDmDCCAoCgAwIBAgIBAzANBgkqhkiG9w0BAQUFADBAMR4wHAYDVQQKExVSZWR...
ca.sslserver.certreq=MIICizCCAXMCAQAwRjEeMBwGA1UEChMVUmVkYnVkY29tcHV0ZXIgRG9tYWluMSQwIgYDV...
ca.sslserver.nickname=Server-Cert cert-pki-ca
ca.sslserver.tokenname=Internal Key Storage Token13.2.3.5. Settings for required subsystems
At a minimum, each subsystem depends on a CA, which means that the CA (and any other required subsystem) has to be configured in the subsystem’s settings. Any connection to another subsystem is prefaced by conn. and then the subsystem type and number.
13.2.3.6. Database settings
All of the subsystems use an LDAP directory to store their information. This internal database is configured in the internaldb parameters, except for the TPS which configured it in the tokendb parameters with a lot of other configuration settings.
For further information on securely configuring LDAP and an explanation of parameters, refer to Section 7.5.4, “Enabling TLS mutual authentication from CS to DS”. No additional configuration is necessary outside of what is done as part Section 7.5.4, “Enabling TLS mutual authentication from CS to DS”.
13.2.3.7. Enabling and configuring a publishing queue
Part of the enrollment process includes publishing the issued certificate to any directories or files. This, essentially, closes out the initial certificate request. However, publishing a certificate to an external network can significantly slow down the issuance process -which leaves the request open.
To avoid this situation, administrators can enable a publishing queue. The publishing queue separates the publishing operation (which may involve an external LDAP directory) from the request and enrollment operations, which uses a separate request queue. The request queue is updated immediately to show that the enrollment process is complete, while the publishing queue sends the information at the pace of the network traffic.
The publishing queue sets a defined, limited number of threads that publish generated certificates, rather than opening a new thread for each approved certificate.
The publishing queue is disabled by default. It can be enabled in the CA Console, along with enabling publishing.
While the publishing queue is disabled by default, the queue is automatically enabled if LDAP publishing is enabled in the Console. Otherwise, the queue can be enabled manually.
Figure 13.1. Enabling the Publishing Queue
13.2.3.7.1. Enabling and configuring a publishing queue by editing the CS.cfg file
Enabling the publishing queue by editing the CS.cfg file allows administrators to set other options for publishing, like the number of threads to use for publishing operations and the queue page size.
Stop the CA server, so that you can edit the configuration files.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the CA’s
CS.cfgfile.vim /var/lib/pki/ instance_name/ca/conf/CS.cfg
# vim /var/lib/pki/ instance_name/ca/conf/CS.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set the
ca.publish.queue.enableto true. If the parameter is not present, then add a line with the parameter.ca.publish.queue.enable=true
ca.publish.queue.enable=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set other related publishing queue parameters:
-
ca.publish.queue.maxNumberOfThreadssets the maximum number of threads that can be opened for publishing operations. The default is 3. -
ca.publish.queue.priorityLevelsets the priority for publishing operations. The priority value ranges from-2(lowest priority) to2(highest priority). Zero (0) is normal priority and is also the default. -
ca.publish.queue.pageSizesets the maximum number of requests that can be stored in the publishing queue page. The default is 40. ca.publish.queue.saveStatussets the interval to save its status every specified number of publishing operations. This allows the publishing queue to be recovered if the CA is restarted or crashes. The default is 200, but any non-zero number will recover the queue when the CA restarts. Setting this parameter to 0 disables queue recovery.ca.publish.queue.maxNumberOfThreads=1 ca.publish.queue.priorityLevel=0 ca.publish.queue.pageSize=100 ca.publish.queue.saveStatus=200
ca.publish.queue.maxNumberOfThreads=1 ca.publish.queue.priorityLevel=0 ca.publish.queue.pageSize=100 ca.publish.queue.saveStatus=200Copy to Clipboard Copied! Toggle word wrap Toggle overflow TIPSetting
ca.publish.queue.enableto false andca.publish.queue.maxNumberOfThreadsto 0 disables both the publishing queue and using separate threads for publishing issued certificates.
-
Restart the CA server.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
13.2.3.8. Settings for PKI tasks
The CS.cfg file is used to configure the PKI tasks for every subsystem. The parameters are different for every single subsystem, without any overlap.
For example, the KRA has settings for a required number of agents to recover a key.
kra.noOfRequiredRecoveryAgents=1
kra.noOfRequiredRecoveryAgents=1
Review the CS.cfg file for each subsystem to become familiar with its PKI task settings; the comments in the file are a decent guide for learning what the different parameters are.
- The CA configuration file lists all of the certificate profiles and policy settings, as well as rules for generating CRLs.
- The TPS configures different token operations.
- The TKS lists profiles for deriving keys from different key types.
- The OCSP sets key information for different key sets.
13.2.3.9. Changing DN attributes in CA-issued certificates
In certificates issued by the Certificate System, DNs identify the entity that owns the certificate. In all cases, if the Certificate System is connected with a Directory Server, the format of the DNs in the certificates should match the format of the DNs in the directory. It is not necessary that the names match exactly; certificate mapping allows the subject DN in a certificate to be different from the one in the directory.
In the Certificate System, the DN is based on the components, or attributes, defined in the X.509 standard. Table 13.8, “Allowed characters for value types” lists the attributes supported by default. The set of attributes is extensible.
| Attribute | Value Type | Object Identifier |
|---|---|---|
| cn | DirectoryString | 2.5.4.3 |
| ou | DirectoryString | 2.5.4.11 |
| o | DirectoryString | 2.5.4.10 |
| c | PrintableString, two-character | 2.5.4.6 |
| l | DirectoryString | 2.5.4.7 |
| st | DirectoryString | 2.5.4.8 |
| street | DirectoryString | 2.5.4.9 |
| title | DirectoryString | 2.5.4.12 |
| uid | DirectoryString | 0.9.2342.19200300.100.1.1 |
| | IA5String | 1.2.840.113549.1.9.1 |
| dc | IA5String | 0.9.2342.19200300.100.1.2.25 |
| serialnumber | PrintableString | 2.5.4.5 |
| unstructuredname | IA5String | 1.2.840.113549.1.9.2 |
| unstructuredaddress | PrintableString | 1.2.840.113549.1.9.8 |
By default, the Certificate System supports the attributes identified in Table 13.8, “Allowed characters for value types”. This list of supported attributes can be extended by creating or adding new attributes. The syntax for adding additional X.500Name attributes, or components, is as follows:
X500Name.NEW_ATTRNAME.oid=n.n.n.n X500Name.NEW_ATTRNAME.class=string_to_DER_value_converter_class
X500Name.NEW_ATTRNAME.oid=n.n.n.n
X500Name.NEW_ATTRNAME.class=string_to_DER_value_converter_class
The value converter class converts a string to an ASN.1 value; this class must implement the netscape.security.x509.AVAValueConverter interface. The string-to-value converter class can be one of the following:
-
netscape.security.x509.PrintableConverterconverts a string to aPrintableStringvalue. The string must have only printable characters. -
netscape.security.x509.IA5StringConverterconverts a string to anIA5Stringvalue. The string must have only IA5String characters. -
netscape.security.x509.DirStrConverterconverts a string to aDirectoryString. The string is expected to be inDirectoryStringformat according to RFC 2253. netscape.security.x509.GenericValueConverterconverts a string character by character in the following order, from the smallest characterset to the largest:- PrintableString
- IA5String
- BMPString
- Universal String
An attribute entry looks like the following:
X500Name.MY_ATTR.oid=1.2.3.4.5.6 X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter
X500Name.MY_ATTR.oid=1.2.3.4.5.6
X500Name.MY_ATTR.class=netscape.security.x509.DirStrConverter13.2.3.9.1. Adding new or custom attributes
To add a new or proprietary attribute to the Certificate System schema, do the following:
Stop the Certificate Manager.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Open the
/var/lib/pki/cs`instance/conf/directory. -
Open the configuration file,
CS.cfg. Add the new attributes to the configuration file.
For example, to add three proprietary attributes,
MYATTR1that is aDirectoryString,MYATTR2that is anIA5String, andMYATTR3that is aPrintableString, add the following lines at the end of the configuration file:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Save the changes, and close the file.
Restart the Certificate Manager.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Reload the enrollment page and verify the changes; the new attributes should show up in the form.
To verify that the new attributes are in effect, request a certificate using the manual enrollment form.
Enter values for the new attributes so that it can be verified that they appear in the certificate subject names. For example, enter the following values for the new attributes and look for them in the subject name:
MYATTR1: a_value MYATTR2: a.Value MYATTR3: aValue cn: John Doe o: Example Corporation
MYATTR1: a_value MYATTR2: a.Value MYATTR3: aValue cn: John Doe o: Example CorporationCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Open the agent services page, and approve the request.
- When the certificate is issued, check the subject name. The certificate should show the new attribute values in the subject name.
13.2.3.9.2. Changing the DER-encoding order
It is possible to change the DER-encoding order of a DirectoryString, so that the string is configurable since different clients support different encodings.
The syntax for changing the DER-encoding order of a DirectoryString is as follows:
X500Name.directoryStringEncodingOrder=encoding_list_separated_by_commas
X500Name.directoryStringEncodingOrder=encoding_list_separated_by_commasThe possible encoding values are as follows:
-
PrintableString -
IA5String -
UniversalString -
BMPString -
UTF8String
For example, the DER-encoding ordered can be listed as follows:
X500Name.directoryStringEncodingOrder=PrintableString,BMPString
X500Name.directoryStringEncodingOrder=PrintableString,BMPString
To change the DirectoryString encoding, do the following:
Stop the Certificate Manager.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Open the
/var/lib/pki/cs`instance/conf/directory. -
Open the
CS.cfgconfiguration file. Add the encoding order to the configuration file.
For example, to specify two encoding values,
PrintableStringandUniversalString, and the encoding order isPrintableStringfirst andUniversalStringnext, add the following line at the end of the configuration file:X500Name.directoryStringEncodingOrder=PrintableString,UniversalString
X500Name.directoryStringEncodingOrder=PrintableString,UniversalStringCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Save the changes, and close the file.
Start the Certificate Manager.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
To verify that the encoding orders are in effect, enroll for a certificate using the manual enrollment form. Use
John_Doefor thecn. - Open the agent services page, and approve the request.
When the certificate is issued, use the
dumpasn1tool to examine the encoding of the certificate.The
cncomponent of the subject name should be encoded as aUniversalString.Create and submit a new request using
John Smithfor thecn.The
cncomponent of the subject name should be encoded as aPrintableString.
13.2.3.10. Setting a CA to use a different certificate to sign CRLs
A Certificate Manager uses the key pair corresponding to its OCSP signing certificate for signing certificates and certificate revocation lists (CRLs). To use a different key pair to sign the CRLs that the Certificate Manager generates, then a CRL signing certificate can be created. The Certificate Manager’s CRL signing certificate must be signed or issued by itself.
To enable a Certificate Manager to sign CRLs with a different key pair, do the following:
Request a CRL signing certificate for the Certificate Manager.
Alternatively, use a tool that is capable of generating keypairs, such as the
certutiltool to generate a key pair, request a certificate for the key pair, and install the certificate in the Certificate Manager’s certificate database. For more information about thecertutiltool, see http://www.mozilla.org/projects/security/pki/nss/tools/.When the certificate request has been created, submit it through the Certificate Manager end-entities page, selecting the right profile, such as the "Manual OCSP Manager Signing Certificate Enrollment" profile. The page has a URL in the following format:
https://hostname:port/ca/ee/ca
https://hostname:port/ca/ee/caCopy to Clipboard Copied! Toggle word wrap Toggle overflow - After the request is submitted, log into the agent services page.
-
Check the request for required extensions. The CRL signing certificate must contain the
Key Usageextension with thecrlSigningbit set. - Approve the request.
- After the CRL signing certificate is generated, install the certificate in the Certificate Manager’s database through System Keys and Certificates in the console.
Stop the Certificate Manager.
pki-server stop instance_name
# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Update the Certificate Manager’s configuration to recognize the new key pair and certificate.
Change to the Certificate Manager instance configuration directory.
cd /var/lib/pki/instance-name/ca/conf/
# cd /var/lib/pki/instance-name/ca/conf/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Open the
CS.cfgfile and add the following lines:ca.crl_signing.cacertnickname=nickname cert-instance_ID ca.crl_signing.defaultSigningAlgorithm=signing_algorithm ca.crl_signing.tokenname=token_name
ca.crl_signing.cacertnickname=nickname cert-instance_ID ca.crl_signing.defaultSigningAlgorithm=signing_algorithm ca.crl_signing.tokenname=token_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow nickname is the name assigned to the CRL signing certificate.
instance_ID is the name of the Certificate Manager instance.
If the installed CA is a RSA-based CA, signing_algorithm can be
SHA256withRSA,SHA384withRSA, orSHA512withRSA. If the installed CA is an EC-based CA, signing_algorithm can beSHA256withEC,SHA384withEC,SHA512withEC.token_name is the name of the token used for generating the key pair and the certificate. If the internal/software token is used, use
Internal Key Storage Tokenas the value.For example, the entries might look like this:
ca.crl_signing.cacertnickname=crlSigningCert cert-pki-ca ca.crl_signing.defaultSigningAlgorithm=SHAMD512withRSA ca.crl_signing.tokenname=Internal Key Storage Token
ca.crl_signing.cacertnickname=crlSigningCert cert-pki-ca ca.crl_signing.defaultSigningAlgorithm=SHAMD512withRSA ca.crl_signing.tokenname=Internal Key Storage TokenCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Save the changes, and close the file.
Restart the Certificate Manager.
pki-server restart instance_name
# pki-server restart instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Now the Certificate Manager is ready to use the CRL signing certificate to sign the CRLs it generates.
13.2.3.11. Configuring CRL generation from cache in CS.cfg
The CRL cache is a simple mechanism that allows cert revocation information to be taken from a collection of revocation information maintained in memory. For best performance, it is recommended that this feature be enabled, which already represents the default behavior. The following configuration information (which is the default) is presented for information purposes or if changes are desired.
Stop the CA server.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the CA configuration directory.
cd /var/lib/ instance_name/conf/
# cd /var/lib/ instance_name/conf/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
CS.cfgfile, setting theenableCRLCacheandenableCacheRecoveryparameters to true:ca.crl.MasterCRL.enableCRLCache=true ca.crl.MasterCRL.enableCacheRecovery=true
ca.crl.MasterCRL.enableCRLCache=true ca.crl.MasterCRL.enableCacheRecovery=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the CA server.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
13.2.3.12. Configuring update intervals for CRLs in CS.cfg
The following describes how to configure the CRL system flexibly to reflect desired behavior. The goal is to configure CRL updates according to some schedule of two types. One type allows for a list of explicit times and the other consists of a length of time interval between updates. There is also a hybrid scenario where both are enabled to account for drift. The Note entry just below actually represents the default out of the box scenario.
The default scenario is listed as follows:
Deviate from this only when a more detailed and specific update schedule is desired. The rest of the section will talk about how that is accomplished.
Configuring the settings for full and delta CRLs in the CS.cfg file involves editing parameters.
| Parameter | Description | Accepted Values |
|---|---|---|
| updateSchema | Sets the ratio for how many delta CRLs are generated per full CRL | An integer value |
| enableDailyUpdates | Enables and disables setting CRL updates based on set times | true or false |
| enableUpdateInterval | Enables and disables setting CRL updates based on set intervals | true or false |
| dailyUpdates | Sets the times the CRLs should be updated | A comma-delimited list of times |
| autoUpdateInterval | Sets the interval in minutes to update the CRLs | An integer value |
| autoUpdateInterval.effectiveAtStart | Allows the system to attempt to use the new value of auto update immediately instead of waiting for the currently scheduled nextUpdate time | true or false |
| nextUpdateGracePeriod | Adds the time in minutes to the CRL validity period to ensure that CRLs remain valid throughout the publishing or replication period | An integer value |
| refreshInSec | Sets the periodicity in seconds of the thread on the clone OCSP to check LDAP for any updates of the CRL | An integer value |
The autoUpdateInterval.effectiveAtStart parameter requires a system restart in order for a new value to apply. The default value of this parameter is false, it should only be changed by users who are sure of what they are doing.
Procedure: How to configure CRL update intervals in CS.cfg
Stop the CA server.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Change to the CA configuration directory.
cd /var/lib/ instance_name/conf/
# cd /var/lib/ instance_name/conf/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
CS.cfgfile, and add the following line to set the update interval:ca.crl.MasterCRL.updateSchema=3
ca.crl.MasterCRL.updateSchema=3Copy to Clipboard Copied! Toggle word wrap Toggle overflow The default interval is 1, meaning a full CRL is generated every time a CRL is generated. The
updateSchemainterval can be set to any integer.Set the update frequency, either by specifying a cyclical interval or set times for the updates to occur:
Specify set times by enabling the
enableDailyUpdatesparameter, and add the desired times to thedailyUpdatesparameter:ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=false ca.crl.MasterCRL.dailyUpdates=0:50,04:55,06:55
ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=false ca.crl.MasterCRL.dailyUpdates=0:50,04:55,06:55Copy to Clipboard Copied! Toggle word wrap Toggle overflow This field sets a daily time when the CRL should be updated. To specify multiple times, enter a comma-separated list of times, such as
01:50,04:55,06:55. To enter a schedule for multiple days, enter a comma-separated list to set the times within the same day, and then a semicolon separated list to identify times for different days. For example, set01:50,04:55,06:55;02:00,05:00,17:00to configure revocation on Day 1 of the cycle at 1:50am, 4:55am, and 6:55am and then Day 2 at 2am, 5am, and 5pm.Specify intervals by enabling the
enableUpdateIntervalparameter, and add the required interval in minutes to theautoUpdateIntervalparameter:ca.crl.MasterCRL.enableDailyUpdates=false ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240
ca.crl.MasterCRL.enableDailyUpdates=false ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Set the following parameters depending on your environment:
If you run a CA without an OCSP subsystem, set:
ca.crl.MasterCRL.nextUpdateGracePeriod=0
ca.crl.MasterCRL.nextUpdateGracePeriod=0Copy to Clipboard Copied! Toggle word wrap Toggle overflow If you run a CA with an OCSP subsystem, set:
ca.crl.MasterCRL.nextUpdateGracePeriod=time_in_minutes
ca.crl.MasterCRL.nextUpdateGracePeriod=time_in_minutesCopy to Clipboard Copied! Toggle word wrap Toggle overflow The
ca.crl.MasterCRL.nextUpdateGracePeriodparameter defines the time in minutes, and the value must be big enough to enable the CA to propagate the new CRL to the OCSP. You must set the parameter to a non-zero value.If you additionally have OCSP clones in your environment, also set:
ocsp.store.defStore.refreshInSec=time_in_seconds
ocsp.store.defStore.refreshInSec=time_in_secondsCopy to Clipboard Copied! Toggle word wrap Toggle overflow The
ocsp.store.defStore.refreshInSecparameter sets the frequency in seconds with which the clone OCSP instances are informed of CRL updates through LDAP replication updates from the master OCSP instance.See Table 13.9, “CRL extended interval parameters” for details on the parameters.
Restart the CA server.
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Schedule drift can occur when updating CRLs by interval. Typically, drift occurs as a result of manual updates and CA restarts.
To prevent schedule drift, set both enableDailyUpdates and enableUpdateInterval parameters to true, and add the required values to autoUpdateInterval and dailyUpdates:
ca.crl.MasterCRL.enableDailyUpdates=true ca.crl.MasterCRL.enableUpdateInterval=true ca.crl.MasterCRL.autoUpdateInterval=240 ca.crl.MasterCRL.dailyUpdates=1:00
ca.crl.MasterCRL.enableDailyUpdates=true
ca.crl.MasterCRL.enableUpdateInterval=true
ca.crl.MasterCRL.autoUpdateInterval=240
ca.crl.MasterCRL.dailyUpdates=1:00
Only one dailyUpdates value will be accepted when updating CRLs by interval.
The interval updates will resynchronize with the dailyUpdates value every 24 hours preventing schedule drift.
13.2.3.13. Changing the access control settings for the subsystem
By default, access control rules are applied by evaluating deny rules first and then by evaluating allow rules. To change the order, change the authz.evaluateOrder parameter in the CS.cfg.
authz.evaluateOrder=deny,allow
authz.evaluateOrder=deny,allow
Additionally, access control rules can be evaluated from the local web.xml file (basic ACLs) or more complex ACLs can be accessed by checking the LDAP database. The authz.sourceType parameter identifies what type of authorization to use.
authz.sourceType=web.xml
authz.sourceType=web.xml
Always restart the subsystem after editing the CS.cfg file to load the updated settings.
13.2.3.14. Setting requirement for pkiconsole to use TLS client certificate authentication
pkiconsole is being deprecated.
Edit the CS.cfg file of each subsystem, search for the authType parameter and set it as follows:
authType=sslclientauth
authType=sslclientauth13.3. Managing system passwords
As explained in Section 2.3.9, “Passwords and watchdog (nuxwdog)”, Certificate System uses passwords bind to servers or to unlock tokens when the server starts.
The password.conf file stores system passwords in plain text. However, some administrators prefer to remove the password file entirely to allow nuxwdog to prompt for manual entry of each password initially and store for auto-restart in case of an unplanned shutdown.
When a Certificate System instance starts, the subsystem automatically checks for the password.conf file. If the file exists, then it uses those passwords to connect to other services, such as the internal LDAP database. If that file does not exist, then the watchdog daemon prompts for all of the passwords required by the PKI server to start.
If the password.conf file is present, the subsystem assumes that all the required passwords are present and properly formatted in clear text. If any passwords are missing or wrongly formatted, then the system fails to start correctly.
The required passwords are listed in the cms.passwordlist parameter in the CS.cfg file:
cms.passwordlist=internaldb,replicationdb,CA LDAP Publishing cms.password.ignore.publishing.failure=true
cms.passwordlist=internaldb,replicationdb,CA LDAP Publishing
cms.password.ignore.publishing.failure=true
The cms.password.ignore.publishing.failure parameter allows a CA subsystem to start up successfully even if it has a failed connection to one of its LDAP publishing directories.
For the CA, KRA, OCSP, and TKS subsystems, the default expected passwords are:
-
internalfor the NSS database -
internaldbfor the internal LDAP database -
replicationdbfor the replication password Any passwords to access external LDAP databases for publishing (CA only)
NoteIf a publisher is configured after the
password.conffile is removed, nothing is written to thepassword.conffile. Unlessnuxwdogis configured, the server will not have access to the prompts for the new publishing password the next time that the instance restarts.- Any external hardware token passwords
For the TPS, this prompts for three passwords:
-
internalfor the NSS database -
tokendbpassfor the internal LDAP database - Any external hardware token passwords
This section describes the two mechanisms provided for Certificate System to retrieve these passwords:
-
password.conffile (the default) - nuxwdog (watchdog)
13.3.1. Configuring the password.conf file
This section is here for reference only. Correct and secure operation must involve using the nuxwdog watchdog. Please refer to Section 13.3.2, “Using the Certificate System watchdog service” to enable nuxwdog, as it is required for full compliance.
By default, passwords are stored in a plain text file, password.conf, in the subsystem conf/ directory. Therefore, it is possible to modify them simply through a text editor.
The list of passwords stored in this file includes the following:
- The bind password used by the Certificate System instance to access and update the internal database.
- The password to the HSM
- The bind password used by the Certificate System instance to access the authentication directory, in case of CMC Shared Token.
- The bind password used by the subsystem to access and update the LDAP publishing directory; this is required only if the Certificate System instance is configured for publishing certificates and CRLs to an LDAP-compliant directory.
- the bind password used by the subsystem to access its replication database.
- For a TPS instance, the bind password used to access and update the token database.
The password.conf file also contains the token passwords needed to open the private keys of the subsystem.
The name and location password file to use for the subsystem is configured in the CS.cfg file:
passwordFile=/var/lib/pki/ instance_name/conf/password.conf
passwordFile=/var/lib/pki/ instance_name/conf/password.confThe internal password store and replication database have randomly-generated PINs which were set when the subsystem was installed and configured; the internal LDAP database password was defined by the administrator when the instance was configured.
The password entries in the password.conf file are in the following format:
name=password
name=passwordFor example:
internal=413691159497
internal=413691159497In cases where an HSM token is required, use the following format:
hardware-name=password
hardware-name=passwordFor example:
hardware-NHSM-CONN-XC=MyHSM$S8cret
hardware-NHSM-CONN-XC=MyHSM$S8cret
Example content of a password.conf file:
internal=376577078151 internaldb=secret12 replicationdb=1535106826 hardware-NHSM-CONN-XC=MyHSM$S8cret
internal=376577078151
internaldb=secret12
replicationdb=1535106826
hardware-NHSM-CONN-XC=MyHSM$S8cret13.3.2. Using the Certificate System watchdog service
In Certificate System, the watchdog service is used to start services which require passwords to access the security database in order to start. In case there is a requirement not to store the unencrypted passwords on the system, the watchdog service:
- prompts for the relevant passwords during server startup and caches them.
- uses cached passwords in case of a failure when the server is automatically restarted due to a crash.
13.3.2.1. Enabling the watchdog service
To enable the watchdog service:
- If you also want to use the Shared Secret feature on this host, enable the Shared Secret feature as described in Section 13.7.8, “Enabling the CMC Shared Secret feature”.
Backup the
server.xmlandpassword.conffiles from the/var/lib/pki/ instance_name/conf/directory. For example:cp -p /var/lib/pki/ instance_name/conf/server.xml /root/ cp -p /var/lib/pki/ instance_name/conf/password.conf /root/
# cp -p /var/lib/pki/ instance_name/conf/server.xml /root/ # cp -p /var/lib/pki/ instance_name/conf/password.conf /root/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Stop and disable the Certificate System instance’s service:
systemctl stop pki-tomcatd@instance_name.service systemctl disable pki-tomcatd@instance_name.service
# systemctl stop pki-tomcatd@instance_name.service # systemctl disable pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow If you use a Hardware Security Module (HSM), enable the watchdog service to prompt for the password of the hardware token:
Display the name of the hardware token:
egrep "^hardware-" /var/lib/pki/ instance_name/conf/password.conf
# egrep "^hardware-" /var/lib/pki/ instance_name/conf/password.conf hardware-HSM_token_name=passwordCopy to Clipboard Copied! Toggle word wrap Toggle overflow The highlighted string in the previous example is the hardware token name.
Add the
cms.tokenListparameter to the/var/lib/pki/ instance_name/conf/ca/CS.cfgfile and set it to the name of the hardware token. For example:cms.tokenList=HMS_token_name
cms.tokenList=HMS_token_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Enable the watchdog configuration for the instance:
pki-server instance-nuxwdog-enable instance_name
# pki-server instance-nuxwdog-enable instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Alternatively, enable the watchdog for all instances:
pki-server nuxwdog-enable
# pki-server nuxwdog-enableCopy to Clipboard Copied! Toggle word wrap Toggle overflow For further details, see the
pki-server-nuxwdog(8)man page.By default,
nuxwdogstarts the server as the user configured in theTOMCAT_USERvariable in the/etc/sysconfig/pki-tomcatfile. Optionally, to modify the user and group:Copy the watchdog
systemdunit file of the instance to the/etc/systemd/system/directory:cp -p /usr/lib/systemd/system/instance_name-nuxwdog@.service /etc/systemd/system/
# cp -p /usr/lib/systemd/system/instance_name-nuxwdog@.service /etc/systemd/system/Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteUnit files in the
/etc/systemd/system/directory have a higher priority and are not replaced during updates.Add the following entries to the
[Service]section in the/etc/pki/ instance_name/nuxwdog.conffile:User new_user_name
User new_user_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Reload the
systemdconfiguration:systemctl daemon-reload
# systemctl daemon-reloadCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Enable the Certificate System service that uses the watchdog:
systemctl enable pki-tomcatd-nuxwdog@instance_name.service
# systemctl enable pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow - Optionally: See Section 13.3.2.3, “Verifying that the Certificate System watchdog service is enabled”.
To start the Certificate System instance, run the following command and enter the prompted passwords:
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
13.3.2.2. Starting and stopping Certificate System with the watchdog enabled
For information how to manage a Certificate System instance refer to Section 2.2.3, “Execution management (systemctl)”.
13.3.2.3. Verifying that the Certificate System watchdog service is enabled
To verify that the watchdog service is enabled:
Verify that the
pki-tomcatd-nuxwdogservice is enabled:systemctl is-enabled pki-tomcatd-nuxwdog@instance_name.service
# systemctl is-enabled pki-tomcatd-nuxwdog@instance_name.service enabledCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify that the
pki-tomcatdservice is disabled:systemctl is-disabled pki-tomcatd@instance_name.service
# systemctl is-disabled pki-tomcatd@instance_name.service disabledCopy to Clipboard Copied! Toggle word wrap Toggle overflow In the
/etc/pki/ instance_name/server.xmlfile:verify that the
passwordFileparameter refers to theCS.cfgfile. For example:passwordFile="/var/lib/pki/ instance_name/ca/CS.cfg"
passwordFile="/var/lib/pki/ instance_name/ca/CS.cfg"Copy to Clipboard Copied! Toggle word wrap Toggle overflow verify that the
passwordClassparameter is set to com.netscape.cms.tomcat.NuxwdogPasswordStore:passwordClass="com.netscape.cms.tomcat.NuxwdogPasswordStore"
passwordClass="com.netscape.cms.tomcat.NuxwdogPasswordStore"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
13.3.2.4. Disabling the watchdog service
To disable the watchdog service:
Stop and disable the Certificate System instance’s service that uses the watchdog:
systemctl stop pki-tomcatd-nuxwdog@instance_name.service systemctl disable pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.service # systemctl disable pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the regular service without watch dog for the instance:
pki-server instance-nuxwdog-disable instance_name
# pki-server instance-nuxwdog-disable instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow Disable the watchdog configuration for the instance:
systemctl enable pki-tomcatd@instance_name.service
# systemctl enable pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow For further details, see the
pki-server-nuxwdog(8)man page.Restore the
password.conffile to its original location. For example:cp /root/password.conf.bak /var/lib/pki/ instance_name/conf/password.conf
# cp /root/password.conf.bak /var/lib/pki/ instance_name/conf/password.confCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the Certificate System instance:
systemctl start pki-tomcatd@instance_name.service
# systemctl start pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
13.4. Configuration files for the tomcat engine and web services
All of the user and administrative (administrators, agents, and auditors) services for the subsystems are accessed over web protocols.
This section discusses the two major sets of configuration files that apply to all Red Hat Certificate System subsystems (CA, KRA, OCSP, TKS, and TPS):
-
/var/lib/pki/ instance_name/conf/server.xmlprovides the configuration for the Tomcat engine. -
/usr/share/pki/subsystem_type/webapps/WEB-INF/web.xmlprovides the configuration for the web services offered by this instance.
13.4.1. Tomcatjss
The later subsections include important configuration information on required changes to parameter values. Ensure they are followed for strict compliance.
The following configuration in the server.xml file found in the example pki-tomcat/conf directory can be used to explain how Tomcatjss fits into the entire Certificate System ecosystem. Portions of the Connector entry for the secure port and its corresponding SSLHostConfig parameters are shown below.
In the server.xml configuration file for the Tomcat engine, there is this Connector configuration element that contains the pointer to the tomcatjss implementation, which can be plugged into the sslImplementation property of this Connector object.
Each key parameter element is explained in the subsections below.
13.4.1.1. TLS cipher configuration
Red Hat Certificate System} supports TLS 1.2 cipher suites. These are defined in the instance’s server.xml when the CS instance acts as a server, and in CS.cfg when the CS instance acts as a client.
- If you need to configure the ciphers, refer to the corresponding post-installation section in Update the ciphers list.
- For information on the supported ciphers, refer to Supported cipher suites.
13.4.1.2. Enabling automatic revocation checking on the CA
Revocation checks are supported/enabled in the CA in the same way as all other RHCS subsystems (see Enabling certificate revocation checking for RHCS subsystems). In general, RHCS recommends OCSP for more efficient certificate revocation checks. However, one thing that sets the CA apart from the other CS subsystems is that the CAs are the creators of the CRLs for the certificates they issue, and therefore are the sources of the CRLs that are needed by the OCSP subsystems. For this reason, they need to be able to start up independently before the OCSP or other RHCS subsystems.
In the case when the CA’s own internal LDAP server-cert is issued by the CA itself, it is very important that the CRL Distribution Point extension is used instead of the AIA (OCSP) so as not to fall victim to the chicken and egg issue during startup of the CA.
13.4.1.2.1. Configure support for CRL Distribution Point
For the purpose of mitigating propagation and reducing storage of large CRLs, it is important to note that RHCS recommends partitioning of the CRL to allow the certificates that utilize the CRL Distribution Point to be grouped into a smaller subset.
See Configure support for CRL Distribution Point for information on how to set up the CA to support partitioned CRL for server-certs that are issued using the CRL Distribution Point certificate enrollment profile.
13.4.1.3. Enabling certificate revocation checking for RHCS subsystems
Certificate revocation check is a vital part of certificate validation in a PKI environment. RHCS provides two types of certificate revocation validation methods: OCSP and CRL by means of detecting/processing either the AIA (OCSP) or the CRL Distribution Point extension of its peer certificate.
RHCS recommends OCSP for more efficient certificate revocation checks.
The usage of CRL Distribution Point is unavoidable in cases when the use of OCSP is not plausible. Such a case can be exemplified in Enabling automatic revocation checking on the CA above.
Applications (in this case, PKI subsystems) adopting OCSP need to know how to contact the OCSP system in order to verify the certificates in question. The PKI subsystems do not have OCSP checking enabled by default. You can enable OCSP checking for a PKI subsystem by editing its server.xml file.
If you have configured the subsystem to use an SSL/TLS connection with its internal database, then the SSL/TLS server certificate of the LDAP internal database must be recognized by the OCSP responder. If the OCSP responder does not recognize the LDAP server certificate, then the subsystem will not start properly. This configuration is covered in the Red Hat Certificate System Planning, Installation and Deployment Guide, since subsystem-LDAP SSL/TLS server connections are configured as part of the subsystem setup.
Procedure
Stop the instance
systemctl stop pki-tomcatd@<instance_name>.service
systemctl stop pki-tomcatd@<instance_name>.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
/var/lib/pki/<instance_name>/conf/server.xmlfile to configure theConnector name="Secure"section:-
Set the
enableOCSPparameter totrue. Make sure you remove these two parameters and their assigned values:
ocspResponderURL ocspResponderCertNickname
ocspResponderURL ocspResponderCertNicknameCopy to Clipboard Copied! Toggle word wrap Toggle overflow For example:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
Set the
Start the instance:
systemctl start pki-tomcatd@<instance_name>.service
systemctl start pki-tomcatd@<instance_name>.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
By default, all PKI system certificates created during installation are generated with an AIA (Authority Information Access) extension pointing to its issuing CA’s internal OCSP service. If you follow the steps in Adding an AIA extension to a certificate, to point to the external OCSP prior to installing PKI subsystems, then all their certificates (and all other certificates issued by its CA thereon) should bear the correct AIA pointing to the external OCSP instead.
13.4.1.3.1. Setting trust of the OCSP signing certificate
Each OCSP signing certificate must chain up to a trusted root in the Certificate System’s NSS database. In RHCS, during validation, each OCSP response includes the OCSP signer certificate chain. Therefore, the following consideration is required.
- If the OCSP responder being used has been configured to provide the entire certificate chain of the OCSP signing certificate with each OCSP response, as is the default case for RHCS OCSP services, then no further action is required. NSS knows how to validate this chain from the given information.
- If on the other hand the OCSP is known to not return the full chain, you then need to import the chain manually during installation setup. For details, see Importing an OCSP responder.
The Certificate System OCSP responder already includes the chain with every response. This includes the Certificate System external OCSP responder and the internal OCSP service that comes with each CA. This behavior is by default and cannot be changed.
13.4.1.3.2. OCSP parameters for server.xml
The following table provides information on each parameter relevant to certificate revocation checks (that is, OCSP and CRL) in the server.xml file.
| Parameter | Description |
|---|---|
| enableRevocationCheck (also known as enableOCSP) | Enables (or disables) revocation checking for the subsystem. |
| ocspResponderURL | Sets the URL where the OCSP requests are sent. For an OCSP Manager, this can be another OCSP service in another OCSP or in a CA. For a TKS or KRA, this always points to an external OCSP service in an OCSP or a CA. |
| ocspResponderCertNickname | Sets the nickname of the signing certificate for the responder, either the OCSP signing certificate or the CA’s OCSP signing certificate. The certificate must be imported into the subsystem’s NSS database and have the appropriate trust settings set. |
| ocspCacheSize | Sets the maximum number of cache entries. |
| ocspMinCacheEntryDuration | Sets minimum seconds before another fetch attempt can be made. For example, if this is set to 120, then the validity of a certificate cannot be checked again until at least 2 minutes after the last validity check. |
| ocspMaxCacheEntryDuration | Sets the maximum number of seconds to wait before making the next fetch attempt. This prevents having too large a window between validity checks. |
| ocspTimeout | Sets the timeout period, in seconds, for the OCSP request. |
If a nextUpdate field is sent with the OCSP response, it can affect the next fetch time with ocspMinCacheEntryDuration and ocspMaxCacheEntryDuration as follows:
-
If the value in
nextUpdatehas been reached before the value set inocspMinCacheEntryDuration, the fetch is not started until the value set inocspMinCacheEntryDurationhas been reached. -
If
ocspMinCacheEntryDurationhas been reached, the server checks if the value innextUpdatehas been reached. If the value has been reached, the fetch will happen. -
Regardless of the value in
nextUpdate, if the setting inocspMaxCacheEntryDurationhas been reached, the fetch will happen.
Due to the underlying SSL/TLS session caches kept by NSS, which follows the industry standard to prevent very expensive full handshakes as well as provide stronger privacy, OCSP requests are only made when NSS determines that a validation is required. The SSL/TLS session caches are independent of the OCSP status cache. Once NSS determines that an OCSP request is to be made, the request will be made and the response received will be kept in the OCSP certificate status cache. Due to the SSL/TLS session caches, these OCSP cache parameters only come into play when allowed by NSS.
13.4.1.4. Adding an AIA extension to a certificate
By default, unless explicitly specified, the CA issues certificates with an AIA (Authority Information Access) extension pointing to the CA’s own internal OCSP. Once you have set up an OCSP instance, you can configure the CA to start issuing certificates with an AIA extension that points to the OCSP instance instead.
Prerequisite
- You are logged in as root user.
Procedure
Stop the CA:
systemctl stop pki-tomcatd@<instance_name>.service
systemctl stop pki-tomcatd@<instance_name>.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the CA’s
CS.cfgand set theca.defaultOcspUrivariable to point to the OCSP. For example:ca.defaultOcspUri=http://hostname:32080/ocsp/ee/ocsp
ca.defaultOcspUri=http://hostname:32080/ocsp/ee/ocspCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the CA:
systemctl start pki-tomcatd@<instance_name>.service
systemctl start pki-tomcatd@<instance_name>.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
The OCSP URL of each subsystem (e.g. KRA) is set in its server.xml file by default. When enabled, this directs the RHCS instance to use the static URL when looking up a certificate status, instead of the AIA extension embedded in the peer certificate. For more information on using the AIA extension, refer to Enabling certificate revocation checking for RHCS subsystems.
13.4.1.5. Adding a CRL Distribution Point extension to a certificate
To add the CRL Distribution Point extension to a certificate, you need to use a certificate enrollment profile equipped with the CRL Distribution Point extension. To enable a certificate enrollment profile, see CA’s enrollment profile configuration with CRL Distribution Points.
Note that the CA needs to be configured to handle CRL Distribution Points for such profiles to work. See Configure support for CRL Distribution Point.
13.4.2. Session timeout
When a user connects to PKI server through a client application, the server will create a session to keep track of the user. As long as the user remains active, the user can execute multiple operations over the same session without having to re-authenticate.
Session timeout determines how long the server will wait since the last operation before terminating the session due to inactivity. Once the session is terminated, the user will be required to re-authenticate to continue accessing the server, and the server will create a new session.
There are two types of timeouts:
- TLS session timeout
- HTTP session timeout
Due to differences in the way clients work, the clients will be affected differently by these timeouts.
Certain clients have their own timeout configuration. For example, Firefox has a keep-alive timeout setting. For details, see http://kb.mozillazine.org/Network.http.keep-alive.timeout. If the value is different from the server’s setting for TLS Session Timeout or HTTP Session Timeout, different behavior can be observed.
13.4.2.1. TLS session timeout
A TLS session is a secure communication channel over a TLS connection established through TLS handshake protocol.
PKI server generates audit events for TLS session activities. The server generates an ACCESS_SESSION_ESTABLISH audit event with Outcome=Success when the connection is created. If the connection fails to be created, the server will generate an ACCESS_SESSION_ESTABLISH audit event with Outcome=Failure. When the connection is closed, the server will generate an ACCESS_SESSION_TERMINATED audit event.
TLS session timeout (that is TLS connection timeout) is configured in the keepAliveTimeout parameter in the Secure Connector element in the /etc/pki/instance/server.xml file:
By default the timeout value is set to 300000 milliseconds (that is 5 minutes). To change this value, edit the /etc/pki/instance/server.xml file and then restart the server.
Note that this value will affect all TLS connections to the server. A large value may improve the efficiency of the clients since they can reuse existing connections that have not expired. However, it may also increase the number of connections that the server has to support simultaneously since it takes longer for abandoned connections to expire.
13.4.2.2. HTTP session timeout
An HTTP session is a mechanism to track a user across multiple HTTP requests using HTTP cookies. PKI server does not generate audit events for the HTTP sessions.
For the purpose of auditing consistency, set the session-timeout value in this section to match the keepAliveTimeout value in Section 13.4.2.1, “TLS session timeout”. For example if keepAliveTimeout was set to 300000 (5 minutes), then set session-timeout to 30.
The HTTP session timeout can be configured in the session-timeout element in the /etc/pki/instance/web.xml file:
By default the timeout value is set to 30 minutes. To change the value, edit the /etc/pki/instance/web.xml file and then restart the server.
Note that this value affects all sessions in all web applications on the server. A large value may improve the experience of the users since they will not be required to re-authenticate or view the access banner again so often. However, it may also increase the security risk since it takes longer for abandoned HTTP sessions to expire.
13.4.2.3. Session timeout for PKI Web UI
PKI Web UI is an interactive web-based client that runs in a browser. Currently it only supports client certificate authentication.
When the Web UI is opened, the browser may create multiple TLS connections to a server. These connections are associated to a single HTTP session.
To configure a timeout for the Web UI, see Section 13.4.2.2, “HTTP session timeout”. The TLS session timeout is normally irrelevant since the browser caches the client certificate so it can recreate the TLS session automatically.
When the HTTP session expires, the Web UI does not provide any immediate indication. However, the Web UI will display an access banner (if enabled) before a user executes an operation.
13.4.2.4. Session timeout for PKI Console
PKI Console is an interactive standalone graphical UI client. It supports username/password and client certificate authentication.
When the console is started, it will create a single TLS connection to the server. The console will display an access banner (if enabled) before opening the graphical interface. Unlike the Web UI, the console does not maintain an HTTP session with the server.
To configure a timeout for the console, see Section 13.4.2.1, “TLS session timeout”. The HTTP session timeout is irrelevant since the console does not use HTTP session.
When the TLS session expires, the TLS connection will close, and the console will exit immediately to the system. If the user wants to continue, the user will need to restart the console.
13.4.2.5. Session timeout for PKI CLI
PKI CLI is a command-line client that executes a series of operations. It supports username/password and client certificate authentication.
When the CLI is started, it will create a single TLS connection to the server and an HTTP session. The CLI will display an access banner (if enabled) before executing operations.
Both timeouts are generally irrelevant to PKI CLI since the operations are executed in sequence without delay and the CLI exits immediately upon completion. However, if the CLI waits for user inputs, is slow, or becomes unresponsive, the TLS session or the HTTP session may expire and the remaining operations fail. If such delay is expected, see Section 13.4.2.1, “TLS session timeout” and Section 13.4.2.2, “HTTP session timeout” to accommodate the expected delay.
13.5. Removing unused interfaces from web.xml (CA only)
Several legacy interfaces (for features like bulk issuance or the policy framework) are still included in the CA’s web.xml file. However, since these features are deprecated and no longer in use, then they can be removed from the CA configuration to increase security.
Procedure
Stop the CA.
pki-server stop instance_name
# pki-server stop instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the web files directory for the CA. For example:
cd /var/lib/pki/ instance_name/ca/webapps/ca/WEB-INF
# cd /var/lib/pki/ instance_name/ca/webapps/ca/WEB-INFCopy to Clipboard Copied! Toggle word wrap Toggle overflow Back up the current
web.xmlfile.cp web.xml web.xml.servlets
# cp web.xml web.xml.servletsCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the
web.xmlfile and remove the entireservlet>entries for each of the following deprecated servlets:- caadminEnroll
- cabulkissuance
- cacertbasedenrollment
- caenrollment
caProxyBulkIssuance
For example, remove the
caadminEnrollservlet entry:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
After removing the servlet entries, remove the corresponding
servlet-mapping>entries.<servlet-mapping> <servlet-name> caadminEnroll </servlet-name> <url-pattern> /admin/ca/adminEnroll </url-pattern> </servlet-mapping><servlet-mapping> <servlet-name> caadminEnroll </servlet-name> <url-pattern> /admin/ca/adminEnroll </url-pattern> </servlet-mapping>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Remove three
filter-mapping>entries for an end-entity request interface.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Start the CA again.
pki-server start instance_name
# pki-server start instance_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
13.6. Customizing Web Services
All of the subsystems (with the exception of the TKS) have some kind of a web-based services page for agents and some for other roles, like administrators or end entities. These web-based services pages use basic HTML and JavaScript, which can be customized to use different colors, logos, and other design elements to fit in with an existing site or intranet.
13.6.1. Customizing subsystem web applications
Each PKI subsystem has a corresponding web application, which contains:
- HTML pages containing texts, JavaScript codes, page layout, CSS formatting, and so on
-
A
web.xmlfile, which defines servlets, paths, security constraints, and other - Links to PKI libraries.
The subsystem web applications are deployed using context files located in the /var/lib/pki/pki-tomcat/conf/Catalina/localhost/ direcotry, for example, the ca.xml file:
Context docBase="/usr/share/pki/ca/webapps/ca" crossContext="true" allowLinking="true"
...
/Context
Context docBase="/usr/share/pki/ca/webapps/ca" crossContext="true" allowLinking="true"
...
/Context
The docBase points to the location of the default web application directory, /usr/share/pki/.
To customize the web application, copy the web application directory into the instance’s webapps directory:
cp -r /usr/share/pki/ca/webapps/ca /var/lib/pki/pki-tomcat/webapps
$ cp -r /usr/share/pki/ca/webapps/ca /var/lib/pki/pki-tomcat/webapps
Then change the docBase to point to the custom web application directory relative from the webapps directory:
Context docBase="ca" crossContext="true" allowLinking="true"
...
/Context
Context docBase="ca" crossContext="true" allowLinking="true"
...
/ContextThe change will be effective immediately without the need to restart the server.
To remove the custom web application, simply revert the docBase and delete the custom web application directory:
rm -rf /var/lib/pki/pki-tomcat/webapps/ca
$ rm -rf /var/lib/pki/pki-tomcat/webapps/ca13.6.2. Customizing the Web UI theme
The subsystem web applications in the same instance share the same theme, which contains:
- CSS files, which determine the global appearance
- Image files including logo, icons, and other
- Branding properties, which determine the page title, logo link, title color, and other.
The Web UI theme is deployed using the pki.xml context file in the /var/lib/pki/pki-tomcat/conf/Catalina/localhost/ directory:
Context docBase="/usr/share/pki/common-ui" crossContext="true" allowLinking="true"
...
/Context
Context docBase="/usr/share/pki/common-ui" crossContext="true" allowLinking="true"
...
/Context
The docBase points to the location of the default theme directory, /usr/share/pki/.
To customize the theme, copy the default theme directory into the pki directory in the instance’s webapps directory:
cp -r /usr/share/pki/common-ui /var/lib/pki/pki-tomcat/webapps/pki
$ cp -r /usr/share/pki/common-ui /var/lib/pki/pki-tomcat/webapps/pki
Then change the docBase to point to the custom theme directory relative from the webapps directory:
Context docBase="pki" crossContext="true" allowLinking="true"
...
/Context
Context docBase="pki" crossContext="true" allowLinking="true"
...
/ContextThe change will be effective immediately without the need to restart the server.
To remove the custom theme, simply revert the docBase and delete the custom theme directory:
rm -rf /var/lib/pki/pki-tomcat/webapps/pki
$ rm -rf /var/lib/pki/pki-tomcat/webapps/pki13.6.3. Customizing TPS token state labels
The default token state labels are stored in the /usr/share/pki/tps/conf/token-states.properties file and described in Section 2.5.2.4.1.4, “Token state and transition labels”.
To customize the labels, copy the file into the instance directory:
cp /usr/share/pki/tps/conf/token-states.properties /var/lib/pki/pki-tomcat/tps/conf
$ cp /usr/share/pki/tps/conf/token-states.properties /var/lib/pki/pki-tomcat/tps/confThe change will be effective immediately without the need to restart the server.
To remove the customized labels, simply delete the customized file:
rm /var/lib/pki/pki-tomcat/tps/conf/token-states.properties
$ rm /var/lib/pki/pki-tomcat/tps/conf/token-states.properties13.7. Using an access banner
In Certificate System, Administrators can configure a banner with customizable text. The banner will be displayed in the following situations:
| Application | When the banner is displayed |
|---|---|
| PKI Console |
|
| Web interface |
|
|
|
|
You can use the banner to display important information to the users before they can use Certificate System. The user must agree to the displayed text to continue.
Example 13.4. When the access banner is displayed
The following example shows when the access banner is displayed if you are using the pki utility:
13.7.1. Enabling an access banner
To enable the access banner, create the /etc/pki/ instance_name/banner.txt file and enter the text to displayed.
The text in the /etc/pki/ instance_name/banner.txt file must use the UTF-8 format. To validate, see Section 13.7.4, “Validating the banner”.
13.7.2. Disabling an access banner
To disable the access banner, either delete or rename the /etc/pki/ instance_name/banner.txt file. For example:
mv /etc/pki/ instance_name/banner.txt /etc/pki/ instance_name/banner.txt.UNUSED
# mv /etc/pki/ instance_name/banner.txt /etc/pki/ instance_name/banner.txt.UNUSED13.7.3. Displaying the banner
To display the currently configured banner:
pki-server banner-show -i instance_name
# pki-server banner-show -i instance_name13.7.4. Validating the banner
To validate that the banner does not contain invalid characters:
pki-server banner-validate -i instance_name
# pki-server banner-validate -i instance_name
---------------
Banner is valid
---------------13.7.5. Configuration for CMC
This section describes how to configure Certificate System for Certificate Management over CMS (CMC).
13.7.6. Understanding how CMC works
Before configuring CMC, read the following documentation to learn more about the subject:
- Section 2.4.1.1.2.2, “Enrolling with CMC”
- Issuing Certificates Using CMC in the Red Hat Certificate System Administration Guide.
- Making Rules for Issuing Certificates (Certificate Profiles) in the Red Hat Certificate System Administration Guide.
13.7.7. Enabling the PopLinkWittnessV2 feature
For a high-level security on the Certificate Authority (CA), enable the following option in the /var/lib/pki/ instance_name/ca/conf/CS.cfg file:
cmc.popLinkWitnessRequired=true
cmc.popLinkWitnessRequired=true13.7.9. Enabling CMCRevoke for the Web User Interface
As described in the Performing a CMC Revocation section in the Red Hat Certificate System Administration Guide, there are two ways to submit CMC revocation requests.
In cases when you use the CMCRevoke utility to create revocation requests to be submitted through the web UI, add the following setting to the /var/lib/pki/ instance_name/ca/conf/CS.cfg file:
cmc.bypassClientAuth=true
cmc.bypassClientAuth=true13.8. ServerSide Key Generation for EE
13.8.1. Overview
Many newer versions of browsers, including Firefox v69 and up, as well as Chrome, have removed the functionality to generate PKI keys and the support for CRMF for key archival. While CLIs such as CRMFPopClient (see "CRMFPopClient --help") or pki (see "pki client-cert-request --help") could be used as a workaround on the Fedora or RHEL platforms, clients on other platforms have been largely left out.
Server-Side Keygen enrollment has been around for a long time since the introduction of Token Key Management System (TMS), where keys could be generated on KRA instead of locally on smart cards. Starting from PKI v.10.5, we adopt a similar mechanism to resolve the browser keygen deficiency issue. Keys are generated on the server (KRA to be specific) and then transferred securely back to the client in PKCS#12.
It is highly recommended that the Server-Side Keygen mechanism only being employed for encryption certificates.
13.8.2. Functionality Highlights
- Certificate request keys are generated on KRA (Note: KRA must be installed to work with the CA)
- The profile default plugin, serverKeygenUserKeyDefaultImpl, provides selection to enable or disable key archival (i.e. the “enableArchival” parameter)
- Support for both RSA and EC keys
- Support for both manual (agent) approval and automatic approval (e.g. directory password-based)
13.8.3. Installation configuration
A KRA instance is required in addition to the CA for setting up Server-Side Keygen.
In the case when the CA and KRA are sharing a Tomcat instance, there is no need to execute the below step to import the transport certificate.
After installing CA and KRA instances, in the case of stand-alone Tomcat web server instances, you’d need to add the KRA’s transport cert to the CA’s nssdb.
First, shut down CA
Systemctl stop pki-tomcatd@<ca_instance_name>.service e.g. # Systemctl stop pki-tomcatd@pki-ca.service
Systemctl stop pki-tomcatd@<ca_instance_name>.service
e.g.
# Systemctl stop pki-tomcatd@pki-ca.serviceExport KRA’s transport certificate into a file
- Find and export KRA transport cert:
grep "kra.transport.cert=" /var/lib/pki/<kra_instance_name>/kra/conf/CS.cfg | sed 's/kra.transport.cert=//' > <kra transport cert file> e.g. # grep "kra.transport.cert=" /var/lib/pki/pki-kra/kra/conf/CS.cfg | sed 's/kra.transport.cert=//' > /tmp/kraTransport.cert
grep "kra.transport.cert=" /var/lib/pki/<kra_instance_name>/kra/conf/CS.cfg | sed 's/kra.transport.cert=//' > <kra transport cert file>
e.g.
# grep "kra.transport.cert=" /var/lib/pki/pki-kra/kra/conf/CS.cfg | sed 's/kra.transport.cert=//' > /tmp/kraTransport.certImport KRA’s transport cert into CA’s nssdb, using the nickname specified in CA’s CS.cfg
- List the transport cert nickname:
grep "ca.connector.KRA.transportCertNickname" /var/lib/pki/<ca_instance_name>/ca/conf/CS.cfg e.g. # grep "ca.connector.KRA.transportCertNickname" /var/lib/pki/pki-ca/ca/conf/CS.cfg ca.connector.KRA.transportCertNickname=KRA transport cert
grep "ca.connector.KRA.transportCertNickname" /var/lib/pki/<ca_instance_name>/ca/conf/CS.cfg
e.g.
# grep "ca.connector.KRA.transportCertNickname" /var/lib/pki/pki-ca/ca/conf/CS.cfg
ca.connector.KRA.transportCertNickname=KRA transport cert- Import using the nickname listed from above step:
certutil -d /var/lib/pki/<ca_instance_name>/alias -A -t “,,” -n <transportNickName> -i <kra transport cert file> e.g. # certutil -d /var/lib/pki/pki-ca/alias -A -t “,,” -n "KRA transport cert" -i /tmp/kraTransport.cert
certutil -d /var/lib/pki/<ca_instance_name>/alias -A -t “,,” -n <transportNickName> -i <kra transport cert file>
e.g.
# certutil -d /var/lib/pki/pki-ca/alias -A -t “,,” -n "KRA transport cert" -i /tmp/kraTransport.certStart CA
systemctl start pki-tomcatd@<ca_instance_name>.service e.g. # Systemctl start pki-tomcatd@pki-ca.service
systemctl start pki-tomcatd@<ca_instance_name>.service
e.g.
# Systemctl start pki-tomcatd@pki-ca.service13.8.4. Profile Configuration
Two default profiles, caServerKeygen_UserCert and caServerKeygen_DirUserCert, are provided by default to allow for certificate enrollments where keys are generated on the server side. However, any profile with the right input, output, and policy set could be turned into a server-side keygen profile.
A Server-Side Keygen profile must contain the following components.
13.8.4.1. Input
input.i1.class_id=serverKeygenInputImpl
input.i1.class_id=serverKeygenInputImpl13.8.4.2. Output
output.o1.class_id=pkcs12OutputImpl
output.o1.class_id=pkcs12OutputImpl13.8.4.3. Policyset
Password for the generated PKCS12 can be enforced with the following policy:
This policy allows to set:
-
password.minSize- the minimum size for the passwor`d; -
password.minUpperLetter- the minimum number of capital letters; -
password.minLowerLetter- the minimum number of lower letters; -
password.minNumber- the minimum number of digits; -
password.minSpecialChar- the minimum number of punctuation characters; -
password.seqLength- the size of substring sequence which cannot be repeated; -
password.maxRepeatedChar- maximum number of repeating for each character;
If the constraint does not include specific configuration, it reads the options from the CS.cfg. In the case the name is different, the prefix password. is replaced by passwordChecker.. The configuration in CS.cfg are used for all the passwords but each profile can overwrite to allow stronger or weaker passwords.
Key type and key size parameters can be configured as exemplified below:
13.8.4.4. Authentication
The two default server-side keygen enrollment profiles different in the authentication mechanism, where
- caServerKeygen_UserCert.cfg
- contains empty value to "auth.class_id=", meaning that enrollment requests through this profile will require approval from a CA agent.
- caServerKeygen_DirUserCert.cfg
- contains "auth.instance_id=UserDirEnrollment", meaning that the user is required to pass LDAP uid/password authentication; Such authentication mechanism is considered as an automatic certificate issuance as it does not require per-request approval from a CA agent.
Automatic approval could be configured by setting the auth.instance_id directive to any compatible authentication plugin class, as examplified in the caServerKeygen_DirUserCert.cfg profile mentioned above. Here is an example of such configuration in CS.cfg:
13.8.5. Enrolling a Certificate Using Server-Side Keygen
The default Sever-Side Keygen enrollment profile can be found on the EE page, under the “List Certificate Profiles” tab:
13.8.5.1. Manual User Dual-Use Certificate Enrollment Using server-side Key generation
Figure 13.2. Server-Side Keygen Enrollment that requires agent manual approval
13.8.5.2. Directory-authenticated User Dual-Use Certificate Enrollment Using server-side Key generation
Figure 13.3. Server-Side Keygen Enrollment that will be automatically approved upon successful LDAP uid/pwd authentication
Regardless of how the request is approved, the Server-Side Keygen Enrollment mechanism requires the End Entity user to enter a password for the PKCS#12 package which will contain the issued certificate as well as the encrypted private key generated by the server once issued.
Users should not share their passwords with anyone. Not even the CA or KRA agents.
When the enrollment request is approved, the PKCS#12 package will be generated and,
- In case of manual approval, the PKCS#12 file will be returned to the CA agent that approves the request; The agent is then expected to forward the PKCS#12 file to the user.
- In case of automatic approval, the PKCS#12 file will be returned to the user who submitted the request
Figure 13.4. Enrollment manually approved by an agent
Once the PKCS#12 is received, the user could use cli such as pkcs12util to import the PKCS#12 file into her/her own user internal cert/key database for each application. E.g. the user’s Firefox nss database.
13.8.6. Key Recovery
If the enableArchival parameter is set to true in the certificate enrollment profile, then the private keys are archived at the time of Server-Side Keygen enrollment. The archived private keys could then be recovered by the authorized KRA agents.
13.8.7. Additional Information
13.8.7.1. KRA Request Records
due to the nature of this mechanism, in case when enableArchival parameter is set to true in the profile, there are two KRA requests records per Server-Side keygen request:
One for request type “asymkeyGenRequest”
- This request type cannot be filtered at “List Requests” on KRA agent page; One could select “Show All Requests” to see them listed.
- One for request type “recovery”
13.8.7.2. Audit Records
Some audit records could be observed if enabled:
CA
- SERVER_SIDE_KEYGEN_ENROLL_KEYGEN_REQUEST
- SERVER_SIDE_KEYGEN_ENROLL_KEY_RETRIEVAL_REQUEST
KRA
- SERVER_SIDE_KEYGEN_ENROLL_KEYGEN_REQUEST_PROCESSED
- SERVER_SIDE_KEYGEN_ENROLL_KEY_RETRIEVAL_REQUEST_PROCESSED (not yet implemented)
13.9. Configuring Certificate Transparency
Certificate System provides a basic version of Certificate Transparency (CT) V1 support (rfc 6962). It has the capability of issuing certificates with embedded Signed Certificate Time stamps (SCTs) from any trusted log where each deployment site choses to have its root CA cert included. You can also configure the system to support multiple CT logs. A minimum of one trusted CT log is required for this feature to work.
It is the responsibility of the deployment site to establish its trust relationship with a trusted CT log server.
To configure Certificate Transparency, edit the CA’s CS.cfg file located in the /var/lib/pki/instance name/ca/conf/CS.cfg directory.
For more information on how to test your Certificate Transparency setup, see the Testing Certificate Transparency section in the Red Hat Certificate System Administration Guide.
13.9.1. ca.certTransparency.mode
The ca.certTransparency.mode specifies one of three Certificate Transparency modes:
- disabled: issued certs will not carry the SCT extension
- enabled: issued certs will carry the SCT extension
-
perProfile: certs enrolled through those profiles that contain the following policyset will carry the SCT extension:
SignedCertificateTimestampListExtDefaultImpl
The default value is disabled.
13.9.2. ca.certTransparency.log.num
ca.certTransparency.log.num specifies the total number of CT logs defined in the configuration.
Not all CT log entries that are defined are considered active; see ca.certTransparency.log.id.enable in Section 13.9.3, “ca.certTransparency.log.id.*”.
13.9.3. ca.certTransparency.log.id.*
ca.certTransparency.log.id.* specifies information pertaining to the log id, where id is a unique id you assign to the CT log server to differentiate it from other CT logs.
The parameter names follow each ca.certTransparency.log.id. and belong to the id:
- ca.certTransparency.log.id.enable specifies whether the id CT log is enabled (true) or disabled (false).
- ca.certTransparency.log.id.pubKey contains the base64 encoding of the CT log’s public key.
- ca.certTransparency.log.id.url contains the base64 encoding of the CT log url.
- ca.certTransparency.log.id.version specifies the CT version number that the CT supports (as well as the CT log server); it currently only supports version 1.
Chapter 14. Managing certificate/key crypto token
This chapter contains instructions on how to manage certificate/key token database on the crypto tokens, specifically on how to import and verify certificates for various scenarios.
- For information about NSS soft token, please see Section 2.3.7.1, “NSS soft token (internal token)”.
- For information about HSM, please see Section 2.3.7.2, “Hardware security module (HSM, external token)”.
14.1. About certutil and PKICertImport
The certutil command is provided by Network Security Services (NSS). certutil is used for validating and importing certificates. A basic overview of how we use certutil is presented below, however, PKICertImport is our wrapper script of choice for safely validating and importing certificates. Using certutil to do so requires multiple command invocations and correct usage is outside the scope of this documentation.
14.1.1. certutil basic usage
certutil [command] [opt][options]
Each certutil invocation takes a command flag, usually denoted by a capital letter, and a series of options which control what the command does. If an option takes a value, that value is named between "<" and ">" symbols.
14.1.2. PKICertImport basic usage
PKICertImport [opt][options]
Each PKICertImport invocation takes a series of options to validate and import a specified certificate. Unlike the broad use cases of certutil, PKICertImport is only focused on safely importing and validating certificates. See Section 14.1.4, “Common certutil and PKICertImport options” for more information about available options.
PKICertImport prompts for the NSS DB and/or HSM passwords multiple times throughout the course of its execution. This is expected as PKICertImport has to interact with the NSS DB multiple times. To avoid having to input the NSS DB password repetitively, specify a password file via -f <filename>. When done, be sure to delete the password file.
14.1.3. certutil common commands
The following commands are specific to certutil and provide a brief overview of several common commands. PKICertImport is not compatible with nor require these command flags.
certutil -A
The -A command denotes "adding" a certificate. It requires a certificate to import (-i), a nickname (-n) for that certificate, and a series of trust flags (-t) for the certificate.
certutil -V
The -V command denotes "verifying" a certificate. It requires a certificate nickname to validate (-n) and a type of verification (-u) to perform.
certutil -D
The -D command denotes "deleting" a certificate. It requires a certificate nickname (-n) to remove.
Note that it ONLY removes the PUBLIC KEY portion of the certificate, and WILL NOT remove any private keys, if present.
certutil -M
The -M command denotes "modifying" a certificate. It requires a certificate nickname (-n) to modify, and a series of trust flags (-t) to give the certificate.
certutil -L
The -L command denotes "listing" a certificate or all certificates. If given the nickname option (-n), it will list detailed information about that certificate, else if omitted, it will list general information about all certificates present.
The result of certutil -L would show each certificate by its nickname along with its trust info. For example:
| Certificate Nickname | Trust Attributes SSL, S/MIME, JAR/XPI |
|---|---|
| caSigningCert pki-ca1 | CT, C, C |
The trust attributes displayed by certutil -L correspond to what is specified with the -t option.
The certutil -L does not modify the database, and can thus be executed safely as many times as desired.
14.1.4. Common certutil and PKICertImport options
When following the steps below, ensure the values are relevant and correct for your specific deployment scenario. Many of these options are available to PKICertImport as well.
-n <nickname>
The -n <nickname> option specifies the nickname for a certificate. This can be any text and is only used as a reference to the certificate. It MUST be unique.
Update this value as appropriate for your configuration.
-d <directory>
The -d <directory> option specifies the path to the NSS DB directory in use. We usually assume you are already in this directory and use "." to refer to the current directory.
Update this value as appropriate for your configuration.
-t <trust>
The -t <trust> option specifies the trust level for the certificate.
There are three main categories of trust:
- trust for TLS
- trust for email
- trust for object signing
Each trust position can have one or more trust letters which specify the desired level of trust. The trust letters we use below are c, C, and T.
-
cstates that this certificate should be a Certificate Authority (CA). -
Cstates that this is a trusted certificate authority for signing server certificates (Cimplies lowercasec, hence you do not need to specify both). -
Tstates that this certificate is a trusted authority for signing client certificates (Timplies lowercasec, hence you do not need to specify bothTandc).
To specify the trust flags for each position, join the letters with commas. For example, the option -t CT,C,c means that the certificate is trusted for signing client and server TLS certificates, signing server email certificates (S/MIME), and is a valid CA for object signing (though untrusted).
- This ensures that, if this certificate signs another certificate, which in turn is used for object signing, it will be deemed invalid.
No trust (or the lack of trust) can be specified by using -t ,,.
To see the trust levels of all certificates in the database, run:
-
certutil -L -d - Each certificate’s nickname will be listed and the trust flags will be specified at the end of the line.
See the notes about HSMs in the -h option.
Note that more trust levels are specified in the certutil manpage. To reference this documentation, please run the man certutil command on a system with certutil properly installed.
-h <HSM>
The -h <HSM> option specifies the name of the HSM to perform operations on.
-h option is incompatible with the -t option, as HSMs cannot store trust. Only an NSS DB can store trust, so using the certutil -A command or the certutil -M command in conjunction with -h <HSM> will fail. Instead, specify the desired trust level on a separate certutil -M command without the -h option.
Update this value as appropriate for your configuration.
-e
The -e option specifies that the validity of the signature is checked as well, when used in conjunction with the certutil -V command. PKICertImport always performs the certificate signature validation and does not understand the -e option.
-a
The -a option specifies that the key in question is in PEM (ASCII) format.
-i <certificate>
The -i <certificate> option specifies the path to the certificate. This is only used in the certutil -A command to specify the path to the certificate to import.
Update this value as appropriate for your configuration.
-u <usage>
The -u <usage> option specifies that usage of the certificate to verify when used in conjunction with the certutil -V command.
There are several usage letters referenced in the following sections.
-
-u Cstands for verify a client TLS certificate. Note that this mostly accepts any certificate, but will check expiration date and signature. -
-u Vstands for verify a server TLS certificate. Note that this will reject CA certificates and will check expiration date and signature. -
-u Lstands for verify a CA TLS certificate. Note that this will validate trust flags (to see ifcis present) and will check key usage to ensure that the key is a CA key. This also checks expiration and signatures. -
-u Ostands for verify a OCSP status responder certificate. Note that this checks expiry and signatures. -
-u Jstands for verify an object signing certificate. Note that this checks expiry and signatures.
If the wrong usage option is specified or the trust flags on the certificate are wrong (such as a missing c flag for an CA TLS certificate), certutil -V will give incorrect results.
More usage options are specified in the certutil manpage. To reference this documentation, run the man certutil command on a system with certutil properly installed.
14.2. Importing a root certificate
Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS DB by other processes (such as a browser). Doing so may corrupt the NSS DB or result in improper usage of these certificates.
When needing to import a new root certificate, ensure you acquire this certificate in a secure manner as it will be able to sign a number of certificates. We assume you already have it in a file named ca_root.crt. Please substitute the correct name and path to this file as appropriate for your scenario.
For more information about the certutil and PKICertImport options used below, see Section 14.1, “About certutil and PKICertImport”.
Procedure
First, change directories into the NSS DB:
cd /path/to/nssdb
cd /path/to/nssdbCopy to Clipboard Copied! Toggle word wrap Toggle overflow To import the root certificate:
PKICertImport -d . -n "CA Root" -t "CT,C,C" -a -i ca_root.crt -u L
PKICertImport -d . -n "CA Root" -t "CT,C,C" -a -i ca_root.crt -u LCopy to Clipboard Copied! Toggle word wrap Toggle overflow This command validates and imports the root certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate because it is expired or because it is not a CA certificate. Therefore, make sure your certificate file is correct and up-to-date. Contact the issuer and ensure that all intermediate and root certificates are present on your system.
14.3. Importing an intermediate certificate chain
Ensure that your web service is offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS DB by other processes (such as a browser). Doing so may corrupt the NSS DB or result in improper usage of these certificates.
If you have not imported and trusted the root certificate, see Section 14.2, “Importing a root certificate”.
When given a series of intermediate certificates between your root and end server or client certificates, we need to import and validate the signed certificate chain in order from closest to furthest from the root CA certificate. We assume the Intermediate CAs are in files named ca_sub_<num>.crt (for example ca_sub_1.crt, ca_sub_2.crt, and so on). Substitute names and paths for your certificates as appropriate to your deployment.
In the unlikely scenario that you are instead given a single file named fullchain.crt, fullchain.pem, or similar and it contains multiple certificates, split it into the above format by copying each block (between and including the ----BEGIN CERTIFICATE----- and an -----END CERTIFICATE----- markers) to its own file. The first ones should be named ca_sub_<num>.crt and the last will be your server cert named service.crt. Server certificates are discussed in later sections.
First, we will import and validate any intermediate CAs in order of closest to furthest from the root CA certificate. If you don’t have any, you can skip to the next section.
For more information about the certutil and PKICertImport options used below, see Section 14.1, “About certutil and PKICertImport”.
Procedure
Before beginning, please change directories into the NSS DB:
cd /path/to/nssdb
cd /path/to/nssdbCopy to Clipboard Copied! Toggle word wrap Toggle overflow For every intermediate certificate in the chain, run the following command:
PKICertImport -d . -n "CA Sub $num" -t "CT,C,C" -a -i ca_sub_$num.crt -u L
PKICertImport -d . -n "CA Sub $num" -t "CT,C,C" -a -i ca_sub_$num.crt -u LCopy to Clipboard Copied! Toggle word wrap Toggle overflow This command validates and imports the Intermediate CA certificate into your NSS DB. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
14.4. Importing a certificate into an HSM
This procedure describes how to import a certificate into an HSM after gaining a newly issued certificate (such as when a system certificate is renewed) whose keys were generated on the same HSM token as the process of creating a CSR.
Before beginning, please change directories into the NSS DB:
-
cd /path/to/nssdbfor examplecd /var/lib/pki/pki-ca/alias
Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS DB by other processes (such as a browser). Doing so may corrupt the NSS DB or result in improper usage of these certificates.
If you have not imported and trusted the root certificate, see Section 14.2, “Importing a root certificate”. If you have not imported and validated the intermediate certificates, see Section 14.3, “Importing an intermediate certificate chain”.
Note that which set of instructions you follow will depend on the usage for the certificate in question.
- For TLS server certs for all PKI substems, follow the server certificate steps.
- For any subsystem’s audit signing cert, follow the steps below for validating an object Signing certificate.
-
For the CA subsystem’s signing cert, follow the steps above for importing and validating an intermediate certificate chain, but do so only with the
caSigningCert. - For the CA subsystem’s OCSP signing cert, follow the steps below for validating an OCSP certificate.
- For all other system certs of the PKI subsystems, follow the Client Certificate steps.
For more information about the certutil and PKICertImport options used below, see Section 14.1, “About certutil and PKICertImport”.
To import a server certificate on the HSM:
Execute
PKICertImport -d . -h HSM -n "host.name.example.com" -t ",," -a -i service.crt -u VThis command validates and imports the server certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. The certificate usually fails to validate due to expiry of a parent certificate or a missing CA trust chain (such as a missing intermediate certificate or a missing CA Root). If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
To import a client certificate on the HSM:
Execute
PKICertImport -d . -h HSM -n "client name" -t ",," -a -i client.crt -u CThis command validates and imports the client certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
To import an object signing certificate on the HSM:
Execute
PKICertImport -d . -h HSM -n "certificate name" -t ",,P" -a -i objectsigning.crt -u JThis command validates and imports the object signing certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
To import an OCSP response signing certificate on the HSM:
Execute
PKICertImport -d . -h HSM -n "certificate name" -t ",," -a -i ocsp.crt -u OThis command validates and imports the OCSP responder certificate onto the HSM. The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
14.5. Importing a certificate into an NSS database
Ensure that your web service is taken offline (stopped, disabled, etc.) while performing these steps and ensure no concurrent access to the NSS database by other processes (such as a browser). Doing so may corrupt the NSS database or result in improper usage of these certificates.
Note that which set of instructions you follow will depend on the usage for the certificate in question.
-
For any subsystem’s
auditSigningCert, please follow the steps below for validating an object Signing certificate. -
For the CA subsystem’s
caSigningCert, please follow the steps above for importing and validating an intermediate certificate chain, but do so only with the caSigningCert. -
For the CA subsystem’s
ocspSigningCert, please follow the steps below for validating an OCSP certificate. - For user’s client or S/MIME certificate, follow the Client Certificate steps.
For more information about the certutil and PKICertImport options used below, see Section 14.1, “About certutil and PKICertImport”.
Importing a client certificate into the NSS database
To import a client certificate into the NSS database:
Change into the NSS database directory. For example:
cd /path/to/nssdb/
# cd /path/to/nssdb/Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 14.2, “Importing a root certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 14.3, “Importing an intermediate certificate chain”.
Validate and import the client certificate:
PKICertImport -d . -n "client name" -t ",," -a -i client.crt -u C
# PKICertImport -d . -n "client name" -t ",," -a -i client.crt -u CCopy to Clipboard Copied! Toggle word wrap Toggle overflow The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Importing an object signing certificate
To import an object signing certificate:
Change into the NSS database directory. For example:
cd /path/to/nssdb/
# cd /path/to/nssdb/Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 14.2, “Importing a root certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 14.3, “Importing an intermediate certificate chain”.
Validate and import the object signing certificate:
PKICertImport -d . -n "certificate name" -t ",,P" -a -i objectsigning.crt -u J
# PKICertImport -d . -n "certificate name" -t ",,P" -a -i objectsigning.crt -u JCopy to Clipboard Copied! Toggle word wrap Toggle overflow The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Importing an OCSP responder
To import an OCSP responder:
Change into the NSS database directory. For example:
cd /path/to/nssdb/
# cd /path/to/nssdb/Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Import and trust the root certificate, if it is not already imported and trusted. For details, see Section 14.2, “Importing a root certificate”.
- Import and validate the intermediate certificates, if not already imported and validated. For details, see Section 14.3, “Importing an intermediate certificate chain”.
Validate and import the OCSP responder certificate:
PKICertImport -d . -n "certificate name" -t ",," -a -i ocsp.crt -u O
# PKICertImport -d . -n "certificate name" -t ",," -a -i ocsp.crt -u OCopy to Clipboard Copied! Toggle word wrap Toggle overflow The validation succeeds when no error message is printed and the return code is 0. To check the return code, execute
echo $?immediately after executing the previous command above. In most cases, a visual error message is printed. If the validation does not succeed, contact the issuer and ensure that all intermediate and root certificates are present on your system.
Chapter 15. Configuring certificate profiles
As part of the installation process of a CA, the certificate enrollment profiles can be modified directly on the file system by modifying the profiles' configuration files. Default files exist for the default profiles at installation; when new profiles are needed, new profile configuration files are to be created. The configuration files are stored in the CA profile directory, instance_directory/ca/profiles/ca/, such as /var/lib/pki/pki-ca/ca/profiles/ca/. The file is named profile_name.cfg. All of the parameters for profile rules can be set or modified in those profile configuration files. Profile rules can be inputs, outputs, authentication, authorization, defaults, and constraints.
The enrollment profiles for the CA certificates are located in the /var/lib/pki/ instance_name/ca/conf directory with the name *.profile.
For audit reasons, use this method only during the CA installation prior to deployment.
Restart the server after editing the profile configuration file for the changes to take effect.
15.1. Configuring non-CA system certificate profiles
15.1.1. Profile configuration parameters
All of the parameters for a profile rule - defaults, inputs, outputs, and constraints - are configured within a single policy set. A policy set for a profile has the name policyset.policyName.policyNumber. For example:
policyset.cmcUserCertSet.6.constraint.class_id=noConstraintImpl policyset.cmcUserCertSet.6.constraint.name=No Constraint policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl policyset.cmcUserCertSet.6.default.name=User Supplied Key Default policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15
policyset.cmcUserCertSet.6.constraint.class_id=noConstraintImpl
policyset.cmcUserCertSet.6.constraint.name=No Constraint
policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl
policyset.cmcUserCertSet.6.default.name=User Supplied Key Default
policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15The common profile configuration parameters are described in Table 15.1, “Profile configuration file parameters”.
| Parameter | Description |
|---|---|
| desc | Gives a free text description of the certificate profile, which is shown on the end-entities page. For example, desc=This certificate profile is for enrolling server certificates with agent authentication. |
| enable | Sets whether the profile is enabled, and therefore accessible through the end-entities page. For example, enable=true. |
| auth.instance_id |
Sets which authentication manager plug-in to use to authenticate the certificate request submitted through the profile. For automatic enrollment, the CA issues a certificate immediately if the authentication is successful. If authentication fails or there is no authentication plug-in specified, the request is queued to be manually approved by an agent. For example, auth.instance_id=CMCAuth. The authentication method must be one of the registered authentication instances from |
| authz.acl | Specifies the authorization constraint. Most commonly, this us used to set the group evaluation ACL. For example, this caCMCUserCert parameter requires that the signer of the CMC request belong to the Certificate Manager Agents group: authz.acl=group="Certificate Manager Agents" In directory-based user certificate renewal, this option is used to ensure that the original requester and the currently-authenticated user are the same.
An entity must authenticate (bind or, essentially, log into the system) before authorization can be evaluated. The authorization method specified must be one of the registered authorization instances from |
| name | Gives the name of the profile. For example, name=Agent-Authenticated Server Certificate Enrollment. This name is displayed in the end users enrollment or renewal page. |
| input.list | Lists the allowed inputs for the profile by name. For example, input.list=i1,i2. |
| input.input_id.class_id | Gives the java class name for the input by input ID (the name of the input listed in input.list). For example, input.i1.class_id=cmcCertReqInputImpl. |
| output.list | Lists the possible output formats for the profile by name. For example, output.list=o1. |
| output.output_id.class_id | Gives the java class name for the output format named in output.list. For example, output.o1.class_id=certOutputImpl. |
| policyset.list | Lists the configured profile rules. For dual certificates, one set of rules applies to the signing key and the other to the encryption key. Single certificates use only one set of profile rules. For example, policyset.list=serverCertSet. |
| policyset.policyset_id.list | Lists the policies within the policy set configured for the profile by policy ID number in the order in which they should be evaluated. For example, policyset.serverCertSet.list=1,2,3,4,5,6,7,8. |
| policyset._policyset_id.policy_number._constraint.class_id | Gives the java class name of the constraint plug-in set for the default configured in the profile rule. For example, policyset.serverCertSet.1.constraint.class_id=subjectNameConstraintImpl. |
| policyset._policyset_id.policy_number._constraint.name | Gives the user-defined name of the constraint. For example, policyset.serverCertSet.1.constraint.name=Subject Name Constraint. |
| policyset.policyset_id.policy_number._constraint.params._attribute | Specifies a value for an allowed attribute for the constraint. The possible attributes vary depending on the type of constraint. For example, policyset.serverCertSet.1.constraint.params.pattern=CN=.*. |
| policyset._policyset_id.policy_number._default.class_id | Gives the java class name for the default set in the profile rule. For example, policyset.serverCertSet.1.default.class_id=userSubjectNameDefaultImpl |
| policyset._policyset_id.policy_number._default.name | Gives the user-defined name of the default. For example, policyset.serverCertSet.1.default.name=Subject Name Default |
| policyset.policyset_id.policy_number._default.params._attribute | Specifies a value for an allowed attribute for the default. The possible attributes vary depending on the type of default. For example, policyset.serverCertSet.1.default.params.name=CN=(Name)$request.requestor_name$. |
15.1.2. Modifying certificate extensions directly on the file system
Changing constraints changes the restrictions on the type of information which can be supplied. Changing the defaults and constraints can also add, delete, or modify the extensions which are accepted or required from a certificate request.
For example, the default caFullCMCUserCert profile is set to create a Key Usage extension from information in the request.
The default is updated to allow user-supplied key extensions:
policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl policyset.cmcUserCertSet.6.default.name=User Supplied Key Default policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15
policyset.cmcUserCertSet.6.default.class_id=userExtensionDefaultImpl
policyset.cmcUserCertSet.6.default.name=User Supplied Key Default
policyset.cmcUserCertSet.6.default.params.userExtOID=2.5.29.15
This sets the server to accept the extension OID 2.5.29.15 in the certificate request.
Other constraints and defaults can be changed similarly. Make sure that any required constraints are included with appropriate defaults, that defaults are changed when a different constraint is required, and that only allowed constraints are used with the default. For more information, see the Defaults Reference section and the Constraints Reference section in the Red Hat Certificate System Administration Guide.
15.1.2.1. key usage and extended key usage consistency
Red Hat Certificate System provides a flexible infrastructure for administrators to create customized enrollment profiles to meet the requirements of their environment. However, it is important that profiles do not allow issuing certificates that violate the requirements defined in RFC 5280. When creating an enrollment profile where both Key Usage (KU) and Extended Key Usage (EKU) extensions are present, it is important to make sure that the consistency between the two extensions is maintained as per section 4.2.1.12. Extended Key Usage of RFC 5280.
For details about the KU extension, see:
The following table provides the guidelines that maps consistent Key Usage bits to the Extended Key Usage Extension for each purpose:
| Purpose / Extended Key Usages | Key Usages |
|---|---|
| TLS Server Authentication command
|
|
| TLS Client (Mutual) Authentication
|
|
| Code Signing
|
|
| Email Protection
|
|
| OCSP Response Signing
|
|
The following shows two examples of inconsistent EKU/KU:
An enrollment profile that is intended for purpose of OCSP response signing contains Extended key usage
id-kp-OCSPSigningbut withkeyEnciphermentkey usage bit:Copy to Clipboard Copied! Toggle word wrap Toggle overflow An enrollment profile that is intended for the purpose of TLS server authentication contains Extended key
usage id-kp-serverAuthbut with CRL signing key usage bit:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - The Extended Key Usage Extension Constraint section in the Red Hat Certificate System Administration Guide.
- The keyUsage section in the Red Hat Certificate System Administration Guide.
For details about the EKU extension, see:
- The Extended Key Usage Extension Constraint section in the Red Hat Certificate System Administration Guide.
- The extKeyUsage section in the Red Hat Certificate System Administration Guide.
15.1.2.2. Configuring cross-pair profiles
Cross-pair certificates are distinct CA signing certificates that establish a trust partner relationship whereby entities from these two distinct PKIs will trust each other. Both partner CAs store the other CA signing certificate in its database, so all of the certificates issued within the other PKI are trusted and recognized.
Two extensions supported by the Certificate System can be used to establish such a trust partner relationship (cross-certification):
-
The Certificate Policies Extension (
CertificatePoliciesExtension) specifies the terms that the certificate fall under, which is often unique for each PKI. -
The Policy Mapping Extension (
PolicyMappingExtension) seals the trust between two PKI’s by mapping the certificate profiles of the two environments.
Issuing cross-pair certificates requires the Certificate Policies Extension, explained in certificatePoliciesExt annex in the Red Hat Certificate System Administration Guide.
To ensure that the issued certificate contains the CertificatePoliciesExtension, the enrollment profile needs to include an appropriate policy rule, for example:
Certificates issued with the enrollment profile in this example would contain the following information:
Identifier: Certificate Policies: - 2.5.29.32 Critical: no Certificate Policies: Policy Identifier: 1.1.1.1
Identifier: Certificate Policies: - 2.5.29.32
Critical: no
Certificate Policies:
Policy Identifier: 1.1.1.1For more information on using cross-pair certificates, see the Using Cross-Pair Certificates section in the Red Hat Certificate System Administration Guide.
For more information on publishing cross-pair certificates, see the see the Publishing Cross-Pair Certificates section in the Red Hat Certificate System Administration Guide.
15.1.3. Adding profile inputs directly on the file system
The certificate profile configuration file in the CA’s profiles/ca directory contains the input information for that particular certificate profile form. Inputs are the fields in the end-entities page enrollment forms. There is a parameter, input.list, which lists the inputs included in that profile. Other parameters define the inputs; these are identified by the format input.ID. For example, this adds a generic input to a profile:
For more information on what inputs, or form fields, are available, see the Input Reference section in the Red Hat Certificate System Administration Guide.
15.2. Changing the default validity time of certificates
In each profile on a Certificate Authority (CA), you can set how long certificates issued using a profile are valid. You can change this value for security reasons.
For example, to set the validity of the generated Certificate Authority (CA) signing certificate to 825 days (approximately 27 months), open the /var/lib/pki/ instance_name/ca/profiles/ca/caCACert.cfg file in an editor and set:
policyset.caCertSet.2.default.params.range=825
policyset.caCertSet.2.default.params.range=82515.3. Configuring CA system certificate profiles
Unlike the non-CA subsystems, the enrollment profiles for CA’s own system certificates are kept in the /var/lib/pki/[instance name]/ca/conf file. Those profiles are:
-
caAuditSigningCert.profile -
eccAdminCert.profile -
rsaAdminCert.profile -
caCert.profile -
eccServerCert.profile -
saServerCert.profile -
caOCSPCert.profile -
eccSubsystemCert.profile -
rsaSubsystemCert.profile
If you wish to change the default values in the profiles above, make changes to the profiles before <<_installation_methods> procedure is performed. The following is an example that demonstrates:
- How to change validity to CA signing certificate.
How to add extensions (e.g. Certificate policies extension).
Back up the original CA certificate profile used by
pkispawn.cp -p /usr/share/pki/ca/conf/caCert.profile /usr/share/pki/ca/conf/caCert.profile.orig
# cp -p /usr/share/pki/ca/conf/caCert.profile /usr/share/pki/ca/conf/caCert.profile.origCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the CA certificate profile used by the configuration wizard.
vim /usr/share/pki/ca/conf/caCert.profile
# vim /usr/share/pki/ca/conf/caCert.profileCopy to Clipboard Copied! Toggle word wrap Toggle overflow Reset the validity period in the Validity Default to whatever you want. For example, to change the period to two years:
2.default.class=com.netscape.cms.profile.def.ValidityDefault 2.default.name=Validity Default 2.default.params.range=7200
2.default.class=com.netscape.cms.profile.def.ValidityDefault 2.default.name=Validity Default 2.default.params.range=7200Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add any extensions by creating a new default entry in the profile and adding it to the list. For example, to add the Certificate Policies Extension, add the default (which, in this example, is default #9):
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Then, add the default number to the list of defaults to use the new default:
list=2,4,5,6,7,8,9
list=2,4,5,6,7,8,9Copy to Clipboard Copied! Toggle word wrap Toggle overflow
15.4. Managing smart card CA profiles
Features in this section on TMS are not tested in the evaluation. This section is for reference only.
The TPS does not generate or approve certificate requests; it sends any requests approved through the Enterprise Security Client to the configured CA to issue the certificate. This means that the CA actually contains the profiles to use for tokens and smart cards. The profiles to use can be automatically assigned, based on the card type.
The profile configuration files are in the /var/lib/ instance_name/ca/profiles/ca/ directory with the other CA profiles. The default profiles are listed in Table 15.2, “Default token certificate profiles”.
| Profile Name | Configuration File | Description |
|---|---|---|
|
| Token Device Key Enrollment | caTokenDeviceKeyEnrollment.cfg |
| For enrolling tokens used for devices or servers. | Token User Encryption Certificate Enrollment | caTokenUserEncryptionKeyEnrollment.cfg |
| For enrolling encryption certificates on the token for a user. | Token User Signing Certificate Enrollment | caTokenUserSigningKeyEnrollment.cfg |
| For enrolling signing certificates on the token for a user. | Token User MS Login Certificate Enrollment | caTokenMSLoginEnrollment.cfg |
| For enrolling user certificates to use for single sign-on to a Windows domain or PC. |
| Temporary Device Certificate Enrollment |
| caTempTokenDeviceKeyEnrollment.cfg | For enrolling certificates for a device on a temporary token. | Temporary Token User Encryption Certificate Enrollment |
| caTempTokenUserEncryptionKeyEnrollment.cfg | For enrolling an encryption certificate on a temporary token for a user. | Temporary Token User Signing Certificate Enrollment |
| caTempTokenUserSigningKeyEnrollment.cfg | For enrolling a signing certificates on a temporary token for a user. |
|
| Token User Encryption Certificate Enrollment (Renewal) | caTokenUserEncryptionKeyRenewal.cfg | For renewing encryption certificates on the token for a user, if renewal is allowed. |
| Token User Signing Certificate Enrollment (Renewal) | caTokenUserSigningKeyRenewal.cfg | For renewing signing certificates on the token for a user, if renewal is allowed. |
15.4.1. Editing enrollment profiles for the tps
Administrators have the ability to customize the default smart card enrollment profiles, used with the TPS. For instance, a profile could be edited to include the user’s email address in the Subject Alternative Name extension. The email address for the user is retrieved from the authentication directory. To configure the CA for LDAP access, change the following parameters in the profile files, with the appropriate directory information:
These CA profiles come with LDAP lookup disabled by default. The ldapStringAttributes parameter tells the CA which LDAP attributes to retrieve from the company directory. For example, if the directory contains uid as an LDAP attribute name, and this will be used in the subject name of the certificate, then uid must be listed in the ldapStringAttributes parameter, and request.uid listed as one of the components in the dnpattern.
Editing certificate profiles is covered in the Setting up Certificate Profiles section in the Red Hat Certificate System Administration Guide.
The format for the dnpattern parameter is covered in the Subject Name Constraint section and the Subject Name Default section in the Red Hat Certificate System Administration Guide.
15.4.2. Creating custom TPS profiles
Certificate profiles are created as normal in the CA, but they also have to be configured in the TPS for it to be available for token enrollments.
New profiles are added with new releases of Red Hat Certificate System. If an instance is migrated to Certificate System 10.0, then the new profiles need to be added to the migrated instance as if they are custom profiles.
- Create a new token profile for the issuing CA. Setting up profiles is covered in the Setting up Certificate Profiles section in the Red Hat Certificate System Administration Guide.
-
Copy the profile into the CA’s profiles directory,
/var/lib/ instance_name/ca/profiles/ca/. Edit the CA’s
CS.cfgfile, and add the new profile references and the profile name to the CA’s list of profiles. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the TPS
CS.cfgfile, and add a line to point to the new CA enrollment profile. For example:vim /etc/pki/ instance_name/tps/CS.cfg
# vim /etc/pki/ instance_name/tps/CS.cfg op.enroll.userKey.keyGen.signing.ca.profileId=tpsExampleEnrollProfileCopy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the instance after editing the smart card profiles:
systemctl restart pki-tomcatd-nuxwdog@instance_name.service
# systemctl restart pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the CA and TPS are in separate instances, restart both instances.
Enrollment profiles for the External Registration (externalReg) setting are configured in the user LDAP entry.
15.4.3. Using the Windows smart card logon profile
The TPS uses a profile to generate certificates to use for single sign-on to a Windows domain or PC; this is the Token User MS Login Certificate Enrollment profile (caTokenMSLoginEnrollment.cfg).
However, there are some special considerations that administrators must account for when configuring Windows smart card login.
- Issue a certificate to the domain controller, if it is not already configured for TLS.
- Configure the smart card login per user, rather than as a global policy, to prevent locking out the domain administrator.
- Enable CRL publishing to the Active Directory server because the domain controller checks the CRL at every login.
15.5. Disabling certificate enrolment profiles
This section provides instructions on how to disable selected profiles.
To disable a certificate profile, edit the corresponding *.cfg file in the /var/lib/pki/ instance_name/ca/profiles/ca/ directory and set the visible and enable parameters to false.
For example, to disable all non-CMC profiles:
List all non-CMC profiles:
ls -l /var/lib/pki/ instance_name/ca/profiles/ca/ | grep -v "CMC"
# ls -l /var/lib/pki/ instance_name/ca/profiles/ca/ | grep -v "CMC"Copy to Clipboard Copied! Toggle word wrap Toggle overflow In each of the displayed files, set the following parameters to
false:visible=false enable=false
visible=false enable=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Additionally, set visible=false in all CMC profiles to make them invisible on the end entity page:
List all CMC profiles:
ls -l /var/lib/pki/ instance_name/ca/profiles/ca/CMC
# ls -l /var/lib/pki/ instance_name/ca/profiles/ca/CMCCopy to Clipboard Copied! Toggle word wrap Toggle overflow In each of the displayed files, set:
visible=false
visible=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 16. Configuring the Key Recovery Authority
This chapter describes recovering keys with the Key Recovery Authority (KRA).
16.1. Manually setting up key archival
This procedure is unnecessary if the CA and KRA are in the same security domain. This procedure is only required for CAs outside the security domain.
Configuring key archival manually demands two things:
- Having a trusted relationship between a CA and a KRA.
- Having the enrollment form enabled for key archival, meaning it has key archival configured and the KRA transport certificate stored in the form.
In the same security domain, both of these configuration steps are done automatically when the KRA is configured because it is configured to have a trusted relationship with any CA in its security domain. It is possible to create that trusted relationship with Certificate Managers outside its security domain by manually configuring the trust relationships and profile enrollment forms.
If necessary, create a trusted manager to establish a relationship between the Certificate Manager and the KRA.
For the CA to be able to request key archival of the KRA, the two subsystems must be configured to recognize, trust, and communicate with each other. Verify that the Certificate Manager has been set up as a privileged user, with an appropriate TLS client authentication certificate, in the internal database of the KRA. By default, the Certificate Manager uses its subsystem certificate for TLS client authentication to the KRA.
Copy the base-64 encoded transport certificate for the KRA.
The transport certificate is stored in the KRA’s certificate database, which can be retrieved using the
certutilutility. If the transport certificate is signed by a Certificate Manager, then a copy of the certificate is available through the Certificate Manager end-entities page in the Retrieval tab.Alternatively, download the transport certificate using the
pkiultility:pki cert-find --name "KRA Transport certificate's subject common name" pki cert-show serial_number --output transport.pem
# pki cert-find --name "KRA Transport certificate's subject common name" # pki cert-show serial_number --output transport.pemCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the transport certificate to the CA’s
CS.cfgfile.Copy to Clipboard Copied! Toggle word wrap Toggle overflow Then edit the enrollment form and add or replace the transport certificate value in the
keyTransportCertmethod.vim /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/ca/ProfileSelect.template
# vim /var/lib/pki/pki-tomcat/ca/webapps/ca/ee/ca/ProfileSelect.template var keyTransportCert = MIIDbDCCAlSgAwIBAgIBDDANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9Eb21haW4gc28gbmFtZWQxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0wNjExMTQxODI2NDdaFw0wODEwMTQxNzQwNThaMD4xGDAWBgNVBAoTD0RvbWFpbiBzbyBuYW1lZDEiMCAGA1UEAxMZRFJNIFRyYW5zcG9ydCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKnMGB3WkznueouwZjrWLFZBLpKt6TimNKV9iz5s0zrGUlpdt81/BTsU5A2sRUwNfoZSMs/d5KLuXOHPyGtmC6yVvaY719hr9EGYuv0Sw6jb3WnEKHpjbUO/vhFwTufJHWKXFN3V4pMbHTkqW/x5fu/3QyyUre/5IhG0fcEmfvYxIyvZUJx+aQBW437ATD99Kuh+I+FuYdW+SqYHznHY8BqOdJwJ1JiJMNceXYAuAdk+9t70RztfAhBmkK0OOP0vH5BZ7RCwE3Y/6ycUdSyPZGGc76a0HrKOz+lwVFulFStiuZIaG1pv0NNivzcj0hEYq6AfJ3hgxcC1h87LmCxgRWUCAwEAAaN5MHcwHwYDVR0jBBgwFoAURShCYtSg+Oh4rrgmLFB/Fg7X3qcwRAYIKwYBBQUHAQEEODA2MDQGCCsGAQUFBzABhihodHRwOi8vY2x5ZGUucmR1LnJlZGhhdC5jb206OTE4MC9jYS9vY3NwMA4GA1UdDwEB/wQEAwIE8DANBgkqhkiG9w0BAQUFAAOCAQEAFYz5ibujdIXgnJCbHSPWdKG0T+FmR67YqiOtoNlGyIgJ42fi5lsDPfCbIAe3YFqmF3wU472h8LDLGyBjy9RJxBj+aCizwHkuoH26KmPGntIayqWDH/UGsIL0mvTSOeLqI3KM0IuH7bxGXjlION83xWbxumW/kVLbT9RCbL4216tqq5jsjfOHNNvUdFhWyYdfEOjpp/UQZOhOM1d8GFiw8N8ClWBGc3mdlADQp6tviodXueluZ7UxJLNx3HXKFYLleewwIFhC82zqeQ1PbxQDL8QLjzca+IUzq6Cd/t7OAgvv3YmpXgNR0/xoWQGdM1/YwHxtcAcVlskXJw5ZR0Y2zA==;Copy to Clipboard Copied! Toggle word wrap Toggle overflow
16.2. Encryption of KRA operations
Certificate System encrypts the following key operations in the Key Recovery Authority (KRA):
Archival:
- Encryption of keys to archive in a Certificate Request Message Format (CRMF) package for transport to the KRA.
- Encryption of the key for storage in the KRA LDAP database.
Recovery:
- Encryption of a user-provided session key for transport to the key.
- Decryption of the secret and re-encryption using the user provided session key or creation of a PKCS#12 package.
Generation:
- Encryption of a generated key for storage.
16.2.1. How clients manage key operation encryption
The Certificate System client automatically uses the encryption algorithm set in the KRA’s configuration and no further actions are required.
16.2.2. Configuring the encryption algorithm in the KRA
Only AES CBC (in case when kra.allowEncDecrypt.archive=true and kra.allowEncDecrypt.recovery=true) and AES Key Wrap (in case when kra.allowEncDecrypt.archive=false and kra.allowEncDecrypt.recovery=false) are allowed in the following configuration. Any FIPS140-2 validated HSM that supports either algorithm is allowed for the key archival and recovery feature provided by KRA.
Certificate System defines groups of configuration parameters related to key operation encryption in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file. We recommend the following set of parameters (see note above for other option):
Each group (kra.storageUnit.wrapping.0.* vs kra.storageUnit.wrapping.1.*) has individual settings, and the number defines which settings belong to the same configuration group. The current configuration group is set in the kra.storageUnit.wrapping.choice parameter in the /var/lib/pki/pki-instance_name/conf/kra/CS.cfg file.
Ensure that kra.storageUnit.wrapping.choice=1 is set in the configuration file before continuing.
Certificate System adds the information required to decrypt the data to the record in the KRA database. Therefore, even after changing the encryption algorithm, Certificate System is still able to decrypt data previously stored in the KRA using a different encryption algorithm.
16.2.2.1. Explanation of parameters and their values
Each secret (a "payload") is encrypted with a session key. Parameters controlling this encryption are prefixed with payload. The set of parameters to be used depends on the value of kra.allowEncDecrypt.archive and kra.allowEncDecrypt.recovery. By default, both of these are false. See Section 16.2.2.2, “Solving limitations of HSMs when using AES encryption in KRAs” for the effect of these two parameters on HSMs.
When kra.allowEncDecrypt.archive and kra.allowEncDecrypt.recovery are both false:
-
payloadWrapAlgorithmdetermines the wrapping algorithm used. The only one valid choice isAES KeyWrap. -
When
payloadWrapAlgorithm=AES/CBC/PKCS5Padding, thenpayloadWrapIVLength=16has to be specified to tell PKI that we need to generate an IV (as CBC requires one).
When kra.allowEncDecrypt.archive and kra.allowEncDecrypt.recovery are both true:
-
payloadEncryptionAlgorithmdetermines the encryption algorithm used. The only valid choice is AES. -
payloadEncryptionModedetermines the block chaining mode. The only valid choice is CBC. -
payloadEncryptionPaddingdetermines the padding scheme. The only valid choice is PKCS5Padding.
The session key is then wrapped with the KRA Storage Certificate, an RSA token. Parameters controlling the session key and its encryption are prefixed with sessionKey.
-
sessionKeyTypeis the type of key to generate. The only valid choice is AES. -
sessionKeyLengthis the length of the generated session key. Valid choices are 128 and 256, to encrypt the payload with 128-bit AES or 256-bit AES respectively. -
sessionKeyWrapAlgorithmis the type of key the KRA Storage Certificate is. The only valid choice in this guide is RSA.
16.2.2.2. Solving limitations of HSMs when using AES encryption in KRAs
If you run Certificate System with AES enabled in the KRA, but the Hardware Security Module (HSM) does not support the AES key wrapping feature, key archival fails. To solve the problem, the following solutions are supported:
Selecting a different algorithm for the key wrapping
Sometimes the KRA does not support the default key wrapping algorithm, but it supports other algorithms. For example, to use AES-128-CBC as the key wrapping algorithm:
Set the following parameters in the
/var/lib/pki/pki-instance_name/conf/kra/CS.cfgfile:kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap kra.storageUnit.wrapping.1.payloadWrapIVLen=16 kra.storageUnit.wrapping.1.sessionKeyLength=128
kra.storageUnit.wrapping.1.payloadWrapAlgorithm=AES KeyWrap kra.storageUnit.wrapping.1.payloadWrapIVLen=16 kra.storageUnit.wrapping.1.sessionKeyLength=128Copy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the instance:
systemctl restart pki-tomcatd@instance_name.service
# systemctl restart pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl restart pki-tomcatd-nuxwdog@instance_name.service
# systemctl restart pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the KRA runs in a difference instance then the CA, you need to restart both instances.
Selecting a different algorithm for the key wrapping has the benefit that if the HSM later adds support for AES key wrapping, you can revert the settings because the key records have the relevant information set.
This configuration uses the kra.storageUnit.wrapping.1.payloadWrap{Algorithm,IVLen} and kra.storageUnit.wrapping.1.payloadEncryption{Algorithm,Mode,Padding} parameters.
Setting the KRA into encryption mode
If the HSM does not support any KeyWrap algorithms, on some occassions it is necessary to place the KRA into Encryption Mode. When setting the KRA into encryption mode, all keys will be stored using encryption algorithms rather than key wrapping algorithms.
To set the KRA into encryption mode:
Set the following parameters in the
/var/lib/pki/pki-instance_name/conf/kra/CS.cfgfile totrue:kra.allowEncDecrypt.archive=true kra.allowEncDecrypt.recovery=true
kra.allowEncDecrypt.archive=true kra.allowEncDecrypt.recovery=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the service:
systemctl restart pki-tomcatd@instance_name.service
# systemctl restart pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl restart pki-tomcatd-nuxwdog@instance_name.service
# systemctl restart pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the KRA runs in a difference instance than the CA, you need to restart both instances.
This configuration uses kra.storageUnit.wrapping.1.payloadEncryption{Algorithm,Mode,Padding} and kra.storageUnit.wrapping.1.payloadWrap{Algorithm,IVLen} parameters.
If you later switch to a different algorithm for the key wrapping according to the section called “Selecting a different algorithm for the key wrapping”, you must manually add the appropriate meta data to records created before you set the KRA into encryption mode.
16.3. Setting up agent-approved key recovery schemes
Key recovery agents collectively authorize and retrieve private encryption keys and associated certificates in a PKCS#12 package. To authorize key recovery, the required number of recovery agents access the KRA agent services page and use the Authorize Recovery area to enter each authorization separately.
One of the agents initiates the key recovery process. For a synchronous recovery, each approving agent uses the reference number (which was returned with the initial request) to open the request and then authorizes key recovery separately. For an asynchronous recovery, the approving agents all search for the key recovery request and then authorize the key recovery. Either way, when all of the authorizations are entered, the KRA checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process.
The key recovery agent scheme configures the KRA to recognize to which group the key recovery agents belong and specifies how many of these agents are required to authorize a key recovery request before the archived key is restored.
16.3.1. Configuring agent-approved key recovery in the command line
To set up agent-initiated key recovery, edit two parameters in the KRA configuration:
- Set the number of recovery managers to require to approve a recovery.
- Set the group to which these users must belong.
These parameters are set in the KRA’s CS.cfg configuration file.
Stop the server before editing the configuration file.
systemctl stop pki-tomcatd@instance_name.service
# systemctl stop pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the KRA’s
CS.cfgfile.vim /var/lib/pki/pki-tomcat/kra/conf/CS.cfg
# vim /var/lib/pki/pki-tomcat/kra/conf/CS.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow Edit the two recovery scheme parameters.
kra.noOfRequiredRecoveryAgents=3 kra.recoveryAgentGroup=Key Recovery Authority Agents
kra.noOfRequiredRecoveryAgents=3 kra.recoveryAgentGroup=Key Recovery Authority AgentsCopy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the server.
systemctl start pki-tomcatd@instance_name.service
systemctl start pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR
systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
For more information on how to configure agent-approved key recovery in the console, see the see the Configuring Agent-Approved Key Recovery in the Console section in the Red Hat Certificate System Administration Guide.
16.3.2. Customizing the Key Recovery Form
The default key agent scheme requires a single agent from the Key Recovery Authority Agents group to be in charge of authorizing key recovery.
It is also possible to customize the appearance of the key recovery form. Key recovery agents need an appropriate page to initiate the key recovery process. By default, the KRA’s agent services page includes the appropriate HTML form to allow key recovery agents to initiate key recovery, authorize key recovery requests, and retrieve the encryption keys. This form is located in the /var/lib/pki/pki-tomcat/kra/webapps/kra/agent/kra/ directory, called confirmRecover.html.
If the key recovery confirmation form is customized, do not to delete any of the information for generating the response. This is vital to the functioning of the form. Restrict any changes to the content in and appearance of the form.
16.3.3. Rewrapping keys in a new private storage key
Some private keys (mainly in older deployments) were wrapped in SHA-1, 1024-bit storage keys when they were archived in the KRA. These algorithms have become less secure as processor speeds improve and algorithms have been broken. As a security measure, it is possible to rewrap the private keys in a new, stronger storage key (SHA-256, 2048-bit keys).
16.3.3.1. About KRATool
Rewrapping and moving keys and key enrollment and recovery requests is done using the KRATool utility (known in previous versions of Red Hat Certificate System as DRMTool).
The KRATool performs two operations: it can rewrap keys with a new private key, and it can renumber attributes in the LDIF file entries for key records, including enrollment and recovery requests. At least one operation (rewrap or renumber) must be performed and both can be performed in a single invocation.
For rewrapping keys, the tool accesses the key entries in an exported LDIF file for the original KRA, unwraps the keys using the original KRA storage key, and then rewraps the keys in the new KRA’s stronger storage key.
Example 16.1. Rewrapping Keys
When multiple KRA instances are being merged into a single instance, it is important to make sure that no key or request records have conflicting CNs, DNs, serial numbers, or request ID numbers. These values can be processed to append a new, larger number to the existing values.
Example 16.2. Renumbering keys
The KRATool options and its configuration file are discussed in more detail in the KRATool(1) man page.
16.3.3.2. Rewrapping and Merging Keys from One or More KRAs into a Single KRA
This procedure rewraps the keys stored in one or more Certificate System KRA (for example, pki-tomcat on sourcekra.example.com) and stores them into another Certificate System KRA (for example, pki-tomcat-2 on targetkra.example.com). This is not the only use case; the tool can be run on the same instance as both the source and target, to rewrap existing keys, or it can be used simply to copy keys from multiple KRA instances into a single instance without rewrapping the keys at all.
The storage key size and type in the pki-tomcat-2 KRA must be set to 2048-bit and RSA.
- Log in to targetkra.example.com.
Stop the
pki-tomcat-2KRA.systemctl stop pki-tomcatd@pki-tomcat-2.service
[root@targetkra ~]# systemctl stop pki-tomcatd@pki-tomcat-2.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a data directory to store the key data that will be imported from the
pki-tomcatKRA instance residing on sourcekra.example.com.mkdir -p /export/pki
[root@targetkra ~]# mkdir -p /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Export the public storage certificate for the
pki-tomcat-2KRA to a flat file in the new data directory.certutil -L -d /var/lib/pki/pki-tomcat-2/alias -n "storageCert cert-pki-tomcat-2 KRA" -a > /export/pki/targetKRA.cert
[root@targetkra ~]# certutil -L -d /var/lib/pki/pki-tomcat-2/alias -n "storageCert cert-pki-tomcat-2 KRA" -a > /export/pki/targetKRA.certCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the Directory Server instance for the
pki-tomcat-2KRA, if it is on the same machine.systemctl stop dirsrv.target
[root@newkra ~]# systemctl stop dirsrv.targetCopy to Clipboard Copied! Toggle word wrap Toggle overflow Export the configuration information for the
pki-tomcat-2KRA.Copy to Clipboard Copied! Toggle word wrap Toggle overflow IMPORTANTMake sure that the LDIF file contains a single blank line at the end.
- Log in to sourcekra.example.com.
Stop the
pki-tomcatKRA.systemctl stop pki-tomcatd@pki-tomcat.service
[root@sourcekra ~]# systemctl stop pki-tomcatd@pki-tomcat.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a data directory to store the key data that will be exported to the
pki-tomcat-2KRA instance residing on targetkra.example.com.mkdir -p /export/pki
[root@sourcekra ~]# mkdir -p /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the Directory Server instance for the
pki-tomcatKRA, if it is on the same machine.systemctl stop dirsrv.target
[root@sourcekra ~]# systemctl stop dirsrv.targetCopy to Clipboard Copied! Toggle word wrap Toggle overflow Export the configuration information for the
pki-tomcatKRA.Copy to Clipboard Copied! Toggle word wrap Toggle overflow IMPORTANTMake sure that the LDIF file contains a single blank line at the end.
Copy the
pki-tomcatKRA NSS security databases to this directory.cp -p /var/lib/pki/pki-tomcat/alias/cert9.db /export/pki cp -p /var/lib/pki/pki-tomcat/alias/key4.db /export/pki cp -p /var/lib/pki/pki-tomcat/alias/pkcs11.txt /export/pki
[root@sourcekra ~]# cp -p /var/lib/pki/pki-tomcat/alias/cert9.db /export/pki [root@sourcekra ~]# cp -p /var/lib/pki/pki-tomcat/alias/key4.db /export/pki [root@sourcekra ~]# cp -p /var/lib/pki/pki-tomcat/alias/pkcs11.txt /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Copy the file with the public storage key from the
pki-tomcat-2KRA machine to this machine. For example:Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
If necessary, edit the default
KRATool.cfgfile to use with the tool. The default file can also be used without changes. Run the
KRATool; all of these parameters should be on a single line:Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteThe command may prompt for the password to the token stored in the
pki-tomcatKRA NSS security databases.When it is done, the command creates the file specified in the -target_ldif_file parameter,
source2targetKRA.ldif.Copy this LDIF file over to the
pki-tomcat-2KRA machine. For example:scp /export/pki/source2targetKRA.ldif root@targetkra.example.com:/export/pki
[root@sourcekra ~]# scp /export/pki/source2targetKRA.ldif root@targetkra.example.com:/export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow ImportantMake sure that the LDIF file contains a single blank line at the end.
If multiple KRA instances are being merged, their data can be merged into a single import operation. Simply perform the same procedure for every KRA, which will be merged.
ImportantMake sure to specify unique values for the -target_ldif_file parameter to create separate LDIF files, and to specify unique -append_id_offset values so that there are no conflicts when the LDIF files are concatenated.
On the
pki-tomcat-2KRA machine, import the LDIF file(s) with the other key data by concatenating thepki-tomcat-2KRA configuration LDIF file and every exported LDIF file for the other KRA instances. For example:cd /export/pki cat pki-tomcat-2.ldif source2targetKRA.ldif > combined.ldif
[root@targetkra ~]# cd /export/pki [root@targetkra ~]# cat pki-tomcat-2.ldif source2targetKRA.ldif > combined.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import this combined LDIF file into the Directory Server database for the
pki-tomcat-2KRA instance./usr/lib64/dirsrv/slapd-instanceName/ldif2db -n pki-tomcat-2-KRA -i /export/pki/combined.ldif
[root@targetkra ~]# /usr/lib64/dirsrv/slapd-instanceName/ldif2db -n pki-tomcat-2-KRA -i /export/pki/combined.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the Directory Server instance for the
pki-tomcat-2KRA.systemctl start dirsrv.target
[root@targetkra ~]# systemctl start dirsrv.targetCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the
pki-tomcat-2KRA.systemctl start pki-tomcatd@pki-tomcat-2.service
[root@targetkra ~]# systemctl start pki-tomcatd@pki-tomcat-2.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
16.3.4. Updating CA-KRA connector information after cloning
For more information on updating CA-KRA information after cloning, see Section 16.3.4, “Updating CA-KRA connector information after cloning”.
Chapter 17. Configuring logs
The Certificate System subsystem log files record events related to operations within that specific subsystem instance. For each subsystem, different logs are kept for issues such as installation, access, and web servers.
All subsystems have similar log configuration, options, and administrative paths.
For details about log administration after the installation, see the Configuring Subsystem Logs section in the Red Hat Certificate System Administration Guide.
For an overview on logs, see Section 2.3.13, “Logs”.
17.1. Certificate System log settings
The way that logs are configured can affect Certificate System performance. For example, log file rotation keeps logs from becoming too large, which slows down subsystem performance. This section explains the different kinds of logs recorded by Certificate System subsystems and covers important concepts such as log file rotation, buffered logging, and available log levels.
17.1.1. Services that are logged
All major components and protocols of Certificate System log messages to log files. The following table lists services that are logged by default. To view messages logged by a specific service, customize log settings accordingly.
| Service | Description |
|---|---|
| ACLs | Logs events related to access control lists. |
| Administration | Logs events related to administration activities, such as HTTPS communication between the Console and the instance. |
| All | Logs events related to all the services. |
| Authentication | Logs events related to activity with the authentication module. |
| Certificate Authority | Logs events related to the Certificate Manager. |
| Database | Logs events related to activity with the internal database. |
| HTTP | Logs events related to the HTTP activity of the server. Note that HTTP events are actually logged to the errors log belonging to the Apache server incorporated with the Certificate System to provide HTTP services. |
| Key Recovery Authority | Logs events related to the KRA. |
| LDAP | Logs events related to activity with the LDAP directory, which is used for publishing certificates and CRLs. |
| OCSP | Logs events related to OCSP, such as OCSP status GET requests. |
| Others | Logs events related to other activities, such as command-line utilities and other processes. |
| Request Queue | Logs events related to the request queue activity. |
| User and Group | Logs events related to users and groups of the instance. |
17.1.2. Log levels (message categories)
The different events logged by Certificate System services are determined by the log levels, which makes identifying and filtering events simpler. The different Certificate System log levels are listed in Table 17.2, “Log levels and corresponding log messages”.
Log levels are represented by numbers 0 to 10, each number indicating the level of logging to be performed by the server. The level sets how detailed the logging should be.
A higher priority level means less detail because only events of high priority are logged.
The default log level is 1 and this value should not be changed. To enable debug logging, see Section 17.3.3, “Additional configuration for debug log”.
The following table is provided for reference to better understand log messages.
| Log level | Message category | Description |
|---|---|---|
| 0 | Debugging | These messages contain debugging information. This level is not recommended for regular use because it generates too much information. |
| 1 | Informational (default selection for audit log) | These messages provide general information about the state of the Certificate System, including status messages such as Certificate System initialization complete and Request for operation succeeded. |
| 2 | Warning | These messages are warnings only and do not indicate any failure in the normal operation of the server. |
| 3 | Failure; the default selection for system and error logs | These messages indicate errors and failures that prevent the server from operating normally, including failures to perform a certificate service operation (User authentication failed or Certificate revoked) and unexpected situations that can cause irrevocable errors (The server cannot send back the request it processed for a client through the same channel the request came from the client). |
| 4 | Misconfiguration | These messages indicate that a misconfiguration in the server is causing an error. |
| 5 | Catastrophic failure | These messages indicate that, because of an error, the service cannot continue running. |
| 6 | Security-related events |
These messages identify occurrences that affect the security of the server. For example, |
| 7 | PDU-related events (debugging) | These messages contain debugging information for PDU events. This level is not recommended for regular use because it generates more information than is normally useful. |
| 8 | PDU-related events | These messages relate transactions and rules processed on a PDU, such as creating MAC tokens. |
| 9 | PDU-related events | This log levels provides verbose log messages for events processed on a PDU, such as creating MAC tokens. |
| 10 | All logging levels | This log level enables all logging levels. |
Log levels can be used to filter log entries based on the severity of an event. By default, log level 3 (Failure) is set for all services.
The log level is successive; specifying a value of 3 causes levels 4, 5, and 6 to be logged. Log data can be extensive, especially at lower (more verbose) logging levels. Make sure that the host machine has sufficient disk space for all the log files. It is also important to define the logging level, log rotation, and server-backup policies appropriately so that all the log files are backed up and the host system does not get overloaded; otherwise, information can be lost.
17.1.3. Buffered and unbuffered logging
The Java subsystems support buffered logging for all types of logs. The server can be configured for either buffered or unbuffered logging.
If buffered logging is configured, the server creates buffers for the corresponding logs and holds the messages in the buffers for as long as possible. The server flushes out the messages to the log files only when one of the following conditions occurs:
-
The buffer gets full. The buffer is full when the buffer size is equal to or greater than the value specified by the
bufferSizeconfiguration parameter. The default value for this parameter is 512 KB. -
The flush interval for the buffer is reached. The flush interval is reached when the time interval since the last buffer flush is equal to or greater than the value specified by the
flushIntervalconfiguration parameter. The default value for this parameter is 5 seconds. - When current logs are read from Console. The server retrieves the latest log when it is queried for current logs.
If the server is configured for unbuffered logging, the server flushes out messages as they are generated to the log files. Because the server performs an I/O operation (writing to the log file) each time a message is generated, configuring the server for unbuffered logging decreases performance.
Setting log parameters is described in the Configuring Logs in the Console section in the Red Hat Certificate System Administration Guide.
17.1.4. Log file rotation
The subsystem logs have an optional log setting that allows them to be rotated and start a new log file instead of letting log files grow indefinitely. Log files are rotated when either of the following occur:
-
The size limit for the corresponding file is reached. The size of the corresponding log file is equal to or greater than the value specified by the
maxFileSizeconfiguration parameter. The default value for this parameter is 100 KB. -
The age limit for the corresponding file is reached. The corresponding log file is equal to or older than the interval specified by the
rolloverIntervalconfiguration parameter. The default value for this parameter is 2592000 seconds (every thirty days).
When a log file is rotated, the old file is named using the name of the file with an appended time stamp. The appended time stamp is an integer that indicates the date and time the corresponding active log file was rotated. The date and time have the forms YYYYMMDD (year, month, day) and HHMMSS (hour, minute, second).
Log files, especially the audit log file, contain critical information. These files should be periodically archived to some backup medium by copying the entire log directory to an archive medium.
The Certificate System does not provide any tool or utility for archiving log files.
The Certificate System provides a command-line utility, signtool, that signs log files before archiving them as a means of tamper detection.
Signing log files is an alternative to the signed audit logs feature. Signed audit logs create audit logs that are automatically signed with a subsystem signing certificate.
Rotated log files are not deleted.
17.2. Operating system (external to RHCS) log settings
17.2.1. Enabling OS-level audit logs
All operations in the following sections have to be performed as root or a privileged user via sudo.
The auditd logging framework provides many additional audit capabilities. These OS-level audit logs complement functionality provided by Certificate System directly. Before performing any of the following steps in this section, make sure the audit package is installed:
sudo dnf install audit
# sudo dnf install audit
Auditing of system package updates (using dnf and rpm and including Certificate System) is automatically performed and requires no additional configuration.
After adding each audit rule and restarting the auditd service, validate the new rules were added by running:
auditctl -l
# auditctl -lThe contents of the new rules should be visible in the output.
For instructions on viewing the resulting audit logs, see the Displaying Operating System-level Audit Logs section in the Red Hat Certificate System Administration Guide.
17.2.1.1. Auditing Certificate System audit log deletion
To receive audit events for when audit logs are deleted, you need to audit system calls whose targets are Certificate System logs.
Create the file /etc/audit/rules.d/rhcs-audit-log-deletion.rules with the following contents:
Then restart auditd:
service auditd restart
# service auditd restart17.2.1.2. Auditing unauthorized Certificate System use of secret keys
To receive audit events for all access to Certificate System Secret or Private keys, you need to audit the file system access to the NSS DB.
Create the /etc/audit/rules.d/rhcs-audit-nssdb-access.rules file with the following contents:
-w /etc/pki/<instance name>/alias -p warx -k rhcs_audit_nssdb
-w /etc/pki/<instance name>/alias -p warx -k rhcs_audit_nssdb
<instance name> is the name of the current instance. For each file (<file>) in /etc/pki/<instance name>/alias, add to /etc/audit/rules.d/rhcs-audit-nssdb-access.rules the following line :
-w /etc/pki/<instance name>/alias/<file> -p warx -k rhcs_audit_nssdb
-w /etc/pki/<instance name>/alias/<file> -p warx -k rhcs_audit_nssdb
For example, if the instance name is pki-ca121318ec and cert9.db, key4.db, NHSM-CONN-XCcert9.db, NHSM-CONN-XCkey4.db, and pkcs11.txt are files, then the configuration file would contain:
Then restart auditd:
service auditd restart
# service auditd restart17.2.1.3. Auditing time change events
To receive audit events for time changes, you need to audit a system call access which could modify the system time.
Create the /etc/audit/rules.d/rhcs-audit-rhcs`audit_time_change.rules file with the following contents:
Then restart auditd:
service auditd restart
# service auditd restartFor instructions on how to set time, see Setting Time and Date in Red Hat Enterprise Linux 7 in the Red Hat Certificate System Administration Guide.
17.2.1.4. Auditing access to Certificate System configuration
To receive audit events for all modifications to the Certificate System instance configuration files, audit the file system access for these files.
Create the /etc/audit/rules.d/rhcs-audit-config-access.rules file with the following contents:
-w /etc/pki/ instance_name/server.xml -p wax -k rhcs_audit_config
-w /etc/pki/ instance_name/server.xml -p wax -k rhcs_audit_config
Additionally, add for each subsystem in the /etc/pki/ instance_name/ directory the following contents:
-w /etc/pki/ instance_name/subsystem/CS.cfg -p wax -k rhcs_audit_config
-w /etc/pki/ instance_name/subsystem/CS.cfg -p wax -k rhcs_audit_configExample 17.1. rhcs-audit-config-access.rules configuration file
For example, if the instance name is pki-ca121318ec and only a CA is installed, the /etc/audit/rules.d/rhcs-audit-config-access.rules file would contain:
-w /etc/pki/pki-ca121318ec/server.xml -p wax -k rhcs_audit_config -w /etc/pki/pki-ca121318ec/ca/CS.cfg -p wax -k rhcs_audit_config
-w /etc/pki/pki-ca121318ec/server.xml -p wax -k rhcs_audit_config
-w /etc/pki/pki-ca121318ec/ca/CS.cfg -p wax -k rhcs_audit_config
Note that access to the PKI NSS database is already audited under rhcs_audit_nssdb.
17.3. Configuring Logs in the CS.cfg File
During the installation configuration, you can configure the logging by directly editing the CS.cfg for the instance.
Stop the subsystem instance.
systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Open the
CS.cfgfile in the/var/lib/pki/<instance_name>/<subsystem_type>/confdirectory. -
To create a new log, copy all of the entries for either the system or transactions log. These are the parameters that begin with
log.instance.Transactionsorlog.instance.System. Paste all entries at the bottom of the logging section and change the name of this instance by changing the wordTransactionsorSystemin each parameter to the new name. To configure a log instance, modify the parameters associated with that log. These parameters begin with
log.instance.Expand Table 17.3. Log entry parameters Parameter Description type
The type of log file. system creates error and system logs; transaction records audit logs.
enable
Sets whether the log is active. Only enabled logs actually record events.
level
Sets the log level in the text field. The level must be manually entered in the field; there is no selection menu. The log level setting is a numeric value, as listed in Section 17.1.2, “Log levels (message categories)”.
fileName
The full path, including the file name, to the log file. The subsystem user should have read/write permission to the file.
bufferSize
The buffer size in kilobytes (KB) for the log. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file. The default size is 512 KB. For more information on buffered logging, see Section 17.1.3, “Buffered and unbuffered logging”.
flushInterval
The amount of time, in seconds, before the contents of the buffer are flushed out and added to the log file. The default interval is 5 seconds.
maxFileSize
The size, kilobytes (KB), a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and the log file is started new. For more information on log file rotation, see Section 17.1.4, “Log file rotation”. The default size is 2000 KB.
rolloverInterval
The frequency which the server rotates the active log file. The available choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly. For more information, see Section 17.1.4, “Log file rotation”.
register
If this variable is set to
false(the default value), the self-test messages are only logged to the log file specified byselftests.container.logger.fileName. If this variable is set totrue, then the self-test messages are written to both the log file specified byselftests.container.logger.fileNameas well as to the log file specified by log.instance.Transactions.fileName.logSigning
Enables signed logging. When this parameter is enabled, provide a value for the signedAuditCertNickname parameter. This option means the log can only be viewed by an auditor. The value is either
trueorfalse.signedAuditCertNickname
The nickname of the certificate used to sign audit logs. The private key for this certificate must be accessible to the subsystem in order for it to sign the log.
events
Specifies which events are logged to the audit log. Log events are separated by commas with no spaces.
- Save the file.
Start the subsystem instance.
systemctl start pki-tomcatd@instance_name.service
systemctl start pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
17.3.1. Enabling and configuring signed audit log
17.3.1.1. Enabling signed audit logging
By default, audit logging is enabled upon installation. However, log signing needs to be enabled manually after installation.
To display the current audit logging configuration:
To enable signed audit logging:
Use the
pki-serverutility to set the --logSigning option totrue:pki-server subsystem-audit-config-mod --logSigning True
# pki-server subsystem-audit-config-mod --logSigning True ... Log Signing: True ...Copy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the instance:
systemctl restart pki-tomcatd@instance_name.service
# systemctl restart pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
17.3.1.2. Configuring audit events
17.3.1.2.1. Enabling and disabling audit events
For details about enabling and disabling audit events, see the Configuring a Signed Audit Log in the Console section in the Red Hat Certificate System Administration Guide.
In addition, audit event filters can be set to finer grained selection. See Section 17.3.1.2.2, “Filtering audit events”.
For a complete list of auditable events in Certificate System, see the Audit events appendix in the Red Hat Certificate System Administration Guide.
17.3.1.2.2. Filtering audit events
In Certificate System administrators can set filters to configure which audit events will be logged in the audit file based on the event attributes.
The format of the filters is the same as for LDAP filters. However, Certificate System only supports the following filters:
| Type | Format | Example |
|---|---|---|
| Presence | (attribute=*) | (ReqID=*) |
| Equality | (attribute=value) | (Outcome=Failure) |
| Substring | (attribute=initial*any*…*any*final) | (SubjectID=admin) |
|
| (&(filter_1)(filter_2)…(filter_n)) | (&(SubjectID=admin)(Outcome=Failure)) |
|
| (|(filter_1)(filter_2)…(filter_n)) | (|(SubjectID=admin)(Outcome=Failure)) |
|
| (!(filter)) | (!(SubjectID=admin)) |
For further details on LDAP filters, see the Using Compound Search Filters section in the Red Hat Directory Server Administration Guide.
Example 17.2. Filtering audit events
To display the current settings for profile certificate requests and processed certificates:
To log only failed events for profile certificate requests and events for processed certificate requests that have the InfoName field set to rejectReason or cancelReason:
Execute the following commands:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Restart Certificate System:
systemctl restart pki-tomcatd@instance_name.service
# systemctl restart pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
17.3.2. Configuring self-tests
The self-tests feature and individual self-tests are registered and configured in the CS.cfg file. If a self-test is enabled, that self-test is listed for either on-demand or start up and is either empty or set as critical.
Critical self-tests have a colon and the word critical after the name of the self-test. Otherwise, nothing is in this place. The server shuts down when a critical self-test fails during on demand self-tests; the server will not start when a critical self-test fails during start up.
The implemented self-tests are automatically registered and configured when the instance was installed. The self-tests that are registered and configured are those associated with the subsystem type.
A self-test’s criticality is changed by changing the respective settings in the CS.cfg file.
17.3.2.1. Default self-tests at startup
The following self-tests are enabled by default at startup.
For the CA subsystem, the following self-tests are enabled by default at startup:
-
CAPresence- used to verify the presence of the CA subsystem. -
CAValidity- used to determine that the CA subsystem is currently valid and has not expired. This involves checking the expiration of the CA certificate. SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked. For the CA subsystem, only validity tests for each certificate are done, leaving out certificate verification tests which could result in an OCSP request. This behavior can be overridden with the following config parameter:selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=true
selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow By default, this config parameter is considered
falseif not present at all.
For the KRA subsystem, the following-self-tests are enabled:
-
KRAPresence- used to verify the presence of the KRA subsystem. -
KRAValidity- used to determine that the KRA subsystem is currently valid and has not expired. This involves checking the expiration of the KRA certificate. -
SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked.
For the OCSP subsystem, the following self-tests are enabled:
-
OCSPPresence- used to verify the presence of the OCSP subsystem. -
OCSPValidity- used to determine that the OCSP subsystem is currently valid and has not expired. This involves checking the expiration of the OCSP certificate. SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked. For the OCSP subsystem, only validity tests for each certificate are done, leaving out certificate verification tests which could result in an OCSP request. This behavior can be overridden with the following config parameter:selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=true
selftests.plugin.SystemCertsVerification.FullCAandOCSPVerify=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow By default, this config parameter is considered
falseif not present at all.
For the TKS subsystem, the following-self-tests are enabled:
-
TKSKnownSessionKey- used to verify the known session key of a TKS subsystem. This verifies the TKS is able to properly assist in creating keys on behalf of the TPS and supported smart cards. -
SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked.
For the TPS subsystem, the following-self-tests are enabled:
-
TPSPresence- used to verify the presence of the TPS subsystem. -
TPSValidity- used to determine that the TPS subsystem is currently valid and has not expired. This involves checking the expiration of the TPS certificate. -
SystemCertsVerification- used to determine that the system certificates are currently valid and have not expired or been revoked.
17.3.2.2. Modifying self-test configuration
By default, the self-test configuration is compliant. However, some settings can change the visibility of self-test logging or improve performance. To modify the configuration settings for self-tests:
- Stop the subsystem instance.
-
Open the
CS.cfgfile located in the instance’sconf/directory. To edit the settings for the self-test log, edit the entries that begin with
selftests.container.logger. Unless otherwise specified, these parameters do not affect compliance. These include the following parameters:- bufferSize- Specify the buffer size in kilobytes (KB) for the log. The default size is 512 KB. Once the buffer reaches this size, the contents of the buffer are flushed out and copied to the log file.
-
enable- Specify
trueto enable. Only enabled logs actually record events. This value must be enabled for compliance. -
fileName- Specify the full path, including the filename, to the file to write messages. The server must have read/write permission to the file. By default, the self-test log file is
/selftest.log -
flushInterval- Specify the interval, in seconds, to flush the buffer to the file. The default interval is 5 seconds. The
flushIntervalis the amount of time before the contents of the buffer are flushed out and added to the log file. - level- The default selection is 1; this log is not set up for any level beside 1.
-
maxFileSize- Specify the file size in kilobytes (KB) for the error log. The default size is 100 KB. The
maxFileSizedetermines how large a log file can become before it is rotated. Once it reaches this size, the file is copied to a rotated file, and a new log file is started. -
register- If this variable is set to
false(the default value), the self-test messages are only logged to the log file specified byselftests.container.logger.fileName. If this variable is set totrue, then the self-test messages are written to both the log file specified byselftests.container.logger.fileNameand the log file specified bylog.instance.Transactions.fileName. - rolloverInterval- Specify the frequency at which the server rotates the active error log file. The choices are hourly, daily, weekly, monthly, and yearly. The default selection is monthly.
-
type- Set to
transaction; do not change this.
To edit the order in which the self-test are run, specify the order by listing any of the self-test as the value of the following parameters separated by a comma and a space.
To mark a self-test critical, add a colon and the word critical to the name of the self-test in the list.
To disable a self-test, remove it as the value of either the
selftests.container.order.onDemandorselftests.container.order.startupparameters.- Save the file.
- Start the subsystem.
17.3.3. Additional configuration for debug log
17.3.3.1. Enabling and disabling debug logging
By default, debug logging is enabled in Certificate System. However, in certain situations, Administrators want to disable or re-enable this feature:
Edit the
/CS.cfgfile and set thedebug.enabledparameter:To disable debug logging, set:
debug.enabled=false
debug.enabled=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteDebug logs are not part of audit logging. Debug logs are helpful when trying to debug specific failures in Certificate System or a failing installation.
By default, debug logs are enabled. If it is not desired, the administrator can safely disable debug logging to turn down verbosity.
To enable debug logging, set:
debug.enabled=true
debug.enabled=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Restart the Certificate System instance:
systemctl restart pki-tomcatd@instance-name.service
# systemctl restart pki-tomcatd@instance-name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl restart pki-tomcatd-nuxwdog@instance-name.service
# systemctl restart pki-tomcatd-nuxwdog@instance-name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
17.3.3.2. Setting up rotation of debug log files
Certificate System is not able to rotate debug logs. Debug logging is enabled by default and these logs grow until the file system is full. Use an external utility, such as logrotate, to rotate the logs.
Example 17.3. Using logrotate to Rotate Debug Logs
Create a configuration file, such as /etc/logrotate.d/rhcs_debug with the following content:
To rotate debug logs for multiple subsystems in one configuration file, list the paths to the logs, each separated by white space, before the opening curly bracket. For example:
/var/log/pki/ instance_name/ca/debug /var/log/pki/ instance_name/kra/debug {
...
}
/var/log/pki/ instance_name/ca/debug /var/log/pki/ instance_name/kra/debug {
...
}
For further details about logrotate and the parameters used in the example, see the logrotate(8) man page.
17.4. Audit retention
Audit data are required to be retained in a way according to their retention categories:
Extended Audit Retention: Audit data that is retained for necessary maintenance for a certificate’s lifetime (from issuance to its expiration or revocation date). In Certificate System, they appear in the following areas:
- Signed audit logs: All events defined in Appendix E. Audit Events of Red Hat Certificate System’s Administration Guide.
- In the CA’s internal LDAP server, certificate request records received by the CA and the certificate records as the requests are approved.
- Normal Audit Retention: Audit data that is typically retained only to support normal operation. This includes all events that do not fall under the extended audit retention category.
Certificate System does not provide any interface to modify or delete audit data.
17.4.1. Location of audit data
This section explains where Certificate System stores audit data and where to find the expiration date which plays a crucial role to determine the retention category.
17.4.1.1. Location of audit logs
Certificate System stores audit logs in the /signedAudit/ directory. For example, the audit logs of a CA are stored in the /ca/logs/signedAudit/ directory. Normal users cannot access files in this directory. See //TBD: cfu: link to the end result of https://trello.com/c/3LuUsheO/373-cc-doc-1425-managing-audit-logs#
For a list of audit log events that need to follow the extended audit retention period, see the Audit events appendix in the Red Hat Certificate System Administration Guide.
Do not delete any audit logs that contain any events listed in the "Extended Audit Events" appendix These audit logs will consume storage space potentially up to all space available in the disk partition.
17.4.1.2. Location of certificate requests and certificate records
When certificate signing requests (CSR) are submitted, the CA stores the CSRs in the request repository provided by the CA’s internal directory server. When these requests are approved, each certificate issued successfully, will result in an LDAP record being created in the certificate repository by the same internal directory server.
The CA’s internal directory server was specified in the following parameters when the CA was created using the pkispawn utility:
-
pki_ds_hostname -
pki_ds_ldap_port -
pki_ds_database -
pki_ds_base_dn
If a certificate request has been approved successfully, the validity of the certificate can be viewed by accessing the CA EE portal either by request ID or by serial number.
To display the validity for a certificate request record:
-
Log into the CA EE portal under
https://host_name:_port_/ca/ee/ca/. - Click .
- Enter the Request Identifier.
- Click .
- Search for Validity.
To display the validity from a certificate record:
-
Log into the CA EE portal under
https://host_name:_port_/ca/ee/ca/. - Enter the serial number range. If you search for one specific record, enter the record’s serial number in both the lowest and highest serial number field.
- Click on the search result.
- Search for Validity.
Do not delete the request of the certificate records of the certificates that have not yet expired.
Chapter 18. Creating a role user
As explained in Section 2.6.6.1, “Default administrative roles”, a bootstrap user was created during the installation. After the installation, create real users and assign them proper system privileges. For compliance, each user must be a member of only one role (group).
This chapter instructs you how to:
- Create a Certificate System administrative user on the operating system
- Create a PKI role in Certificate System
18.1. Creating a PKI administrative user on the operating system
This section is for administrative role users. Agent and Auditor role users, see Section 18.2, “Creating a PKI role user in Certificate System”.
In general, administrators, agents, and auditors in Certificate System can manage the Certificate System instance remotely using client applications, such as command-line utilities, the Java Console, and browsers. For the majority of CS management tasks, a Certificate System role user does not need to log on to the host machine where the instance runs. For example, an auditor role user is allowed to retrieve signed audit logs remotely for verification, and an agent role user can use the agent interface to approve a certificate issuance, while an administrator role user can use command-line utilities to configure a profile.
In certain cases, however, a Certificate System administrator requires to log in to the host system to modify configuration files directly, or to start or stop a Certificate System instance. Therefore, on the operating system, the administrator role user should be someone who is allowed to make changes to the configuration files and read various logs associated with Red Hat Certificate System.
Do not allow the Certificate System administrators or anyone other than the auditors to access the audit log files.
Create the
pkiadmingroup on the operating system.groupadd -r pkiadmin
# groupadd -r pkiadminCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the
pkiuserto thepkiadmingroup:usermod -a -G pkiadmin pkiuser
# usermod -a -G pkiadmin pkiuserCopy to Clipboard Copied! Toggle word wrap Toggle overflow Create a user on the operating system. For example, to create the
jsmithaccount:useradd -g pkiadmin -d /home/jsmith -s /bin/bash -c "Red Hat Certificate System Administrator John Smith" -m jsmith
# useradd -g pkiadmin -d /home/jsmith -s /bin/bash -c "Red Hat Certificate System Administrator John Smith" -m jsmithCopy to Clipboard Copied! Toggle word wrap Toggle overflow For details, see the
useradd(8)man page.Add the user
jsmithto thepkiadmingroup:usermod -a -G pkiadmin jsmith
# usermod -a -G pkiadmin jsmithCopy to Clipboard Copied! Toggle word wrap Toggle overflow For details, see the
usermod(8)man page.If you are using a nCipher hardware security module (HSM), add the user who manages the HSM device to the
nfastgroup:usermod -a -G nfast pkiuser usermod -a -G nfast jsmith
# usermod -a -G nfast pkiuser # usermod -a -G nfast jsmithCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add proper
sudorules to allow thepkiadmingroup to Certificate System and other system services.For both simplicity of administration and security, the Certificate System and Directory Server processes can be configured so that PKI administrators (instead of only root) can start and stop the services.
A recommended option when setting up subsystems is to use a
pkiadminsystem group. (Details are Section 6.5, “Certificate System operating system users and groups”). All of the operating system users which will be Certificate System administrators are then added to this group. If thispkiadminsystem group exists, then it can be granted sudo access to perform certain tasks.Edit the
/etc/sudoersfile; on Red Hat Enterprise Linux, this can be done using thevisudocommand:visudo
# visudoCopy to Clipboard Copied! Toggle word wrap Toggle overflow Depending on what is installed on the machine, add a line for the Directory Server, the {ADS}, PKI management tools, and each PKI subsystem instance, granting
sudorights to thepkiadmingroup:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
ImportantMake sure to set sudo permissions for every Certificate System, Directory Server, and {ADS} on the machine -and only for those instances on the machine. There could be multiple instances of the same subsystem type on a machine or no instance of a subsystem type. It depends on the deployment.
Set the group on the following files to
pkiadmin:chgrp pkiadmin /etc/pki/ instance_name/server.xml chgrp -R pkiadmin /etc/pki/ instance_name/alias chgrp pkiadmin /etc/pki/ instance_name/subsystem/CS.cfg chgrp pkiadmin /var/log/pki/ instance_name/subsystem/debug
# chgrp pkiadmin /etc/pki/ instance_name/server.xml # chgrp -R pkiadmin /etc/pki/ instance_name/alias # chgrp pkiadmin /etc/pki/ instance_name/subsystem/CS.cfg # chgrp pkiadmin /var/log/pki/ instance_name/subsystem/debugCopy to Clipboard Copied! Toggle word wrap Toggle overflow
After creating the administrative user on the operating system, follow Section 18.2, “Creating a PKI role user in Certificate System”.
18.2. Creating a PKI role user in Certificate System
To create a PKI role user, see the Managing Certificate System Users and Groups section in the Red Hat Certificate System Administration Guide.
Chapter 19. Deleting the Bootstrap User
Before you delete the bootstrap user, create a real PKI administrative user as described in Chapter 18, Creating a role user.
To delete the bootstrap user, follow the procedure described in the Deleting a Certificate System User section in the Red Hat Certificate System Administration Guide.
19.1. Disabling multi-roles support
By default, users can belong to more than one subsystem group at once, allowing the user to act as more than one role. For example, John Smith could belong to both an agent and an administrator group. However, for highly secure environments, the subsystem roles should be restricted so that a user can only belong to one role. This can be done by disabling the multirole attribute in the instance’s configuration.
For all subsystems:
Stop the server:
systemctl stop pki-tomcatd@instance_name.service
# systemctl stop pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl stop pki-tomcatd-nuxwdog@instance_name.service
# systemctl stop pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Open the
CS.cfgfile:vim /var/lib/pki/ instance_name/ca/conf/CS.cfg
# vim /var/lib/pki/ instance_name/ca/conf/CS.cfgCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Change the
multiroles.enableparameter value fromtruetofalse. Add or edit the list of default roles in Certificate System that are affected by the multi-roles setting. If multi-roles is disabled and a user belongs to one of the roles listed in the
multiroles.false.groupEnforceListparameter, then the user cannot be added to any group for any of the other roles in the list.multiroles.false.groupEnforceList=Administrators,Auditors,Trusted Managers,Certificate Manager Agents,Registration Manager Agents,Key Recovery Authority Agents,Online Certificate Status Manager Agents,Token Key Service Manager Agents,Enterprise CA Administrators,Enterprise KRA Adminstrators,Enterprise OCSP Administrators,Enterprise TKS Administrators,Enterprise TPS Administrators,Security Domain Administrators,Subsystem Group
multiroles.false.groupEnforceList=Administrators,Auditors,Trusted Managers,Certificate Manager Agents,Registration Manager Agents,Key Recovery Authority Agents,Online Certificate Status Manager Agents,Token Key Service Manager Agents,Enterprise CA Administrators,Enterprise KRA Adminstrators,Enterprise OCSP Administrators,Enterprise TKS Administrators,Enterprise TPS Administrators,Security Domain Administrators,Subsystem GroupCopy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the server:
systemctl start pki-tomcatd@instance_name.service
systemctl start pki-tomcatd@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow OR (if using
nuxwdog watchdog)systemctl start pki-tomcatd-nuxwdog@instance_name.service
# systemctl start pki-tomcatd-nuxwdog@instance_name.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Part IV. Upgrading to Certificate System 10.x
This part provides information on the maintenance of Red Hat Certificate System.
Chapter 20. Upgrading from Certificate System 9 to Certificate System 10
Users are recommended to upgrade to the most recent version of Red Hat Certificate System to get security and bug fixes through the Errata-Support channel. Currently, the most recent versions are RHCS 9.7 on RHEL 7.9 and RHCS 10.8 on RHEL 8.10.
20.1. Migrating a CA
A Certificate System migration using the existing certificate files requires the following steps:
20.1.1. Exporting data from the previous system
Before you set up the new Certificate System instance, export the data of the current certificate authority (CA) using the steps below. In this example, the CA’s instance name is <pki-rootCA> and is located at /var/lib/pki/<instance_name>.
Export the CA signing certificate and key.
grep internal= /var/lib/pki/<instance_name>/conf/password.conf | awk -F= '{print $2;}' > internal.txt echo <Secret.123> > password.txt PKCS12Export -d /var/lib/pki/<instance_name>/alias -p internal.txt -o ca.p12 -w password.txt# grep internal= /var/lib/pki/<instance_name>/conf/password.conf | awk -F= '{print $2;}' > internal.txt # echo <Secret.123> > password.txt # PKCS12Export -d /var/lib/pki/<instance_name>/alias -p internal.txt -o ca.p12 -w password.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Export the Certificate Signing Requests (CSR).
echo "-----BEGIN NEW CERTIFICATE REQUEST-----" > ca_signing.csr sed -n "/^ca.signing.certreq=/ s/[=]*=// p" < /var/lib/pki/<instance_name>/ca/conf/CS.cfg >> ca_signing.csr echo "-----END NEW CERTIFICATE REQUEST-----" >> ca_signing.csr
# echo "-----BEGIN NEW CERTIFICATE REQUEST-----" > ca_signing.csr # sed -n "/^ca.signing.certreq=/ s/[=]*=// p" < /var/lib/pki/<instance_name>/ca/conf/CS.cfg >> ca_signing.csr # echo "-----END NEW CERTIFICATE REQUEST-----" >> ca_signing.csrCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the old CA is an intermediate CA (with a single root CA in the chain), extract the root CA from the NSS database:
certutil -L -d /var/lib/pki/<instance_name>/alias/ -n root_CA_nickname -a > ca_rootca_signing.crt
# certutil -L -d /var/lib/pki/<instance_name>/alias/ -n root_CA_nickname -a > ca_rootca_signing.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Back up the internal LDAP database:
Find the name of the CA database by checking the value of internaldb.database in the CA’s
CS.cfg:grep internaldb.database /etc/pki/<instance_name>/ca/CS.cfg
# grep internaldb.database /etc/pki/<instance_name>/ca/CS.cfg internaldb.database=<CS_database_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Export this database to a
.ldiffile using the instance-specific script generated bysetup-ds.plwhen the instance was created:cd /usr/lib64/dirsrv/<instance_name> ./db2ldif -n "<CS_database_name>" -a /tmp/old_ca.ldif
# cd /usr/lib64/dirsrv/<instance_name> # ./db2ldif -n "<CS_database_name>" -a /tmp/old_ca.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow The
db2ldifcommand runs as the DB user, so it needs a destination folder with writing permissions.
-
Transfer the
old_ca.ldif,ca_p12,ca_signing.csrfiles to the new CA machine. If the CA being migrated is also an intermediate CA, transfer theca_rootca_signing.crtas well.
20.1.2. Verifying the PKCS12 file
On the new CA, a new database instance runs on the standard port (389). The PKCS12 file contains all the system certificates for the old system. Verify that the file includes the CA signing certificate and the key.
In FIPS mode, you must run the pki pkcs12 commands with an NSS database. For more information, see the pki-pkcs12 CLI.
Find the CA signing certificate and the key.
echo "<Secret.123>" > password.txt pki pkcs12-cert-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt pki pkcs12-key-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ echo "<Secret.123>" > password.txt $ pki pkcs12-cert-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt $ pki pkcs12-key-find --pkcs12-file ca.p12 --pkcs12-password-file password.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow Verify the presence of the trust flags of the CA signing certificate. If the flags are not "CTu,Cu,Cu" or they are missing, add them.
pki pkcs12-cert-mod "<caSigningCert cert-pki-rootCA>" \ --pkcs12-file ca.p12 --pkcs12-password-file password.txt \ --trust-flags "CTu,Cu,Cu"
$ pki pkcs12-cert-mod "<caSigningCert cert-pki-rootCA>" \ --pkcs12-file ca.p12 --pkcs12-password-file password.txt \ --trust-flags "CTu,Cu,Cu"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Remove other certificates and keys.
pki pkcs12-cert-del "<Server-Cert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt pki pkcs12-cert-del "<subsystemCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt pki pkcs12-cert-del "<ocspSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt pki pkcs12-cert-del "<auditSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<Server-Cert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt $ pki pkcs12-cert-del "<subsystemCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt $ pki pkcs12-cert-del "<ocspSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt $ pki pkcs12-cert-del "<auditSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow If the CA being migrated is also an intermediate CA, remove the root CA certificate from the PKCS#12 file.
pki pkcs12-cert-del "<Top-level Root CA Signing Certificate>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<Top-level Root CA Signing Certificate>" --pkcs12-file ca.p12 --pkcs12-password-file password.txtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
20.1.3. Setting up the CA on the new host
After you have exported the data from the existing instance, create and set up the certificate authority (CA) on the new host.
Create a configuration file for
pkispawn, for example CA.cfg, using the parameters of the old CA. This instance runs on the standard port (389).Copy to Clipboard Copied! Toggle word wrap Toggle overflow If the old CA is an intermediate CA, add the following two lines to the configuration file. They correspond to the path to the root CA certificate and the nickname to use when storing the certificate in the NSS database.
pki_cert_chain_path=<rootca_signing.crt> pki_cert_chain_nickname=<caSigningCert cert-pki-ca>
pki_cert_chain_path=<rootca_signing.crt> pki_cert_chain_nickname=<caSigningCert cert-pki-ca>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run
pkispawnon the new host to create the new CA instance:pkispawn -s CA -f ca.cfg -vv
# pkispawn -s CA -f ca.cfg -vvCopy to Clipboard Copied! Toggle word wrap Toggle overflow
For instructions on how to set up a new DS instance for the new CA, see Installing Red Hat Directory Server.
20.1.4. Importing the old data into the new CA
After you have created the new CA instance, import the data into the new CA database:
Stop the CA service.
systemctl stop pki-tomcatd@<instance_name>.service
# systemctl stop pki-tomcatd@<instance_name>.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optional: Back up the CA database on the new host.
dsctl -v idm-qe-01 db2bak
# dsctl -v idm-qe-01 db2bakCopy to Clipboard Copied! Toggle word wrap Toggle overflow The backup is stored in the
/var/lib/dirsrv/<instance_name>/bak/<host_name-time_stamp>/directory.Remove the certificate entry for the signing certificate from the new RHEL 8 internal database.
ldapdelete -x -w <password< -D 'cn=Directory Manager' "cn=<serial_number<,ou=certificateRepository,ou=ca,o=pki-tomcat-CA"
# ldapdelete -x -w <password< -D 'cn=Directory Manager' "cn=<serial_number<,ou=certificateRepository,ou=ca,o=pki-tomcat-CA"Copy to Clipboard Copied! Toggle word wrap Toggle overflow The entry is now imported from the old data, so that the CRL attributes in that entry point to the correct entries.
Import the data into the new database:
ldapmodify -x -W <password> -D 'cn=Directory Manager' -a -c -f <path/to/old_ca.ldif>
# ldapmodify -x -W <password> -D 'cn=Directory Manager' -a -c -f <path/to/old_ca.ldif>Copy to Clipboard Copied! Toggle word wrap Toggle overflow The
ldapmodifyutility only adds new entries and does not update existing entries, created when you installed the CA.-
Optional: Verify the output in the
import.logfile. You can search for failed actions, such asldap_add: Invalid syntax (21). Remove the directory entry for the old security domain.
ldapmodify -W <password> -x -D "cn=Directory Manager"
# ldapmodify -W <password> -x -D "cn=Directory Manager" dn: cn=<server.example.com:9445>,cn=CAList,ou=Security Domain,<o=pki-tomcat-CA> changetype: deleteCopy to Clipboard Copied! Toggle word wrap Toggle overflow Enable the
ca.crl.MasterCRL.enableparameter in the/etc/pki/<instance_name>/ca/CS.cfgfile, to have the CA act as the certificate revocation list (CRL) master:ca.crl.MasterCRL.enable=true
ca.crl.MasterCRL.enable=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow Restart the CA service:
systemctl start pki-tomcatd@<instance_name>
# systemctl start pki-tomcatd@<instance_name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
20.1.5. Reassigning users to default groups
Add members to the default groups manually, using the ldapmodify utility or the pki utility.
Set up the client:
pki -c <password> client-init
# pki -c <password> client-init Client initializedCopy to Clipboard Copied! Toggle word wrap Toggle overflow pk12util -i ~/.dogtag/<instance_name>/ca_admin_cert.p12 -d ~/.dogtag/nssdb/
# pk12util -i ~/.dogtag/<instance_name>/ca_admin_cert.p12 -d ~/.dogtag/nssdb/ Enter Password or Pin for "NSS Certificate DB": Enter password for PKCS12 file: pk12util: PKCS12 IMPORT SUCCESSFULCopy to Clipboard Copied! Toggle word wrap Toggle overflow Add the
useraccount to theAdministratorsandSecurity Domain Administratorsgroups:pki -n "<PKI Administrator for example.com>" -c <password> \ user-membership-add <user_name> "Certificate Manager Agents"
# pki -n "<PKI Administrator for example.com>" -c <password> \ user-membership-add <user_name> "Certificate Manager Agents"Copy to Clipboard Copied! Toggle word wrap Toggle overflow The default (bootstrap) admin users in RHCS 9 and RHCS 10 have the same default roles, that is the same group membership. However, if you have a non-default admin user or have customized the admin roles in RHCS 9, those changes might not be migrated properly. In this case, reconfigure the roles in RHCS 10:
pki -n "<PKI Administrator for example.com>" -c <password> \ user-membership-add <user> "Administrators" pki -n "<PKI Administrator for example.com>" -c <password> \ user-membership-add <user> "Security Domain Administrators"
# pki -n "<PKI Administrator for example.com>" -c <password> \ user-membership-add <user> "Administrators" # pki -n "<PKI Administrator for example.com>" -c <password> \ user-membership-add <user> "Security Domain Administrators"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
If you want to make sure the certificate has been migrated successfully, check its existence on the new host by running the ca-cert-find command.
20.2. Migrating a KRA
Simple KRA migration requires the following steps:
The KRA located on alpha.example.com contains the data, while the KRA located on omega.example.com does not exist yet.
| Hostname | PKI KRA Version |
|---|---|
| alpha.example.com | PKI KRA 10.5 on RHCS 9.7 |
| omega.example.com | PKI KRA 10.13 on RHCS 10.4 |
20.2.1. Setting up the KRA on the new host
On omega.example.com as the root user:
- Install and configure a new PKI 10.13 KRA on omega.example.com.
Stop the KRA instance.
systemctl stop pki-tomcatd@<pki-kra>
# systemctl stop pki-tomcatd@<pki-kra>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a directory to export all required files.
mkdir -p /export/pki
# mkdir -p /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Export KRA storage certificates to a file. You will need the KRA storage certificate later to re-encrypt the decrypted old data from the KRA on alpha. In the following example, the file is called
omega.crt:Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Move the
omega.crtfile to the/export/pkidirectory. Stop the Directory Server.
systemctl stop dirsrv@omega
# systemctl stop dirsrv@omegaCopy to Clipboard Copied! Toggle word wrap Toggle overflow NoteIf
db2ldifis missing, install the389-ds-base-legacy-toolspackage.Extract the KRA LDAP database configurations. You will need the new KRA LDAP database configurations for transforming the old data to the new.
/usr/lib64/dirsrv/slapd-omega/db2ldif -n <pki-kra-KRA> -a /tmp/omega.ldif
# /usr/lib64/dirsrv/slapd-omega/db2ldif -n <pki-kra-KRA> -a /tmp/omega.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Move the
/tmp/omega.ldiffile to the/export/pkidirectory.mv /tmp/omega.ldif /export/pki/
# mv /tmp/omega.ldif /export/pki/Copy to Clipboard Copied! Toggle word wrap Toggle overflow
20.2.2. Exporting contents from the previous system
On alpha.example.com as the root user:
Create a common directory:
mkdir -p /export/pki
# mkdir -p /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Stop the Directory Server. In this example, the server is named alpha:
systemctl stop dirsrv@alpha
# systemctl stop dirsrv@alphaCopy to Clipboard Copied! Toggle word wrap Toggle overflow Generate the LDIF from the KRA LDAP database:
/usr/lib64/dirsrv/slapd-alpha/db2ldif -n <pki-kra-KRA> -a /tmp/alpha.ldif
# /usr/lib64/dirsrv/slapd-alpha/db2ldif -n <pki-kra-KRA> -a /tmp/alpha.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Move the
/tmp/alpha.ldiffile to/export/pkidirectory:mv /tmp/alpha.ldif /export/pki/
# mv /tmp/alpha.ldif /export/pki/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Copy the KRA NSS security databases to the data area:
cp -p /var/lib/pki/<pki-kra>/alias/* /export/pki/
# cp -p /var/lib/pki/<pki-kra>/alias/* /export/pki/Copy to Clipboard Copied! Toggle word wrap Toggle overflow Go to the
/export/pkidirectory:cd /export/pki
# cd /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Obtain the flat-file containing the new KRA’s storage certificate from omega.example.com:
sftp root@omega.example.com sftp> cd /export/pki sftp> get omega.crt sftp> quit
sftp root@omega.example.com sftp> cd /export/pki sftp> get omega.crt sftp> quitCopy to Clipboard Copied! Toggle word wrap Toggle overflow Obtain the internal password:
cat /var/lib/<instance_name>/conf/password.conf
# cat /var/lib/<instance_name>/conf/password.confCopy to Clipboard Copied! Toggle word wrap Toggle overflow Run the
KRAToolon alpha.example.com:Copy to Clipboard Copied! Toggle word wrap Toggle overflow NoteAlternatively, you can create a plain-text file protected from unauthorized access containing one and only password that will be automatically accessed by a certificate or a certificate database. Add this file to
KRAToolwith the-source_pki_security_database_pwdfile <path_to_PKI_password_file>command-line option.Copy the
alpha2omega.ldiffile to omega.example.com:sftp root@omega.example.com sftp> cd /export/pki sftp> put alpha2omega.ldif sftp> quit
sftp root@omega.example.com sftp> cd /export/pki sftp> put alpha2omega.ldif sftp> quitCopy to Clipboard Copied! Toggle word wrap Toggle overflow
20.2.3. Importing the data into the new KRA
On omega.example.com as the root user:
Go to
/export/pkidirectory.cd /export/pki
# cd /export/pkiCopy to Clipboard Copied! Toggle word wrap Toggle overflow Concatenate the
ldiffiles:cat omega.ldif alpha2omega.ldif > omega_alpha.ldif
# cat omega.ldif alpha2omega.ldif > omega_alpha.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Import the
omega_alpha.ldiffile into the LDAP database associated with the PKI KRA:/usr/lib64/dirsrv/slapd-omega/ldif2db -n <pki-kra-KRA> -i /export/pki/omega_alpha.ldif
# /usr/lib64/dirsrv/slapd-omega/ldif2db -n <pki-kra-KRA> -i /export/pki/omega_alpha.ldifCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the Directory Server:
systemctl start dirsrv@omega
# systemctl start dirsrv@omegaCopy to Clipboard Copied! Toggle word wrap Toggle overflow Start the KRA instance.
systemctl start pki-tomcatd@<pki-kra>
# systemctl start pki-tomcatd@<pki-kra>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
20.2.4. Validating the presence of migrated keys from the KRA Agent Page
The last step is to perform key recovery of migrated keys from the KRA Agent page.
20.2.5. Post-Upgrade Testing
Follow the key recovery operation for user key archived before upgrade.
Procedure 21.1. Key Recovery Test
Display the base64 user certificate created before upgrade.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Use this certificate to generate a key recovery request through KRA Agent UI.
Approve the recovery request.
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Download the key from the KRA UI.
Chapter 21. Upgrading Certificate System 10 to the latest minor version
To upgrade Red Hat Certificate System 10 to the latest minor version, for example 10.5, you need to update the packages and the configuration files.
Upgrade all packages on the server:
dnf update
# dnf updateCopy to Clipboard Copied! Toggle word wrap Toggle overflow During the update, Certificate System configuration files, such as
/etc/pki/<instance_name>/subsystem/CS.cfgand/etc/pki/<instance_name>/server.xml, are automatically modified to the new version.Log files generated during the Certificate System upgrade are:
-
/var/log/pki/pki-server-upgrade-version.log /var/log/pki/pki-upgrade-version.logNote that the version number in the log file’s name represent the pki* package version and not the Certificate System version.
NoteIf Directory Server is installed on a different host, additionally update all packages on that host as well. For details about updating Directory Server, see:
- the corresponding chapter in the Red Hat Directory Server Installation Guide.
- Red Hat Directory Server Release Notes for notable changes, bug fixes, and known issues in Directory Server.
-
Restart the Certificate System instance:
systemctl restart pki-tomcatd@<instance_name>.service
# systemctl restart pki-tomcatd@<instance_name>.serviceCopy to Clipboard Copied! Toggle word wrap Toggle overflow
To migrate from a lower major version, such as 9.7, to Certificate System 10, see Chapter 20, Upgrading from Certificate System 9 to Certificate System 10.
Part V. Uninstalling Certificate System subsystems
This part provides information on the maintenance of Red Hat Certificate System.
Chapter 22. Uninstalling Certificate System subsystems
It is possible to remove individual subsystems or to uninstall all packages associated with an entire subsystem. Subsystems are installed and uninstalled individually. For example, it is possible to uninstall a KRA subsystem while leaving an installed and configured CA subsystem. It is also possible to remove a single CA subsystem while leaving other CA subsystems on the machine.
22.1. Removing a subsystem
Removing a subsystem requires specifying the subsystem type and the name of the server in which the subsystem is running. This command removes all files associated with the subsystem (without removing the subsystem packages).
pkidestroy -s subsystem_type -i instance_name
pkidestroy -s subsystem_type -i instance_name
The -s option specifies the subsystem to be removed (such as CA, KRA, OCSP, TKS, or TPS). The -i option specifies the instance name, such as pki-tomcat.
For example, to remove a CA subsystem:
The pkidestroy utility removes the subsystem and any related files, such as the certificate databases, certificates, keys, and associated users. It does not uninstall the subsystem packages. If the subsystem is the last subsystem on the server instance, the server instance is removed as well.
22.2. Removing Certificate System subsystem packages
A number of subsystem-related packages and dependencies are installed with Red Hat Certificate System; these are listed in Section 6.4, “Certificate System packages”. Removing a subsystem removes only the files and directories associated with that specific subsystem. It does not remove the actual installed packages that are used by that instance. Completely uninstalling Red Hat Certificate System or one of its subsystems requires using package management tools, like dnf, to remove each package individually.
To uninstall an individual Certificate System subsystem package:
Remove all the associated subsystems. For example:
pkidestroy -s CA -i pki-tomcat
pkidestroy -s CA -i pki-tomcatCopy to Clipboard Copied! Toggle word wrap Toggle overflow Run the uninstall utility. For example:
dnf remove pki-subsystem_type
dnf remove pki-subsystem_typeCopy to Clipboard Copied! Toggle word wrap Toggle overflow The subsystem type can be
ca,kra,ocsp,tks, ortps.-
To remove other packages and dependencies, remove the packages specifically, using
dnf. The complete list of installed packages is at Section 6.4, “Certificate System packages”.
Part VI. Appendix: Sample configuration files
Chapter 23. Sample configuration files for pkispawn
This section contains sample configuration files for pkispawn for the various installation methods.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}