 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
CSSM_TP_RetrieveCredResult(3)
NAME
CSSM_TP_RetrieveCredResult - Return the results of the credentials request
(CDSA)
SYNOPSIS
# 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)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
TPHandle (input)
The handle that describes the certification authority module used
to perform this function.
ReferenceIdentifier (input)
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().
CallerAuthCredentials (input/optional)
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.
EstimatedTime (output)
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.
ConfirmationRequired (output)
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.
RetrieveOutput (output)
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.
DESCRIPTION
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().
RETURN VALUE
A CSSM_RETURN value combined with estimated time to indicate one of three
results:
Complete Function EstimatedTime
Function
Return
RetrieveOutput
Result Value
CSSM_OK NA
Request results
returned to caller
Non-NULL
pointer
CSSM_OK
Request results not
ready, but expected
in the future
NULL
pointer
CSSM_ESTIMATED_TIME_
UNKNOWN or <estimated
seconds>
(!CSSM_OK) NA NA
Fatal Error, results
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
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
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|