RSA BSAFE Cert-C API Reference

Cert-C OCSP Revocation Status Service Provider

Use the Cert-C OCSP Revocation Status service provider to check the validity of certificates without requiring CRLs. This service provider uses the Online Certificate Status Protocol (OCSP), and is suitable for client applications that require a method for getting more timely certificate revocation status information than a CRL can usually provide.

One benefit of OCSP is that the burden of certificate revocation status checking is placed onto the server side. However, an application should still do some filtering or validation before sending a request to an OCSP responder. For example, if an application expects to receive a significant number of authentication requests with forged certificates, then it would make sense for the application to manually validate the certificate's signature locally before issuing a status request. This could result in better overall performance rather than relying on an OCSP network service as the only source of information regarding the status and content of a certificate. Additionally, some pre-verification or pre-validation of end-entity certificates might simplify an application's OCSP configuration.

An OCSP responder is usually maintained by a CA. Some OCSP responders accept requests on behalf of more than one CA. The OCSP protocol allows for signed or unsigned requests to be made to OCSP responders. However, a particular OCSP responder might require a request to be signed as proof of authorization and authentication to use the OCSP responder service. OCSP requires that all responses from an OCSP responder must be signed. Unless the CA or an authority to which OCSP responsibilities have been delegated signs the OCSP response, it is up to the application to choose which OCSP responders to trust to sign the responses.

The validity period of OCSP responses are often on the order of hours. Therefore, it is imperative to set the client application's local clock to the correct time and time zone. Incorrect time and time zone settings could cause OCSP responses to be interpreted incorrectly, allowing an incorrect status to be returned to the calling application.

Applications need to supply OCSP configuration information, in the form of one or more OCSP_RESPONDER entries, to the Cert-C OCSP Revocation Status service provider at initialization. The service provider determines which OCSP responder to contact from the configuration information passed in as an array of OCSP_RESPONDERs. Information encoded within the certificate, combined with this initialization information, is used to select an OCSP_RESPONDER entry, construct a request, and interpret a response.

The service provider will not issue more than one request for each certificate; in particular none of the following will occur:

• Retrying a request to a non-working responder,
• when multiple OCSP_RESPONDER entries could be matched by certificate and initialization information combinations, or
• retrying a request with a signed request, after an unsigned request was rejected.

The procedure for identifying the correct OCSP_RESPONDER configuration to use with a certificate has been simplified. The OCSP provider now performs the following process to select an OCSP_RESPONDER entry:

1. A candidate OCSP_RESPONDER entry is selected when the certificate’s issuer name matches a name in the OCSP_RESPONDER’s responderCAs list. If no candidate is found in any configuration then no request is generated, the CERT_REVOCATION’s status field is set to CERT_REVOCATION_UNKNOWN, and the evidenceType field is set to CRE_NONE.
   
   
2. If a candidate is found then a URL is required to send the request. The URL must come from either the certificate’s AIA extension or the candidate responder’s transport.destList. If no URL is available then the next candidate responder is checked.
   
   Note: If the path validation option PF_IGNORE_AIA is set then any AIA in the certificate is ignored and a URL must come from the responder configuration.
   
   

   If the certificate has no URL in an AIA and no candidate has a URL then a request is not generated, the CERT_REVOCATION’s status field is set to CERT_REVOCATION_UNKNOWN, and the evidenceType field is set to CRE_ERROR with an error of E_NOURI. The application is responsible for freeing this evidence type information.
   
   

3. If both the candidate responder configuration and the certificate’s AIA contain a URL then the URL in the certificate’s AIA is used to direct the request.

From this algorithm some general guidlines can be recommended for various situations:

• The CA issues certificates which have no AIAs. In this case an OCSP_RESPONDER entry must have a URL in the destList field, or no request can be sent.
  
  
• The CA issues certificates which have AIAs. The OCSP_RESPONDER entry need not have any URL in its destList field.
  
  
• The CA has issued some certificates without AIAs and some with AIAs. This might arise when a CA has issued older certificates without an AIA and has now been upgraded to issue newer certificates with an AIA. There will be a period when both types of issued certificates are in common use. This scenario can be broken down further by the OCSP responders used to validate the certificates:
  
  
  • If one responder is used for all certificates, then only one OCSP_RESPONDER entry, with a URL in the destination list, is needed. Requests for certificates without the AIA succeed because a URL is available in the configuration, and requests for certificates with the AIA succeed because they already have a URL.
    
    
  • If one responder is used for the newer certificates (for example, it might require signed requests), while another is used for the older certificates (for example, it allows unsigned requests) then two OCSP_RESPONDER entries are needed. The first entry must be for the newer certificates and it must not have a URL in its destList. The second entry must have a URL in its destList. Request generation on newer certificates succeeds because they match immediately on the first entry and a URL is available from the certificate. Request generation on older certificates fails on the first entry (no URL available anywhere) but succeed on the second (a URL comes from the destList).

