RSA BSAFE Cert-C API Reference

Cert-C CRL Revocation Status service provider

Use the Cert-C CRL Revocation Status service provider to check the validity of a certificate against a set of CRLs. This service provider implements all of the CERT_REVOKE_FUNCS's functions.

To initialize or register the Cert-C CRL 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_InitializeCRLStatus function, and the corresponding parameter is a pointer to a CRL_STATUS_INIT_PARAMS structure. This function initializes the Cert-C CRL Revocation Status service provider’s implementation of the revocation status functions and stores pointers to them in the revoke member in SERVICE_FUNCS, which is an CERT_REVOKE_FUNCS structure. S_InitializeCRLStatus is never called directly by the application.

To use the Cert-C CRL Revocation Status service provider with an application, include the crlstat.h header file. The chain sample program makes use of this service provider.

CRL Distribution Points

Beginning with Cert-C 2.5, the Cert-C CRL Revocation Status service provider uses CRL distribution points. If a CRL distribution point (DP) extension is present in a certificate, it is used to access CRLs to verify the status of a certificate. However, only CRL distribution points stored in the Uniform Resource Identifier (URI) form, an IA5String, are used. All other forms of CRL distribution points are ignored.

Any CRLs obtained from CRL DP, can be cached into a database service provider, preferably the Cert-C In-Memory Database service provider. The client application passes the database name to the Cert-C CRL Revocation Status service provider. The Cert-C CRL Revocation Status service provider binds to this database service provider and uses the stored CRLs or adds new CRLs to it. The client application must clean up any CRLs in the database, as necessary.

CRL Distribution Point Features

1. The cRLIssuer names of the CRLs retrieved from DP are used as CRL issuer names in Cert-C CRL Revocation Status service provider to locate a CRL from the user-provided database.
   
   
2. The behavior of the Cert-C CRL Revocation Status service provider varys with the presence of DPs.
   • If a distribution point is present, only URI forms are supported. Any other forms are ignored and a message is logged.
   • If a distribution point is not present, the CRL issuer name field is searched for the URI. The CRL issuer name field cannot be omitted.
   
   In either case, the first URI in a DP is used; all others are ignored.
   
   
3. The optional reason code in a DP is ignored.
   
   
4. URLs must be in standard forms, LDAP or HTTP, as follows

        ldap://ldap.xyz.com:1389/id=smith,o=company.com?certificateRevocationList:binary?sub
        http://monaco.rsa.com/ca3.crl

5. Delta CRLs are not supported.
   
   
6. CRL files on the server side must be in DER/BER format. If they are not in this format, they are ignored and a message is logged. Similarly, any object that is not a CRL object is also ignored and a message is logged.
   
   
7. If the path algorithm is PA_X509_V1, DPs are not searched. With other path algorithms, set the path option flag to PF_IGNORE_CRL_DP to ensure DPs are not searched.
   
   
8. Multiple CRL issuers are supported.
   • The crlIssuer field in a DP specifies a designated CRL issuer. If this field is not NULL, Cert-C uses the first general name with the DIRECTORY_NAME type as one of the designated CRL issuers.
   • If the path algorithm is PKIX, the CRL issuer must be same as the certificate issuer, the CA.
   • If the path algorithm is PKIX2, there can be multiple CRL issuers, namely, all the designated CRL issuers and the certificate issuer, the CA.
   • The valid CRL with the latest time stamp determines the status of the certificate, if the path algorithm is either PKIX or PKIX2.
   • All retrieved CRLs are inserted into the caching database, unless path-option flags are set that specify different behavior.

Path Algorithms, Options and the Caching Database

The behavior of the Cert-C CRL Revocation Status service provider can be altered by setting certain combinations of path algorithms and the two path-option flags, PF_IGNORE_CRL_DP and PF_FORCE_CRL_DP. For more information on path-option flags, see the pathOption member of the CERT_PATH_CTX structure.

PA_X509_V1 Path Algorithm

Path-Option Flag	Caching DB Required	Behavior
Any valid combination	No	No change from Cert-C 2.0.

Note: Selecting both PF_IGNORE_CRL_DP and PF_FORCE_CRL_DP always returns an E_INVALID_PARAMETER error.

PKIX Path Algorithm

Path Option Flag	Caching DB Required	Behavior
PF_IGNORE_CRL_DP and not PF_FORCE_CRL_DP	No	No change from Cert-C 2.0. The CRL issued by the CA with the latest time stamp determines the certificate status.
PF_FORCE_CRL_DP and not PF_IGNORE_CRL_DP	Yes. Omitting causes error E_INVALID_PARAMETER	Retrieves all CRLs from URIs defined in the DP extension and inserts them into the caching database. The CRL issued by the CA with the latest time stamp determines the certificate status.
Neither PF_FORCE_CRL_DP nor PF_IGNORE_CRL_DP	No	Search the CRL from the latest CA. If the certificate status cannot be determined, continue to step 2. If there is no caching database specified, return CERT_REVOCATION_UNKNOWN; otherwise, continue to step 3. Retrieve all CRLs from the URIs defined in the DP extension and insert them into the caching database. The CRL issued by the CA with the latest time stamp determines the certificate status.

Note: Selecting both PF_IGNORE_CRL_DP and PF_FORCE_CRL_DP always returns an E_INVALID_PARAMETER error.

PKIX2 Path Algorithm

Path Option Flag	Caching DB Required	Behavior
PF_IGNORE_CRL_DP and not PF_FORCE_CRL_DP	No	The CRL issued by the CA with the latest timestamp determines the certificate status.
PF_FORCE_CRL_DP and not PF_IGNORE_CRL_DP	Yes. Omitting causes error E_INVALID_PARAMETER	Get all designated CRL issuers specified in the DP extension. Retrieve all CRLs from the URIs defined in the DP extension and insert them into the caching database. The CRL issued by one of the designated CRL issuers or by the CA with the latest time stamp determines the certificate status.
Neither PF_FORCE_CRL_DP nor PF_IGNORE_CRL_DP	Yes. Omitting causes error E_INVALID_PARAMETER	Search the CRL from the latest CA. If the certificate status cannot be determined, continue to step 2. If there is no caching database specified, return E_INVALID_PARAMETER; otherwise, continue to step 3. Retrieve all CRLs from the URIs defined in the DP extension and insert them into the caching database. The CRL issued by one of the designated CRL issuers or by the CA with the latest time stamp determines the certificate status.

Note: Selecting both PF_IGNORE_CRL_DP and PF_FORCE_CRL_DP always returns an E_INVALID_PARAMETER error.