TP_SubmitCredRequest(3)TP_SubmitCredRequest(3)NAME
TP_SubmitCredRequest, CSSM_TP_SubmitCredRequest - Submit credential
request (CDSA)
SYNOPSIS
# 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_AUTHOR‐
ITY_REQUEST_TYPE RequestType, const CSSM_TP_REQUEST_SET *RequestInput,
const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthContext, sint32 *Estimated‐
Time, CSSM_DATA_PTR ReferenceIdentifier)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
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 mod‐
ule and recorded in the MDS Primary relation. Multiple credentials can
be required. If the local service provider module does not require cre‐
dentials from a caller, then the CallerCredentials field of this veri‐
fication context structure can be NULL. The structure optionally con‐
tains additional credentials that can be used to support the authenti‐
cation process. Authentication credentials required by the authority
should be included in the RequestInput. The local service provider mod‐
ule can forward this credential information to the authority, as appro‐
priate, 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_Retrieve‐
CredResult() (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 applica‐
tion 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 confirma‐
tion by the requester, the reference identifier is invalidated when the
corresponding CSSM_TP_RetrieveCredResult() (CSSM API), or TP_Retrieve‐
CredResult() (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).
DESCRIPTION
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 spec‐
ified, 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 refer‐
enced by the structure Data bases containing credentials Callback func‐
tions 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 cre‐
dentials 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 (spec‐
ified 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 immedi‐
ately using CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCre‐
dResult() (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.
RETURN VALUE
A CSSM_RETURN value indicating success or specifying a particular error
condition. The value CSSM_OK indicates success. All other values repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_AUTHORITY CSS‐
MERR_TP_NO_DEFAULT_AUTHORITY CSSMERR_TP_UNSUPPORTED_ADDR_TYPE CSS‐
MERR_TP_INVALID_NETWORK_ADDR CSSMERR_TP_UNSUPPORTED_SERVICE CSS‐
MERR_TP_INVALID_REQUEST_INPUTS 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
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_TP_RetrieveCredResult(3)
Functions for the TP SPI:
TP_RetrieveCredResult(3)TP_SubmitCredRequest(3)
