RSA BSAFE Cert-C

CERT_PATH_CTX Struct Reference

This structure is used with the C_BuildCertPath(), C_GetNextCertInPath(), C_ValidateCert(), C_WriteSignedDataMsg(), C_ReadSignedDataMsg(), and C_ExportPKCS12() functions. CERT_PATH_CTX is also used with the C_CheckCertRevocation() function. The interpretation of CERT_PATH_CTX's components are service-provider specific when CERT_PATH_CTX is used with the C_CheckCertRevocation() function. For specific details about each Cert-C certificate revocation status service provider's implementation of CERT_PATH_CTX, see the information for a specific service provider. C_BuildCertPath() generally calls C_CheckCertRevocation() as part of its path building operation, therefore the same CERT_PATH_CTX is used by both functions. This structure is also used in the PKI_PROTECT_INFO structure, which is used with the C_RequestPKICert(), C_WritePKICertRequestMsg(), and C_ReadPKICertResponseMsg() functions.

Data Fields

pathAlgorithm

An int value that identifies the certificate path-processing algorithm. The supported values are:

Path-Processing Algorithm	Description
`PA_X509_V1`	Path-processing algorithm as specified by X.509 v1 (ignores extensions).
`PA_PKIX`	Path-processing algorithm as specified by RFC 2459.
`PA_PKIX2`	Path-processing algorithm as specified by the draft "son of 2459" draft-ietf-pkix-new-part1-12.

pathOptions

A UINT4 value that contains a set of 1-bit flags that you can use to modify the basic certificate path-processing algorithm. The flags are used to turn off certain checks in certificate path building or validation. Individual flags can be combined using the bitwise-'OR' operator. Not all flags apply to every algorithm. Setting this field to 0 (zero) results in the normal behavior of the specified path-processing algorithm. The high-order 4 bits of the flags (a 32-bit unsigned integer) are reserved for service- provider-specific flags. The interpretation of service-provider-specific flags is determined by the particular certificate-path service provider that implements the Cert-C path-processing operation. The remaining unassigned bits are reserved for future use.

Path Option Flag	Description
`PF_IGNORE_SIGNATURE`	Setting this flag causes path processing not to verify certificate signatures. Unless signatures are known to be valid by out-of-band means, disabling this check is not recommended.
`PF_IGNORE_VALIDATION_TIME`	Setting this flag causes path processing not to check the validity period contained within each certificate.
`PF_IGNORE_REVOCATION`	Setting this flag causes path processing not to check the revocation status of each certificate.
`PF_IGNORE_NAME_CHAINING`	Setting this flag causes path processing not to verify the subject name / issuer name linkage between adjacent certificates in the path.
`PF_IGNORE_NAME_CONSTRAINTS`	Setting this flag causes path processing not to verify that the subject name and Subject Alternate Name extension are consistent with the name constraints contained in the path certificates.
`PF_IGNORE_BASIC_CONSTRAINTS`	Setting this flag causes path processing not to verify the path length established by the basic constraints extensions in the path certificates.
`PF_IGNORE_KEY_USAGE`	Setting this flag causes path processing not to enforce key usage extensions contained within certificates, even if marked critical. In particular, the CertSign flag will be ignored.
`PF_IGNORE_CRITICALITY`	Setting this flag causes path processing not to fail if any unrecognized critical extensions are encountered in the path.
`PF_IGNORE_UID_CHAINING`	Setting this flag causes path processing not to verify the subject unique identifier/issuer unique identifier linkage between adjacent certificates in the path.
`PF_IGNORE_KEY_ID_CHAINING`	Setting this flag causes path processing not to verify the subject key identifier/authority key identifier linkage between adjacent certificates in the path.
`PF_IGNORE_CRL_DP`	Setting this flag cause path processing not to use information in CRL Distribution Points extensions when checking certificate revocation status.
`PF_FORCE_CRL_DP`	Setting this flag cause path processing to use information in CRL Distribution Points extensions first when checking certificate revocation status.
`PF_IGNORE_AIA`	Setting this flag causes path processing not to use information in Authority Information Access extensions when building or validating certificate paths.
`PF_IGNORE_CRL_NUMBER`	Setting this flag causes path processing not to use CRL Number extensions when selecting the most current CRL.
`PF_IGNORE_DELTA_CRL`	Setting this flag causes path processing not to use delta CRLs when checking certificate revocation status. A complete CRL must be used instead.
`PF_IGNORE_CRL_IDP`	Setting this flag causes path processing not to use Issuing Distribution Point information contained in a CRL. It also causes the Certificate Issuer extension in CRL entries to be ignored.
`PF_IGNORE_POLICY`	Setting this flag cause path processing not to consider any policy or policy mapping information in the certificates. This flag is used with the `PA_PKIX2` path-processing algorithm; it has no effect if the `PA_PKIX` path-processing is selected.
`PF_INHIBIT_POLICY_MAPPING`	Setting this flag inhibits all policy mapping in the certificate path. This flag is used with the `PA_PKIX2` path-processing algorithm; it has no effect if the `PA_PKIX` path-processing is selected.
`PF_REQUIRE_EXPLICIT_POLICY`	Setting this flag indicates the certificate path MUST be valid for at least one of the policies in the users initial policy set. This flag is used with the `PA_PKIX2` path-processing algorithm; it has no effect if the `PA_PKIX` path-processing is selected.
`PF_INHIBIT_ANYPOLICY`	Setting this flag indicates the anyPolicy OID should not be processed if it is included in a certificate. This flag is used with the `PA_PKIX2` path-processing algorithm; it has no effect if the `PA_PKIX` path-processing is selected.

