gsk_validate_certificate

Validates an X.509 certificate.

Format

#include <gskcms.h>

gsk_status gsk_validate_certificate_mode (
                                     gskdb_data_sources *                data_sources,
                                     x509_certificate *                  subject_certificate,
                                     gsk_boolean                         accept_root,
                                     gsk_int32 *                         issuer_record_id,
                                     GSKCMS_CERT_VALIDATION_MODE         validation_mode,
                                     gsk_uint32                          arg_count,
                                     [GSKCMS_CERT_VALIDATE_KEYRING_ROOT  validate_root]
                                     ...)

Parameters

data_sources: Specifies the data sources for CA certificates and revocation lists. The data sources are searched in the order they occur in the data source array, so trusted sources should be included before untrusted sources and local sources should be included before remote sources.
subject_certificate: Specifies the certificate to be validated.
accept_root: Specify TRUE if a self-signed root certificate is to be accepted without checking the data sources. Specify FALSE if a self-signed root certificate must be found in one of the trusted data sources to be accepted.
issuer_record_id: Returns the record identifier for the issuer certificate that is used to validate the certificate. The record identifier is 0 if the issuer certificate is found in a non-database source. Specify NULL for this parameter if the issuer record identifier is not needed.
validation_mode: Specifies certificate validation mode to customize the policy that is used for certificate validation.
arg_count: Specifies the number of optional parameters following the arg_count parameter. The arg_count parameter can be set to either 0 or 1. If set to 1, the validate_root parameter must be specified.
validate_root: Specifies how certificates in a SAF key ring are validated. Specify GSKCMS_CERT_VALIDATE_KEYRING_ROOT_ON if SAF key ring certificates are validated to the root CA certificate. Specify GSKCMS_CERT_VALIDATE_KEYRING_ROOT_OFF if SAF key ring certificates are validated only to the trust anchor certificate when a sole intermediate certificate exists in the SAF key ring. By default, SAF key ring certificates are only validated to the trust anchor certificate. This setting does not affect the validation of SSL key database file and PKCS #11 token certificates as these certificates are always validated to the root CA certificate.

Results

The return status is zero if the validation is successful. Otherwise, it is one of the return codes that are listed in the gskcms.h include file. These are some possible errors:

