x509host.h File Reference

X.509 certificate hostname and endpoint matching utilities. More...

#include "qsccommon.h"
#include "x509types.h"

Go to the source code of this file.

Functions
QSC_EXPORT_API bool	qsc_x509_dns_name_match (const char *pattern, const char *hostname)
	Match a DNS hostname against a certificate pattern.
QSC_EXPORT_API bool	qsc_x509_certificate_match_dns_name (const qsc_x509_certificate *certificate, const char *hostname)
	Match a hostname against certificate DNS identifiers.
QSC_EXPORT_API bool	qsc_x509_certificate_match_ip_address (const qsc_x509_certificate *certificate, const uint8_t *address, size_t addresslen)
	Match an IP address against certificate IP identifiers.
QSC_EXPORT_API bool	qsc_x509_certificate_match_hostname (const qsc_x509_certificate *certificate, const char *hostname)
	Match a hostname against a certificate.
QSC_EXPORT_API bool	qsc_x509_certificate_match_endpoint (const qsc_x509_certificate *certificate, const char *hostname, const uint8_t *address, size_t addresslen)
	Match a network endpoint against a certificate.

Detailed Description

X.509 certificate hostname and endpoint matching utilities.

This header defines helper functions used to evaluate whether a hostname or network address matches the identity information contained in an X.509 certificate. Matching is performed against Subject Alternative Name entries when present, and may fall back to the subject distinguished name common name when no DNS SAN is present.

DNS matching follows a restrained wildcard model compatible with common X.509 hostname validation practice. Wildcards are accepted only in the left-most label, the wildcard pattern must cover at least two additional labels, and wildcard matching is not applied to IDNA A-label inputs.

Function Documentation

qsc_x509_certificate_match_dns_name()

QSC_EXPORT_API bool qsc_x509_certificate_match_dns_name	(	const qsc_x509_certificate *	certificate,
		const char *	hostname )

Match a hostname against certificate DNS identifiers.

Evaluates the supplied hostname against the DNS names contained in the certificate Subject Alternative Name extension. If no DNS SAN entries are present, the implementation falls back to matching against the subject common name.

Parameters

certificate	[const][struct] The certificate to evaluate.
hostname	[const] The hostname to match.

Returns

Returns true if the hostname matches a certificate DNS identifier; otherwise returns false.

qsc_x509_certificate_match_endpoint()

QSC_EXPORT_API bool qsc_x509_certificate_match_endpoint	(	const qsc_x509_certificate *	certificate,
		const char *	hostname,
		const uint8_t *	address,
		size_t	addresslen )

Match a network endpoint against a certificate.

Evaluates both hostname and IP address inputs against the certificate. The function first attempts DNS name matching when a hostname is supplied, then attempts IP address matching when a binary address is supplied. Either input may be NULL, but at least one identity input should be provided by the caller.

Parameters

certificate	[const][struct] The certificate to evaluate.
hostname	[const] The hostname to match, or NULL.
address	[const] The binary IP address, or NULL.
addresslen	The length of the IP address in bytes.

Returns

Returns true if the endpoint matches the certificate identity; otherwise returns false.

qsc_x509_certificate_match_hostname()

QSC_EXPORT_API bool qsc_x509_certificate_match_hostname	(	const qsc_x509_certificate *	certificate,
		const char *	hostname )

Match a hostname against a certificate.

Performs hostname validation against a certificate using DNS SAN entries and common-name fallback when no DNS SAN is present.

Parameters

certificate	[const][struct] The certificate to evaluate.
hostname	[const] The hostname to match.

Returns

Returns true if the hostname is valid for the certificate; otherwise returns false.

qsc_x509_certificate_match_ip_address()

QSC_EXPORT_API bool qsc_x509_certificate_match_ip_address	(	const qsc_x509_certificate *	certificate,
		const uint8_t *	address,
		size_t	addresslen )

Match an IP address against certificate IP identifiers.

Compares a binary IPv4 or IPv6 address against the iPAddress entries contained in the certificate Subject Alternative Name extension.

Parameters

certificate	[const][struct] The certificate to evaluate.
address	[const] The binary IP address.
addresslen	The address length in bytes. Supported values are 4 and 16.

Returns

Returns true if the address matches a certificate IP identifier; otherwise returns false.

qsc_x509_dns_name_match()

QSC_EXPORT_API bool qsc_x509_dns_name_match	(	const char *	pattern,
		const char *	hostname )

Match a DNS hostname against a certificate pattern.

Compares a hostname against a certificate DNS pattern. The implementation performs ASCII case-insensitive comparison and supports a single wildcard in the left-most label when the pattern is of the form "*.example.com".

Parameters

pattern	[const] The certificate DNS pattern.
hostname	[const] The hostname to evaluate.

Returns

Returns true if the hostname matches the pattern; otherwise returns false.