7.6. Using the Online Certificate Status Protocol (OCSP) Responder

7.6.1. Setting up the OCSP Responder

If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the OCSP service. The CA's CRL publishing is set up automatically, and its signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the OCSP service must be manually configured after the Online Certificate Status Manager is configured.

Note

Not every CA within the security domain to which the OCSP Manager belongs is automatically trusted by the OCSP Manager when it is configured. Every CA in the certificate chain of the CA configured in the CA panel is trusted automatically by the OCSP Manager. Other CAs within the security domain but not in the certificate chain must be trusted manually.
To set up the Online Certificate Status Manager for a Certificate Manager outside the security domain:
  1. Configure the CRLs for every CA that will publish to an OCSP responder.
  2. Enable publishing, set up a publisher, and set publishing rules in every CA that the OCSP service will handle (Chapter 8, Publishing Certificates and CRLs). This is not necessary if the Certificate Managers publish to an LDAP directory and the Online Certificated Status Manager is set up to read from that directory.
  3. The certificate profiles must be configured to include the Authority Information Access extension, pointing to the location at which the Certificate Manager listens for OCSP service requests (Section 7.6.4, “Enabling the Certificate Manager's Internal OCSP Service”).
  4. Configure the OCSP Responder.
  5. Restart both subsystems after configuring them.
  6. Verify that the CA is properly connected to the OCSP responder (Section 7.6.2.1, “Verify Certificate Manager and Online Certificate Status Manager Connection”).

7.6.2. Identifying the CA to the OCSP Responder

Before a CA is configured to publish CRLs to the Online Certificate Status Manager, the CA must be identified to the Online Certificate Status Manager by storing the CA signing certificate in the internal database of the Online Certificate Status Manager. The Certificate Manager signs CRLs with the key pair associated with this certificate; the Online Certificate Status Manager verifies the signature against the stored certificate.

Note

If a CA within the security domain is selected when the Online Certificate Status Manager is configured, there is no extra step required to configure the Online Certificate Status Manager to recognize the CA; the CA signing certificate is automatically added and trusted in the Online Certificate Status Manager's certificate database. However, if a non-security domain CA is selected, then the CA signing certificate must be manually added to the certificate database after the Online Certificate Status Manager is configured.
It is not necessary to import the certificate chain for a CA which will publish its CRL to the Online Certificate Status Manager. The only time a certificate chain is needed for the OCSP service is if the CA connects to the Online Certificate Status Manager through SSL/TLS authentication when it publishes its CRL. Otherwise, the Online Certificate Status Manager does not need to have the complete certificate chain.
However, the Online Certificate Status Manager must have the certificate which signed the CRL, either a CA signing certificate or a separate CRL signing certificate, in its certificate database. The OCSP service verifies the CRL by comparing the certificate which signed the CRL against the certificates in its database, not against a certificate chain. If both a root CA and one of its subordinate CAs publish CRLs to the Online Certificate Status Manager, the Online Certificate Status Manager needs the CA signing certificate of both CAs.
To import the CA or CRL signing certificate which is used to sign the certificates the CA is publishing to the Online Certificate Status Manager, do the following:
  1. Get the Certificate Manager's base-64 CA signing certificate from the end-entities page of the CA.
  2. Open the Online Certificate Status Manager agent page. The URL has the format https://hostname:SSLport/ocsp/agent/ocsp.
  3. In the left frame, click Add Certificate Authority.
  4. In the form, paste the encoded CA signing certificate inside the text area labeled Base 64 encoded certificate (including the header and footer).
  5. To verify that the certificate is added successfully, in the left frame, click List Certificate Authorities.
The resulting form should show information about the new CA. The This Update, Next Update, and Requests Served Since Startup fields should show a value of zero (0).

7.6.2.1. Verify Certificate Manager and Online Certificate Status Manager Connection

When the Certificate Manager is restarted, it tries to connect to the Online Certificate Status Manager's SSL/TLS port. To verify that the Certificate Manager did indeed communicate with the Online Certificate Status Manager, check the This Update and Next Update fields, which should be updated with the appropriate timestamps of the CA's last communication with the Online Certificate Status Manager. The Requests Served Since Startup field should still show a value of zero (0) since no client has tried to query the OCSP service for certificate revocation status.

7.6.2.2. Configure the Revocation Info Stores: Internal Database

The Online Certificate Status Manager stores each Certificate Manager's CRL in its internal database and uses it as the CRL store for verifying the revocation status of certificates. To change the configuration that the Online Certificate Status Manager uses for storing the CRLs in its internal database:
  1. Open the Online Certificate Status Manager Console.
    pkiconsole https://server.example.com:8443/ocsp
  2. In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
    The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
  3. Select the defStore, and click Edit/View.
  4. Edit the defStore values.
    • notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
    • byName. The OCSP Responder only supports the basic response type, which includes the ID of the OCSP Responder making the response. The ResponderID field within the basic response type is determined by the value of the ocsp.store.defStore.byName parameter. If byName parameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. If byName parameter is false, the OCSP authority signing certificate key hash will be the ResponderID field of the OCSP response.
    • includeNextUpdate. Includes the timestamp of the next CRL update time.

7.6.2.3. Configure the Revocation Info Stores: LDAP Directory

Although the OCSP Manager stores the CA CRLs in its internal database by default, it can be configured to use a CRL published to an LDAP directory instead.

Important

If the ldapStore method is enabled, the OCSP user interface does not check the certificate status.
To configure the Online Certificate Status Manager to use an LDAP directory:
  1. Open the Online Certificate Status Manager Console.
    pkiconsole https://server.example.com:8443/ocsp
  2. In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
    The right pane shows the two repositories the Online Certificate Status Manager can use; by default, it uses the CRL in its internal database.
  3. To use the CRLs in LDAP directories, click Set Default to enable the ldapStore option.
  4. Select ldapStore, and click Edit/View.
  5. Set the ldapStore parameters.
    • numConns. The total number of LDAP directories the OCSP service should check. By default, this is set to 0. Setting this value shows the corresponding number of host, port, baseDN, and refreshInSec fields.
    • host. The fully-qualified DNS hostname of the LDAP directory.
    • port. The non-SSL/TLS port of the LDAP directory.
    • baseDN. The DN to start searching for the CRL. For example, O=example.com.
    • refreshInSec. How often the connection is refreshed. The default is 86400 seconds (daily).
    • caCertAttr. Leave the default value, cACertificate;binary, as it is. It is the attribute to which the Certificate Manager publishes its CA signing certificate.
    • crlAttr. Leave the default value, certificateRevocationList;binary, as it is. It is the attribute to which the Certificate Manager publishes CRLs.
    • notFoundAsGood. Sets the OCSP service to return an OCSP response of GOOD if the certificate in question cannot be found in any of the CRLs. If this is not selected, the response is UNKNOWN, which, when encountered by a client, results in an error message.
    • byName. The OCSP Responder only supports the basic response type, which includes the ID of the OCSP Responder making the response. The ResponderID field within the basic response type is determined by the value of the ocsp.store.defStore.byName parameter. If byName parameter is true or is missing, the OCSP authority signing certificate subject name is used as the ResponderID field of the OCSP response. If byName parameter is false, the OCSP authority signing certificate key hash will be the ResponderID field of the OCSP response.
    • includeNextUpdate. The Online Certificate Status Manager can include the timestamp of the next CRL update time.

7.6.2.4. Testing the OCSP Service Setup

Test whether the Certificate Manager can service OCSP requests properly by doing the following:
  1. Turn on revocation checking in the browser or client.
  2. Request a certificate from the CA that has been enabled for OCSP services.
  3. Approve the request.
  4. Download the certificate to the browser or client.
  5. Make sure the CA is trusted by the browser or client.
  6. Check the status of Certificate Manager's internal OCSP service.
    Open the CA agent services page, and select the OCSP Services link.
  7. Test the independent Online Certificate Status Manager subsystem.
    Open the Online Certificate Status Manager agent services page, and click the List Certificate Authorities link.
    The page should show information about the Certificate Manager configured to publish CRLs to the Online Certificate Status Manager. The page also summarizes the Online Certificate Status Manager's activity since it was last started.
  8. Revoke the certificate.
  9. Verify the certificate in the browser or client. The server should return that the certificate has been revoked.
  10. Check the Certificate Manager's OCSP-service status again to verify that these things happened:
    • The browser sent an OCSP query to the Certificate Manager.
    • The Certificate Manager sent an OCSP response to the browser.
    • The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.
  11. Check the independent OCSP service subsystem again to verify that these things happened:
    • The Certificate Manager published the CRL to the Online Certificate Status Manager.
    • The browser sent an OCSP response to the Online Certificate Status Manager.
    • The Online Certificate Status Manager sent an OCSP response to the browser.
    • The browser used that response to validate the certificate and returned its status, that the certificate could not be verified.

7.6.3. Setting the Response for Bad Serial Numbers

OCSP responders check the revocation status and expiration date of a certificate before determining whether the certificate is valid; by default, the OCSP does not validate other information on the certificate.
The notFoundAsGood parameter sets how the OCSP handles a certificate with an invalid serial number. This parameter is enabled by default, which means that if a certificate is present with a bad serial number but the certificate is otherwise valid, the OCSP returns a status of GOOD for the certificate.
To have the OCSP check and reject certificates based on bad serial numbers as well as revocation status, change the notFoundAsGood setting. In that case, the OCSP returns a status of UNKNOWN with a certificate with a bad serial number. The client interprets that as an error and can respond accordingly.
  1. Open the Online Certificate Status Manager Console.
    pkiconsole https://server.example.com:8443/ocsp
  2. In the Configuration tab, select Online Certificate Status Manager, and then select Revocation Info Stores.
  3. Select the defStore, and click Edit/View.
  4. Edit the notFoundAsGood value. Selecting the checkbox means that the OCSP returns a value of GOOD even if the serial number on the certificate is bad. Unselecting the checkbox means that the OCSP sends a value of UNKNOWN, which the client can intrepret as an error.
  5. Restart the OCSP Manager.
    ]# systemctl restart pki-tomcatd@instance-name.service

