NAME

CL_CertRetrieve

SYNOPSIS

CSSM_DATA_PTR CSSMCLI CL_CertRetrieve
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA_PTR ReferenceIdentifier,
    const CSSM_NET_ADDRESS_PTR CALocation,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    sint32 *EstimatedTime)

DESCRIPTION

This function returns the certificate created in response to the CL_CertRequest function call. The reference identifier denotes the corresponding CertRequest call. The signing operation, performed by the Certificate Authority (CA) process, may have been performed locally or remotely. In either case, the private key associated with the certificate is stored in the local CSP specified by the caller. The CL module and the CA process provide secure handling (via key wrapping) of the private key until it is securely stored in the local CSP. The CL module incorporates knowledge of the name, location, and interface protocol for communicating with the CA.

The caller may be required to provide additional authentication information to retrieve the certificate. The format of these credentials is defined by the CL module and recorded in the CLSubservice structure, which can be queried by the caller.

This function returns the signed certificate and stores the associated private key in the CSP specified in CL_CertRequest. It is possible that the certificate is not ready to be retrieved when this call is made. In that case, an EstimatedTime to complete certificate creation is returned with a NULL certificate pointer. The caller reuses the reference identifier to retrieve the certificate after the estimated time to completion has elapsed.

PARAMETERS

CLHandle (input)

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

ReferenceIdentifier (input)

A reference identifier which uniquely identifies the CSSM_CL_CertRequest call that initiated creation of the certificate returned by this function. The identifier persists across application executions until the CSSM_CL_CertRetrieve function completes (in success or failure).

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 state information associated with the ReferenceIdentifier or can assume a default CA process location. If insufficient state is associated with the ReferenceIdentifier and a default cannot be assumed, the retrieval cannot be completed and the operation fails.

UserAuthentication (input/optional)

A pointer to the CSSM_USER_AUTHENTICATION structure containing the authentication information to be used in association with this request. The authentication information may be a pass-phrase, a PIN, a completed registration form, a Certificate to facilitate a signing operation, and so on, depending on the context of the request. The required format for this credential is defined by the CL and recorded in the CLSubservice structure describing this module. If the supplied information is insufficient, additional information can be provided by the substructure field MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If authentication information is not required, this parameter must be NULL.

EstimatedTime (output)

The number of seconds estimated before the signed Certificate will be returned. A (default) value of zero indicates that the signed Certificate has been returned as a result of this call. When the certification process cannot estimate the time required to sign the certificate, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.

RETURN VALUE

A pointer to the CSSM_DATA structure containing the signed certificate. If the pointer is NULL, the calling application is expected to call back after the specified EstimatedTime. If the pointer is NULL and EstimatedTime is zero, an error has occurred. If the EstimatedTime is CSSM_ESTIMATED_TIME_UNKNOWN, the call back time is not defined and the application must periodically poll for completion. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_CL_INVALID_CL_HANDLE

Invalid Certificate Library Handle.

CSSM_CL_INVALID_IDENTIFIER

Invalid reference identifier.

CSSM_AUTHENTICATION_FAIL

Invalid/unauthorized credential for operation.

CSSM_CL_CERT_SIGN_FAIL

Unable to sign certificate.

CSSM_CL_EXTRA_SERVICE_FAIL

Unable to perform additional certificate-creation-related services.

CSSM_CL_PRIVATE_KEY_STORE_FAIL

Unable to store private key in CSP.

CSSM_CL_MEMORY_ERROR

Not enough memory.

SEE ALSO

CL_CertRequest, CL_CertUnsign, CL_CertVerify