|
|
TP_SubmitCredRequest(3)
Contents |
TP_SubmitCredRequest, CSSM_TP_SubmitCredRequest - Submit
credential request (CDSA)
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_TP_SubmitCredRequest
(CSSM_TP_HANDLE TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority,
CSSM_TP_AUTHORITY_REQUEST_TYPE RequestType,
const CSSM_TP_REQUEST_SET *RequestInput, const
CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthContext, sint32
*EstimatedTime, CSSM_DATA_PTR ReferenceIdentifier) SPI:
CSSM_RETURN CSSMTPI TP_SubmitCredRequest (CSSM_TP_HANDLE
TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority,
CSSM_TP_AUTHORITY_REQUEST_TYPE RequestType, const
CSSM_TP_REQUEST_SET *RequestInput, const CSSM_TP_CALLERAUTH_CONTEXT
*CallerAuthContext, sint32 *EstimatedTime,
CSSM_DATA_PTR ReferenceIdentifier)
Common Security Services Manager library (libcssm.so)
The handle that describes the certification authority module
used to perform this function. The identifier which
uniquely describes the Certificate Service Authority to
submit the request to. The identifier of the type of
request to submit. A pointer to the input parameters to
be submitted to the authority who will perform the
requested service. 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 the MDS Primary
relation. Multiple credentials can be required. If
the local service provider module does not require credentials
from a caller, then the CallerCredentials 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 service provider
module can forward this credential information to the
authority, as appropriate, but is not required to do so.
The number of estimated seconds before the service results
are ready to be retrieved. A (default) value of zero indicates
that the results can be retrieved immediately via
the corresponding CSSM_TP_RetrieveCredResult() (CSSM API),
or TP_RetrieveCredResult() (TP SPI), function call. When
the local service provider module or the authority cannot
estimate the time required to perform the requested service,
the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.
A reference identifier, which
uniquely identifies this specific request. The handle 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()
(CSSM API), or TP_RetrieveCredResult() (TP SPI),
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_ConfirmCredResu() (CSSM
API), or CSSM_TP_ConfirmCredResult() (TP SPI).
If the caller is successfully authenticated, then this
function submits a request to the Authority identified by
PreferredAuthority. The authority service can be local or
remote. If the Authority is not specified, then the TP
module can assume a default authority based on the
RequestType and the CallerAuthContext. RequestType indicates
the type of Authority request and RequestInput specifies
the input parameters needed by the authority to perform
the request.
The request is submitted to the authority only if the TP
module can successfully authenticate the caller. The
CallerAuthContext presents the caller's credentials and a
list of one or more policies under which the caller should
be authenticated. Caller credentials can be presented in
several forms: Memory-resident credential values, directly
referenced by the structure Data bases containing credentials
Callback functions that can be invoked to obtain
credentials from an active entity
The local service provider must select and forward the
credentials required by the Authority. The caller must
provide all necessary credentials through the CallerAuthContext
parameter.
If the caller can not be authenticated by the local service
provider, the function fails and the request is not
submitted to the selected authority.
This function returns a ReferenceIdentifier and an EstimatedTime
(specified in seconds). ReferenceIdentifier is
an ID for the submitted request. EstimatedTime defines
the expected time to process the request. This time may be
substantial when the request requires offline authentication
procedures by the Authority process. In contrast, the
estimated time can be zero, meaning the result can be
obtained immediately using CSSM_TP_RetrieveCredResult()
(CSSM API), or TP_RetrieveCredResult() (TP SPI). After the
specified time has elapsed, the caller must use the function
CSSM_TP_RetrieveCredResult() (CSSMAPI), or
TP_RetrieveCredResult() (TP SPI), with the reference identifier,
to obtain the result of the request.
A CSSM_RETURN value indicating success or specifying a
particular error condition. The value CSSM_OK indicates
success. All other values represent an error condition.
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_AUTHORITY CSSMERR_TP_NO_DEFAULT_AUTHORITY
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE
CSSMERR_TP_INVALID_NETWORK_ADDR CSSMERR_TP_UNSUPPORTED_SERVICE
CSSMERR_TP_INVALID_REQUEST_INPUTS
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
Books
Intel CDSA Application Developer's Guide (see
CDSA_intro(3))
Reference Pages [Toc] [Back]
Functions for the CSSM API:
CSSM_TP_RetrieveCredResult(3)
Functions for the TP SPI:
TP_RetrieveCredResult(3)
TP_SubmitCredRequest(3)
[ Back ] |
