NAME

CSSM_CL_CrlRequest

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_CL_CrlRequest
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_FIELD_PTR CrlIdentifier,
    const CSSM_DATA_PTR CACert,
    const CSSM_FIELD_PTR SignScope,
    uint32 ScopeSize,
    const CSSM_NET_ADDRESS_PTR CALocation,
    CSSM_CA_SERVICES MoreServiceRequests,
    sint32 *EstimatedTime,
    const CSSM_DATA_PTR ReferenceIdentifier)

DESCRIPTION

This function submits a request to a Certificate Authority (CA) process to issue the most current version of a CRL of a specified name. The SignerCert input parameter indicates which CA process should receive the request. The selected CA process may be local or remote.

When all prerequisite conditions have been satisfied, such as some minimum time has elapsed since the last version of the requested CRL was issued, the CA process closes out the CRL, signs it and can distribute it to all interested and requesting parties. The CA must have access to the private keys associated with the signer's certificate to sign the CRL. If no signer's certificate is specified, the CL module can assume a default CA process from which it always acquires CRLs. If no defaults are known to the CL module, the CL module can reject the request.

The CL module selects and uses a default CSP for any required cryptographic operations. The CL module and the CA process are responsible for creating and destroying all cryptographic contexts required to perform this service.

The SignScope defines the set of CRL fields that are to be included in the signing process.

The caller can request additional CRL-related services from the CA. These requests are designated by the MoreServiceRequests bit mask. CSSM-defined bit masks allow the caller to request immediate distribution of the latest CRL to any and all interested parties. CAs are not required to provide these additional services. The CL module works with the CA process to provide the requested CRL.

This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). The estimate time defines the expected closing, signing and distribution time. This time may be substantial when closing a CRL requires off-line procedures or the service model mandates a minimum time between distributions. In contrast, the estimated time can be zero, meaning the CRL can be obtained immediately. After the specified time has elapsed, the caller must use the CL module interface CSSM_CL_CrlRetrieve, with the reference identifier, to obtain the CRL.

PARAMETERS

CLHandle (input)

The handle that describes the add-in certificate library module used to perform this function.

CrlIdentifier (input)

A pointer to an OID-value pair that uniquely identifies (names) the CRL being requested from the CA.

CACert (input/optional)

A pointer to the CSSM_DATA structure containing the desired Certification Authority's signing certificate to be used when issuing the CRL. If the CACert is NULL, the CL module or the CA process can provide a default signing certificate for issuing the CRL.

SignScope (input/optional)

A pointer to the CSSM_FIELD array containing the OID/value pairs specifying the CRL fields to be included in the signature calculation. When the input value is NULL, the CA assumes and includes a default set of CRL fields in the signing process.

ScopeSize (input)

The number of entries in the sign scope list. If no signing scope is specified, then the scope size must be zero.

CALocation (input/optional)

A pointer to a network address directly or indirectly identifying the location of the CA process. If the input is NULL, the module can determine a CA process and its location based on the CACert input parameter or can assume a default CA process location. If a CACert is not specified and a default cannot be assumed, the request cannot be initiated and the operation fails.

MoreServiceRequests (input/optional)

A bit mask requesting additional CRL-related services from the Certificate Authority performing this function.

EstimatedTime (output)

The number of seconds estimated before the CRL will be ready to be retrieved. A (default) value of zero indicates that the CRL can be retrieved immediately via the corresponding CL_CrlRetrieve function call. When the certification process cannot estimate the time required to prepare the CRL, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

ReferenceIdentifier (output)

A reference identifier which uniquely identifies this specific request. The identifier persists across application executions until it is terminated by successful or failed completion of the CSSM_CL_CrlRetrieve function.

RETURN VALUE

A CSSM_OK return value signifies the requested operation has proceeded and that CL_CrlRetrieve should be called (after the specified amount of time) in order to retrieve the results. If CSSM_FAIL is returned, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_CL_INVALID_CL_HANDLE

Invalid Certificate Library handle.

CSSM_CL_INVALID_CSP_HANDLE

Invalid CSP handle.

CSSM_CL_INVALID_DATA_POINTER

Invalid pointer input.

CSSM_CL_UNKNOWN_FORMAT

Unrecognized certificate format.

CSSM_CL_INVALID_SIGNER_CERTIFICATE

Revoked or expired signer certificate.

CSSM_CL_INVALID_SCOPE

Invalid scope.

CSSM_CL_MEMORY_ERROR

Not enough memory.

CSSM_CL_SIGN_REQUEST_FAIL

Unable to submit certificate signing request.

SEE ALSO

CL_CrlRetrieve