Search
SupportConsoleDevelopersStart a trialContact

2.4. PKI with Certificate System

download PDF
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:
  1. 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.
  2. The enrollment form triggers the creation of the public and private keys or for dual-key pairs for the request.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. The certificate request is either rejected because it did not meet the certificate profile or authentication requirements, or a certificate is issued.
  9. 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.
  10. An automatic notice can be sent to the end entity when the certificate is issued or rejected.
  11. The new certificate is stored in the Certificate Manager's internal database.
  12. If publishing is set up for the Certificate Manager, the certificate is published to a file or an LDAP directory.
  13. 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:
  1. Generate a PKCS #10 or CRMF certificate signing request (CSR) using a utility, such as PKCS10Client or CRMFPopClient.

    Note

    If key archival is enabled in the Key Recovery Agent (KRA), use the CRMFPopClient utility with the KRA's transport certificate in Privacy Enhanced Mail (PEM) format set in the kra.transport file.
  2. Use the CMCRequest utility to convert the CSR into a CMC request. The CMCRequest 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.
  3. 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 the HttpClient 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 the HttpClient command without any parameters.
  4. Use the CMCResponse utility to check the issuance result of the PKCS #7 file generated by HttpClient. If the request is successful, CMCResponse displays the certificate chain in a readable format.
    For further details, see the CMCResponse(1) man page.
  5. Import the new certificate into the application. For details, follow the instructions of the application to which you want to import the certificate.

    Note

    The certificate retrieved by HttpClient is in PKCS #7 format. If the application supports only Base64-encoded certificates, use the BtoA 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.4. The Shared Secret Workflow
Certificate System provides the Shared Secret authentication mechanism for CMC requests according to RFC 5272. In order to protect the passphrase, an issuance protection certificate must be provided when using the CMCSharedToken command. The issuance protection certificate works similar to the KRA transport certificate. For further details, see the CMCSharedToken(1) man page and Section 13.8.3, “Enabling the CMC Shared Secret Feature”.

Shared Secret Created by the End Entity User (Preferred)

The following describes the workflow, if the user generates the shared secret:
  1. The end entity user obtains the issuance protection certificate from the CA administrator.
  2. The end entity user uses the CMCSharedToken utility to generate a shared secret token.

    Note

    The -p option sets the passphrase that is shared between the CA and the user, not the password of the token.
  3. The end entity user sends the encrypted shared token generated by the CMCSharedToken utility to the administrator.
  4. The administrator adds the shared token into the shrTok attribute in the user's LDAP entry.
  5. The end entity user uses the passphrase to set the witness.sharedSecret parameter in the configuration file passed to the CMCRequest utility.

Shared Secret Created by the CA Administrator

The following describes the workflow, if the CA administrator generates the shared secret for a user:
  1. The administrator uses the CMCSharedToken utility to generate a shared secret token for the user.

    Note

    The -p option sets the passphrase that is shared between the CA and the user, not the password of the token.
  2. The administrator adds the shared token into the shrTok attribute in the user's LDAP entry.
  3. The administrator shares the passphrase with the user.
  4. The end entity user uses the passphrase to set the witness.sharedSecret parameter in the configuration file passed to the CMCRequest utility.
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.
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.
  1. 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.
  2. The CA periodically publishes CRLs to an OCSP responder.
  3. The OCSP responder maintains the CRL it receives from the CA.
  4. 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.
  5. 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 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.
How the Key Archival Process Works in Client-Side Key Generation

Figure 2.2. How the Key Archival Process Works in Client-Side Key Generation

  1. The client generates a CRMF request and submits it through the CA’s enrollment portal.
    1. The client’s private key is wrapped within the CRMF request and can only be unwrapped by the KRA.
  2. Detecting that it’s a CRMF request with key archival option, CA forwards the request to KRA for private key archival.
  3. The KRA decrypts / unwraps the user private key, and after confirming that the private key corresponds to the public key, the KRA encrypts / wraps it again before storing it in its internal LDAP database.
  4. Once the private encryption key has been successfully stored, the KRA responds to CA confirming that the key has been successfully archived.
  5. The CA sends the request down its Enrollment Profile Framework for certificate information content creation as well as validation. When everything passes, it then issues the certificate and sends it back to the end entity in its response.

2.4.5.2. Recovering Keys

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

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:
  1. Generate a new KRA transport key and certificate
  2. Transfer the new transport key and certificate to KRA clones
  3. Update the CA configuration with the new KRA transport certificate
  4. 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
  1. Request the KRA transport certificate.
    1. Stop the KRA: 
      # systemctl stop pki-tomcatd@pki-kra.service
      OR (if using the nuxwdog watchdog) 
      # systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
    2. Go to the KRA NSS database directory: 
      # cd /etc/pki/pki-kra/alias
    3. Create a subdirectory and save all the NSS database files into it. For example: 
      mkdir nss_db_backup
