Search
SupportConsoleDevelopersStart a trialContact

6.2. Revoking Certificates

download PDF

6.2.1. Performing a CMC Revocation

Similar to Certificate Management over CMS (CMC) enrollment, CMC revocation enables users to set up a revocation client, and sign the revocation request with either an agent certificate or a user certificate with a matching subjectDN attribute. Then the user can send the signed request to the Certificate Manager.
Alternatively, CMC revocation can also be authenticated using the Shared Secret Token mechanism. For details, see Section 8.1.3, “CMC SharedSecret Authentication”.
Regardless of whether a user or agent signs the request or if a Shared Secret Token is used, the Certificate Manager automatically revokes the certificate when it receives a valid revocation request.
Certificate System provides the following utilities for CMC revocation requests:

Important

Red Hat recommends using the CMCRequest utility to generate CMC revocation requests, because it provides more options than CMCRevoke.

6.2.1.1. Revoking a Certificate Using CMCRequest

To revoke a certificate using CMCRequest:
  1. Create a configuration file for the CMC revocation request, such as /home/user_name/cmc-request.cfg, with the following content: 
    #numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#output: full path for the CMC request in binary format
output=/home/user_name/cmc.revoke.userSigned.req

#tokenname: name of token where user signing cert can be found
#(default is internal)
tokenname=internal

#nickname: nickname for user signing certificate which will be used
#to sign the CMC full request.
nickname=signer_user_certificate

#dbdir: directory for cert8.db, key3.db and secmod.db
dbdir=/home/user_name/.dogtag/nssdb/

#password: password for cert8.db which stores the user signing
#certificate and keys
password=myPass

#format: request format, either pkcs10 or crmf.
format=pkcs10

## revocation parameters
revRequest.enable=true
revRequest.serial=45
revRequest.reason=unspecified
revRequest.comment=user test revocation
revRequest.issuer=issuer
revRequest.sharedSecret=shared_secret
  2. Create the CMC request: 
    # CMCRequest /home/user_name/cmc-request.cfg
    If the command succeeds, the CMCRequest utility stores the CMC request in the file specified in the output parameter in the request configuration file.
  3. Create a configuration file, such as /home/user_name/cmc-submit.cfg, which you use in a later step to submit the CMC revocation request to the CA. Add the following content to the created file: 
    #host: host name for the http server
host=>server.example.com

#port: port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be
#in binary format
input=/home/user_name/cmc.revoke.userSigned.req

#output: full path for the response in binary format
output=/home/user_name/cmc.revoke.userSigned.resp

#tokenname: name of token where TLS client authentication certificate
#can be found (default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert8.db, key3.db and secmod.db
#This parameter will be ignored if secure=false
dbdir=/home/user_name/.dogtag/nssdb/

#clientmode: true for client authentication, false for no client
#authentication. This parameter will be ignored if secure=false
clientmode=true

#password: password for cert8.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=signer_user_certificate

    Important

    If the CMC revocation request is signed, set the secure and clientmode parameters to true and, additionally, fill the nickname parameter.
  4. Depending on who signed the request, the servlet parameter in the configuration file for HttpClient must be set accordingly:
    • If an agent signed the request, set: 
      servlet=/ca/ee/ca/profileSubmitCMCFull
    • If a user signed the request, set: 
      servlet=/ca/ee/ca/profileSubmitUserSignedCMCFull
  5. Submit the CMC request: 
    # HttpClient /home/user_name/cmc-submit.cfg
For further details about revoking a certificate using CMCRequest, see the CMCRequest(1) man page.

6.2.1.2. Revoking a Certificate Using CMCRevoke

The CMC revocation utility, CMCRevoke, is used to sign a revocation request with an agent's certificate. This utility simply passes the required information — certificate serial number, issuer name, and revocation reason — to identify the certificate to revoke, and then the require information to identify the CA agent performing the revocation (certificate nickname and the database with the certificate).

Important