7.6.4. Enabling the Certificate Manager's Internal OCSP Service

The Certificate Manager has a built-in OCSP service, which can be used by OCSP-compliant clients to query the Certificate Manager directly about the revocation status of the certificate. When the Certificate Manager is installed, an OCSP signing certificate is issued and the OCSP service is turned on by default. This OCSP signing certificate is used to sign all responses to OCSP service requests. Since the internal OCSP service checks the status of certificates stored in the Certificate Manager's internal database, publishing does not have to be configured to use this service.
Clients can query the OCSP service through the non-SSL/TLS end-entity port of the Certificate Manager. When queried for the revocation status of a certificate, the Certificate Manager searches its internal database for the certificate, checks its status, and responds to the client. Since the Certificate Manager has real-time status of all certificates it has issued, this method of revocation checking is the most accurate.
Every CA's built-in OCSP service is turned on at installation. However, to use this service, the CA needs to issue certificates with the Authority Information Access extension.
  1. Go to the CA's end-entities page. For example:
    https://server.example.com:8443/ca/ee/ca
  2. Find the CA signing certificate.
  3. Look for the Authority Info Access extension in the certificate, and note the Location URIName value, such as https://server.example.com:8443/ca/ocsp.
  4. Update the enrollment profiles to enable the Authority Information Access extension, and set the Location parameter to the Certificate Manager's URI. For information on editing the certificate profiles, see Section 3.2, “Setting up Certificate Profiles”.
  5. Restart the CA instance.
    ]# systemctl restart pki-tomcatd@instance-name.service

