Index Index for
Section 3
Index Alphabetical
listing for T
Bottom of page Bottom of
page		 

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_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 (libcssm.so)


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_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


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)

Index Index for
Section 3
Index Alphabetical
listing for T
Top of page Top of
page