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