Note

To disable the Certificate Manager's internal OCSP service, edit the CA's CS.cfg file and change the value of the ca.ocsp parameter to false.
ca.ocsp=false

7.6.5. Submitting OCSP Requests Using the OCSPClient program

The OCSPClient program can be used for performing OCSP requests. For example:
]# OCSPClient -h server.example.com -p 8080 -d /etc/pki/pki-tomcat/alias -c "caSigningCert cert-pki-ca" --serial 2
CertID.serialNumber=2
CertStatus=Good
The OCSPClient command can be used with the following command-line options:

Table 7.1. Available OCSPClient Options

Option Description
-d database Security database location (default: current directory)
-h hostname OCSP server hostname (default: example.com)
-p port OCSP server port number (default: 8080)
-t path OCSP service path (default: /ocsp/ee/ocsp)
-c nickname CA certificate nickname (defaut: CA Signing Certificate)
-n times Number of submissions (default: 1)
--serial serial_number Serial number of certificate to be checked
--input input_file Input file containing DER-encoded OCSP request
--output output_file Output file to store DER-encoded OCSP response
-v, --verbose Run in verbose mode
--help Show help message

7.6.6. Submitting OCSP Requests Using the GET Method

OCSP requests which are smaller than 255 bytes can be submitted to the Online Certificate Status Manager using a GET method, as described in RFC 6960. To submit OCSP requests over GET:
  1. Generate an OCSP request for the certificate the status of which is being queried. For example:
    ]# openssl ocsp -CAfile ca.pem -issuer issuer.pem -serial serial_number -reqout - | base64
    
    MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
  2. Paste the URL in the address bar of a web browser to return the status information. The browser must be able to handle OCSP requests.
    https://server.example.com:8443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
  3. The OCSP Manager responds with the certificate status which the browser can interpret. The possible statuses are GOOD, REVOKED, and UNKNOWN.
