|
|
CSSM_TP_RetrieveCredResult(3)
Contents |
CSSM_TP_RetrieveCredResult - Return the results of the
credentials request (CDSA)
# include <cdsa/cssm.h>
CSSM_RETURN CSSMAPI CSSM_TP_RetrieveCredResult
(CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier,
const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials,
sint32 *EstimatedTime, CSSM_BOOL *ConfirmationRequired,
CSSM_TP_RESULT_SET_PTR *RetrieveOutput)
Common Security Services Manager library (libcssm.so)
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 identifier 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 certificate services that do not require
explicit confirmation by the requester, the reference
identifier is invalidated when the corresponding
CSSM_TP_RetrieveCredResult() function completes
(by returning valid results or by failure, which
blocks returned results). For certificate services
that require explicit confirmation by the
requester, the reference identifier is invalidated
by successfully invoking the function CSSM_TP_ConfirmCredResult().
This structure contains a set of
caller authentication 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
credentials 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
RequestInput. The local TP module can forward
information from CallerAuthCredentials 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 service, the output value
for estimated time is CSSM_ESTIMATED_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 indicates the caller must call
CSSM_TP_ConfirmCredResult(). CSSM_FALSE indicates
that the caller must not call CSSM_TP_ConfirmCredResult().
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_SubmitCredRequest().
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 ReferenceIdentifier.
This function returns the results of a CSSM_TP_SubmitCredRequest()
call.
The single identifier ReferenceIdentifier denotes the
CSSM_TP_SubmitCredRequest() 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 corresponding 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 calling CSSM_TP_ConfirmCredResult().
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 are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_IDENTIFIER_POINTER CSSMERR_TP_INVALID_IDENTIFIER
CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER
CSSMERR_TP_INVALID_POLICY_IDENTIFIERS
CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY
CSSMERR_TP_INVALID_CALLBACK
CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE
CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE
CSSMERR_TP_INVALID_DB_LIST_POINTER
CSSMERR_TP_INVALID_DB_LIST
CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS
CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED
CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED
CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY
CSSMERR_TP_INVALID_SIGNATURE
CSSMERR_TP_INVALID_NAME CSSMERR_TP_REQUEST_LOST CSSMERR_TP_REQUEST_REJECTED
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
Functions for the CSSM API:
CSSM_TP_SubmitCredRequest(3)
Functions for the TP SPI:
TP_SubmitCredRequest(3)
CSSM_TP_RetrieveCredResult(3)
[ Back ] | 