2.4. PKI with Certificate System
The Certificate System is comprised of subsystems which each contribute different functions of a public key infrastructure. A PKI environment can be customized to fit individual needs by implementing different features and functions for the subsystems.
Note
A conventional PKI environment provides the basic framework to manage certificates stored in software databases. This is a non-TMS environment, since it does not manage certificates on smart cards. A TMS environment manages the certificates on smart cards.
At a minimum, a non-TMS requires only a CA, but a non-TMS environment can use OCSP responders and KRA instances as well.
2.4.1. Issuing Certificates
As stated, the Certificate Manager is the heart of the Certificate System. It manages certificates at every stage, from requests through enrollment (issuing), renewal, and revocation.
The Certificate System supports enrolling and issuing certificates and processing certificate requests from a variety of end entities, such as web browsers, servers, and virtual private network (VPN) clients. Issued certificates conform to X.509 version 3 standards.
For more information, see About Enrolling and Renewing Certificates.
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
PKCS10Client
orCRMFPopClient
.Note
If key archival is enabled in the Key Recovery Agent (KRA), use theCRMFPopClient
utility with the KRA's transport certificate in Privacy Enhanced Mail (PEM) format set in thekra.transport
file. - Use the
CMCRequest
utility to convert the CSR into a CMC request. TheCMCRequest
utility uses a configuration file as input. This file contains, for example, the path to the CSR and the CSR's format.For further details and examples, see the CMCRequest(1) man page. - Use the
HttpClient
utility to send the CMC request to the CA.HttpClient
uses a configuration file with settings, such as the path to the CMC request file and the servlet.If theHttpClient
command succeeds, the utility receives a PKCS #7 chain with CMC status controls from the CA.For details about what parameters the utility provides, enter theHttpClient
command without any parameters. - Use the
CMCResponse
utility to check the issuance result of the PKCS #7 file generated byHttpClient
. If the request is successful,CMCResponse
displays the certificate chain in a readable format.For further details, see the CMCResponse(1) man page. - Import the new certificate into the application. For details, follow the instructions of the application to which you want to import the certificate.
Note
The certificate retrieved byHttpClient
is in PKCS #7 format. If the application supports only Base64-encoded certificates, use theBtoA
utility to convert the certificate.Additionally, certain applications require a header and footer for certificates in Privacy Enhanced Mail (PEM) format. If these are required, add them manually to the PEM file after you converted the certificate.
2.4.1.1.2.2.1. CMC Enrollment without POP
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.
Note
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.8.3, “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
2.4.1.2. Certificate Profiles
The Certificate System uses certificate profiles to configure the content of the certificate, the constraints for issuing the certificate, the enrollment method used, and the input and output forms for that enrollment. A single certificate profile is associated with issuing a particular type of certificate.
A set of certificate profiles is included for the most common certificate types; the profile settings can be modified. Certificate profiles are configured by an administrator, and then sent to the agent services page for agent approval. Once a certificate profile is approved, it is enabled for use. In case of a UI-enrollment, a dynamically-generated HTML form for the certificate profile is used in the end-entities page for certificate enrollment, which calls on the certificate profile. In case of a command line-based enrollment, the certificate profile is called upon to perform the same processing, such as authentication, authorization, input, output, defaults, and constraints. The server verifies that the defaults and constraints set in the certificate profile are met before acting on the request and uses the certificate profile to determine the content of the issued certificate.
The Certificate Manager can issue certificates with any of the following characteristics, depending on the configuration in the profiles and the submitted certificate request:
- Certificates that are X.509 version 3-compliant
- Unicode support for the certificate subject name and issuer name
- Support for empty certificate subject names
- Support for customized subject name components
- Support for customized extensions
By default, the certificate enrollment profiles are stored in
<instance directory>/ca/profiles/ca
with names in the format of <profile id>.cfg
. LDAP-based profiles are possible with proper pkispawn
configuration parameters.
2.4.1.3. Authentication for Certificate Enrollment
Certificate System provides authentication options for certificate enrollment. These include agent-approved enrollment, in which an agent processes the request, and automated enrollment, in which an authentication method is used to authenticate the end entity and then the CA automatically issues a certificate. CMC enrollment is also supported, which automatically processes a request approved by an agent.
2.4.1.4. Cross-Pair Certificates
It is possible to create a trusted relationship between two separate CAs by issuing and storing cross-signed certificates between these two CAs. By using cross-signed certificate pairs, certificates issued outside the organization's PKI can be trusted within the system.
2.4.2. Renewing Certificates
When certificates reach their expiration date, they can either be allowed to lapse, or they can be renewed.
Renewal regenerates a certificate request using the existing key pairs for that certificate, and then resubmits the request to Certificate Manager. The renewed certificate is identical to the original (since it was created from the same profile using the same key material) with one exception — it has a different, later expiration date.
Renewal can make managing certificates and relationships between users and servers much smoother, because the renewed certificate functions precisely as the old one. For user certificates, renewal allows encrypted data to be accessed without any loss.
2.4.3. Publishing Certificates and CRLs
Certificates can be published to files and an LDAP directory, and CRLs to files, an LDAP directory, and an OCSP responder. The publishing framework provides a robust set of tools to publish to all three places and to set rules to define with more detail which types of certificates or CRLs are published where.
2.4.4. Revoking Certificates and Checking Status
End entities can request that their own certificates be revoked. When an end entity makes the request, the certificate has to be presented to the CA. If the certificate and the keys are available, the request is processed and sent to the Certificate Manager, and the certificate is revoked. The Certificate Manager marks the certificate as revoked in its database and adds it to any applicable CRLs.
An agent can revoke any certificate issued by the Certificate Manager by searching for the certificate in the agent services interface and then marking it revoked. Once a certificate is revoked, it is marked revoked in the database and in the publishing directory, if the Certificate is set up for publishing.
If the internal OCSP service has been configured, the service determines the status of certificates by looking them up in the internal database.
Automated notifications can be set to send email messages to end entities when their certificates are revoked by enabling and configuring the certificate revoked notification message.
2.4.4.1. Revoking Certificates
Users can revoke their certificates using:
- The end-entity pages. For details, see the Certificate Revocation Pages section in the Red Hat Certificate System Administration Guide.
- The
CMCRequest
utility on the command line. For details, see the Performing a CMC Revocation section in the Red Hat Certificate System Administration Guide. - The
pki
utility on the command line. For details, see pki-cert(1) man page.
2.4.4.2. Certificate Status
2.4.4.2.1. CRLs
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.
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.
Note
The OCSP responder will never return a response of Unknown. The response will always be either Good or Revoked.
2.4.4.2.2.3. OCSP Services
There are two ways to set up OCSP services:
- The OCSP built into the Certificate Manager
- The Online Certificate Status Manager subsystem
In addition to the built-in OCSP service, the Certificate Manager can publish CRLs to an OCSP-compliant validation authority. CAs can be configured to publish CRLs to the Certificate System Online Certificate Status Manager. The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses the appropriate CRL to verify the revocation status of a certificate when queried by an OCSP-compliant client.
The Certificate Manager can generate and publish CRLs whenever a certificate is revoked and at specified intervals. Because the purpose of an OCSP responder is to facilitate immediate verification of certificates, the Certificate Manager should publish the CRL to the Online Certificate Status Manager every time a certificate is revoked. Publishing only at intervals means that the OCSP service is checking an outdated CRL.
Note
If the CRL is large, the Certificate Manager can take a considerable amount of time to publish the CRL.
The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL to verify certificates. The Online Certificate Status Manager can also use the CRL published to an LDAP directory, meaning the Certificate Manager does not have to update the CRLs directly to the Online Certificate Status Manager.
2.4.5. Archiving, Recovering, and Rotating Keys
In the world of PKI, private key archival allows parties the possibility to recover the encrypted data in case the private key is lost. Private keys can be lost due to various reasons such as hardware failure, forgotten passwords, lost smartcards, incapacitated password holder, et caetera. Such archival and recovery feature is offered by the Key Recovery Authority (KRA) subsystem of RHCS.
Only keys that are used exclusively for encrypting data should be archived; signing keys in particular should never be archived. Having two copies of a signing key makes it impossible to identify with certainty who used the key; a second archived copy could be used to impersonate the digital identity of the original key owner.
2.4.5.1. Archiving Keys
There are two types of key archival mechanisms provided by KRA:
- Client-side key generation: With this mechanism, clients are to generate CSRs in CRMF format, and submit the requests to the CA (with proper KRA setup) for enrollment and key archival. See 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 Generating CSRs Using Server-Side Key Generation.
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.
![How the Key Archival Process Works in Client-Side Key Generation](https://access.redhat.com/webassets/avalon/d/Red_Hat_Certificate_System-9-Planning_Installation_and_Deployment_Guide-en-US/images/591e11328765db4b1aba2a34143c6f1e/kra_arc.png)
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”.
![Asynchronous Recovery](https://access.redhat.com/webassets/avalon/d/Red_Hat_Certificate_System-9-Planning_Installation_and_Deployment_Guide-en-US/images/d210fdb84677e5169d8d69a913ed451a/recovery-options.png)
Figure 2.3. Asynchronous Recovery
The KRA informs the agent who initiated the key recovery process of the status of the authorizations.
When all of the authorizations are entered, the KRA checks the information. If the information presented is correct, it retrieves the requested key and returns it along with the corresponding certificate in the form of a PKCS #12 package to the agent who initiated the key recovery process.
Warning
The PKCS #12 package contains the encrypted private key. To minimize the risk of key compromise, the recovery agent must use a secure method to deliver the PKCS #12 package and password to the key recipient. The agent should use a good password to encrypt the PKCS #12 package and set up an appropriate delivery mechanism.
The key recovery agent scheme configures the KRA to recognize to which group the key recovery agents belong and specifies how many of these recovery agents are required to authorize a key recovery request before the archived key is restored.
Important
The above information refers to using a web browser, such as Firefox. However, functionality critical to KRA usage is no longer included in Firefox version 31.6 that was released on Red Hat Enterprise Linux 7 platforms. 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:
# systemctl stop pki-tomcatd@pki-kra.service
OR (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Create a subdirectory and save all the NSS database files into it. For example:
mkdir nss_db_backup cp *.db nss_db_backup
- Create a new request by using the
PKCS10Client
utility. For example:# PKCS10Client -p password -d '.' -o 'req.txt' -n 'CN=KRA Transport 2 Certificate,O=example.com Security Domain'
Alternatively, use thecertutil
utility. For example:# certutil -d . -R -k rsa -g 2048 -s 'CN=KRA Transport 2 Certificate,O=example.com Security Domain' -f password-file -a -o transport-certificate-request-file
- Submit the transport certificate request on the Manual Data Recovery Manager Transport Certificate Enrollment page of the CA End-Entity page.
- Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
- Approve the KRA transport certificate through the CA Agent Services interface.
- Retrieve the KRA transport certificate.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
- Once the new KRA transport certificate is available, paste its Base64-encoded value into a text file, for example a file named
cert-serial_number.txt
. Do not include the header (-----BEGIN CERTIFICATE-----
) or the footer (-----END CERTIFICATE-----
).
- Import the KRA transport certificate.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Import the transport certificate into the KRA NSS database:
# certutil -d . -A -n 'transportCert-serial_number cert-pki-kra KRA' -t 'u,u,u' -a -i cert-serial_number.txt
- Update the KRA transport certificate configuration.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Verify that the new KRA transport certificate is imported:
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file and add the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Propagating the new transport key and certificate to KRA clones
- Start the KRA:
# systemctl start pki-tomcatd@pki-kra.service
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-kra.service
- Extract the new transport key and certificate for propagation to clones.
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Stop the KRA:
# systemctl stop pki-tomcatd@pki-kra.service
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Verify that the new KRA transport certificate is present:
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Export the KRA new transport key and certificate:
# pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'
- Verify the exported KRA transport key and certificate:
# pk12util -l transport.p12
- Perform these steps on each KRA clone:
- Copy the
transport.p12
file, including the transport key and certificate, to the KRA clone location. - Go to the clone NSS database directory:
# cd /etc/pki/pki-kra/alias
- Stop the KRA clone:
# systemctl stop pki-tomcatd@pki-kra.service
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Check the content of the clone NSS database:
# certutil -d . -L
- Import the new transport key and certificate of the clone:
# pk12util -i transport.p12 -d .
- Add the following line to the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file on the clone:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Start the KRA clone:
# systemctl start pki-tomcatd@pki-kra.service
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-kra.service
- Updating the CA configuration with the new KRA transport certificate
- Format the new KRA transport certificate for inclusion in the CA.
- Obtain the
cert-serial_number.txt
KRA transport certificate file created when retrieving the KRA transport certificate in the previous procedure. - Convert the Base64-encoded certificate included in
cert-serial_number.txt
to a single-line file:# tr -d '\n' < cert-serial_number.txt > cert-one-line-serial_number.txt
- Do the following for the CA and all its clones corresponding to the KRA above:
- Stop the CA:
# systemctl stop pki-tomcatd@pki-ca.service
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-ca.service
- In the
/var/lib/pki/pki-ca/ca/conf/CS.cfg
file, locate the certificate included in the following line:ca.connector.KRA.transportCert=certificate
Replace that certificate with the one contained incert-one-line-serial_number.txt
. - Start the CA:
# systemctl start pki-tomcatd@pki-ca.service
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-ca.service
Note
While the CA and all its clones are being updated with the new KRA transport certificate, the CA instances that have completed the transition use the new KRA transport certificate, and the CA instances that have not yet been updated continue to use the old KRA transport certificate. Because the corresponding KRA and its clones have already been updated to use both transport certificates, no downtime occurs.- Updating the KRA configuration to use only the new transport key and certificate
- For the KRA and each of its clones, do the following:
- Go to the KRA NSS database directory:
# cd /etc/pki/pki-kra/alias
- Stop the KRA:
# systemctl stop pki-tomcatd@pki-kra.service
or (if using thenuxwdog watchdog
)# systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
- Verify that the new KRA transport certificate is imported:
# certutil -d . -L # certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
- Open the
/var/lib/pki/pki-kra/kra/conf/CS.cfg
file, and look for thenickName
value included in the following line:kra.transportUnit.nickName=transportCert cert-pki-kra KRA
Replace thenickName
value with thenewNickName
value included in the following line:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
As a result, theCS.cfg
file includes this line:kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRA
- Remove the following line from
/var/lib/pki/pki-kra/kra/conf/CS.cfg
:kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
- Start the KRA:
# systemctl start pki-tomcatd@pki-kra.service
or (if using thenuxwdog watchdog
)# systemctl start pki-tomcatd-nuxwdog@pki-kra.service