Using CMCRevoke requires that the CA administrator followed the instructions specified in the Enabling CMCRevoke for the Web User Interface section in the Red Hat Certificate System 9 Planning, Installation and Deployment Guide (Common Criteria Edition) during the installation.
The reason the certificate is being revoked can be any of the following (with the number being the value passed to the CMCRevoke utility):
  • 0 — unspecified
  • 1 — the key was compromised
  • 2 — the CA key was compromised
  • 3 — the employee's affiliation changed
  • 4 — the certificate has been superseded
  • 5 — cessation of operation
  • 6 — the certificate is on hold
The available tool arguments are described in detail in the Command-Line Tools Guide.
6.2.1.2.1. Testing CMCRevoke
  1. Create a CMC revocation request for an existing certificate. 
    CMCRevoke -d/path/to/agent-cert-db -nnickname -iissuerName -sserialName -mreason -ccomment
    For example, if the directory containing the agent certificate is ~jsmith/.mozilla/firefox/, the nickname of the certificate is AgentCert, and the serial number of the certificate is 22, the command is as shown: 
    CMCRevoke -d"~jsmith/.mozilla/firefox/" -n"ManagerAgentCert" -i"cn=agentAuthMgr" -s22 -m0 -c"test comment"

    Note

    Surround values that include spaces in quotation marks.

    Important

    Do not have a space between the argument and its value. For example, giving a serial number of 26 is -s26, not -s 26.
  2. Open the end-entities page. 
    https://server.example.com:8443/ca/ee/ca
  3. Select the Revocation tab.
  4. Select the CMC Revoke link on the menu.
  5. Paste the output from the CMCRevoke into the text area.
  6. Remove -----BEGIN NEW CERTIFICATE REQUEST----- and ----END NEW CERTIFICATE REQUEST----- from the pasted content.
  7. Click Submit.
  8. The returned page should confirm that correct certificate has been revoked.

6.2.2. Performing Revocation as an Agent from the Web UI

A Certificate Manager agent can use the agent services page to find a specific certificate issued by the Certificate System or to retrieve a list of certificates that match specified criteria. The certificates which are retrieved can be examined or revoked by the agent. The Certificate Manager agent can also manage the certificate revocation list (CRL).

6.2.2.1. Listing Certificates

It is possible to list certificates within a range of serial numbers. All certificates within the range may be displayed or, if the agent selects, only those that are currently valid.
To find a specific certificate or to list certificates by serial number:
  1. Open the Certificate Manager agent services page.
  2. Click List Certificates.
    List Certificates

    Figure 6.1. List Certificates

    • To find a certificate with a specific serial number, enter the serial number in both the upper limit and lower limit fields of the List Certificates form, in either decimal or hexadecimal form. Use 0x to indicate the beginning of a hexadecimal number; for example, 0x00000006. Serial numbers are displayed in hexadecimal form in the Search Results and Details pages.
    • To find all certificates within a range of serial numbers, enter the upper and lower limits of the serial number range in decimal or hexadecimal form.
    Leaving either the lower limit or upper limit field blank displays the certificate with the specified number, plus all certificates before or after it in sequence.
  3. To limit the returned list to valid certificates, select the check boxes labeled with filtering methods. It is possible to include revoked certificates, to include expired certificates or certificates that are not yet valid, or to display only valid certificates.
  4. Enter the maximum number of certificates matching the criteria that should be returned in the results page.
    When any number is entered, the first certificates up to that number matching the criteria are displayed.
  5. Click Find.
    The Certificate System displays a list of the certificates that match the search criteria. Select a certificate in the list to examine it in more detail or perform various operations on it. For more information, refer to Section 6.2.2.3, “Examining Certificate Details”.

6.2.2.3. Examining Certificate Details

  1. On the agent services page, click List Certificates or Search for Certificates, specify search criteria, and click Find to display a list of certificates.
  2. On the Search Results form, select a certificate to examine.
    If the desired certificate is not shown, scroll to the bottom of the list, specify an additional number of certificates to be returned, and click Find. The system displays the next certificates up to that number that match the original search criteria.
  3. After selecting a certificate, click the Details button at the left side of its entry.
  4. The Certificate page shows the detailed contents of the selected certificate and instructions for installing the certificate in a server or in a web browser.
    Certificate Details

    Figure 6.2. Certificate Details

  5. The certificate is shown in base-64 encoded form at the bottom of the Certificate page, under the heading Installing this certificate in a server.

