CSSM_TP_RetrieveCredResult(3)CSSM_TP_RetrieveCredResult(3)NAMECSSM_TP_RetrieveCredResult - Return the results of the credentials
request (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_TP_RetrieveCredResult (CSSM_TP_HANDLE TPHan‐
dle, const CSSM_DATA *ReferenceIdentifier, const CSSM_TP_CALLER‐
AUTH_CONTEXT *CallerAuthCredentials, sint32 *EstimatedTime, CSSM_BOOL
*ConfirmationRequired, CSSM_TP_RESULT_SET_PTR *RetrieveOutput)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The handle that describes the certification authority module used to
perform this function. A reference identifier that uniquely identifies
the CSSM_TP_SubmitCredRequest() call that initiated the certificate
service request whose results are returned by this function. The iden‐
tifier persists across application executions and becomes undefined
when all local processing of the request has completed.
Local processing is completed in one of two ways: For certifi‐
cate services that do not require explicit confirmation by the
requester, the reference identifier is invalidated when the cor‐
responding CSSM_TP_RetrieveCredResult() function completes (by
returning valid results or by failure, which blocks returned
results). For certificate services that require explicit con‐
firmation by the requester, the reference identifier is invali‐
dated by successfully invoking the function CSSM_TP_ConfirmCre‐
dResult(). This structure contains a set of caller authentica‐
tion credentials. The authentication information can be a
passphrase, a PIN, a completed registration form, a certificate,
or a template of user-specific data. The required set of creden‐
tials is defined by the service provider module and recorded in
a record in the MDS Primary relation. Multiple credentials can
be required. If the local service provider module does not
require credentials from a caller, then the Credentials field of
this verification context structure can be NULL. The structure
optionally contains additional credentials that can be used to
support the authentication process. Authentication credentials
required by the authority should be included in the RequestIn‐
put. The local TP module can forward information from Caller‐
AuthCredentials to the authority, as appropriate, but is not
required to do so. The number of seconds estimated before the
results of a requested service will be returned to the
requester. When the local TP module or the authority process
cannot estimate the time required to perform the requested ser‐
vice, the output value for estimated time is CSSM_ESTI‐
MATED_TIME_UNKNOWN. A Boolean value indicating whether the
caller must invoke CSSM_TP_ConfirmCredResult() to acknowledge
retrieving the results of the service request. CSSM_TRUE indi‐
cates the caller must call CSSM_TP_ConfirmCredResult().
CSSM_FALSE indicates that the caller must not call CSSM_TP_Con‐
firmCredResult(). The value of this output parameter is not
applicable until CSSM_TP_RetrieveCredResult() completes by
returning results of the request or terminates in unrecoverable
failure. A pointer to the results returned by the authority in
response to the service requests submitted by CSSM_TP_SubmitCre‐
dRequest(). The output results are ordered corresponding to the
requests. The structure of the response set is determined by
the type of request. The caller and the service provider must
retain knowledge of the request type associated with the Refer‐
enceIdentifier.
DESCRIPTION
This function returns the results of a CSSM_TP_SubmitCredRequest()
call.
The single identifier ReferenceIdentifier denotes the CSSM_TP_Submit‐
CredRequest() invocation that initiated the request.
It is possible that the results are not ready to be retrieved when this
call is made. In that case, an EstimatedTime to complete processing is
returned. The caller must attempt to retrieve the results again after
the estimated time to completion has elapsed.
This function can fail in total for any one of the following reasons:
The reference identifier is invalid. The TP process cannot be located.
The TP process encountered a fatal error when attempting to process the
requests.
When this function completes, the set of return results is ordered cor‐
responding to the order of the originating request.
Some certificate services require the requester to confirm retrieval of
the results. The ConfirmationRequired parameter indicates whether the
caller must confirm completion of CSSM_TP_RetrieveCredResult() by call‐
ing CSSM_TP_ConfirmCredResult().
RETURN VALUE
A CSSM_RETURN value combined with estimated time to indicate one of
three results:
Complete Function Function Retrieve‐ EstimatedTime
Return Output
Result Value
Request results CSSM_OK Non-NULL NA
returned to caller pointer
Request results not CSSM_OK NULL CSSM_ESTIMATED_TIME_
ready, but expected pointer UNKNOWN or <estimated
in the future seconds>
Fatal Error, results (!CSSM_OK) NA NA
will never be
returned
The (!CSSM_OK) return value represents a specific error code.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_IDENTIFIER_POINTER CSS‐
MERR_TP_INVALID_IDENTIFIER CSSMERR_TP_INVALID_CALLERAUTH_CON‐
TEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSS‐
MERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSS‐
MERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSS‐
MERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSS‐
MERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSS‐
MERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSS‐
MERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSS‐
MERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED
CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSS‐
MERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSS‐
MERR_TP_REQUEST_LOST CSSMERR_TP_REQUEST_REJECTED
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_TP_SubmitCredRequest(3)
Functions for the TP SPI:
TP_SubmitCredRequest(3)CSSM_TP_RetrieveCredResult(3)