CL_CertRetrieve
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)
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.
- 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.
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.
- 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.
CL_CertRequest, CL_CertUnsign, CL_CertVerify
Contents | Next section | Index |