6.2.2.4. Revoking Certificates

Only Certificate Manager agents can revoke certificates other than their own. A certificate must be revoked if one of the following situations occurs:
  • The owner of the certificate has changed status and no longer has the right to use the certificate.
  • The private key of a certificate owner has been compromised.
These two reasons are not the only ones why a certificate would need revoked; there are six reasons available for revoking a certificate.
To revoke one or more certificates, search for the certificates to revoke using the Revoke Certificates button. While the search is similar to the one through the Search for Certificates form, the Search Results form returned by this search offers the option of revoking one or all of the returned certificates.
6.2.2.4.1. Revoking Certificates
  1. Open the Certificate Manager agent services page.
  2. Click Revoke Certificates.

    Note

    The search form that appears has the same search criteria sections as the Search for Certificates form.
  3. Specify the search criteria by selecting the check boxes for the sections and filling in the required information.
  4. Scroll to the bottom of the form, and set the number of matching certificates to display.
  5. Click Find.
  6. The search returns a list of matching certificates. It is possible to revoke one or all certificates in the list.

    Note

    If the search criteria are very specific and all of the certificates returned are to be revoked, then click the Revoke ALL # Certificates button at the bottom of the page. The number shown on the button is the total number of certificates returned by the search. This is usually a larger number than the number of certificates displayed on the current page.
    Verify that all of the certificates returned by the search should be revoked, not only those displayed on the current page.
  7. Click the Revoke button next to the certificate to be revoked.

    Warning

    Whether revoking a single certificate or a list of certificates, be extremely careful that the correct certificate has been selected or that the list contains only certificates which should be revoked. Once a revocation operation has been confirmed, there is no way to undo it.
  8. Select an invalidity date. The invalidity date is the date which it is known or suspected that the user's private key was compromised or that the certificate became invalid. A set of drop down lists allows the agent to select the correct invalidity date.
  9. Select a reason for the revocation.
    • Key compromised
    • CA key compromised
    • Affiliation changed
    • Certificate superseded
    • Cessation of operation
    • Certificate is on hold
  10. Enter any additional comment. The comment is included in the revocation request.
When the revocation request is submitted, it is automatically approved, and the certificate is revoked. Revocation requests are viewed by listing requests with a status of Completed.
6.2.2.4.2. Taking Ceritificates Off Hold
There can be instances when a certificate is inaccessible, and therefore should be treated as revoked, but that certificate can be recovered. For example, a user may have a personal email certificate stored on a flash drive which he accidentally leaves at home. The certificate is not compromised, but it should be temporarily suspended.
That certificate can be temporarily revoked by putting it on hold (one of the options given when revoking a certificate, as in Section 6.2.2.4.1, “Revoking Certificates”). At a later time — such as when the forgotten flash drive is picked up — that certificate can be taken off hold and is again active.
  1. Search for the on hold certificate, as in Section 6.2.2.2, “Searching for Certificates (Advanced)”. Scroll to the Revocation Information section, and set the Certificate is on hold revocation reason as the search criterion.
  2. In the results list, click the Off Hold button by the certificate to take off hold.

6.2.2.5. Managing the Certificate Revocation List