cp *.db nss_db_backup
    4. 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 the certutil 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
    5. Submit the transport certificate request on the Manual Data Recovery Manager Transport Certificate Enrollment page of the CA End-Entity page.
    6. Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
  2. Approve the KRA transport certificate through the CA Agent Services interface.
  3. Retrieve the KRA transport certificate.
    1. Go to the KRA NSS database directory: 
      # cd /etc/pki/pki-kra/alias
    2. Wait for the agent approval of the submitted request to retrieve the certificate by checking the request status on the End-Entity retrieval page.
    3. 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-----).
  4. Import the KRA transport certificate.
    1. Go to the KRA NSS database directory: 
      # cd /etc/pki/pki-kra/alias
    2. 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
  5. Update the KRA transport certificate configuration.
    1. Go to the KRA NSS database directory: 
      # cd /etc/pki/pki-kra/alias
    2. Verify that the new KRA transport certificate is imported: 
      # certutil -d . -L
# certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
    3. 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
  1. Start the KRA: 
    # systemctl start pki-tomcatd@pki-kra.service
    or (if using the nuxwdog watchdog) 
    # systemctl start pki-tomcatd-nuxwdog@pki-kra.service
  2. Extract the new transport key and certificate for propagation to clones.
    1. Go to the KRA NSS database directory: 
      # cd /etc/pki/pki-kra/alias
    2. Stop the KRA: 
      # systemctl stop pki-tomcatd@pki-kra.service
      or (if using the nuxwdog watchdog) 
      # systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
    3. Verify that the new KRA transport certificate is present: 
      # certutil -d . -L
# certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
    4. Export the KRA new transport key and certificate: 
      # pk12util -o transport.p12 -d . -n 'transportCert-serial_number cert-pki-kra KRA'
    5. Verify the exported KRA transport key and certificate: 
      # pk12util -l transport.p12
  3. Perform these steps on each KRA clone:
    1. Copy the transport.p12 file, including the transport key and certificate, to the KRA clone location.
    2. Go to the clone NSS database directory: 
      # cd /etc/pki/pki-kra/alias
    3. Stop the KRA clone: 
      # systemctl stop pki-tomcatd@pki-kra.service
      or (if using the nuxwdog watchdog) 
      # systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
    4. Check the content of the clone NSS database: 
      # certutil -d . -L
    5. Import the new transport key and certificate of the clone: 
      # pk12util -i transport.p12 -d .
    6. 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
    7. Start the KRA clone: 
      # systemctl start pki-tomcatd@pki-kra.service
      or (if using the nuxwdog watchdog) 
      # systemctl start pki-tomcatd-nuxwdog@pki-kra.service
Updating the CA configuration with the new KRA transport certificate
  1. Format the new KRA transport certificate for inclusion in the CA.
    1. Obtain the cert-serial_number.txt KRA transport certificate file created when retrieving the KRA transport certificate in the previous procedure.
    2. 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
  2. Do the following for the CA and all its clones corresponding to the KRA above:
    1. Stop the CA: 
      # systemctl stop pki-tomcatd@pki-ca.service
      or (if using the nuxwdog watchdog) 
      # systemctl stop pki-tomcatd-nuxwdog@pki-ca.service
    2. 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 in cert-one-line-serial_number.txt.
    3. Start the CA: 
      # systemctl start pki-tomcatd@pki-ca.service
      or (if using the nuxwdog 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:
  1. Go to the KRA NSS database directory: 
    # cd /etc/pki/pki-kra/alias
  2. Stop the KRA: 
    # systemctl stop pki-tomcatd@pki-kra.service
    or (if using the nuxwdog watchdog) 
    # systemctl stop pki-tomcatd-nuxwdog@pki-kra.service
  3. Verify that the new KRA transport certificate is imported: 
    # certutil -d . -L
# certutil -d . -L -n 'transportCert-serial_number cert-pki-kra KRA'
  4. Open the /var/lib/pki/pki-kra/kra/conf/CS.cfg file, and look for the nickName value included in the following line: 
    kra.transportUnit.nickName=transportCert cert-pki-kra KRA
    Replace the nickName value with the newNickName value included in the following line: 
    kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
    As a result, the CS.cfg file includes this line: 
    kra.transportUnit.nickName=transportCert-serial_number cert-pki-kra KRA
  5. Remove the following line from /var/lib/pki/pki-kra/kra/conf/CS.cfg: 
    kra.transportUnit.newNickName=transportCert-serial_number cert-pki-kra KRA
  6. Start the KRA: 
    # systemctl start pki-tomcatd@pki-kra.service
    or (if using the nuxwdog watchdog) 
    # systemctl start pki-tomcatd-nuxwdog@pki-kra.service
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.