V9.6.0.1: Configuring Rational DOORS to support PKI certificate revocation lists

In version 9.6.0.1 and later, you can configure IBM® Rational® DOORS® to use public key infrastructure (PKI) certificate revocation lists (CRLs) for managing user access.

Before you begin

To use CRLs, administrators must configure Rational DOORS to enable PKI support and encryption compliance. For details, see Configuring smart cards and certificates for Rational DOORS

About this task

A CRL is a signed data structure that contains a time-stamped list that identifies revoked certificates. Revoked certificates are no longer trusted for authentication. Typically, CRLs block access when a user's employment status or assignment changes, or when a user's certificate or the corresponding private key is compromised.

Client certificates and CRLs must meet these conditions:

If PKI certificates are used for user authentication, you can configure the database server to support CRLs. When support for CRLs is enabled, the server checks client certificates when a user attempts to login to verify that the certificate is not revoked.

Administrators use the dbadmin command to set CRL options for the server. The server sends the CRL settings to the server log. If diagnostic information about the CRL is available, the server logs this information when a certificate is validated.

You can enable the Rational DOORS client to perform a CRL check of the server certificate when you open the client. Specify CRL options with the doors.exe command at the command line or set keys and values in the registry. Users who have permission to view database properties in the client can examine the CRL options that are used by the server.

If a revoked user certificate is rejected by the server, the client displays this message:
The user certificate was not validated.
Some possible reasons for the error:
1. the server does not trust the whole certificate chain
2. the user certificate has been revoked
3. the user certificate CRL is not available
DOORS will now exit.
The following message is posted in the server log:
received invalid socket: boost::exception_detail::clone_impl<class SecureCommsException>: GSKit SocInit failed: GSK_ERROR_BAD_CERT -- unable to validate the client certificate
- the certificate chain might not be trusted
- the certificate might be revoked
- the certificate CRL might not be available
If a revoked server certificate is rejected by the client, the client displays this message:
Unable to validate the server certificate. The server certificate has been revoked.
DOORS will now exit.

The server uses the most recent available option settings to validate a certificate. If you change the CRL options, you must restart the server to apply the changes.

Note: Rational DOORS supports only the DER format for CRLs. Rational DOORS Web Access supports both DER (binary) and PEM (base-64) formats.

Procedure

  1. Use these dbadmin command switches and parameters to set the options to enable support for CRLs on the Rational DOORS database server. For details about how to use the dbadmin command, see Command-line switches for the database server.
    dbadmin switches and parameters Description
    -useHttpCrl true | false

    Enables CRL checking for user authentication.

    Default value: false

    -useHttpCrlCache true | false

    Determines whether the cache is used for CRL checking.

    Default value: false

    -httpCrlCacheSize size

    Specifies the number of entries in the cache when the CRL checking is enabled. Set this value to 32 or less, because CRLs can be large.

    Default value: 32

    -httpCdpMaxResponseSize number-of-bytes

    The maximum size of a response that is accepted from an HTTP Server when retrieving CRLs. This value is not the size of the CRL file itself.

    Default value: 204800 bytes

    -httpCdpTimeout seconds

    The timeout of the wait for a response from the HTTP server for a CRL.

    Default value: 5 seconds

  2. To check the CRL option settings on the database server, enter this command:
    dbadmin -showCrlOptions
  3. To enable support for CRLs on the Rational DOORS client, do one of these tasks:
    • Use switches and parameter values when you open the Rational DOORS client from the command line, as in this example:
      doors.exe -useHttpCrl -httpCdpMaxResponseSize 500000 -httpCdpTimeout 10
    • Set registry keys and values in the Rational DOORS client folder in the registry. Here is an example of the registry location:
      HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Telelogic\DOORS\9.version\Config
    Command-line switches and registry keys Description
    Command-line switch: -useHttpCrl

    Registry key: useHttpCrl

    Enables the client to do a CRL check of the server certificate. Do not include a parameter value with this command-line switch. CRL checking is not enabled by default.

    When you specify this setting in the registry, you must include a value with the useHttpCrl key. The value is false, by default. Set the value to true to enable CRL checking by the client.

    Command-line switch: -httpCdpMaxResponseSize number_of_bytes

    Registry key: httpCdpMaxResponseSize

    Sets the maximum size of a response that is accepted from an HTTP Server when retrieving CRLs. This value is not the size of the CRL file itself.

    Default value: 204800 bytes

    Command-line switch: -httpCdpTimeout seconds

    Registry key: httpCdpTimeout

    Sets the timeout of the wait for a response from the HTTP server for a CRL.

    Default value: 5 seconds

  4. To view the CRL option settings in the Rational DOORS client, open the DOORS Database Properties window and click the Login Policy tab. The settings are read-only in the client, because they are set by using the dbadmin command. If the Enable CRL revocation checks checkbox is selected, you can click the CRL Options button to view the options that are set for the database server.

Feedback