Revoking a certificate notifies other users that the certificate is no longer valid. This notification is done by publishing a list of the revoked certificates, called the certificate revocation list (CRL), to an LDAP directory or to a flat file. This list is publicly available and ensures that revoked certificates are not misused.
6.2.2.5.1. Viewing or Examining CRLs
It may be necessary to view or examine a CRL, such as before manually updating a directory with the latest CRL. To view or display the CRL:
  1. Go to the Certificate Manager agent services page.
  2. Click Display Certificate Revocation List to display the form for viewing the CRL.
  3. Select the CRL to view. If the administrator has created multiple issuing points, these are listed in the Issuing point drop-down list. Otherwise, only the master CRL is shown.
  4. Choose how to display the CRL by selecting one of the options from the Display Type menu. The choices on this menu are as follows:
    • Cached CRL. Views the CRL from the cache rather than from the CRL itself. This option displays results faster than viewing the entire CRL.
    • Entire CRL. Retrieves and displays the entire CRL.
    • CRL header. Retrieves and displays the CRL header only.
    • Base 64 Encoded. Retrieves and displays the CRL in base-64 encoded format.
    • Delta CRL. Retrieves and displays a delta CRL, which is a subset of the CRL showing only new revocations since the last CRL was published. This option is available only if delta CRL generation is enabled.
  5. To examine the selected CRL, click Display.
    The CRL appears in the browser window. This allows the agent to check whether a particular certificate (by its serial number) appears in the list and to note recent changes such as the total number of certificates revoked since the last update, the total number of certificates taken off hold since the last update, and the total number of certificates that expired since the last update.
6.2.2.5.2. Updating the CRL
CRLs can be automatically updated if a schedule for automatic CRL generation is enabled, and the schedule can set the CRL to be generated at set time schedules or whenever there are certificate revocations.
Likewise, CRLs can be also automatically published if CRL publishing is enabled.
In some cases, the CRL may need to be updated manually, such as updating the list after the system has been down or removing expired certificates to reduce the file size. (Expired certificates do not need to be included in the CRL because they are already invalid because of the expiration date.) Only a Certificate Manager agent can manually update the CRL.
To update the CRL manually:
  1. Open the Certificate Manager agent services page.
  2. Click Update Revocation List to display the form for updating the CRL.
    Update Certificate Revocation List

    Figure 6.3. Update Certificate Revocation List

  3. Select the CRL issuing point which will update the CRL. There can be multiple issuing points configured for a single CA.
  4. Select the algorithm to use to sign the new CRL. Before choosing an algorithm, make sure that any system or network applications that need to read or view this CRL support the algorithm.
    • SHA-256 with RSA.
    • SHA-384 with RSA.
    • SHA-512 with RSA.
    Before selecting an algorithm, make sure that the Certificate System has that algorithm enabled. The Certificate System administrator will have that information.
  5. Click Update to update the CRL with the latest certificate revocation information.

6.2.3. Performing Revocation on Own Certificate as a User Using the Web UI

Revoking a certificate invalidates it before its expiration date. This can be necessary if a certificate is lost, compromised, or no longer needed.

6.2.3.1. Revoking Your User Certificate

  1. Click the Revocation tab.
  2. Click the User Certificate link.
  3. Select the reason why the certificate is being revoked, and click Submit.
  4. Select the certificates to revoke from the list.

6.2.3.2. Checking Whether a Certificate Is Revoked

  1. Click the Retrieval tab.
  2. Click the Import Certificate Revocation List link.
  3. Select the radio button by Check whether the following certificate is included in CRL cache or Check whether the following certificate is listed by CRL, and enter the serial number of the certificate.
  4. Click the Submit button.
    A message is returned either saying that the certificate is not listed in any CRL or giving the information for the CRL which contains the certificate.

6.2.3.3. Downloading and Importing CRLs

Certificate revocation lists (CRLs) can be downloaded and installed in a web client, application, or machine. They can also be viewed to see what certificates have been revoked.
  1. Click the Retrieval tab.
  2. Click the Import Certificate Revocation List link.
  3. Select the radio button to view, download, or import the CRL.
    • To import the CRL into the browser or download and save it, select the appropriate radio button. There are two options: to download/import the full CRL or the delta CRL. The delta CRL only imports/downloads the list of certificates which have been revoked since the last time the CRL was generated.
    • To view the CRL, select Display the CRL information and select which CRL subset (called an issuing point) to view. This shows the CRL information, including the number of certificates included in it.
  4. Click the Submit button.
  5. Save the file or approve the import operation.
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.