TP_CertGroupVerify(3)TP_CertGroupVerify(3)NAME
TP_CertGroupVerify, CSSM_TP_CertGroupVerify - Determine if a certifi‐
cate is trusted (CDSA)
SYNOPSIS
# include <cdsa/cssm.h>
API: CSSM_RETURN CSSMAPI CSSM_TP_CertGroupVerify (CSSM_TP_HANDLE TPHan‐
dle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const
CSSM_CERTGROUP *CertGroupToBeVerified, const CSSM_TP_VERIFY_CONTEXT
*VerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR VerifyContextResult)
SPI: CSSM_RETURN CSSMTPI TP_CertGroupVerify (CSSM_TP_HANDLE TPHandle,
CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_CERT‐
GROUP *CertGroupToBeVerified, const CSSM_TP_VERIFY_CONTEXT *VerifyCon‐
text, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR VerifyContextResult)
LIBRARY
Common Security Services Manager library (libcssm.so)
PARAMETERS
The handle that describes the add-in trust policy module used to per‐
form this function. The handle that describes the add-in certificate
library module that can be used to manipulate the subject certificate
and anchor certificates. If no certificate library module is specified,
the TP module uses an assumed CL module, if required. The handle that
describes the add-in cryptographic service provider module that can be
used to perform the cryptographic operations required to carry out the
verification. If no CSP handle is specified, the TP module allocates a
suitable CSP. A group of one or more certificates to be verified. The
first certificate in the group is the primary target certificate for
verification. Use of the subsequent certificates during the verifica‐
tion process is specific to the trust domain. A structure containing
credentials, policy information, and contextual information to be used
in the verification process. All of the input values in the context are
optional except Action. The service provider can define default values
or can attempt to operate without input for all the other fields of
this input structure. The operation can fail if a necessary input value
is omitted and the service module can not define an appropriate default
value. A pointer to a structure containing information generated dur‐
ing the verification process. The information can include:
Evidence .PP (output/optional)
NumberOfEvidences .PP (output/optional)
DESCRIPTION
This function determines whether the certificate is trusted. The
actions performed by this function differ based on the trust policy
domain. The factors include practices, procedures and policies defined
by the certificate issuer.
Typically certificate verification involves the verification of multi‐
ple certificates. The first certificate in the group is the target of
the verification process. The other certificates in the group are used
in the verification process to connect the target certificate with one
or more anchors of trust. The supporting certificates can be contained
in the provided certificate group or can be stored in the data stores
specified in the VerifyContext DBList. This allows the trust policy
module to construct a certificate group and perform verification in one
operation. The data stores specified by DBList can also contain cer‐
tificate revocation lists used in the verification process. It is also
possible to provide a data store of anchor certificates. Typically the
points of Trust are few in number and are embedded in the caller or in
the TPM during software manufacturing or at runtime
The caller can select to be notified incrementally as each certificate
is verified. The CallbackWithVerifiedCert parameter (in the VerifyCon‐
text) can specify a caller function to be invoked at the end of each
certificate verification, returning the verified certificate for use by
the caller.
Anchor certificates are a list of implicitly trusted certificates.
These include root certificates, cross certified certificates, and
locally defined sources of trust. These certificates form the basis to
determine trust in the subject certificate.
A policy identifier can specify an additional set of conditions that
must be satisfied by the subject certificate in order to meet the trust
criteria. The name space for policy identifiers is defined by the
application domains to which the policy applies. This is outside of
CSSM. A list of policy identifiers can be specified and the stopping
condition for evaluating that set of conditions.
The evaluation and verification process can produce a list of evidence.
The evidence can be selected values from the certificates examined in
the verification process, entire certificates from the process or other
pertinent information that forms an audit trail of the verification
process. This evidence is returned to the caller after all steps in the
verification process have been completed.
If verification succeeds, the trust policy module may carry out the
action on the specified data or may return approval for the action
requiring the caller to perform the action. The caller must consult TP
module documentation outside of this specification to determine all
module-specific side effects of this operation.
RETURN VALUE
A CSSM_RETURN value indicating success or specifying a particular error
condition. The value CSSM_OK indicates success. All other values repre‐
sent an error condition.
ERRORS
Errors are described in the CDSA technical standard. See
CDSA_intro(3). CSSMERR_TP_INVALID_CL_HANDLE CSS‐
MERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_CERTGROUP_POINTER CSS‐
MERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSS‐
MERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VER‐
IFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSS‐
MERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSS‐
MERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POL‐
ICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSS‐
MERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSS‐
MERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSS‐
MERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSS‐
MERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSS‐
MERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSS‐
MERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED
CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSS‐
MERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSS‐
MERR_TP_INVALID_NAME
SEE ALSO
Books
Intel CDSA Application Developer's Guide (see CDSA_intro(3))
Reference Pages
TP_CertGroupVerify(3)