NAME

TP_CertRetrieve

SYNOPSIS

CSSM_DATA_PTR CSSMTPI TP_CertRetrieve
    (CSSM_TP_HANDLE TPHandle,
    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 handle identifies the corresponding CertRequest call. At completion of this operation, the private key associated with the new certificate must be stored in the local CSPspecified in the corresponding 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.

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 reference identifier must persist until the request either succeeds or fails. The caller must use this reference identifier again attempting to retrieve the certificate after the newly specified estimated time has elapsed.

PARAMETERS

TPHandle (input)

The handle that describes the add-in trust policy 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. For example, a pass-phrase may be requested from the end-user in order to authenticate the request. 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

TP_CertRequest, CSSM_CL_CertRequest, CSSM_CL_CertUnsign, CSSM_CL_CertVerify