Specifying a caching database is required with certain combination of path algorithms and the PF_IGNORE_CRL_DP and PF_FORCE_CRL_DP path option flags. Specifying a caching database will never return an error, even when it is not required, although it can generating a warning.

The following table summarizes the caching database requirements:

Path Algorithm	Path Option Flag	Caching DB Required
PA_X509_V1	Any valid combination	No
PKIX	`PF_IGNORE_CRL_DP` and not `PF_FORCE_CRL_DP`	No
PKIX	`PF_FORCE_CRL_DP` and not `PF_IGNORE_CRL_DP`	Yes
PKIX	Neither `PF_FORCE_CRL_DP` nor `PF_IGNORE_CRL_DP`	No
PKIX2	`PF_IGNORE_CRL_DP` and not `PF_FORCE_CRL_DP`	No
PKIX2	`PF_FORCE_CRL_DP` and not `PF_IGNORE_CRL_DP`	Yes
PKIX2	Neither `PF_FORCE_CRL_DP` nor `PF_IGNORE_CRL_DP`	Yes

Note: Selecting both PF_IGNORE_CRL_DP and PF_FORCE_CRL_DP will always return an E_INVALID_PARAMETER error.

For more information on a caching database and service provider behavior, see the Cert-C CRL Revocation Status Service Provider.

trustedCerts A LIST_OBJ object that contains a collection of one or more certificates whose public keys are trusted by the application. These certificates can be, but need not always be, self-signed. Valid certificate paths end in one of these certificates. Each entry in the list is of type CERT_OBJ.

policies A LIST_OBJ object that contains a set of initial policy identifiers. These identify one or more certificate policies that are acceptable for processing certificate paths. If you accept any policy, set this value to ANY_POLICY, a constant that is defined in certpath.h and is available for you to use. Each entry in the list is of type ITEM, where the item value is the policy object identifier.

validationTime A UINT4 value that indicates the time for which the validity of the path should be determined. This can be either the current date and time or some point in the past. The time is specified as the number of seconds since 12:00 AM GMT, January 1, 1970. Set the validationTime parameter to 0 (zero) or to PF_VALIDATION_TIME_NOW to indicate that the validation time should be the time at which the certificate-path operation is performed.

database A SERVICE handle that specifies which databases to use. Cert-C uses the database service provider instances bound to the database service handle when retrieving certificates and CRLs for path-processing operations. This parameter must contain any database that is specified in the dbname member of the CRL_STATUS_INIT_PARAMS structure.

00665 typedef struct {
00666   int      pathAlgorithm;      /* path processing algorithm */
00667   UINT4    pathOptions;        /* modify base path algorithm */
00668   LIST_OBJ trustedCerts;       /* "root" certificates */
00669   LIST_OBJ policies;           /* acceptable policies */
00670   UINT4    validationTime;     /* path must be valid at this time */
00671   SERVICE  database;           /* database(s) for path processing */
00672 } CERT_PATH_CTX;