This function is deprecated. Use gsk_validate_certificate_mode() instead.

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 in order to be accepted.

issuer_record_id

Returns the record identifier for the issuer certificate used to validate the certificate. The record identifier will be 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.

Results

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

[CMSERR_ALG_NOT_SUPPORTED]

The signature algorithm is not supported.

[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_CERT_CHAIN_NOT_TRUST]

The certification chain is not trusted

[CMSERR_CERTIFICATE_REVOKED]

The certificate is revoked.

[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_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_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_NOT_YET_VALID]

The certificate is not yet valid.

[CMSERR_PATH_TOO_LONG]

The certification chain exceeds the maximum allowed by the CA.

[CMSERR_SELF_SIGNED_NOT_FOUND]

A self-signed certificate is not found in a trusted data source

Usage

The gsk_validate_certificate() routine validates an X.509 certificate by performing these checks on the subject certificate:

• The certificate subject name must be either a non-empty distinguished name or an empty distinguished name with a SubjectAltName certificate extension
• An empty subject name is not allowed for a CA certificate
• The certificate issuer name must not be an empty distinguished name
• The CertificatePolicy extension, if present, must not be a critical extension
• The current time must not be earlier than the start of the certificate validity period
• The current time must not be later than the end of the certificate validity period
• The issuer certificate must be a valid CA certificate
• The certificate signature must be correct
• The certificate must not be revoked
• The certification chain must lead to a certificate obtained from a trusted data source
• No certificate in the certification chain can be revoked or expired.

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

The gsk_validate_certificate() routine will obtain any necessary CA certificates from the supplied data sources. The CA certificate will be validated as described if it is obtained from an untrusted data source. In addition, these checks will be performed on CA certificates when validating the certification chain:

• The BasicConstraints extension, if present, must have the CA indicator set and the path length constraint must not be violated by subordinate certificates in the certification chain
• The NameConstraints extension, if present, must not be violated by the subject certificate

A root certificate is a self-signed certificate and its signature is verified using the public key in the certificate. If accept_root is FALSE, the root certificate must be found in a trusted data source in order 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 signed by another entity. Its signature is verified 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, the intermediate certificate will be allowed to act as a trust anchor and the chain will be considered complete. It is strongly recommended that a SAF key ring containing an intermediate certificate also has the rest of the certificate chain connected to the key ring, including the root certificate.

The data sources must contain at least one LDAP directory source or CRL source in order 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 will be 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 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 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 returned by the gsk_open_directory() routine. This is an untrusted data source. Any certificate or revocation list obtained from this source will be validated before being accepted. See the gsk_get_directory_certificates() and gsk_get_directory_crls() routines for more information concerning 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 used from this list will be validated before being 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 will be validated before being accepted.
• gskdb_source_cert_callback - The source is the address of a callback routine which will receive 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() routine will call 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 code 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 which will receive control when a certificate needs to 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 defined in the gskcms.h include file.