TP_ReceiveConfirmation(3)TP_ReceiveConfirmation(3)NAME
TP_ReceiveConfirmation, CSSM_TP_ReceiveConfirmation - Poll for confir‐
mation (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_TP_ReceiveConfirmation (CSSM_TP_HANDLE
TPHandle, const CSSM_DATA *ReferenceIdentifier, CSSM_TP_CON‐
FIRM_RESPONSE_PTR *Responses, sint32 *ElapsedTime) SPI: CSSM_RETURN
CSSMTPI TP_ReceiveConfirmation (CSSM_TP_HANDLE TPHandle, const
CSSM_DATA *ReferenceIdentifier, CSSM_TP_CONFIRM_RESPONSE_PTR
*Responses, sint32 *ElapsedTime)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The handle that describes the certification authority module used to
perform this function. A reference identifier that uniquely identifies
a set of service requests and the results created in response to those
requests. An ordered vector of acknowledges indicating the caller's
acceptance or rejection of results. The vector contains one acknowl‐
edgement per result created by the certificate authority. If the con‐
firmation has not been received, this output value is the number of
seconds elapsed since the certificate authority created the results or
CSSM_ELAPSED_TIME_UNKNOWN. If the confirmation has been received, this
output value is CSSM_ELAPSED_TIME_COMPLETE.
DESCRIPTION
A certificate authority uses this function to poll for confirmation
from a requester who has been served by the authority. A requester
sends a confirmation to the authority by successfully invoking the
function CSSM_TP_ConfirmCredResult() (CSSM API), or TP_ConfirmCre‐
dResult() (TP SPI).
The ReferenceIdentifier uniquely identifies the service request and
corresponding results for which confirmation is expected. This refer‐
ence identifier need not be identical to the reference identifier used
by the requester, but a one-to-one mapping between the two name spaces
must be well-defined.
Responses is an ordered vector of acknowledgements indicating, for each
returned result, whether the result was accepted or rejected by the
original requester for whom the service was performed.
If a result is rejected by the receiver, then the authority process
must undo the service if a reverse operation is possible and available.
If a fatal error occurs, this function returns an error code, indicat‐
ing that the function call can never be completed. If confirmation has
not been received, the function return value is CSSM_OK and the
ElapsedTime is returned to the caller of this function. The time repre‐
sents elapsed seconds since the service results were produced by the
authority process. Note that there can be a difference between the
time the authority process produces the results and the time the
results are actually received by the requester. Elapsed time is rela‐
tive and should increase with consecutive calls using the same Referen‐
ceIdentifier. If the TP module has no knowledge of the elapsed time,
the value CSSM_ELAPSED_TIME_UNKNOWN must be returned. If the service
requester has confirmed receipt of the service results, this function
returns CSSM_OK and ElapsedTime is CSSM_ELAPSED_TIME_COMPLETE.
This function can be invoked repeatedly until the confirmation is
received or until the caller decides the acknowledgement may be lost
and chooses to undo the results of the original service request.
This function fails if the ReferenceIdentifier is invalid or does not
match any requested service for which confirmation is expected.
RETURN VALUE
A CSSM return value combined with elapsed time to indicate one of three
results:
───────────────────────────────────────────────────────────────────────────────────
Complete Function Function Return RetrieveOutput EstimatedTime
───────────────────────────────────────────────────────────────────────────────────
Result Value
Confirmation CSSM_OK CSSM_ELAPSED_TIME_COM‐
Received PLETE
Confirmation not CSSM_OK CSSM_ELAPSED_TIME_UNKNOWN
received, but or <elapsed seconds>
expected in the
future
Fatal Error, Confir‐ (!CSSM_OK) NA
mation is not
expected
───────────────────────────────────────────────────────────────────────────────────
For a return value of (!CSSM_OK) the return value is an error code.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_IDENTIFIER_POINTER CSS‐
MERR_TP_INVALID_IDENTIFIER
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
Functions for the CSSM API:
CSSM_TP_ConfirmCredResult(3)
Functions for the TP SPI:
CSSM_TP_ConfirmCredResult(3)TP_ReceiveConfirmation(3)