NAME

CSSM_TP_CertRetrieve

SYNOPSIS

CSSM_DATA_PTR CSSMAPI CSSM_TP_CertRetrieve
    (CSSM_TP_HANDLE TPHandle,
    (CSSM_CL_HANDLE CLHandle,
    const CSSM_DATA_PTR ReferenceIdentifier,
    const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
    sint32 *EstimatedTime)

DESCRIPTION

This function returns the certificate created in response to the TP_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 has been stored in the local CSP specified in the call to TP_CertRequest. The TP module, 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 caller may be required to provide additional authentication information to retrieve the certificate. The format of these credentials is defined by the Policy identifiers specified in the corresponding TP_CertRequest call and the CL module used to create the certificate. The CL module cert format is recorded in the CLSubservice structure, which can be queried by the caller.

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 the reference identifier and a NULL certificate pointer. The caller must attempt to retrieve the certificate again after the estimated time to completion has elapsed.

PARAMETERS

TPHandle (input)

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

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_TP_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).

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 provided is insufficient, additional information can be provided by the substructure field names MoreAuthenticationData. This field contains an immediate data value or a callback function to collect additional information from the user. If additional 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_INVALID_CL_HANDLE

Invalid Certificate Library Handle.

CSSM_INVALID_CSP_HANDLE

Invalid CSP Handle.

CSSM_TP_INVALID_REFERENCE

Invalid reference identifier.

SEE ALSO

CSSM_TP_CertRequest, CSSM_CL_CertRequest,
CSSM_CL_CertUnsign, CSSM_CL_CertVerify