Alternatively, run the OCSP from the command line by using a tool such as curl to send the request and openssl to parse the response. For example:
  1. Generate an OCSP request for the certificate the status of which is being queried. For example:
    ]# openssl ocsp -CAfile ca.pem -issuer issuer.pem -serial serial_number -reqout - | base64
    
    MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE=
  2. Connect to the OCSP Manager using curl to send the OCSP request.
    curl https://server.example.com:8443/ocsp/ee/ocsp/MEIwQDA+MDwwOjAJBgUrDgMCGgUABBT4cyABkyiCIhU4JpmIBewdDnn8ZgQUbyBZ44kgy35o7xW5BMzM8FTvyTwCAQE= > ocspresp.der
  3. Parse the response using openssl:
    openssl ocsp -respin ocspresp.der -resp_text
For certificates issued by a 7.1 CA with the Authority Information Access extension to be sent to the OCSP with the GET method, a redirect needs to be created to forward the requests to the appropriate URL, as described in Section 7.6.7, “Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier”.

7.6.7. Setting up a Redirect for Certificates Issued in Certificate System 7.1 and Earlier

The location for the OCSP user pages, specified in the URL with the file root /ocsp/ee/ocsp/, is different in Certificate System 9 or Certificate System 8.1 than the location in Certificate System 7.1, which was simply /ocsp/. In order for certificates issued by a 7.1 or earlier CA with the Authority Information Access extension to be sent to the OCSP, create a redirect to forward the requests to the appropriate URL.

Note

