Setting up client certificate revocation checking for Teracloud® Streams users

A certificate authority (CA) that issues an X.509 client certificate can also revoke that certificate. If the CA revokes a certificate, user authentication fails. The security.revocationMethod domain property specifies the method that a Teracloud® Streams domain uses to check whether a certificate is revoked. If you are not using client certificate authentication, this property is ignored.

About this task

A CA must provide a method to check the revocation status of a client certificate. Two common certificate revocation methods for determining revocation status are the Certificate Revocation List (CRL) method and the Online Certificate Status Protocol (OCSP) method. Teracloud® Streams supports both methods.
You can use the default setting for the security.revocationMethod property or specify another value. The default value is automatic. This value specifies that the domain uses the following methods to check for revoked certificates:
  • If the certificate contains an OCSP responder URL, the domain uses the OCSP method. For more information about this method, see the description of the ocsp value.

  • If a CRL is referenced in the certificate or is specified on the security.revocationFile or security.revocationLdapUrl domain property, the domain uses the CRL method. For more information about this method, see the description of the crl value.

  • If both OCSP and CRL information is provided, the domain uses the OCSP method first. If the OCSP responder does not reply, the CRL method is used.

  • If no OCSP or CRL information is provided, certificate authentication fails.
To change the default value, you can set the security.revocationMethod property to one of the following values:
  • ocsp: This value specifies that the domain uses OCSP information to check for revoked certificates. The OCSP information in the certificate must contain the URL of an OCSP responder. The OCSP responder determines the revocation status of the certificate. If the certificate does not contain an OCSP responder URL or the OCSP responder does not respond, certificate authentication fails.

  • crl: This value specifies that the domain uses CRL information to check for revoked certificates. The CRL is obtained from the location that is referenced in the certificate or specified on the security.revocationFile or security.revocationLdapUrl domain property. If you specify this value and do not provide a CRL, certificate authentication fails.

  • none: This value specifies that no certificate revocation checks occur. The contents of the certificate and the security.revocationFile and security.revocationLdapUrl property settings are ignored.
Notes:
  • If a client certificate does not include URLs for certificate revocation, you can use the security.revocationFile and security.revocationLdapUrl domain properties to refer to a CRL. In this case, add only the associated CA certificate to the web management service truststore for the domain because these properties apply to only one CA.

  • If a client certificate does not include a URI to a CRL file, you might be able to manually download it from the CA. If you set the security.revocationFile property to the fully qualified path of the CRL file on the system, the CRL can be used during certificate authentication.

    Every Teracloud® Streams resource in the domain that is configured to run the authentication and authorization service must be able to access the CRL file. If you are not using a shared file system, there must be a copy of the CRL file on each resource.

  • If the CRL is in an LDAP directory, set the security.revocationLdapUrl domain property using the URL obtained from the LDAP administrator.
    The format of the LDAP URL to a CRL is ldap://host[:port]/dn?attribute.
    • host is the domain name or IP address of the resource that is running the LDAP server.
    • port is the port number of the LDAP server, which is optional. The default port number is 389.
    • dn is the distinguished name of the object in the LDAP directory that contains the attribute.
    • attribute is named certificateRevocationList;binary and contains the CRL contents.
    You can update domain properties by using the Domain Manager or the streamtool setdomainproperty command. For more information about this command, enter streamtool man setdomainproperty.
    Important: If you use the streamtool command to update the security.revocationLdapUrl property, enclose the URL in quotation marks. Otherwise, the URL is not updated correctly.

For more information about domain properties, enter streamtool man domainproperties.