RSA BSAFE Cert-C API Reference

certpath.h File Reference

This file defines the certificate-path data structures and API.

#include "basetype.h"
#include "certext.h"

Go to the source code of this file.

Data Structures
struct	CERT_PATH_CTX
	Stores certificate path-processing information. More...
struct	CERT_REVOCATION
	Stores information about a certificate's status. More...
struct	CRL_EVIDENCE
	One type of revocation evidence. More...
struct	OCSP_EVIDENCE
	Contains information returned in an OCSP response. More...
struct	OCSP_REVOCATION_INFO
	Contains additional revocation information, the reason and time the certificate, in the CRL entry, was revoked. More...
Functions
int	C_BuildCertPath (CERTC_CTX ctx, CERT_PATH_CTX *pathCtx, POINTER startObject, LIST_OBJ certPath, LIST_OBJ crlList, LIST_OBJ crlCerts, LIST_OBJ policyInfoList)
	Constructs a path from startObject to one of the trusted certificates in the certificate-path processing context. More...
int	C_GetNextCertInPath (CERTC_CTX ctx, CERT_PATH_CTX *pathCtx, POINTER startObject, LIST_OBJ certList)
	Returns a set of candidate certificates whose public keys can be used to verify the start object's signature. More...
int	C_ValidateCert (CERTC_CTX ctx, CERT_PATH_CTX *pathCtx, CERT_OBJ cert, B_KEY_OBJ validationKey)
	Verifies those aspects of the certificate-path processing policy that can be determined from the information available in the specified certificate, or other function parameters, without referring to information contained in other certificates in the certificate path. More...
int	C_CheckCertRevocation (CERTC_CTX ctx, CERT_PATH_CTX *pathCtx, CERT_OBJ cert, CERT_REVOCATION *revocation)
	Determines the revocation status of the specified certificate. More...
void	C_DestroyCRLEvidence (CRL_EVIDENCE **crlEvidence)
	De-allocates memory for the CRL_EVIDENCE structure and its components, and sets the address to NULL. More...
void	C_DestroyOCSPEvidence (OCSP_EVIDENCE **ocspEvidence)
	De-allocates memory for the OCSP_EVIDENCE structure and its components, and sets the address to (OCSP_EVIDENCE*)0. More...

---

Function Documentation

int C_BuildCertPath (  CERTC_CTX    ctx, CERT_PATH_CTX *    pathCtx, POINTER    startObject, LIST_OBJ    certPath, LIST_OBJ    crlList, LIST_OBJ    crlCerts, LIST_OBJ    policyInfoList )  ;

Constructs a path from startObject to one of the trusted certificates in the certificate-path processing context. This function can be used for path validation because a valid path must exist for this function to return successfully. To validate a certificate path, pass NULL_PTR values for the certPath, crlList, crlCerts, and policyInfoList parameters. This function appends items to the LIST_OBJ parameters that hold paths, CRLs, additional certificates, and policies. Any existing items in them are retained. Note: If the path algorithm, specified in pathCtx is PA_PKIX, and the base certificate has an authorityKeyId extension and if a subject key is not present in the candidate certificates in the path, an E_NOT_VALIDATED error is returned with the reason code MISSING_SUB_KEY. For more information on reason codes that are returned with the PA_PKIX path algorithm, see the pkixpath.h header file. Parameters: ctx This input parameter contains the Cert-C context handle. pathCtx This input parameter is the path-processing context. It ensures that the constructed certificate path is valid. The pathCtx.pathOptions field can be used to request the appropriate level of checking during path construction. startObject This input parameter can be either a CERT_OBJ or a CRL_OBJ object. If the startObject is a certificate, then the resulting path includes the starting object as the first certificate in the path. If the startObject is a CRL, then the first certificate in the path is the CRL issuer's certificate. certPath This is both an input and an output parameter; it is a certificate-path list. This parameter is optional, and can be set to NULL_PTR if not used. On output, certPath contains a sequence of certificates extending from the starting object to one of the trusted certificates identified in the certificate-path context. The trusted certificate selected is included as the last certificate in the path. crlList This is both an input and an output parameter; it is a CRL list. This parameter is optional, and can be set to NULL_PTR if not used. On output, the list contains any CRLs that were used to verify the resulting certificate path. Note that some certificate-path processing service providers may not use or return CRLs. crlCerts This is both an input and an output parameter; it is a list of CRL certificates. This parameter is optional, and can be set to NULL_PTR if not used. On output, the list contains any additional certificates, not included in certPath, that were used to validate the CRLs returned in crlList. If the crlList parameter is set to NULL_PTR, crlCerts is ignored. The certificates returned in crlCerts are the union of certificate paths extending from the returned CRLs to the trusted certificates in the certificate-path context, minus certificates returned in the certPath parameter. policyInfoList This is both an input and an output parameter; it is a policy information list. This parameter is optional and can be set to NULL_PTR if not used. On output, the policy information list contains an entry for each policy under which the certificate was issued. Each entry in the list is of type POLICY_INFO. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_CheckCertRevocation (  CERTC_CTX    ctx, CERT_PATH_CTX *    pathCtx, CERT_OBJ    cert, CERT_REVOCATION *    revocation )  ;

