Copyright Digital Equipment Corp. All rights reserved.
TP_SubmitCredRequest
NAME
TP_SubmitCredRequest,
CSSM_TP_SubmitCredRequest - Submit credential request (CDSA)
SYNOPSIS
# include <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)
LIBRARY
Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)
PARAMETERS
TPHandle (input)
The handle that describes the certification authority
module used to perform this function.
PreferredAuthority (input/optional)
The identifier which uniquely describes the Certificate
Service Authority to submit the request to.
RequestType (input)
The identifier of the type of request to submit.
RequestInput (input)
A pointer to the input parameters to be submitted to the
authority who will perform the requested service.
CallerAuthContext (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 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.
EstimatedTime (output)
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.
ReferenceIdentifier (output)
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).
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 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.
RETURN VALUE
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
Errors are described in the CDSA technical standard. See CDSA.
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
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA)
Other Help Topics
Functions for the CSSM API:
CSSM_TP_RetrieveCredResult
Functions for the TP SPI:
TP_RetrieveCredResult