[CMSERR_ALG_NOT_SUPPORTED]: The signature algorithm is not supported.
[CMSERR_BAD_ARG_COUNT]: Variable argument count is not valid.
[CMSERR_BAD_CRL]: Certificate revocation list cannot be found.
[CMSERR_BAD_EXT_DATA]: Certificate extension data is incorrect.
[CMSERR_BAD_HANDLE]: The database handle is not valid.
[CMSERR_BAD_KEY_SIZE]: The key size is not valid.
[CMSERR_BAD_ISSUER_NAME]: The certificate issuer name is not valid.
[CMSERR_BAD_SIGNATURE]: The signature is not correct.
[CMSERR_BAD_SUBJECT_NAME]: Subject name is not valid.
[CMSERR_BAD_VALIDATE_ROOT_ARG]: Variable argument validate root is not valid.
[CMSERR_BAD_VALIDATION_OPTION]: Validation option is not valid.
[CMSERR_CERT_CHAIN_NOT_TRUSTED]: The certification chain is not trusted.
[CMSERR_CERTIFICATE_REVOKED]: The certificate is revoked.
[CMSERR_CRITICAL_EXT_INCORRECT]: Certificate extension has an incorrect critical indicator.
[CMSERR_DISTRIBUTION_POINTS]: Cannot match CRL distribution points.
[CMSERR_DUPLICATE_EXTENSION]: Supplied extensions contain a duplicate extension.
[CMSERR_ECURVE_NOT_FIPS_APPROVED]: Elliptic Curve not supported in FIPS mode.
[CMSERR_ECURVE_NOT_SUPPORTED]: Elliptic Curve is not supported.
[CMSERR_EXPIRED]: The certificate is expired.
[CMSERR_EXT_NOT_SUPPORTED]: Certificate extension is not supported.
[CMSERR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[CMSERR_ICSF_NOT_AVAILABLE]: ICSF services are not available.
[CMSERR_ICSF_NOT_FIPS]: ICSF PKCS #11 not operating in FIPS mode.
[CMSERR_ICSF_SERVICE_FAILURE]: ICSF callable service returned an error.
[CMSERR_INCORRECT_DBTYPE]: The database type does not support certificates.
[CMSERR_INCORRECT_KEY_USAGE]: The issuer certificate does not allow signing certificates
[CMSERR_ISSUER_NOT_CA]: The certificate issuer is not a certification authority.
[CMSERR_ISSUER_NOT_FOUND]: The issuer certificate is not found in one of the data sources.
[CMSERR_LDAP_NOT_AVAILABLE]: LDAP is not available.
[CMSERR_NAME_CONSTRAINTS_VIOLATED]: The certificate name is not consistent with the name constraints.
[CMSERR_NAME_NOT_SUPPORTED]: The AuthorityKeyIdentifier extension name is not a directory name.
[CMSERR_NO_ACCEPTABLE_POLICIES]: Acceptable policy intersection cannot be found.
[CMSERR_NOT_YET_VALID]: The certificate is not yet valid.
[CMSERR_PATH_TOO_LONG]: The certification chain exceeds the maximum that is allowed by the CA.
[CMSERR_RECORD_NOT_FOUND]: Record not found.
[CMSERR_REQUIRED_EXT_MISSING]: Required certificate extension is missing.

Usage

The gsk_validate_certificate_mode() routine validates an X.509 certificate according to the standards defined in RFC 2459: X.509 certificate, certificate revocation list, and certificate extensions, RFC 3280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, or RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile. Any necessary CA or issuer certificates are obtained from the supplied data sources. The CA certificate is also validated according to the previously mentioned Internet standards.

The validation_mode parameter determines the Internet standard that the certificate and certificate chain are validated against. The following validation modes are supported:

GSKCMS_CERT_VALIDATION_MODE_2459 – validate the certificate against RFC 2459 only.
GSKCMS_CERT_VALIDATION_MODE_3280 – validate the certificate against RFC 3280 only.
GSKCMS_CERT_VALIDATION_MODE_5280 – validate the certificate against RFC 5280 only.
GSKCMS_CERT_VALIDATION_MODE_ANY – attempt to validate the certificate against RFC 2459 initially. If that fails, validate against RFC 3280. If that fails, validate against RFC 5280.

Note: The z/OS® specific HostIDMapping certificate extension is supported by System SSL and can be validated as a critical extension in any validation mode.

A root certificate is a self-signed certificate and its signature is verified by using the public key in the certificate. If accept_root is FALSE, the root certificate must be found in a trusted data source to be accepted. If accept_root is TRUE, the self-signed certificate is accepted if the signature is correct.

An intermediate certificate or an end-entity certificate is a certificate that is signed by another entity. Its signature is verified by using the public key in the issuer's certificate. The issuer certificate must be found in one of the supplied data sources. When intermediate CA certificates are used, the certificate chain is validated until the root certificate for the chain is found in one of the trusted data sources. If a sole intermediate certificate is found in a SAF key ring and the next issuer is not found in the same SAF key ring, and validate_root is not specified or is set to GSKCMS_CERT_VALIDATE_KEYRING_ROOT_OFF, the intermediate certificate is allowed to act as a trust anchor, and the chain is considered complete. By default, SAF key ring certificates are only validated to the trust anchor certificate. If validate_root is set to GSKCMS_CERT_VALIDATE_KEYRING_ROOT_ON, an intermediate certificate in a SAF key ring is not allowed to be established as a trust anchor and full certificate validation to the root CA must occur. Make sure that a SAF key ring containing an intermediate certificate also has the rest of the certificate chain that is connected to the key ring, including the root certificate. The validate_root setting does not affect the validation of SSL key database file and PKCS #11 token certificates because these certificates are always validated to the root CA certificate.

The data sources must contain at least one LDAP directory source or CRL source to check for revoked certificates. The CRL distribution point name (or the certificate issuer name if the certificate does not have a CrlDistributionPoints extension) is used as the distinguished name of the LDAP directory entry containing the certificate revocation list (CRL). The CRL distribution point name and CRL issuer name must be X.500 directory names. The BasicConstraints certificate extension determines whether the CA revocation list or the user revocation list is used. An error is returned if a CRL obtained from an untrusted source cannot be validated.

Security levels for connecting to LDAP directories are based on the GSKCMS_CRL_SECURITY_LEVEL setting. When using the CMS APIs, the GSKCMS_CRL_SECURITY_LEVEL setting can be specified by using the gsk_set_directory_enum() routine. Security levels can be set to LOW, MEDIUM or HIGH. See gsk_attribute_set_enum(), gsk_set_directory_enum() and Environment variables for more information about CRL security level settings.

These data sources are supported:

gskdb_source_key_database - The source is a key database. The handle must be a database handle that is returned by the gsk_create_database() routine, the gsk_open_database() routine, or the gsk_open_keyring() routine. This is a trusted data source.
gskdb_source_directory - The source is an LDAP directory. The handle must be the directory handle that is returned by the gsk_open_directory() routine. This is an untrusted data source. Any certificate or revocation list that is obtained from this source is validated before it is accepted. See the gsk_get_directory_certificates() and gsk_get_directory_crls() routines for more information about the use of LDAP directory entries.
gskdb_source_trusted_certs - The source is an array of certificates. This is a trusted data source.
gskdb_source_untrusted_certs - The source is an array of certificates. This is an untrusted data source. Any certificate that is used from this list is validated before it is accepted.
gskdb_source_trusted_crls - The source is an array of certificate revocation lists. This is a trusted data source.
gskdb_source_untrusted_crls - The source is an array of certificate revocation lists. This is an untrusted data source. Any CRL used from this list is validated before it is accepted.
gskdb_source_cert_callback - The source is the address of a callback routine that receives control when an issuer certificate is needed. This is a trusted data source. The subject name is passed as an input parameter and the certCallback routine returns an array of one or more certificates with that subject name. The gsk_validate_certificate_mode() routine calls the freeCallback routine to release the certificates. The return status should be 0 if no errors are detected. Otherwise, it should be one of the error codes that are listed in the gskcms.h include file. The return status should be 0 and the certificate count should be 0 if there are no certificates matching the supplied subject name.
gskdb_source_crl_callback - The source is the address of a callback routine that receives control when a certificate must be checked to see if it has been revoked. This is a trusted source. The return value should be 0 if the certificate is not revoked. If the callback routine is unable to check the certificate for revocation and processing should continue to the next data source, the return value should be -1. Otherwise, it should be one of the error codes that are defined in the gskcms.h include file.

The validate_root optional parameter must be specified when arg_count is set to 1. If validate_root is not specified and arg_count is set to 1, an error of CMSERR_BAD_VALIDATE_ROOT_ARG is returned.

If the arg_count parameter is 0, any additional parameters that are specified are ignored.

If executing in FIPS mode, only FIPS-approved algorithms and key sizes are supported. See System SSL and FIPS 140-2 for more details.