HP Open Source Security for OpenVMS Volume 1:...

API Functions

TP_ReceiveConfirmation

TP_TupleGroupToCertGroup

NAME

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  

 PARAMETERS  

TPHandle (input)
		The handle that describes the certification authoritymodule used to perform this function.
PreferredAuthority (input/optional)
		The identifier which uniquely describes the CertificateService 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 submittedto the authority who will perform the requested service.
CallerAuthContext (input/optional)
		This structure contains a set of caller authenticationcredentials. The authentication information can be a passphrase,a PIN, a completed registration form, a certificate, or a templateof user-specific data. The required set of credentials is definedby the service provider module and recorded in the MDS Primary relation.Multiple credentials can be required. If the local service providermodule does not require credentials from a caller, then the CallerCredentials fieldof this verification context structure can be NULL. The structureoptionally contains additional credentials that can be used to supportthe authentication process. Authentication credentials requiredby the authority should be included in the RequestInput.The local service provider module can forward this credential informationto the authority, as appropriate, but is not required to do so.
EstimatedTime (output)
		The number of estimated seconds before the serviceresults are ready to be retrieved. A (default) value of zero indicatesthat 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 providermodule or the authority cannot estimate the time required to performthe requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.
ReferenceIdentifier (output)
		A reference identifier, which uniquely identifiesthis specific request. The handle persists across application executionsand becomes undefined when all local processing of the request hascompleted. Local processing is completed in one of two ways: For certificate services that do notrequire explicit confirmation by the requester, the reference identifieris invalidated when the corresponding CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCredResult() (TP SPI), function completes (by returning valid resultsor by failure, which blocks returned results) For certificate services that require explicit confirmationby the requester, the reference identifier is invalidated by successfullyinvoking the function CSSM_TP_ConfirmCredResu() (CSSM API), or CSSM_TP_ConfirmCredResult() (TP SPI).

 DESCRIPTION  

The request is submitted to the authority only if the TP modulecan successfully authenticate the caller. The CallerAuthContext presentsthe caller's credentials and a list of one or more policies underwhich the caller should be authenticated. Caller credentials canbe presented in several forms:

• Memory-resident credential values,directly referenced by the structure



• Data bases containing credentials



• Callback functions that can be invoked to obtaincredentials from an active entity

The local service provider must select and forward the credentialsrequired by the Authority. The caller must provide all necessarycredentials through the CallerAuthContext parameter.

If the caller can not be authenticated by the local serviceprovider, the function fails and the request is not submitted tothe selected authority.

This function returns a ReferenceIdentifier andan EstimatedTime (specified in seconds). ReferenceIdentifier isan ID for the submitted request. EstimatedTime definesthe expected time to process the request. This time may be substantialwhen the request requires offline authentication procedures by theAuthority 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, thecaller must use the function CSSM_TP_RetrieveCredResult() (CSSMAPI), or TP_RetrieveCredResult() (TP SPI), with the reference identifier, to obtain theresult of the request.

 RETURN VALUE  

 ERRORS  

CSSMERR_TP_INVALID_AUTHORITYCSSMERR_TP_NO_DEFAULT_AUTHORITYCSSMERR_TP_UNSUPPORTED_ADDR_TYPECSSMERR_TP_INVALID_NETWORK_ADDRCSSMERR_TP_UNSUPPORTED_SERVICECSSMERR_TP_INVALID_REQUEST_INPUTSCSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTERCSSMERR_TP_INVALID_POLICY_IDENTIFIERSCSSMERR_TP_INVALID_TIMESTRINGCSSMERR_TP_INVALID_STOP_ON_POLICYCSSMERR_TP_INVALID_CALLBACKCSSMERR_TP_INVALID_ANCHOR_CERTCSSMERR_TP_CERTGROUP_INCOMPLETECSSMERR_TP_INVALID_DL_HANDLECSSMERR_TP_INVALID_DB_HANDLECSSMERR_TP_INVALID_DB_LIST_POINTERCSSMERR_TP_INVALID_DB_LISTCSSMERR_TP_AUTHENTICATION_FAILEDCSSMERR_TP_INSUFFICIENT_CREDENTIALSCSSMERR_TP_NOT_TRUSTEDCSSMERR_TP_CERT_REVOKEDCSSMERR_TP_CERT_SUSPENDEDCSSMERR_TP_CERT_EXPIREDCSSMERR_TP_CERT_NOT_VALID_YETCSSMERR_TP_INVALID_CERT_AUTHORITYCSSMERR_TP_INVALID_SIGNATURECSSMERR_TP_INVALID_NAME

 SEE ALSO  

Intel CDSA Application Developer's Guide

Online Help

Functions for the CSSM API:

CSSM_TP_RetrieveCredResult

Functions for the TP SPI:

TP_RetrieveCredResult

TP_ReceiveConfirmation

TP_TupleGroupToCertGroup