gsk_validate_hostname()

Validates a host certificate against the supplied hostname.

Format

#include <gskcms.h>

gsk_status gsk_validate_hostname (
                                x509_certificate *         host_certificate,
                                const char *               host_name,
                                GSKCMS_VALIDATE_HOSTNAME   val_option)

Parameters

host_certificate: Specifies the host certificate to be validated.
host_name: Specifies the fully-qualified host name in the local code page.
val_option: Specifies validation option to customize the order of the validation process.

Results

The function return value will be 0 (GSK_OK) 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_HOST_NOT_VALID]: The certificate is not valid for the specified host name.
[CMSERR_BAD_VALIDATION_OPTION]: Validation option is not valid.

Usage

The gsk_validate_hostname() routine validates the certificate against the specified host name. For successful validation the certificate must contain the specified host name as either the common name (CN) element of the subject name or as a DNS entry for the subject alternate name as indicated by the validation option.A case-sensitive (exact match) comparison is used for comparison with the common name (CN) element of the subject name when the common name attribute value is encoded as UTF-8 data (x509_string_utf8).

The val_option parameter determines the composition and order of the validation process. A value of:

GSKCMS_VALIDATE_HOSTNAME_CN validates the host name against the common name (CN) of the certificate first and then against the DNS entry for the subject alternate name extension if no match is found in the CN.
GSKCMS_VALIDATE_HOSTNAME_CN_ONLY validates the host name against the common name (CN) of the certificate only.
GSKCMS_VALIDATE_HOSTNAME_DNS validates the host name against the DNS entry in the subject alternate name extension first and, only if that is not present, validate the host name against the common name.
GSKCMS_VALIDATE_HOSTNAME_DNS_ONLY validates the host name against the DNS entry in the subject alternate name extension only.

The host name in the certificate can be a fully-qualified name (for example, 'dcesec4.endicott.ibm.com), a domain suffix (for example, '.endicott.ibm.com) or a wildcard name beginning with an asterisk (for example, '*.endicott.ibm.com). A case-sensitive comparison is performed between the supplied host name and the host name in the certificate. A fully-qualified name must be the same as the supplied host name. A domain suffix matches any host name with the same suffix but does not match the suffix itself. For example, '*.endicott.ibm.com matches ldap.dcesec4.endicott.ibm.com and 'dcesec4.endicott.ibm.com but does not match 'endicott.ibm.com. A wildcard name matches any name ending with the characters that follow the asterisk. A trailing period in a host name is ignored (for example, 'dcesec4.endicott.ibm.com.' is the same as dcesec4.endicott.ibm.com).

No other certificate validation is performed. The gsk_validate_certificate_mode() routine should be called if the certificate itself must be validated.