Setting the redirect is only required to manage certificates issued by a 7.1 or earlier CA with the Authority Information Access extension. If the certificates are issued by a later version Certificate Manager or do not contain the Authority Information Access extension, then this configuration is not necessary.
  1. Stop the OCSP Responder.
    ]# systemctl stop pki-tomcatd@instance-name.service
  2. Change to the OCSP's end user web applications directory. For example:
    ]# cd /var/lib/pki-ocsp/webapps/ocsp
  3. Change to the ROOT/WEB-INF/ directory in the ROOT folder of the OCSP's web applications directory. For example:
    ]# cd /var/lib/pki-ocsp/webapps/ocsp/ROOT/WEB-INF/
  4. Create and open the lib/ directory in the ROOT folder of the OCSP's web applications directory.
    ]# mkdir lib
    ]# cd lib/
  5. Create a symlink that links back to the /usr/share/java/pki/cms.jar JAR file. For example:
    ]# ln -s /usr/share/java/pki/cms.jar cms.jar
  6. Move up to the main web application directory. For example:
    ]# cd /var/lib/pki-ocsp/webapps/ocsp/
  7. Rename the current instance (ocsp) directory. For example:
    ]# mv /var/lib/pki-ocsp/webapps/ocsp/ocsp /var/lib/pki-ocsp/webapps/ocsp/ocsp2
  8. Change to the WEB-INF/ directory in the original ocsp/ directory. For example:
    ]# cd  /var/lib/pki-ocsp/webapps/ocsp/ocsp/WEB-INF
  9. In original ocsp/WEB-INF/ directory, edit the web.xml file and add lines mapping between the eeocspAddCRL and csadmin-wizard servlets.
       <servlet-mapping>
          <servlet-name>  ocspOCSP  </servlet-name>
          <url-pattern>   /ee/ocsp/*  </url-pattern>
       </servlet-mapping>
  10. Create and install the web.xml file in the ROOT directory. For example:
    <?xml version="1.0" encoding="ISO-8859-1"?>
    <web-app>
    
      <display-name>Welcome to Tomcat</display-name>
      <description>
         Welcome to Tomcat
      </description>
    
      <servlet>
        <servlet-name>ocspProxy</servlet-name>
        <servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class>
        <init-param>
          <param-name>destContext</param-name>
          <param-value>/ocsp2</param-value>
        </init-param>
        <init-param>
          <param-name>destServlet</param-name>
          <param-value>/ee/ocsp</param-value>
        </init-param>
      </servlet>
    
      <servlet>
        <servlet-name>ocspOther</servlet-name>
        <servlet-class>com.netscape.cms.servlet.base.ProxyServlet</servlet-class>
        <init-param>
          <param-name>destContext</param-name>
          <param-value>/ocsp2</param-value>
        </init-param>
        <init-param>
          <param-name>srcContext</param-name>
          <param-value>/ocsp</param-value>
        </init-param>
        <init-param>
          <param-name>destServlet</param-name>
          <param-value></param-value>
        </init-param>
        <init-param>
          <param-name>matchURIStrings</param-name>
    
    <param-value>/ocsp/registry,/ocsp/acl,/ocsp/jobsScheduler,/ocsp/ug,/ocsp/server,/ocsp/log,
                /ocsp/auths,/ocsp/start,/ocsp/ocsp,/ocsp/services,/ocsp/agent,/ocsp/ee,
                /ocsp/admin</param-value>
        </init-param>
        <init-param>
          <param-name>destServletOnNoMatch</param-name>
          <param-value>/ee/ocsp</param-value>
        </init-param>
        <init-param>
          <param-name>appendPathInfoOnNoMatch</param-name>
          <param-value>/ocsp</param-value>
        </init-param>
      </servlet>
    
      <servlet-mapping>
        <servlet-name>ocspProxy</servlet-name>
        <url-pattern>/ocsp</url-pattern>
      </servlet-mapping>
    
      <servlet-mapping>
        <servlet-name>ocspOther</servlet-name>
        <url-pattern>/ocsp/*</url-pattern>
      </servlet-mapping>
    
    </web-app>
  11. Edit the /var/lib/pki-ocsp/conf/context.xml file, changing the following line:
    <Context>
     to 
    <Context crossContext="true" >
  12. Edit the /var/lib/pki-ocsp/webapps/ocsp/ocsp2/services.template file and change the following line:
    result.recordSet[i].uri);
     to 
    result.recordSet[i].uri + "/");
  13. Start the OCSP instance.
    ]# systemctl restart pki-tomcatd@instance-name.service