Determines the revocation status of the specified certificate. It returns the certificate's revocation status and related information in a CERT_REVOCATION data structure. This function uses either the CRL or the OCSP revocation-status protocol, depending on the Certificate Revocation Status service provider that was registered when the Cert-C context was initialized. When there are multiple providers, that is, a CRL and an OCSP provider, this API calls each provider and stops as soon as a definite CERT_REVOKED or a CERT_NOT_REVOKED is returned. This behavior is different from other APIs that support multiple providers. For example, the database APIs call every provider in order, even if one of the providers returns a certificate. Parameters: ctx This input parameter contains the Cert-C context handle. pathCtx This input parameter points to the certificate-path processing context that is used to determine the status-checking mechanism for this certificate. The service provider uses the pathOptions, trustedCerts, and validationTime fields of the CERT_PATH_CTX structure. cert This input parameter contains the certificate to be checked. If you are using the OCSP revocation-status protocol, and you did not specify a trusted signer for OCSP responses when you registered the service provider, the certificate must have an Authority Information Access extension that contains the URL of a trusted OCSP responder. revocation This output parameter points to a CERT_REVOCATION structure that contains revocation status and information for the certificate in cert. The caller should pass in a pointer to an allocated CERT_REVOCATION structure that is initialized to 0 (zero). The caller is responsible for validating the revocation evidence that is returned (for example, validating the CRL signature and certificate path). If the response is valid OCSP response, the evidenceType field of the CERT_REVOCATION structure is set to CRE_OCSP and the evidence field of the CERT_REVOCATION structure contains a pointer to the OCSP_EVIDENCE structure. The caller is responsible for freeing the memory associated with this parameter. Differenct calls are used to free the revocation.evidence member, depending on the value of revocation.evidenceType. The following table shows these calls: revocation.evidenceType Call CRE_NONE No Action Needed CRE_OCSP Call C_DestroyOCSPEvidence() CRE_CRL Call C_DestroyCRLEvidence() CRE_ERROR Call T_free CRE_TRANSPORT_ERROR Call T_free after calling C_DestroyListObject() on the statusString member of the PKI_TRANSPORT_INFO structure. Returns: If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyCRLEvidence (  CRL_EVIDENCE **    crlEvidence )  ;

De-allocates memory for the CRL_EVIDENCE structure and its components, and sets the address to NULL. If it is already NULL, no action is taken. Parameters: crlEvidence This is both an input and an output parameter. As an input parameter, it is the address of a pointer to a CRL_EVIDENCE structure that Cert-C should destroy. As an output parameter, the content of crlEvidence is set to (CRL_EVIDENCE *)NULL_PTR. Returns: None.

void C_DestroyOCSPEvidence (  OCSP_EVIDENCE **    ocspEvidence )  ;

De-allocates memory for the OCSP_EVIDENCE structure and its components, and sets the address to (OCSP_EVIDENCE*)0. If the structure is already (OCSP_EVIDENCE*)0, no action is taken. C_DestroyOCSPEvidence() must be called to destroy the evidence contained in the CERT_REVOCATION structure's evidence field when evidenceType is CRE_OCSP. Calling this function with an evidenceType other than CRE_OCSP can have severe consequences, such as the application crashing. Parameters: ocspEvidence This is both an input and an output parameter. As an input parameter, it is the address of a pointer to an OCSP_EVIDENCE structure that Cert-C should destroy. As an output parameter, the content of ocspEvidence is set to (OCSP_EVIDENCE*)NULL_PTR. Returns: None.

int C_GetNextCertInPath (  CERTC_CTX    ctx, CERT_PATH_CTX *    pathCtx, POINTER    startObject, LIST_OBJ    certList )  ;

Returns a set of candidate certificates whose public keys can be used to verify the start object's signature. Parameters: ctx This input parameter is the Cert-C context handle. pathCtx This input parameter is the path-processing context. It ensures that the constructed certificate path is valid. You can use the pathCtx.pathOptions field to request the appropriate level of checking during path construction. startObject This input parameter is an object used to locate one or more certificates that may contain the public key needed to verify the start object's signature. Cert-C uses the information contained in the start object (typically the issuer name and/or authority key identifier) to select a set of certificates. Currently, the startObject parameter can be either a CERT_OBJ or CRL_OBJ object. certList This is both an input and an output parameter; it is a list of certificates. On output, this parameter is a list of certificates that can verify the start object's signature. This function can optionally apply additional criteria from the path-processing algorithm and options to reduce the set of candidate certificates. The caller is responsible for the validation of the start object, the candidate certificates, and any relationship between the start object and candidate certificates required by the certificate-path processing algorithm. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_ValidateCert (  CERTC_CTX    ctx, CERT_PATH_CTX *    pathCtx, CERT_OBJ    cert, B_KEY_OBJ    validationKey )  ;

Verifies those aspects of the certificate-path processing policy that can be determined from the information available in the specified certificate, or other function parameters, without referring to information contained in other certificates in the certificate path. C_ValidateCert() verifies the following items: The certificate was signed using the private key corresponding to the public key specified in the function parameters. The certificate validity period includes the validation time specified in the certificate-path context. The calling application must determine the revocation status of cert. It should consult the appropriate CRL by using C_CheckCertRevocation or any other valid out-of-band mechanism to establish that cert is not revoked or on hold status. The pathCtx.pathOptions field can be used to selectively disable the preceding checks, or to disable other checks implemented by the service provider. Parameters: ctx This input parameter is the Cert-C context handle. pathCtx This input parameter is the path-processing context. Although the selected fields are specific to the service provider, they generally include the validation algorithm, the validation time, and the path options. Some fields might not be applicable to single-certificate validation. cert This input parameter contains the certificate to validate. The certificate cannot be revoked or on hold. validationKey This input parameter contains the key used to validate the certificate signature. Returns: If successful, returns 0. If not, returns a Cert-C error code.

---

RSA BSAFE^® Cert-C 2.7 API Reference