Once an OCSP_RESPONDER entry is selected, the OCSP protocol request data is constructed. Depending on how OCSP_RESPONDER's flags field is set, zero or more certificates are included in the request to help the OCSP responder verify the signature of the request signer. These certificates must be included in CERT_PATH_CTX's database field and included as a parameter to C_CheckCertRevocation.

If a communications (transport) error occurs, then a CERT_REVOCATION's evidenceType field, of type CRE_TRANSPORT_ERROR, is returned. It will contain a pointer to a PKI_STATUS_INFO structure. If any other error occurs, then a CERT_REVOCATION's evidenceType field, of type CRE_ERROR, will be returned containing a pointer to an integer, set to a standard Cert-C error value.

The Cert-C OCSP Revocation Status service provider can use certificates and certificate identifiers for the following purposes:

• Identifying OCSP_RESPONDER entries to use,
• Signing requests to be sent to an OCSP responder,
• Including certificates as extra certificates to be sent in the request to an OCSP responder,
• Identifying expected OCSP response signers,
• Validating response signatures, and
• Building certificate trust chains from response signers to trusted roots.

These certificates can come from OCSP_RESPONDER entries or from the CERT_PATH_CTX's database and trustedCerts fields, that is passed to C_CheckCertRevocation. If certificates are needed to perform signature verification and certificate path building, then the certificates are extracted from the CERT_PATH_CTX. Otherwise, they are to be taken from the one or more OCSP_RESPONDER entries supplied at service provider initialization time.

The data structures used with this service provider are CERT_REVOKE_FUNCS, REVOKE_OCSP_INIT_PARAMS, REVOKE_OCSP_INIT_STRUCT, OCSP_RESPONDER, and OCSP_SIGNER. This service provider implements all of the CERT_REVOKE_FUNCS functions.

To initialize or register the Cert-C OCSP Revocation Status service provider, call either the C_InitializeCertC or the C_RegisterService function. Both functions take SERVICE_HANDLER as a parameter. The Initialize member in SERVICE_HANDLER points to the S_InitializeOCSP function. This function initializes the Cert-C OCSP Revocation service provider’s implementation of the certificate revocation status functions. It stores pointers to them in the revoke member in SERVICE_FUNCS, which is an CERT_REVOKE_FUNCS structure. S_InitializeOCSP is never called directly by the application.

To use the Cert-C OCSP Revocation Status service provider with an application, link in the certcsp library and include the ocsp.h, certpath.h, and the certext.h header files. The ocsp.c sample program makes use of this service provider.

The following profile definitions are in ocsp.h:

     #define  REVOKE_OCSP_PROFILE_GENERIC      0
     #define  REVOKE_OCSP_PROFILE_VALICERT     1
     #define  REVOKE_OCSP_PROFILE_VERISIGN     2
     #define  REVOKE_OCSP_PROFILE_RSAKCA       3

1. RSA Keon Certificate Authority 6.0, all combinations of:
   
   Request formats:
   • Unsigned requests
   • Signed requests using SHA-1 with RSA (SA_SHA1_WITH_RSA_ENCRYPTION)
   • DSA signed OCSP requests are currently not supported by KCA 6.0
   
   Responders configured for:
   • CA-signed responses
   • Delegated responder signed responses
   • Trusted responder signed responses
   
   
2. RSA Keon Certificate Authority 5.7, all combinations of:
   
   Request formats:
   • Unsigned requests
   • Signed requests using SHA1 with RSA (SA_SHA1_WITH_RSA_ENCRYPTION)
   • Signed requests using SHA1 with DSA (SA_DSA_WITH_SHA1)
   
   Responders configured for:
   • CA-signed responses
   • Delegated responder signed responses
   • Trusted responder signed responses
   
   
3. RSA KCS 5.5 and ValiCert Enterprise VA 3.2.1 (build 4); the responder accepting unsigned requests and operating as a "Trusted Responder" when signing responses (an explicitly trusted, self-signed certificate signs the response). The responder must be configured to look up the CRLs published by KCS in an LDAP directory.
   
   Currently, KCS 5.5 does not support CA-signed responses, nor can it issue authorized responder certificates.

Note: Although there are references to VeriSign in some Cert-C OCSP header and source files, Cert-C does not currently interoperate with VeriSign.