Within the first category of TP servives, applications are viewed as executing within a trust domain. For example, executing an installation program at the office takes place within the corporate information technology trust domain. Executing an installation program on a system at home takes place within the user's personal system trust domain. The trust policy that allows or blocks the installation action is different for the two domains. The corporate domain may require extensive credentials and accept only credentials signed by selected parties. The personal system domain may require only a credential that establishes the bearer as a known user on the local system.
The general CSSM trust model defines a set of basic trust objects that most (if not all) trust policies use to model their trust domain and the policies over that domain. These basic trust objects include:
Policies define the credentials required for authorization to perform an action on another object. (For example, a system administrator policy controls creating new user accounts on a computer system.) Certificates are the basic credentials representing a trust relationship among a set of two or more parties. When an organization issues certificates it defines its issuing procedure in a Certification Practice Statement (CPS). The statement identifies existing policies consistent with the CPS. The statement can also be the source of new policy definitions if the action and target object domains are not covered by an existing, published policy. An application domain can recognize multiple policies. A given policy can be recognized by multiple application domains.
Evaluation of trust depends on relationships among certificates. Certificate chains represent hierarchical trust, where a root authority is the source of trust. Entities attain a level of trust based on their relationship to the root authority. Certificate graphs represent an introducer model of trust, where the number and strength of endorsers (represented by immediate links in the trust graph) increases the level of trust attained by an entity. In both models, the trust domain can define accepted sources of trust, called anchors. Anchors can be mandated by fiat or can be computed by some other means. In contrast to the sources of trust, certificate revocation lists represent sources of distrust. Trust policies may consult these lists during the verification process.
Trust evaluation can be performed with respect to a specific action the bearer wishes to perform, or with respect to a policy, or with respect to the application domain in general. In the latter case, the action is understood to be either one specific action, or any and all actions in the domain.
When verifying trust, a Trust Policy Module (TPM) processes a group of 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. Supporting certificates can also be provided from a data store accessed by the TPM. It is also possible to provide a data store of anchor certificates. This case is less common. 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 result of verification is a list of evidence, which forms an audit trail of the process. The evidence may be a list of verified attribute values that were contained in the certificates, or the entire set of verified certificates, or some other information that serves as evidence of the verification. In the end, the trust and authorizations asserted are based on the authority implied by a set of assumed or otherwise-specified public keys.
Many applications are hard-coded to select a specific trust policy. The Module Directory Services system provides query mechanisms so applications can access TP module descriptions. This information is provided by the TP module during installation and can assist the application in selecting the appropriate TP module for a given application domain.
In the second category of service, the Trust Policy interfaces provide access to authorities providing services that support the complete life cycles of certificates and certificate life cycles.
The certificate life cycle is presented in
After registration, keying material is generated and certificates are created. Once the private key material and public key certificate are issued to a user and backed up if appropriate, the active phase of the certificate management life cycle begins.
The active phase includes:
These services can be provided by a local authority or a remote authority. Requesters must be authorized to request a service and to receive the results of that service. Ultimately access is controlled by the authority's policy. Policy enforcement can be distributed. By distributed enforcement we mean a local client system may enforce portions of the CA's policy prior to submitting request to the remote authority. The local policy statement can be the empty set (if appropriate). The remote authority enforces policy and performs the service. If the requester is authorized and the service succeeds, then results are returned to the requester. To support asynchronous completion of services, submitting a request and retrieving a result are performed using separate interfaces. The function pairs are:
The request service may not complete for several days. Applications can submit requests and retrieve results in separate executions of the application.
The MDS records describing the TP service provider should include a list of the authorities and life cycle services the TP module can access on behalf of a caller. If the authority is remote, the protocol used to communication with the remote authority is encapsulated in the local Trust Policy Service Provider. The TP service provider can record the implemented protocols in it's associated MDS records. Applications can query MDS records to determine what services are provided by a TP module.
typedef CSSM_MODULE_HANDLE CSSM_TP_HANDLE; /* Trust Policy Handle */
typedef struct cssm_tp_authority_id {
CSSM_DATA *AuthorityCert;
CSSM_NET_ADDRESS_PTR AuthorityLocation;
} CSSM_TP_AUTHORITY_ID, *CSSM_TP_AUTHORITY_ID_PTR;
typedef uint32 CSSM_TP_AUTHORITY_REQUEST_TYPE,
*CSSM_TP_AUTHORITY_REQUEST_TYPE_PTR;
#define CSSM_TP_AUTHORITY_REQUEST_CERTISSUE (0x01)
#define CSSM_TP_AUTHORITY_REQUEST_CERTREVOKE (0x02)
#define CSSM_TP_AUTHORITY_REQUEST_CERTSUSPEND (0x03)
#define CSSM_TP_AUTHORITY_REQUEST_CERTRESUME (0x04)
#define CSSM_TP_AUTHORITY_REQUEST_CERTVERIFY (0x05)
#define CSSM_TP_AUTHORITY_REQUEST_CERTNOTARIZE (0x06)
#define CSSM_TP_AUTHORITY_REQUEST_CERTUSERECOVER (0x07)
#define CSSM_TP_AUTHORITY_REQUEST_CRLISSUE (0x100)
typedef CSSM_RETURN (CSSMAPI * CSSM_TP_VERIFICATION_RESULTS_CALLBACK)
(CSSM_MODULE_HANDLE ModuleHandle,
void *CallerCtx,
CSSM_DATA_PTR VerifiedCert);
typedef struct cssm_tp_policyinfo {
uint32 NumberOfPolicyIds;
CSSM_FIELD_PTR PolicyIds;
void *PolicyControl;
} CSSM_TP_POLICYINFO, *CSSM_TP_POLICYINFO_PTR;
typedef uint32 CSSM_TP_SERVICES;
/* bit masks for additional Authority services available through TP */
#define CSSM_TP_KEY_ARCHIVE (0x0001) /* archive cert & keys */
#define CSSM_TP_CERT_PUBLISH (0x0002) /* register cert in
directory */
#define CSSM_TP_CERT_NOTIFY_RENEW (0x0004) /* notify at renewal time */
#define CSSM_TP_CERT_DIR_UPDATE (0x0008) /* update cert registry
entry */
#define CSSM_TP_CRL_DISTRIBUTE (0x0010) /* push CRL to everyone */
typedef uint32 CSSM_TP_ACTION;
#define CSSM_TP_ACTION_DEFAULT (0)
typedef enum cssm_tp_stop_on {
CSSM_TP_STOP_ON_POLICY = 0, /* use the pre-defined stopping
criteria */
CSSM_TP_STOP_ON_NONE = 1, /* evaluate all condition whether
TRUE or FALSE */
CSSM_TP_STOP_ON_FIRST_PASS = 2, /* stop evaluation at first TRUE */
CSSM_TP_STOP_ON_FIRST_FAIL = 3 /* stop evaluation at first FALSE */
} CSSM_TP_STOP_ON;
This string contains a date and time in the format "YYYYMMDDhhmmss", defined by:
typedef char *CSSM_TIMESTRING;
typedef struct cssm_tp_callerauth_context {
CSSM_TP_POLICYINFO Policy;
CSSM_TIMESTRING VerifyTime;
CSSM_TP_STOP_ON VerificationAbortOn;
CSSM_TP_VERIFICATION_RESULTS_CALLBACK CallbackWithVerifiedCert;
uint32 NumberOfAnchorCerts;
CSSM_DATA_PTR AnchorCerts;
CSSM_DL_DB_LIST_PTR DBList;
CSSM_ACCESS_CREDENTIALS_PTR CallerCredentials;
} CSSM_TP_CALLERAUTH_CONTEXT, *CSSM_TP_CALLERAUTH_CONTEXT_PTR;
CSSM_TP_STOP_ON | Definition |
---|---|
CSSM_STOP_ON_POLICY | Stop verification whenever the policy dictates it |
CSSM_STOP_ON_NONE | Stop verification only after all conditions have been tested (ignoring the pass- fail status of each condition) |
CSSM_STOP_ON_FIRST_PASS | Stop verification on the first condition that passes |
CSSM_STOP_ON_FIRST_FAIL | Stop verification on the first condition that fails |
The service provider module can ignore the caller's specified stopping condition and revert to the implicit, default stopping policy.
typedef uint32 CSSM_CRL_PARSE_FORMAT, * CSSM_CRL_PARSE_FORMAT_PTR;
#define CSSM_CRL_PARSE_FORMAT_NONE (0x00)
#define CSSM_CRL_PARSE_FORMAT_CUSTOM (0x01)
#define CSSM_CRL_PARSE_FORMAT_SEXPR (0x02)
#define CSSM_CRL_PARSE_FORMAT_COMPLEX (0x03)
#define CSSM_CRL_PARSE_FORMAT_OID_NAMED (0x04)
#define CSSM_CRL_PARSE_FORMAT_TUPLE (0x05)
#define CSSM_CRL_PARSE_FORMAT_MULTIPLE (0x7FFE)
#define CSSM_CRL_PARSE_FORMAT_LAST (0x7FFF)
/* Applications wishing to define their own custom parse
* format should create a uint32 value greater than the
* CSSM_CL_CUSTOM_CRL_PARSE_FORMAT */
#define CSSM_CL_CUSTOM_CRL_PARSE_FORMAT (0x8000)
typedef struct cssm_parsed_crl {
CSSM_CRL_TYPE CrlType; /* CRL type */
CSSM_CRL_PARSE_FORMAT ParsedCrlFormat;
/* struct of ParsedCrl */
void *ParsedCrl; /* parsed CRL (to be typecast) */
} CSSM_PARSED_CRL, *CSSM_PARSED_CRL_PTR ;
typedef struct cssm_crl_pair {
CSSM_ENCODED_CRL EncodedCrl; /* an encoded CRL blob */
CSSM_PARSED_CRL ParsedCrl; /* equivalent parsed CRL */
} CSSM_CRL_PAIR, *CSSM_CRL_PAIR_PTR;
The CRL can have an equivalent parsed representation. If the parsed representation is provided it is contained in ParsedCrl.
The CRL can have an equivalent encoded representation. If the encoded representation is provided it is contained in EncodedCrl.
typedef uint32 CSSM_CRLGROUP_TYPE, * CSSM_CRLGROUP_TYPE_PTR;
#define CSSM_CRLGROUP_DATA (0x00)
#define CSSM_CRLGROUP_ENCODED_CRL (0x01)
#define CSSM_CRLGROUP_PARSED_CRL (0x02)
#define CSSM_CRLGROUP_CRL_PAIR (0x03)
typedef struct cssm_crlgroup {
CSSM_CRL_TYPE CrlType;
CSSM_CRL_ENCODING CrlEncoding;
uint32 NumberOfCrls;
union {
CSSM_DATA_PTR CrlList ; /* CRL blob */
CSSM_ENCODED_CRL_PTR EncodedCrlList ; /* CRL blob
w/ separate type */
CSSM_PARSED_CRL_PTR ParsedCrlList; /* bushy, parsed CRL */
CSSM_CRL_PAIR_PTR PairCrlList;
} GroupLCrllist;
CSSM_CRLGROUP_TYPE CrlGroupType;
} CSSM_CRLGROUP, *CSSM_CRLGROUP_PTR;
CrlGroupType Value | Field Name | Description |
---|---|---|
CSSM_CRLGROUP_DATA | CrlList | (Legacy) A pointer to an array of CSSM_DATA structures. Each CrlList array entry references a single CRL structure and indicates the length of the structure. A single type and encoding apply to all CRLs in this group. The type and encoding are indicated in CrlType and CrlEncoding respectively. |
CSSM_CRLGROUP_ENCODED_CRL | EncodedCrlList | A pointer to an array of CSSM_ENCODED_CRL structures. Each EncodedCrlList array entry references a CRL in an opaque, single byte-array representation, and describes the format of the CRL data contained in the byte-array. Each CRL encoding and type can be distinct, as indicated in each array element. |
CSSM_CRLGROUP_PARSED_CRL | ParsedCrlList | A pointer to an array of CSSM_PARSED_CRL structures. Each ParsedCrlList array entry references a CRL in a parsed representation, and indicates the CRL type and parse format of that CRL. |
CSSM_CRLGROUP_CRL_PAIR | PairCrlList | A pointer to an array of CSSM_CRL_PAIR structures. Each PairCrlList array
entry aggregates two CRL representations: an opaque encoded CRL blob,
and a parsed CRL representation.
At least one of the two representations must be present in each array entry. If both are present, they are assumed but not guaranteed to correspond to one another. If the parsed form is being used in a security sensitive operation, then it must have been verified against the packed, encoded form, whose signature must have been verified. |
typedef struct cssm_fieldgroup {
int NumberOfFields ; /* number of fields in the array */
CSSM_FIELD_PTR Fields ; /* array of fields */
} CSSM_FIELDGROUP, *CSSM_FIELDGROUP_PTR ;
typedef uint32 CSSM_EVIDENCE_FORM;
#define CSSM_EVIDENCE_FORM_UNSPECIFIC 0x0
#define CSSM_EVIDENCE_FORM_CERT 0x1
#define CSSM_EVIDENCE_FORM_CRL 0x2
#define CSSM_EVIDENCE_FORM_CERT_ID 0x3
#define CSSM_EVIDENCE_FORM_CRL_ID 0x4
#define CSSM_EVIDENCE_FORM_VERIFIER_TIME 0x5
#define CSSM_EVIDENCE_FORM_CRL_THISTIME 0x6
#define CSSM_EVIDENCE_FORM_CRL_NEXTTIME 0x7
#define CSSM_EVIDENCE_FORM_POLICYINFO 0x8
#define CSSM_EVIDENCE_FORM_TUPLEGROUP 0x9
typedef struct cssm_evidence {
CSSM_EVIDENCE_FORM EvidenceForm;
void *Evidence; /* Evidence content */
} CSSM_EVIDENCE, *CSSM_EVIDENCE_PTR;
The correspondence between the value of
EvidenceForm
and the structure type contained in the
Evidence
field is defined as follows:
Value of EvidenceForm | Data Type of Evidence |
---|---|
CSSM_EVIDENCE_FORM_UNSPECIFIC | void * |
CSSM_EVIDENCE_FORM_CERT | CSSM_ENCODED_CERT |
CSSM_EVIDENCE_FORM_CRL | CSSM_ENCODED_CRL |
CSSM_EVIDENCE_FORM_CERT_ID | Big-endian integer |
CSSM_EVIDENCE_FORM_CRL_ID | Big-endian integer |
CSSM_EVIDENCE_FORM_VERIFIER_TIME | CSSM_TIMESTRING |
CSSM_EVIDENCE_FORM_CRL_THISTIME | CSSM_TIMESTRING |
CSSM_EVIDENCE_FORM_CRL_NEXTTIME | CSSM_TIMESTRING |
CSSM_EVIDENCE_FORM_TUPLEGROUP | CSSM_TUPLEGROUP |
CSSM_EVIDENCE_FORM_POLICYINFO | CSSM_TP_POLICYINFO |
typedef struct cssm_tp_verify_context {
CSSM_TP_ACTION Action;
CSSM_DATA ActionData;
CSSM_CRLGROUP Crls;
CSSM_TP_CALLERAUTH_CONTEXT_PTR Cred;
} CSSM_TP_VERIFY_CONTEXT, *CSSM_TP_VERIFY_CONTEXT_PTR;
typedef struct cssm_tp_verify_context_result {
uint32 *NumberOfEvidences;
CSSM_EVIDENCE_PTR Evidence;
} CSSM_TP_VERIFY_CONTEXT_RESULT, *CSSM_TP_VERIFY_CONTEXT_RESULT_PTR;
typedef struct cssm_tp_request_set {
uint32 NumberOfRequests;
void *Requests;
} CSSM_TP_REQUEST_SET, *CSSM_TP_REQUEST_SET_PTR;
A call to
typedef struct cssm_tp_result_set {
uint32 *NumberOfResults;
void *Results;
} CSSM_TP_RESULT_SET, *CSSM_TP_RESULT_SET_PTR;
typedef uint32 CSSM_TP_CONFIRM_STATUS, *CSSM_TP_CONFIRM_STATUS_PTR;
#define CSSM_TP_CONFIRM_STATUS_UNKNOWN 0x0
/* indeterminate */
#define CSSM_TP_CONFIRM_ACCEPT 0x1
/* accept results of executing a submit-retrieve function pair */
#define CSSM_TP_CONFIRM_REJECT 0x2
/* reject results of executing a submit-retrieve function pair */
typedef struct cssm_tp_confirm_response {
uint32 NumberOfResponses;
CSSM_TP_CONFIRM_STATUS_PTR Responses;
} CSSM_TP_CONFIRM_RESPONSE, *CSSM_TP_CONFIRM_RESPONSE_PTR;
#define CSSM_ESTIMATED_TIME_UNKNOWN -1
#define CSSM_ELAPSED_TIME_UNKNOWN (-1)
#define CSSM_ELAPSED_TIME_COMPLETE (-2)
typedef struct cssm_tp_certissue_input {
CSSM_SUBSERVICE_UID CSPSubserviceUid;
CSSM_CL_HANDLE CLHandle;
uint32 NumberOfTemplateFields;
CSSM_FIELD_PTR SubjectCertFields;
CSSM_TP_SERVICES MoreServiceRequests;
uint32 NumberOfServiceControls;
CSSM_FIELD_PTR ServiceControls;
CSSM_ACCESS_CREDENTIALS_PTR UserCredentials;
} CSSM_TP_CERTISSUE_INPUT, *CSSM_TP_CERTISSUE_INPUT_PTR;
typedef uint32 CSSM_TP_CERTISSUE_STATUS
#define CSSM_TP_CERTISSUE_STATUS_UNKNOWN 0x0
/* indeterminate */
#define CSSM_TP_CERTISSUE_OK 0x1
/* cert issued as requested */
#define CSSM_TP_CERTISSUE_OKWITHCERTMODS 0x2
/* cert issued but cert contents were updated by the
issuing authority */
#define CSSM_TP_CERTISSUE_OKWITHSERVICEMODS 0x3
/* cert issued but some requested backend services were
not performed by the issuing authority */
#define CSSM_TP_CERTISSUE_REJECTED 0x4
/* cert was not issued due to some error condition */
#define CSSM_TP_CERTISSUE_NOT_AUTHORIZED 0x5
/* cert was not issued, the request was not authorized */
#define CSSM_TP_CERTISSUE_WILL_BE_REVOKED 0x6
/* cert was issued, but TP has initiated a revocation
of the certificate */
typedef struct cssm_tp_certissue_output {
CSSM_TP_CERTISSUE_STATUS IssueStatus;
CSSM_CERTGROUP_PTR CertGroup;
CSSM_TP_SERVICES PerformedServiceRequests;
} CSSM_TP_CERTISSUE_OUTPUT, *CSSM_TP_CERTISSUE_OUTPUT_PTR;
typedef uint32 CSSM_TP_CERTCHANGE_ACTION;
#define CSSM_TP_CERTCHANGE_NONE (0x0) /* no change */
#define CSSM_TP_CERTCHANGE_REVOKE (0x1) /* Revoke the certificate */
/* This action type indicates a request to revoke a single
certificate. Notice of the revocation operation remains
in affect until the certificate itself expires. Revocation
should be used to permanently remove a certificate from use. */
#define CSSM_TP_CERTCHANGE_HOLD (0x2) /* Hold/suspend the
certificate */
/* This action type indicates a request to suspend a
single certificate. A suspension operation implies
that the requester intends, at some time in the future,
to request that the certificate be released from hold,
making it available for use again. Placing a hold on
a certificate does not obligate the requester to
request a release. In practice, a certificate may
remain on hold until the certificate itself expires.
Revocation should be used to permanently remove a
certificate from use. */
#define CSSM_TP_CERTCHANGE_RELEASE (0x3) /* Release the held
certificate */
/* This action type indicates a request to release a
single certificate currently on hold. A release
operation makes a certificate available for use again.
Revocation should be used to permanently remove a
certificate from use. */
typedef uint32 CSSM_TP_CERTCHANGE_REASON;
#define CSSM_TP_CERTCHANGE_REASON_UNKNOWN (0x0)
/* unspecified */
#define CSSM_TP_CERTCHANGE_REASON_KEYCOMPROMISE (0x1)
/* Subject key believed to be compromised */
#define CSSM_TP_CERTCHANGE_REASON_CACOMPROMISE (0x2)
/* CA's key believed to be compromised */
#define CSSM_TP_CERTCHANGE_REASON_CEASEOPERATION (0x3)
/*certificate holder ceases operation under the
jurisdiction of this certificate */
#define CSSM_TP_CERTCHANGE_REASON_AFFILIATIONCHANGE (0x4)
/*certificate holder has moved from this jurisdiction */
#define CSSM_TP_CERTCHANGE_REASON_SUPERCEDED (0x5)
/*certificate holder as issued a new, superceding
certificate */
#define CSSM_TP_CERTCHANGE_REASON_SUSPECTEDCOMPROMISE (0x6)
/*certificate could be compromised */
#define CSSM_TP_CERTCHANGE_REASON_HOLDRELEASE (0x7)
/*certificate holder resumes operation under
the jurisdiction of this certificate */
typedef struct cssm_tp_certchange_input{
CSSM_TP_CERTCHANGE_ACTION Action;
CSSM_TP_CERTCHANGE_REASON Reason;
CSSM_CL_HANDLE CLHandle;
CSSM_DATA_PTR Cert;
CSSM_FIELD_PTR ChangeInfo;
CSSM_TIMESTRING StartTime;
CSSM_ACCESS_CREDENTIALS_PTR CallerCredentials;
} CSSM_TP_CERTCHANGE_INPUT, *CSSM_TP_CERTCHANGE_INPUT_PTR;
typedef uint32 CSSM_TP_CERTCHANGE_STATUS;
#define CSSM_TP_CERTCHANGE_STATUS_UNKNOWN (0x0)
/* indeterminate */
#define CSSM_TP_CERTCHANGE_OK (0x1)
/* cert state was successfully changed
beginning at the specified time */
#define CSSM_TP_CERTCHANGE_OKWITHNEWTIME (0x2)
/* cert state was successfully changed, at
a modified effective time */
#define CSSM_TP_CERTCHANGE_WRONGCA (0x3)
/* cert state was not changed, the selected
CA is not authorized to change the cert state */
#define CSSM_TP_CERTCHANGE_REJECTED (0x4)
/* cert state was not changed due to some
error condition */
#define CSSM_TP_CERTCHANGE_NOT_AUTHORIZED (0x5)
/* cert state was not changed, the requester is
not authorized to change the cert state */
typedef struct cssm_tp_certchange_output {
CSSM_TP_CERTCHANGE_STATUS ActionStatus;
CSSM_FIELD RevokeInfo;
} CSSM_TP_CERTCHANGE_OUTPUT, *CSSM_TP_CERTCHANGE_OUTPUT_PTR;
typedef struct cssm_tp_certverify_input{
CSSM_CL_HANDLE CLHandle;
CSSM_DATA_PTR Cert;
CSSM_TP_VERIFY_CONTEXT_PTR VerifyContext;
} CSSM_TP_CERTVERIFY_INPUT, *CSSM_TP_CERTVERIFY_INPUT_PTR;
typedef uint32 CSSM_TP_CERTVERIFY_STATUS
#define CSSM_TP_CERTVERIFY_UNKNOWN (0x0)
#define CSSM_TP_CERTVERIFY_VALID (0x1)
#define CSSM_TP_CERTVERIFY_INVALID (0x2)
#define CSSM_TP_CERTVERIFY_REVOKED (0x3)
#define CSSM_TP_CERTVERIFY_SUSPENDED (0x4)
#define CSSM_TP_CERTVERIFY_EXPIRED (0x5)
#define CSSM_TP_CERTVERIFY_NOT_VALID_YET (0x6)
#define CSSM_TP_CERTVERIFY_INVALID_AUTHORITY (0x7)
#define CSSM_TP_CERTVERIFY_INVALID_SIGNATURE (0x8)
#define CSSM_TP_CERTVERIFY_INVALID_CERT_VALUE (0x9)
#define CSSM_TP_CERTVERIFY_INVALID_CERTGROUP (0xA)
#define CSSM_TP_CERTVERIFY_INVALID_POLICY (0xB)
#define CSSM_TP_CERTVERIFY_INVALID_POLICY_IDS (0xC)
#define CSSM_TP_CERTVERIFY_INVALID_BASIC_CONSTRAINTS (0xD)
#define CSSM_TP_CERTVERIFY_INVALID_CRL_DIST_PT (0xE)
#define CSSM_TP_CERTVERIFY_INVALID_NAME_TREE (0xF)
#define CSSM_TP_CERTVERIFY_UNKNOWN_CRITICAL_EXT (0x10)
typedef struct cssm_tp_certverify_output {
CSSM_TP_CERTVERIFY_STATUS VerifyStatus;
uint32 NumberOfEvidence;
CSSM_EVIDENCE_PTR Evidence;
} CSSM_TP_CERTVERIFY_OUTPUT, *CSSM_TP_CERTVERIFY_OUTPUT_PTR;
typedef struct cssm_tp_certnotarize_input {
CSSM_CL_HANDLE CLHandle;
uint32 NumberOfFields;
CSSM_FIELD_PTR MoreFields;
CSSM_FIELD_PTR SignScope;
uint32 ScopeSize;
CSSM_TP_SERVICES MoreServiceRequests;
uint32 NumberOfServiceControls;
CSSM_FIELD_PTR ServiceControls;
CSSM_ACCESS_CREDENTIALS_PTR UserCredentials;
} CSSM_TP_CERTNOTARIZE_INPUT, *CSSM_TP_CERTNOTARIZE_INPUT_PTR;
typedef struct cssm_tp_certnotarize_output {
CSSM_TP_CERTNOTARIZE_STATUS NotarizeStatus;
CSSM_CERTGROUP_PTR NotarizedCertGroup;
CSSM_TP_SERVICES PerformedServiceRequests;
} CSSM_TP_CERTNOTARIZE_OUTPUT, *CSSM_TP_CERTNOTARIZE_OUTPUT_PTR;
typedef struct cssm_tp_certreclaim_input {
CSSM_CL_HANDLE CLHandle;
uint32 NumberOfSelectionFields;
CSSM_FIELD_PTR SelectionFields;
CSSM_ACCESS_CREDENTIALS_PTR UserCredentials;
} CSSM_TP_CERTRECLAIM_INPUT, *CSSM_TP_CERTRECLAIM_INPUT_PTR;
typedef uint32 CSSM_TP_CERTRECLAIM_STATUS;
#define CSSM_TP_CERTRECLAIM_STATUS_UNKNOWN (0x0)
/* indeterminate */
#define CSSM_TP_CERTRECLAIM_OK (0x1)
/* a set of one or more certificates were returned by the CA
for local recovery of the associated private key */
#define CSSM_TP_CERTRECLAIM_NOMATCH (0x2)
/* no certificates owned by the requester were found matching
the specified selection fields */
#define CSSM_TP_CERTRECLAIM_REJECTED (0x3)
/* certificate reclamation failed due to some error condition */
#define CSSM_TP_CERTRECLAIM_NOT_AUTHORIZED (0x4)
/* certificate reclamation was not performed, the request
was not authorized */
typedef struct cssm_tp_certreclaim_output {
CSSM_TP_CERTRECLAIM_STATUS ReclaimStatus;
CSSM_CERTGROUP_PTR ReclaimedCertGroup;
CSSM_LONG_HANDLE KeyCacheHandle;
} CSSM_TP_CERTRECLAIM_OUTPUT, *CSSM_TP_CERTRECLAIM_OUTPUT_PTR;
If CRL retrieval is a controlled operation, the caller can present the necessary credentials in CallerCredentials.
typedef struct cssm_tp_crlissue_input {
CSSM_CL_HANDLE CLHandle;
uint32 CrlIdentifier;
CSSM_TIMESTRING CrlThisTime;
CSSM_FIELD_PTR PolicyIdentifier;
CSSM_ACCESS_CREDENTIALS_PTR CallerCredentials;
} CSSM_TP_CRLISSUE_INPUT, *CSSM_TP_CRLISSUE_INPUT_PTR;
typedef uint32 CSSM_TP_CRLISSUE_STATUS;
#define CSSM_TP_CRLISSUE_STATUS_UNKNOWN (0x0)
/* indeterminate */
#define CSSM_TP_CRLISSUE_OK (0x1)
/* a copy of the most current CRL was issued as requested
and the time for issuing the next CRL is also returned */
#define CSSM_TP_CRLISSUE_NOT_CURRENT (0x2)
/* either no CRL has been issued since the CRL identified
in the request, or it is not time to issue an updated CRL.
no CRL has been returned, but the time for issuing the
next CRL is included in the results */
#define CSSM_TP_CRLISSUE_INVALID_DOMAIN (0x3)
/* CRL domain was not recognized or was outside the
CA jurisdiction, no CRL or time for the next CRL
has been returned */
#define CSSM_TP_CRLISSUE_UNKNOWN_IDENTIFIER (0x4)
/* unrecognized CRL identifier,
no CRL or time for the next CRL has been returned */
#define CSSM_TP_CRLISSUE_REJECTED (0x5)
/* CRL was not issued due to some error condition,
no CRL or time for the next CRL has been returned */
#define CSSM_TP_CRLISSUE_NOT_AUTHORIZED (0x6)
/* CRL was not issued, the request was not authorized,
no CRL or time for the next CRL has been returned */
typedef struct cssm_tp_crlissue_output {
CSSM_TP_CRLISSUE_STATUS IssueStatus;
CSSM_ENCODED_CRL_PTR Crl;
CSSM_TIMESTRING CrlNextTime;
} CSSM_TP_CRLISSUE_OUTPUT, *CSSM_TP_CRLISSUE_OUTPUT_PTR;
typedef uint32 CSSM_TP_FORM_TYPE;
#define CSSM_TP_FORM_TYPE_GENERIC (0x0)
#define CSSM_TP_FORM_TYPE_REGISTRATION (0x1)
The Error Values that can be returned by TP functions can be either
derived from the Common Error
Codes defined in
The TP Error Values defined in this section list the TP Error Values in the Common set, plus any Error Values that are specific to a function.
#define CSSMERR_TP_INTERNAL_ERROR \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)
#define CSSMERR_TP_MEMORY_ERROR \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)
#define CSSMERR_TP_MDS_ERROR \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_MDS_ERROR)
#define CSSMERR_TP_INVALID_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)
#define CSSMERR_TP_INVALID_INPUT_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)
#define CSSMERR_TP_INVALID_OUTPUT_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)
#define CSSMERR_TP_FUNCTION_NOT_IMPLEMENTED \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)
#define CSSMERR_TP_SELF_CHECK_FAILED \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_SELF_CHECK_FAILED)
#define CSSMERR_TP_OS_ACCESS_DENIED \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)
#define CSSMERR_TP_FUNCTION_FAILED \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)
#define CSSMERR_TP_INVALID_CONTEXT_HANDLE \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_CONTEXT_HANDLE)
#define CSSMERR_TP_INVALID_DATA \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_DATA)
#define CSSMERR_TP_INVALID_DB_LIST \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_DB_LIST)
#define CSSMERR_TP_INVALID_CERTGROUP_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_CERTGROUP_POINTER)
#define CSSMERR_TP_INVALID_CERT_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_CERT_POINTER)
#define CSSMERR_TP_INVALID_CRL_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_CRL_POINTER)
#define CSSMERR_TP_INVALID_FIELD_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_FIELD_POINTER)
#define CSSMERR_TP_INVALID_DATA \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_DATA)
#define CSSMERR_TP_CRL_ALREADY_SIGNED \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_CRL_ALREADY_SIGNED)
#define CSSMERR_TP_INVALID_NUMBER_OF_FIELDS \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_NUMBER_OF_FIELDS)
#define CSSMERR_TP_VERIFICATION_FAILURE \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_VERIFICATION_FAILURE)
#define CSSMERR_TP_INVALID_DB_HANDLE \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_DB_HANDLE)
#define CSSMERR_TP_UNKNOWN_FORMAT \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_UNKNOWN_FORMAT)
#define CSSMERR_TP_UNKNOWN_TAG \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_UNKNOWN_TAG)
#define CSSMERR_TP_INVALID_PASSTHROUGH_ID \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_PASSTHROUGH_ID)
#define CSSMERR_TP_INVALID_DL_HANDLE \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_DL_HANDLE)
#define CSSMERR_TP_INVALID_CL_HANDLE \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_CL_HANDLE)
#define CSSMERR_TP_INVALID_TP_HANDLE \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_TP_HANDLE)
#define CSSMERR_TP_INVALID_DB_LIST_POINTER \
(CSSM_TP_BASE_ERROR+CSSM_ERRCODE_INVALID_DB_LIST_POINTER)
#define CSSM_TP_BASE_TP_ERROR \
(CSSM_TP_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)
#define CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER \
(CSSM_TP_BASE_TP_ERROR+1)
#define CSSMERR_TP_INVALID_IDENTIFIER_POINTER (CSSM_TP_BASE_TP_ERROR+2)
#define CSSMERR_TP_INVALID_KEYCACHE_HANDLE (CSSM_TP_BASE_TP_ERROR+3)
#define CSSMERR_TP_INVALID_CERTGROUP (CSSM_TP_BASE_TP_ERROR+4)
#define CSSMERR_TP_INVALID_CRLGROUP (CSSM_TP_BASE_TP_ERROR+5)
#define CSSMERR_TP_INVALID_CRLGROUP_POINTER (CSSM_TP_BASE_TP_ERROR+6)
#define CSSMERR_TP_AUTHENTICATION_FAILED (CSSM_TP_BASE_TP_ERROR+7)
#define CSSMERR_TP_CERTGROUP_INCOMPLETE (CSSM_TP_BASE_TP_ERROR+8)
#define CSSMERR_TP_CERTIFICATE_CANT_OPERATE (CSSM_TP_BASE_TP_ERROR+9)
#define CSSMERR_TP_CERT_EXPIRED (CSSM_TP_BASE_TP_ERROR+10)
#define CSSMERR_TP_CERT_NOT_VALID_YET (CSSM_TP_BASE_TP_ERROR+11)
#define CSSMERR_TP_CERT_REVOKED (CSSM_TP_BASE_TP_ERROR+12)
#define CSSMERR_TP_CERT_SUSPENDED (CSSM_TP_BASE_TP_ERROR+13)
#define CSSMERR_TP_INSUFFICIENT_CREDENTIALS (CSSM_TP_BASE_TP_ERROR+14)
#define CSSMERR_TP_INVALID_ACTION (CSSM_TP_BASE_TP_ERROR+15)
#define CSSMERR_TP_INVALID_ACTION_DATA (CSSM_TP_BASE_TP_ERROR+16)
#define CSSMERR_TP_INVALID_NETWORK_ADDR (CSSM_TP_BASE_TP_ERROR+17)
#define CSSMERR_TP_INVALID_ANCHOR_CERT (CSSM_TP_BASE_TP_ERROR+18)
#define CSSMERR_TP_INVALID_AUTHORITY (CSSM_TP_BASE_TP_ERROR+19)
#define CSSMERR_TP_VERIFY_ACTION_FAILED (CSSM_TP_BASE_TP_ERROR+20)
#define CSSMERR_TP_INVALID_CERTIFICATE (CSSM_TP_BASE_TP_ERROR+21)
#define CSSMERR_TP_INVALID_CERT_AUTHORITY (CSSM_TP_BASE_TP_ERROR+22)
#define CSSMERR_TP_INVALID_CRL_AUTHORITY (CSSM_TP_BASE_TP_ERROR+23)
#define CSSMERR_TP_INVALID_CRL_ENCODING (CSSM_TP_BASE_TP_ERROR+24)
#define CSSMERR_TP_INVALID_CRL_TYPE (CSSM_TP_BASE_TP_ERROR+25)
#define CSSMERR_TP_INVALID_CRL (CSSM_TP_BASE_TP_ERROR+26)
#define CSSMERR_TP_INVALID_FORM_TYPE (CSSM_TP_BASE_TP_ERROR+27)
#define CSSMERR_TP_INVALID_ID (CSSM_TP_BASE_TP_ERROR+28)
#define CSSMERR_TP_INVALID_IDENTIFIER (CSSM_TP_BASE_TP_ERROR+29)
#define CSSMERR_TP_INVALID_INDEX (CSSM_TP_BASE_TP_ERROR+30)
#define CSSMERR_TP_INVALID_NAME (CSSM_TP_BASE_TP_ERROR+31)
#define CSSMERR_TP_INVALID_POLICY_IDENTIFIERS (CSSM_TP_BASE_TP_ERROR+32)
#define CSSMERR_TP_INVALID_TIMESTRING (CSSM_TP_BASE_TP_ERROR+33)
#define CSSMERR_TP_INVALID_REASON (CSSM_TP_BASE_TP_ERROR+34)
#define CSSMERR_TP_INVALID_REQUEST_INPUTS (CSSM_TP_BASE_TP_ERROR+35)
#define CSSMERR_TP_INVALID_RESPONSE_VECTOR (CSSM_TP_BASE_TP_ERROR+36)
#define CSSMERR_TP_INVALID_SIGNATURE (CSSM_TP_BASE_TP_ERROR+37)
#define CSSMERR_TP_INVALID_STOP_ON_POLICY (CSSM_TP_BASE_TP_ERROR+38)
#define CSSMERR_TP_INVALID_CALLBACK (CSSM_TP_BASE_TP_ERROR+39)
#define CSSMERR_TP_INVALID_TUPLE (CSSM_TP_BASE_TP_ERROR+40)
#define CSSMERR_TP_NOT_SIGNER (CSSM_TP_BASE_TP_ERROR+41)
#define CSSMERR_TP_NOT_TRUSTED (CSSM_TP_BASE_TP_ERROR+42)
#define CSSMERR_TP_NO_DEFAULT_AUTHORITY (CSSM_TP_BASE_TP_ERROR+43)
#define CSSMERR_TP_REJECTED_FORM (CSSM_TP_BASE_TP_ERROR+44)
#define CSSMERR_TP_REQUEST_LOST (CSSM_TP_BASE_TP_ERROR+45)
#define CSSMERR_TP_REQUEST_REJECTED (CSSM_TP_BASE_TP_ERROR+46)
#define CSSMERR_TP_UNSUPPORTED_ADDR_TYPE (CSSM_TP_BASE_TP_ERROR+47)
#define CSSMERR_TP_UNSUPPORTED_SERVICE (CSSM_TP_BASE_TP_ERROR+48)
#define CSSMERR_TP_INVALID_TUPLEGROUP_POINTER (CSSM_TP_BASE_TP_ERROR+49)
#define CSSMERR_TP_INVALID_TUPLEGROUP (CSSM_TP_BASE_TP_ERROR+50)
CSSM_TP_SubmitCredRequest
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)
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() . After the specified time has elapsed, the caller must use the functionCSSM_TP_RetrieveCredResult() , with the reference identifier, to obtain the result of the request.
- 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 correspondingCSSM_TP_RetrieveCredResult() 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() 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_ConfirmCredResult() .
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.
See also the Error Codes and Error Values section earlier in this Chapter.
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
CSSM_TP_RetrieveCredResult()
CSSM_TP_RetrieveCredResult
CSSM_RETURN CSSMAPI CSSM_TP_RetrieveCredResult (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, sint32 *EstimatedTime, CSSM_BOOL *ConfirmationRequired, CSSM_TP_RESULT_SET_PTR *RetrieveOutput)
This function returns the results of aCSSM_TP_SubmitCredRequest() call.The single identifier ReferenceIdentifier denotes the
CSSM_TP_SubmitCredRequest() invocation that initiated the request.It is possible that the results are not ready to be retrieved when this call is made. In that case, an EstimatedTime to complete processing is returned. The caller must attempt to retrieve the results again after the estimated time to completion has elapsed.
This function can fail in total for any one of the following reasons:
- The reference identifier is invalid
- The TP process can not be located
- The TP process encountered a fatal error when attempting to process the request.
When this function completes, the set of return results is ordered corresponding to the order of the originating request.
Some certificate services require the requester to confirm retrieval of the results. ConfirmationRequired indicates whether the caller must confirm completion of
CSSM_TP_RetrieveCredResult() by callingCSSM_TP_ConfirmCredResult() .
- TPHandle (input)
The handle that describes the certification authority module used to perform this function.
- ReferenceIdentifier (input)
A reference identifier that uniquely identifies theCSSM_TP_SubmitCredRequest() call that initiated the certificate service request whose results are returned by this function. The identifier 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() 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_ConfirmCredResult() .
- CallerAuthCredentials (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 a record 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 Credentials 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 TP module can forward information from the CallerAuthCredentials to the authority, as appropriate, but is not required to do so.
- EstimatedTime (output)
The number of seconds estimated before the results of a requested service will be returned to the requester. When the local TP module or the authority process cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN.
- ConfirmationRequired (output)
A boolean value indicating whether the caller must invokeCSSM_TP_ConfirmCredResult() to acknowledge retrieving the results of the service request. CSSM_TRUE indicates the caller must callCSSM_TP_ConfirmCredResult() . CSSM_FALSE indicates that the caller must not callCSSM_TP_ConfirmCredResult() . The value of this output parameter is not applicable until theCSSM_TP_RetrieveCredResult() completes by returning results of the request or terminates in unrecoverable failure.
- RetrieveOutput (output)
A pointer to the results returned by the authority in response to the service requests submitted byCSSM_TP_SubmitCredRequest() . The output results are ordered corresponding to the requests. The structure of the response set is determined by the type of request. The caller and the service provider must retain knowledge of the request type associated with the ReferenceIdentifier.
A CSSM_RETURN value combined with estimated time to indicate one of three results:
Complete Function Function Return RetrieveOutput EstimatedTime Result Value Request results returned to caller CSSM_OK Non-NULL pointer NA Request results not ready, but expected in the future CSSM_OK NULL pointer CSSM_ESTIMATED_TIME_
UNKNOWN or <estimated seconds>Fatal Error, results will never be returned (!CSSM_OK) NA NA For a return value of (!CSSM_OK) the return value represents a specific error code.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_IDENTIFIER_POINTER
CSSMERR_TP_INVALID_IDENTIFIER
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
CSSMERR_TP_REQUEST_LOST
CSSMERR_TP_REQUEST_REJECTED
CSSM_TP_SubmitCredRequest()
CSSM_TP_ConfirmCredResult
CSSM_RETURN CSSMAPI CSSM_TP_ConfirmCredResult (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, const CSSM_TP_CONFIRM_RESPONSE *Responses, const CSSM_TP_AUTHORITY_ID *PreferredAuthority)
This function submits a vector of acknowledgements to a Certificate Authority for a set of requests and corresponding results identified by ReferenceIdentifier. The caller must execute the call sequenceCSSM_TP_SubmitCredRequest() andCSSM_TP_RetrieveCredResult() to submit a set of requests and to retrieve the results of those requests. Some Certificate Authority services accessed through the request and retrieve functions require confirmation. The functionCSSM_TP_RetrieveCredResult() returns a value indicating whether the caller must invokeCSSM_TP_ConfirmCredResult() to successfully complete the service.The Responses vector accepts or rejects each result independently. If the caller rejects a returned result, the action taken by the authority depends on the requested type of service.
The ReferenceIdentifier also identifies the authority process state associated with the function pair
CSSM_TP_SubmitCredRequest() andCSSM_TP_RetrieveCredResult() . The PreferredAuthority information can be used to further identify the authority to receive the acknowledgement. After successful execution of this function, the value of the ReferenceIdentifier is undefined and should not be used in subsequent operations in the current module attach session.This function fails if ReferenceIdentifier is invalid or the Authority process can not be located.
- TPHandle (input)
The handle that describes the certification authority module used to perform this function.
- ReferenceIdentifier (input)
A reference identifier that uniquely identifies execution of the call sequenceCSSM_TP_SubmitCredRequest() andCSSM_TP_RetrieveCredResult() to submit a set of requests and to retrieve the results of those requests.
- CallerAuthCredentials (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 a record 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 Credentials 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 TP module can forward information from the CallerAuthCredentials to the authority, as appropriate, but is not required to do so.
- Responses (input)
An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. The vector contains one acknowledgement per result returned byCSSM_TP_RetrieveCredResult() .
- PreferredAuthority (input/optional)
The identifier which uniquely describes the Authority to receive the acknowledgements. The structure can include:
- An identity certificate for the authority
- The location of the authority
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_IDENTIFIER_POINTER
CSSMERR_TP_INVALID_IDENTIFIER
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
CSSMERR_TP_INVALID_RESPONSE_VECTOR
CSSMERR_TP_INVALID_AUTHORITY
CSSMERR_TP_NO_DEFAULT_AUTHORITY
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE
CSSMERR_TP_INVALID_NETWORK_ADDR
CSSM_TP_SubmitCredRequest()
CSSM_TP_RetrieveCredResult()
CSSM_TP_ReceiveConfirmation()
CSSM_TP_ReceiveConfirmation
CSSM_RETURN CSSMAPI CSSM_TP_ReceiveConfirmation (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, CSSM_TP_CONFIRM_RESPONSE_PTR *Responses, sint32 *ElapsedTime)
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 functionCSSM_TP_ConfirmCredResult() .The ReferenceIdentifier uniquely identifies the service request and corresponding results for which confirmation is expected. This reference 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, indicating 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 represents 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 relative and should increase with consecutive calls using the same ReferenceIdentifier. 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.
- TPHandle (input)
The handle that describes the certification authority module used to perform this function.
- ReferenceIdentifier (input)
A reference identifier that uniquely identifies a set of service requests and the results created in response to those requests.
- Responses (output)
An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. The vector contains one acknowledgement per result created by the certificate authority.
- ElapsedTime (output)
- If the confirmation 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.
A CSSM return value combined with elapsed time to indicate one of three results:
Complete Function Function Return RetrieveOutput EstimatedTime Result Value Confirmation Received CSSM_OK CSSM_ELAPSED_TIME_COMPLETE Confirmation not received, but expected in the future CSSM_OK CSSM_ELAPSED_TIME_UNKNOWN
or <elapsed seconds>Fatal Error, Confirmation is not expected (!CSSM_OK) NA For a return value of (!CSSM_OK) the return value is an error code.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_IDENTIFIER_POINTER
CSSMERR_TP_INVALID_IDENTIFIER
CSSM_TP_ConfirmCredResult()
CSSM_TP_CertReclaimKey
CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimKey (CSSM_TP_HANDLE TPHandle, const CSSM_CERTGROUP *CertGroup, uint32 CertIndex, CSSM_LONG_HANDLE KeyCacheHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry)
This function recovers the private key associated with a certificate and securely stores that key in the specified cryptographic service provider. The key and its associated certificate are among a set of certificates and private keys reclaimed from a certificate authority.The particular private key to be recovered to the local system is identified by its associated certificate. The certificate is identified by its CertIndex position within the CertGroup.
The reclamation process associates the private key with the public key contained in the certificate, and securely stores the private key in the specified cryptographic service provider. The CSP can require that the caller provide access credentials authorizing inserting a new key into the CSP through an UnwrapKey operation. The caller should also provide an initial Access Control List (ACL) entry for the newly inserted key. The ACL entry is used to control future use of the recovered private key. These inputs are provided in CredAndAclEntry.
When all required private keys have been reclaimed, the key cache can be discarded using the function
CSSM_TP_CertReclaimAbort() . The caller must free the CertGroup when it is no longer needed.
- TPHandle (input)
The handle that describes the service provider module used to perform this operation.
- CertGroup (input)
A pointer to a structure containing a reference to a group of certificates and the number of certificates contained in that group. The certificate group contains all certificates that are candidates for reclamation.
- CertIndex (input)
An index value that identifies the certificate whose associated private key is to be recovered and stored in the local CSP. This index value I references the I-th certificate in CertGroup.
- KeyCacheHandle (input)
A reference handle that uniquely identifies the cache of protected private keys associated with the reclaimed certificates contained in CertGroup. The structure of the cache is opaque to the caller.
- CSPHandle (input)
The handle that describes the CSP module where the private key is to be stored. Optionally, the CA service provider can use this CSP to perform additional cryptographic operations or may use another default CSP for that purpose.
- CredAndAclEntry (input/optional)
A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_INDEX
CSSMERR_TP_INVALID_KEYCACHE_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_AUTHENTICATION_FAILED
CSSMERR_TP_INSUFFICIENT_CREDENTIALS
CSSM_TP_RetrieveCredResult()
CSSM_TP_Cert_ReclaimAbort()
CSSM_TP_CertReclaimAbort
CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimAbort (CSSM_TP_HANDLE TPHandle, CSSM_LONG_HANDLE KeyCacheHandle)
This function terminates the iterative process of reclaiming certificates and recovering their associated private keys from a protected key cache. This function must be called even if all private keys are recovered from the cache. This function destroys all intermediate state and secret information used during the reclamation process. At completion of this function, the cache handle is invalid.
- TPHandle (input)
The handle that describes the service provider module used to perform this function.
- KeyCacheHandle (input)
An opaque handle that identifies the cache of protected private keys reclaimed from a certificate authority for potentially recovery on the local system.
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.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_TP_INVALID_KEYCACHE_HANDLE
CSSM_TP_CertReclaimKey()
CSSM_TP_FormRequest
CSSM_RETURN CSSMAPI CSSM_TP_FormRequest (CSSM_TP_HANDLE TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority, CSSM_TP_FORM_TYPE FormType, CSSM_DATA_PTR BlankForm)
This function returns a blank form of type FormType from an Authority. If the PreferredAuthority list is NULL, the CA module can use a default authority name and location based on FormType. The CA module must incorporate knowledge of the interface protocol for communicating with the authority.
- TPHandle (input)
The handle that describes the certification authority module used to perform this function.
- PreferredAuthority (input/optional)
A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the Authority process, or a network address directly or indirectly identifying the location of the authority. If the input is NULL, the module can assume a default authority location. If a default authority can not be assumed, the request can not be initiated and the operation fails.
- FormType (input)
- ,br Indicates the type of form being requested.
- BlankForm (output)
A CSSM_DATA structure containing the requested form. The caller must have knowledge of the structure of the form based on FormType.
CSSMERR_TP_INVALID_AUTHORITY
CSSMERR_TP_NO_DEFAULT_AUTHORITY
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE
CSSMERR_TP_INVALID_NETWORK_ADDR
CSSMERR_TP_INVALID_FORM_TYPE
CSSM_TP_FormSubmit()
CSSM_TP_FormSubmit
CSSM_RETURN CSSMAPI CSSM_TP_FormSubmit (CSSM_TP_HANDLE TPHandle, CSSM_TP_FORM_TYPE FormType, const CSSM_DATA *Form, const CSSM_TP_AUTHORITY_ID *ClearanceAuthority, const CSSM_TP_AUTHORITY_ID *RepresentedAuthority, CSSM_ACCESS_CREDENTIALS_PTR Credentials)
The completed Form is submitted to a ClearanceAuthority, who is acting on behalf of a RepresentedAuthority. Typically the submitted form is requesting an authorization credential required as input to future service requests to the RepresentedAuthority.If the form is honored by the ClearanceAuthority, then a set of one or more Credentials is returned to the requester. These credential can be used as the input credential in future service requests submitted to the RepresentedAuthority.
- TPHandle (input)
A handle for the service provider module that will perform the operation.
- FormType (input)
Indicates the type of form being submitted.
- Form (input)
A pointer to the CSSM_DATA structure containing the completed form to be submitted to the ClearanceAuthority.
- ClearanceAuthority (input/optional)
A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the clearance authority process, or a network address directly or indirectly identifying the location of the authority. If the input is NULL, the service provider module can assume a default authority based on the FormType and contents of Form. If a default authority can not be assumed, the request can not be initiated and the operation fails.
- RepresentedAuthority (input/optional)
A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the authority represented by the ClearanceAuthority. If the input is NULL, the service provider module can assume a default authority based on the FormType and contents of Form. If a default authority can not be assumed, the request can not be initiated and the operation fails.
- Credentials (output/optional)
A pointer to a structure containing one or more credentials issued in response to the contents of the Form. If the output is NULL, either no credentials were returned or an error occurred.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_FORM_TYPE
CSSMERR_TP_INVALID_AUTHORITY
CSSMERR_TP_NO_DEFAULT_AUTHORITY
CSSMERR_TP_UNSUPPORTED_ADDR_TYPE
CSSMERR_TP_INVALID_NETWORK_ADDR
CSSMERR_TP_AUTHENTICATION_FAILED
CSSMERR_TP_INSUFFICIENT_CREDENTIALS
CSSMERR_TP_REJECTED_FORM
CSSM_TP_FormRequest()
CSSM_TP_CertGroupVerify
CSSM_RETURN CSSMAPI CSSM_TP_CertGroupVerify (CSSM_TP_HANDLE TPHandle, 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)
This functions verifies that the subject certificate is authorized to perform an action on some data. The action and the target data are specified in the verifycontext structure along with many other input and output parameters for this operation. Anchor certificates are also specified. These are implicitly trusted certificates including root certificates, cross-certified certificates, and locally-defined sources of trust. These certificates form the basis to determine trust in the subject certificate.The verifycontext includes a set of policy identifiers. Each policy identifier specifies an additional set of conditions that must be satisfied by the subject certificate in order to meet the trust criteria. A stopping condition for evaluating that set of conditions can also be specified.
Typically certificate verification involves the verification of multiple certificates. These certificates can be contained in the provided certificate group or supporting certificates can be stored in the data stores specified in the 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 certificate revocation lists used in the verification process. The caller can select to be notified incrementally as each certificate is verified. The CallbackWithVerifiedCert parameter (in the verifycontext) can specify a caller function to be invoked at the end of each certificate verification, returning the verified certificate for use by the caller.
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, complete certificates from the verification 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.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
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.
- CSPHandle (input/optional)
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 module is specified, the TP module uses an assumed CSP module.
- CertGroupToBeVerified (input)
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 verification process is specific to the trust domain.
- VerifyContext (input/optional)
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.
- VerifyContextResult (output/optional)
A pointer to a structure containing information generated during the verification process. The information can include:
- Evidence
- (output/optional)
- NumberOfEvidences
- (output/optional)
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSM_TP_CertCreateTemplate
CSSM_RETURN CSSMAPI CSSM_TP_CertCreateTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CertFields, CSSM_DATA_PTR CertTemplate)
This function creates an unsigned, memory-resident certificate template. Fields in the certificate are initialized based on the descriptive data specified by the OID/value input pairs in CertFields and the local domain policy of the TP. The TP module may specify a set of fields that must be or cannot be set using this operation. The CertTemplate output is an unsigned certificate template in the format supported by the TP.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input)
The handle that describes the certificate library module used to perform this function.
- NumberOfFields (input)
The number of certificate field values specified in the CertFields.
- CertFields (input)
A pointer to an array of OID/value pairs that identifies the field values to initialize a new certificate.
- CertTemplate (output)
A pointer to a CSSM_DATA structure that will contain the unsigned certificate template as a result of this function.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_FIELD_POINTER
CSSMERR_TP_UNKNOWN_TAG
CSSMERR_TP_INVALID_NUMBER_OF_FIELDS
CSSM_TP_CertGetAllTemplateFields()
CSSM_TP_CertSign()
CSSM_TP_CertGetAllTemplateFields
CSSM_RETURN CSSMAPI CSSM_TP_CertGetAllTemplateFields (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_DATA *CertTemplate, uint32 *NumberOfFields, CSSM_FIELD_PTR *CertFields)
This function extracts and returns a copy of the values stored in the encoded CertTemplate. The memory for the CertFields output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory by callingCSSM_CL_FreeFields() .
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input)
The handle that describes the certificate library module used to perform this function.
- CertTemplate (input)
A pointer to the CSSM_DATA structure containing the packed, encoded certificate template.
- NumberOfFields (output)
The length of the output array of fields.
- CertFields (output)
A pointer to an array of CSSM_FIELD structures which contains the OIDs and values of the fields of the input certificate template.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_FIELD_POINTER
CSSMERR_TP_UNKNOWN_FORMAT
CSSM_TP_CertCreateTemplate()
CSSM_TP_CertSign()
CSSM_TP_CertSign
CSSM_RETURN CSSMAPI CSSM_TP_CertSign (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertTemplateToBeSigned, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, CSSM_DATA_PTR SignedCert)
The TP module decides whether the signer certificate is trusted to sign the CertTemplateToBeSigned. The signer certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, this operation signs the entire certificate. The caller must provide a credential that permits the caller to use the private key for this signing operation. The credential can be provided in the cryptographic context CCHandle. If CCHandle is NULL, the credentials in the SignerVerifyContext specify the credential value.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module used to perform this function.
- CCHandle (input/optional)
The handle that describes the cryptographic context for signing the certificate. This context also identifies the cryptographic service provider to be used to perform the signing operation. If this handle is not provided by the caller, the trust policy module can assume a default signing algorithm and a default CSP. If the trust policy module does not assume defaults or the default CSP is not available on the local system, an error occurs.
- CertTemplateToBeSigned (input)
A pointer to a structure containing a certificte template to be signed. The CRL type and encoded are included in this structure.
- SignerCertGroup (input)
A group of one or more certificates that partially or fully represent the signer for this operation. The first certificate in the group is the target certificate representing the signer. Use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain.
- SignerVerifyContext (input/optional)
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. 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.
- SignerVerifyResult (output/optional)
A pointer to a structure containing information generated during the verification process. The information can include:
- Evidence
- (output/optional)
- NumberOfEvidences
- (output/optional)
- SignedCert (output)
A pointer to the CSSM_DATA structure containing the signed certificate. The SignedCert->Data is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CONTEXT_HANDLE
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_UNKNOWN_FORMAT
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSMERR_TP_CERTIFICATE_CANT_OPERATE
CSSM_TP_CertCreateTemplate()
CSSM_TP_CrlSign()
CSSM_TP_CrlVerify
CSSM_RETURN CSSMAPI CSSM_TP_CrlVerify (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_ENCODED_CRL *CrlToBeVerified, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *VerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult)
This function verifies the integrity of the certificate revocation list and determines whether it is trusted. The conditions for trust are part of the trust policy module. It can include conditions such as validity of the signer's certificate, verification of the signature on the CRL, the identity of the signer, the identity of the sender of the CRL, date the CRL was issued, the effective dates on the CRL, and so on.The caller can specify additional points of trust represented by anchor certificates in the VerifyContext. The trust policy module can use these additional points of trust in the verification process.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module that can be used to manipulate the certificates to be verified. If no certificate library module is specified, the TP module uses an assumed CL module, if required.
- CSPHandle (input/optional)
The handle referencing a Cryptographic Service Provider to be used to verify signatures on the signer's certificate and on the CRL. The TP module is responsible for creating the cryptographic context structure required to perform the verification operation. If no CSP is specified, the TP module uses an assumed CSP to perform the operations.
- CrlToBeVerified (input)
A pointer to the CSSM_DATA structure containing a signed certificate revocation list to be verified.
- SignerCertGroup (input)
A pointer to the CSSM_CERTGROUP structure containing one or more related certificates used to sign the CRL. The caller can specify additional points of trust represented by anchor certificates in the VerifyContext. The trust policy module can use these additional points of trust in the verification process.
- VerifyContext (input/optional)
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. 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
- RevokerVerifyResult (output/optional)
A pointer to a structure containing information generation during the verification process. The information can include:
- Evidence
- (output/optional)
- NumberOfEvidences
- (output/optional)
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_INVALID_CRL_TYPE
CSSMERR_TP_INVALID_CRL_ENCODING
CSSMERR_TP_INVALID_CRL_POINTER
CSSMERR_TP_INVALID_CRL
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSMERR_TP_CERTIFICATE_CANT_OPERATE
CSSM_CL_CrlVerify()
CSSM_TP_CrlCreateTemplate
CSSM_RETURN CSSMAPI CSSM_TP_CrlCreateTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlFields, CSSM_DATA_PTR NewCrlTemplate)
This function creates an unsigned, memory-resident CRL template. Fields in the CRL are initialized based on the descriptive data specified by the OID/value input pairs in CrlFields and the local domain policy of the TP. The specified OID/value pairs can initialize all or a subset of the general attribute fields in the new CRL, though the module developer may specify a set of fields that must be or cannot be set using this operation. The NewCrlTemplate output is an unsigned CRL template in the format supported by the TP.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module used to perform this function.
- NumberOfFields (input)
The number of OID/value pairs specified in the CrlFields input parameter.
- CrlFields (input)
Any array of field OID/value pairs containing the values to initialize the CRL attribute fields
- NewCrl (output)
A pointer to the CSSM_DATA structure containing the new CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_FIELD_POINTER
CSSMERR_TP_UNKNOWN_TAG
CSSMERR_TP_INVALID_NUMBER_OF_FIELDS
TP_CrlSignWithKey()
TP_CrlSignWithCert()
CSSM_TP_CertRevoke
CSSM_RETURN CSSMAPI CSSM_TP_CertRevoke (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *OldCrlTemplate, const CSSM_CERTGROUP *CertGroupToBeRevoked, const CSSM_CERTGROUP *RevokerCertGroup, const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, CSSM_TP_CERTCHANGE_REASON Reason, CSSM_DATA_PTR NewCrlTemplate)
The TP module determines whether the revoking certificate group can revoke the subject certificate group. The revoker certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, the TP revokes the subject certificate by adding it to the certificate revocation list.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module used to perform this function.
- CSPHandle (input/optional)
The handle that describes the add-in cryptographic service provider module used to perform this function.
- OldCrlTemplate (input/optional)
A pointer to the CSSM_DATA structure containing an existing certificate revocation list. If this input is NULL, a new list is created or the operation fails.
- CertGroupToBeRevoked (input)
A group of one or more certificates that partially or fully represent the certificate to be revoked by this operation. The first certificate in the group is the target certificate. The use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain.
- RevokerCertGroup (input)
A group of one or more certificates that partially or fully represent the revoking entity for this operation. The first certificate in the group is the target certificate representing the revoker. The use of subsequent certificates is specific to the trust domain.
- RevokerVerifyContext (input)
A structure containing policy elements useful in verifying certificates and their use with respect to a security policy. Optional elements in the verify context left unspecified will cause the internal default values to be used. Default values are specified in the TP module vendor release documents. This context is used to verify the revoker certificate group.
- RevokerVerifyResult (output/optional)
A pointer to a structure containing information generated during the verification process. The information can include:
- Evidence
- (output/optional)
- NumberOfEvidences
- (output/optional)
- Reason (input/optional)
The reason for revoking the subject certificate.
- NewCrlTemplate (outputl)
A pointer to the CSSM_DATA structure containing the updated certificate revocation list. If the pointer is NULL, an error has occurred.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_INVALID_CRL_POINTER
CSSMERR_TP_INVALID_CRL
CSSMERR_TP_UNKNOWN_FORMAT
CSSMERR_TP_CRL_ALREADY_SIGNED
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSMERR_TP_CERTIFICATE_CANT_OPERATE
CSSMERR_TP_INVALID_REASON
CSSM_CL_CrlAddCert()
CSSM_TP_CertRemoveFromCrlTemplate
CSSM_RETURN CSSMAPI CSSM_TP_CertRemoveFromCrlTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *OldCrlTemplate, const CSSM_CERTGROUP *CertGroupToBeRemoved, const CSSM_CERTGROUP *RevokerCertGroup, const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, CSSM_DATA_PTR NewCrlTemplate)
The TP module determines whether the revoking certificate group can remove the subject certificate group from the CRL template. The revoker certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, the TP removes the certificates from the CRL template.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module used to perform this function.
- CSPHandle (input/optional)
The handle that describes the add-in cryptographic service provider module used to perform this function.
- OldCrlTemplate (input/optional)
A pointer to the CSSM_DATA structure containing an existing certificate revocation list. If this input is NULL, a new list is created or the operation fails.
- CertGroupToBeRemoved (input)
A group of one or more certificates to be removed from the the CRL template.
- RevokerCertGroup (input)
A group of one or more certificates that partially or fully represent the revoking entity for this operation. The first certificate in the group is the target certificate representing the revoker. The use of subsequent certificates is specific to the trust domain.
- RevokerVerifyContext (input)
A structure containing policy elements useful in verifying certificates and their use with respect to a security policy. Optional elements in the verify context left unspecified will cause the internal default values to be used. Default values are specified in the TP module vendor release documents. This context is used to verify the revoker certificate group.
- RevokerVerifyResult (output/optional)
A pointer to a structure containing information generated during the verification process. The information can include:
- Evidence
- (output/optional)
- NumberOfEvidences
- (output/optional)
- NewCrlTemplate (output)
A pointer to the CSSM_DATA structure containing the updated certificate revocation list. If the pointer is NULL, an error has occurred.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_INVALID_CRL_POINTER
CSSMERR_TP_INVALID_CRL
CSSMERR_TP_UNKNOWN_FORMAT
CSSMERR_TP_CRL_ALREADY_SIGNED
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSMERR_TP_CERTIFICATE_CANT_OPERATE
CSSM_CL_CrlAddCert()
CSSM_TP_CrlSign
CSSM_RETURN CSSMAPI CSSM_TP_CrlSign (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_ENCODED_CRL *CrlToBeSigned, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, CSSM_DATA_PTR SignedCrl)
The TP module decides whether the signer certificate is trusted to sign the entire certificate revocation list. The signer certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, this operation signs the entire certificate revocation list. Individual records within the certificate revocation list were signed when they were added to the list. The caller must provide a credential that permits the caller to use the private key for this signing operation. The credential can be provided in the cryptographic context CCHandle. If CCHandle is NULL, the credentials in the SignerVerifyContext specify the credential value.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module that can be used to manipulate the certificates to be verified. If no certificate library module is specified, the TP module uses an assumed CL module, if required.
- CCHandle (input/optional)
The handle that describes the cryptographic context for signing the CRL. This context also identifies the cryptographic service provider to be used to perform the signing operation. If this handle is not provided by the caller, the trust policy module can assume a default signing algorithm and a default CSP. If the trust policy module does not assume defaults or the default CSP is not available on the local system an error occurs.
- CrlToBeSigned (input)
A pointer to the CSSM_DATA structure containing a certificate revocation list to be signed.
- SignerCertGroup (input)
A pointer to the CSSM_CERTGROUP structure containing one or more related certificates used to sign the CRL. The first certificate in the group is the certificate representing the CRL signer. The other certificates in the group should be related to the CRL signer's certificate based on the trust domain.
- SignerVerifyContext (input/optional)
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. 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.
- SignerVerifyResult (output/optional)
A pointer to a structure containing information generation during the verification process. The information can include:
- Evidence
- (output/optional)
- NumberOfEvidences
- (output/optional)
- SignedCrl (output)
A pointer to the CSSM_DATA structure containing the signed certificate revocation list. The SignedCrl->Data is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CONTEXT_HANDLE
CSSMERR_TP_INVALID_CRL_TYPE
CSSMERR_TP_INVALID_CRL_ENCODING
CSSMERR_TP_INVALID_CRL_POINTER
CSSMERR_TP_INVALID_CRL
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSMERR_TP_CERTIFICATE_CANT_OPERATE
CSSM_CL_CrlSign()
CSSM_TP_ApplyCrlToDb
CSSM_RETURN CSSMAPI CSSM_TP_ApplyCrlToDb (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_ENCODED_CRL *CrlToBeApplied, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *ApplyCrlVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR ApplyCrlVerifyResult)
This function updates persistent storage to reflect entries in the certificate revocation list. The TP module determines whether the memory-resident CRL is trusted, and if it should be applied to one or more of the persistent databases. Side effects of this function can include saving a persistent copy of the CRL in a data store, or removing certificate records from a data store.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
The handle that describes the add-in certificate library module that can be used to manipulate the CRL as it is applied to the data store and to manipulate the certificates effected by the CRL, if required. If no certificate library module is specified, the TP module uses an assumed CL module, if required.
- CSPHandle (input/optional)
The handle referencing a Cryptographic Service Provider to be used to verify signatures on the CRL determining whether to trust the CRL and apply it to the data store. The TP module is responsible for creating the cryptographic context structures required to perform the verification operation. If no CSP is specified, the TP module uses an assumed CSP to perform these operations.
- CrlToBeApplied (input)
A pointer to a structure containing the encoded certificate revocation list to be applied to the data store. The CRL type and encoding are included in this structure.
- SignerCertGroup (input)
A pointer to the CSSM_CERTGROUP structure containing one or more related certificates used to sign the CRL. The first certificate in the group is the certificate representing the CRL signer. The other certificates in the group should be related to the CRL signer's certificate based on the trust domain.
- ApplyCrlVerifyContext (input/optional)
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. 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.
- ApplyCrlVerifyResult (output/optional)
A pointer to a structure containing information generated during the verification process. The information can include:
Evidence (output/optional) NumberOfEvidences (output/optional)
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_INVALID_CRL_TYPE
CSSMERR_TP_INVALID_CRL_ENCODING
CSSMERR_TP_INVALID_CRL_POINTER
CSSMERR_TP_INVALID_CRL
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_INVALID_ACTION
CSSMERR_TP_INVALID_ACTION_DATA
CSSMERR_TP_VERIFY_ACTION_FAILED
CSSMERR_TP_INVALID_CRLGROUP_POINTER
CSSMERR_TP_INVALID_CRLGROUP
CSSMERR_TP_INVALID_CRL_AUTHORITY
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
CSSMERR_TP_CERTIFICATE_CANT_OPERATE
CSSM_CL_CrlGetFirstItem()
CSSM_CL_CrlGetNextItem()
CSSM_DL_CertRevoke()
CSSM_TP_CertGroupConstruct
CSSM_RETURN CSSMAPI CSSM_TP_CertGroupConstruct (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DL_DB_LIST *DBList, const void *ConstructParams, const CSSM_CERTGROUP *CertGroupFrag, CSSM_CERTGROUP_PTR *CertGroup)
This function builds a collection of certificates that together make up a meaningful credential for a given trust domain. For example, in a hierarchical trust domain, a certificate group is a chain of certificates from an end entity to a top level certification authority. The constructed certificate group format (such as ordering) is implementation specific. However, the subject or end-entity is always the first certificate in the group.A partially constructed certificate group is specified in CertGroupFrag. The first certificate is interpreted to be the subject or end-entity certificate. Subsequent certificates in the CertGroupFrag structure may be used during the construction of a certificate group in conjunction with certificates found in the data stores specified in DBList. The trust policy defines the certificates that will be included in the resulting set.
The output set is a sequence of certificates ordered by the relationship among them. The result set can be augmented by adding semantically-related certificates obtained by searching the certificate data stores specified in DBList. The data stores are searched in order of appearance in DBList. If the TP supports a hierarchical model of certificates, the function output is an uninterrupted, ordered chain of certificates based on the first certificate as the leaf of the certificate chain. If the certificate is multiply-signed, then the ordered chain will follow the first signing certificate. The function should also detect cross-certificate pairs and should include both certificates without duplicating either certificate.
Extraneous certificates in the CertGroupFrag fragment or contained in the DBList data stores are ignored. The certificate group returned by this function can be used as input to the function
TP_CertGroupVerify() .The constructed certificate group can be consistent locally or globally. Consistency can be limited to the local system if locally-defined points of trust are inserted into the group.
- TPHandle (input)
The handle to the trust policy module to perform this operation.
- CLHandle (input/optional)
The handle to the certificate library module that can be used to manipulate and parse values in stored in the certgroup certificates. If no certificate library module is specified, the TP module uses an assumed CL module.
- CSPHandle (input./optional)
A handle specifying the Cryptographic Service Provider to be used to verify certificates as the certificate group is constructed. If the a CSP handle is not specified, the trust policy module can assume a default CSP. If the module cannot assume a default, or the default CSP is not available on the local system, an error occurs.
- DBList (input)
A list of handle pairs specifying a data storage library module and a data store managed by that module. These data stores should contain const void *ConstructParams, certificates (and possibly other security objects). The data stores should be searched to complete construction of a semantically-related certificate group.
- ConstructParams (input/optional)
A pointer to data that can be used by the add-in trust policy module in constructing the CertGroup.Thesemanticsofthisparameteraredefinedby the trust policy and the credential model supported by that policy. The input parameter can consist of a set of values, each guiding some aspect of the construction process. Parameter values can:
- Limit the certificates that are added to the constructed set.
- Identify other sources of certificates for inclusion in the constructed set.
- CertGroupFrag (input)
A list of certificates that form a possibly incomplete set of certificates. The first certificate in the group represents the target certificate for which a group of semantically related certificates will be assembled
- CertGroup (output)
A pointer to a complete certificate group based on the original subset of certificates and the certificate data stores. The CSSM_CERTGROUP and its sub-structure is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CSP_HANDLE
CSSMERR_TP_INVALID_DL_HANDLE
CSSMERR_TP_INVALID_DB_HANDLE
CSSMERR_TP_INVALID_DB_LIST_POINTER
CSSMERR_TP_INVALID_DB_LIST
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_CERTGROUP_INCOMPLETE
CSSM_TP_CertGroupPrune()
CSSM_TP_CertGroupVerify()
CSSM_TP_CertGroupPrune
CSSM_RETURN CSSMAPI CSSM_TP_CertGroupPrune (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_DL_DB_LIST *DBList, const CSSM_CERTGROUP *OrderedCertGroup, CSSM_CERTGROUP_PTR *PrunedCertGroup)
This function removes certificates from a certificate group. The prune operation can remove those certificates that have been signed by any local certificate authority, as it is possible that these certificates will not be meaningful on other systems.This operation can also remove additional certificates that can be added to the certificate group again using the CertGroupConstruct operation. The pruned certificate group should be suitable for transmission to external hosts, which can in turn reconstruct and verify the certificate group.
The DBList parameter specifies a set of data stores containing certificates that should be pruned from the group.
- TPHandle (input)
The handle to the trust policy module to perform this operation.
- CLHandle (input/optional)
The handle to the certificate library module that can be used to manipulate and parse the certgroup certificates and the certificates in the specified data stores. If no certificate library module is specified, the TP module uses an assumed CL module.
- DBList (input)
A list of handle pairs specifying a data storage library module and a data store managed by that module. These data stores must contain certificates (and possibly other security objects). The data stores are searched for anchor certificates restricted to have local scope. These certificates are candidates for removal from the subject certificate group.
- OrderedCertGroup (input)
The initial, complete set of certificates from which certificates will be selectively removed.
- PrunedCertGroup (output)
A pointer to a certificate group containing those certificates which are verifiable credentials outside of the local system. The CSSM_CERTGROUP and its sub-structure is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_DL_HANDLE
CSSMERR_TP_INVALID_DB_HANDLE
CSSMERR_TP_INVALID_DB_LIST_POINTER
CSSMERR_TP_INVALID_DB_LIST
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSMERR_TP_INVALID_CERTIFICATE
CSSMERR_TP_CERTGROUP_INCOMPLETE
CSSM_TP_CertGroupConstruct()
CSSM_TP_CertGroupVerify()
CSSM_TP_CertGroupToTupleGroup
CSSM_RETURN CSSMAPI CSSM_TP_CertGroupToTupleGroup (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_CERTGROUP *CertGroup, CSSM_TUPLEGROUP_PTR *TupleGroup)
This function creates a set of authorization tuples based on a set of input certificates. The certificates must be of the type managed by the Trust Policy module. The trust policy module may require that the input certificates be successfully verified before being translated to tuples. It is assumed that the certificates carry authorizations. The trust policy service provider interprets the certificate authorization fields and generates one or more tuples corresponding to those authorizations. The certificates of the type managed by the Trust Policy module. The resulting tuples can be input to an authorization evaluation function, such asCSSM_AC_AuthCompute() , which determines whether a particular action is authorized under a basic set of authorization assumptions.
- TPHandle (input)
The handle that describes the trust policy service module used to perform this function.
- CLHandle (input/optional)
The handle that describes the certificate library module that can be used to scan the certificate fields for values. If no certificate library module is specified, the TP module uses an assumed CL module.
- CertGroup (input)
A group of certificates in the native certificate format supported by the Trust Policy module. The certificates carry authorizations for one or more certificate subjects.
- TupleGroup (output)
A pointer to a structure containing references to one or more tuples resulting from the translation process. Storage for structure and the tuples is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CERTGROUP_POINTER
CSSMERR_TP_INVALID_CERTGROUP
CSSM_TP_TupleGroupToCertGroup() CSSM_AC_AuthCompute()
CSSM_TP_TupleGroupToCertGroup
CSSM_RETURN CSSMAPI CSSM_TP_TupleGroupToCertGroup (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_TUPLEGROUP *TupleGroup, CSSM_CERTGROUP_PTR *CertTemplates)
This function creates a set of certificate templates based on a set of input tuples. The tuples describe a set of authorizations for one or more subjects. The trust policy service provider maps these authorizations to appropriate template values for one or more certificates of the type managed by the Trust Policy module. The resulting certificate templates can be input to a certificate creation function, such asCSSM_CL_CertSign() . The signed certificates created by these functions should carry the authorizations described in the input tuples.
- TPHandle (input)
The handle that describes the trust policy service module used to perform this function.
- CLHandle (input/optional)
The handle that describes the certificate library module that can be used to assist in the creation of field values. If no certificate library module is specified, the TP module uses an assumed CL module, if required.
- TupleGroup (input)
A pointer to a group of CSSM_TUPLE describing authorizations for one or more subjects.
- CertTemplates (output)
A pointer to a structure containing references to one or more certificate templates resulting from the translation process. Storage for the structure and certificate templates is allocated by the service provider and must be deallocated by the application.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_TUPLEGROUP_POINTER
CSSMERR_TP_INVALID_TUPLEGROUP
CSSMERR_TP_INVALID_TUPLE
CSSM_TP_CertGroupToTupleGroup()
CSSM_AC_AuthCompute()
CSSM_TP_PassThrough
CSSM_RETURN CSSMAPI CSSM_TP_PassThrough (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DL_DB_LIST *DBList, uint32 PassThroughId, const void *InputParams, void **OutputParams)
This function allows applications to call trust policy module-specific operations that have been exported. Such operations may include queries or services specific to the domain represented by the TP module.
- TPHandle (input)
The handle that describes the add-in trust policy module used to perform this function.
- CLHandle (input/optional)
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.
- CCHandle (input/optional)
The handle that describes the context of the cryptographic operation. If the module-specific operation does not perform any cryptographic operations, a cryptographic context is not required
- DBList (input/optional)
A list of handle pairs specifying a data storage library module and a data store managed by that module. These data stores can contain certificates that might be effected by the CRL, they may contain CRLs, or both. If no DL and DB handle pairs are specified, the TP module can use an assumed DL module and an assumed data store for this operation.
- PassThroughId (input)
An identifier assigned by the TP module to indicate the exported function to perform.
- InputParams (input/optional)
A pointer to a module, implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested TP module.
- OutputParams (output/optional)
A pointer to a module, implementation-specific structure containing the output data. The service provider allocates the memory for sub-structures. The application must free the memory for the sub-structures.
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.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_TP_INVALID_CL_HANDLE
CSSMERR_TP_INVALID_CONTEXT_HANDLE
CSSMERR_TP_INVALID_DL_HANDLE
CSSMERR_TP_INVALID_DB_HANDLE
CSSMERR_TP_INVALID_DB_LIST_POINTER
CSSMERR_TP_INVALID_DB_LIST
CSSMERR_TP_INVALID_PASSTHROUGH_ID
Contents | Next section | Index |