X.509 certificate and certification-path verification interface. More...

#include "qsccommon.h"
#include "x509types.h"
#include "x509time.h"
#include "x509rev.h"

Data Structures
struct	qsc_x509_verify_options_t

Typedefs
typedef enum qsc_x509_verify_status_t	qsc_x509_verify_status
typedef bool(*	qsc_x509_signature_verify_callback) (const qsc_x509_certificate certificate, const qsc_x509_certificate issuer, void *state)
	Caller-supplied certificate signature verification callback.
typedef enum qsc_x509_verify_purpose_t	qsc_x509_verify_purpose
typedef struct qsc_x509_verify_options_t	qsc_x509_verify_options

Enumerations
enum	qsc_x509_verify_status_t { QSC_X509_VERIFY_STATUS_SUCCESS = 0 , QSC_X509_VERIFY_STATUS_INVALID_INPUT = 1 , QSC_X509_VERIFY_STATUS_INVALID_CERTIFICATE = 2 , QSC_X509_VERIFY_STATUS_ALGORITHM_MISMATCH = 3 , QSC_X509_VERIFY_STATUS_EXPIRED = 4 , QSC_X509_VERIFY_STATUS_NOT_YET_VALID = 5 , QSC_X509_VERIFY_STATUS_ISSUER_MISMATCH = 6 , QSC_X509_VERIFY_STATUS_KEY_IDENTIFIER_MISMATCH = 7 , QSC_X509_VERIFY_STATUS_NOT_CA = 8 , QSC_X509_VERIFY_STATUS_PATH_LENGTH_EXCEEDED = 9 , QSC_X509_VERIFY_STATUS_KEY_USAGE_REJECTED = 10 , QSC_X509_VERIFY_STATUS_SIGNATURE_REJECTED = 11 , QSC_X509_VERIFY_STATUS_TRUST_NOT_FOUND = 12 , QSC_X509_VERIFY_STATUS_UNSUPPORTED = 13 , QSC_X509_VERIFY_STATUS_CALLBACK_FAILURE = 14 , QSC_X509_VERIFY_STATUS_UNSUPPORTED_CRITICAL_EXTENSION = 15 , QSC_X509_VERIFY_STATUS_PURPOSE_REJECTED = 16 , QSC_X509_VERIFY_STATUS_REVOKED = 17 , QSC_X509_VERIFY_STATUS_REVOCATION_UNKNOWN = 18 , QSC_X509_VERIFY_STATUS_CHAIN_LOOP = 19 , QSC_X509_VERIFY_STATUS_NAME_MISMATCH = 20 }
enum	qsc_x509_verify_purpose_t { QSC_X509_VERIFY_PURPOSE_GENERIC = 0 , QSC_X509_VERIFY_PURPOSE_TLS_SERVER = 1 , QSC_X509_VERIFY_PURPOSE_TLS_CLIENT = 2 }

Functions
QSC_EXPORT_API void	qsc_x509_verify_options_initialize (qsc_x509_verify_options *options)
	Initialize a verification options structure.
QSC_EXPORT_API bool	qsc_x509_certificate_is_self_issued (const qsc_x509_certificate *certificate)
	Test whether a certificate is self-issued.
QSC_EXPORT_API bool	qsc_x509_certificate_is_self_signed (const qsc_x509_certificate certificate, qsc_x509_signature_verify_callback callback, void state)
	Test whether a certificate is self-signed.
QSC_EXPORT_API bool	qsc_x509_certificate_is_ca (const qsc_x509_certificate *certificate)
	Test whether a certificate is authorized to act as a CA.
QSC_EXPORT_API bool	qsc_x509_certificate_allows_server_auth (const qsc_x509_certificate *certificate)
	Test whether a certificate allows TLS server authentication.
QSC_EXPORT_API bool	qsc_x509_certificate_allows_client_auth (const qsc_x509_certificate *certificate)
	Test whether a certificate allows TLS client authentication.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_structure (const qsc_x509_certificate *certificate)
	Check RFC-aligned certificate structural invariants.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_algorithms (const qsc_x509_certificate *certificate)
	Check certificate algorithm consistency.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_validity (const qsc_x509_certificate certificate, const qsc_asn1_time ascnow)
	Check certificate validity at a supplied time.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_purpose (const qsc_x509_certificate *certificate, qsc_x509_verify_purpose purpose)
	Check certificate suitability for a requested purpose.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_hostname (const qsc_x509_certificate certificate, const char hostname)
	Check whether a certificate matches a hostname.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_ip_address (const qsc_x509_certificate certificate, const uint8_t address, size_t addresslen)
	Check whether a certificate matches an IP address.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_check_issuer (const qsc_x509_certificate issuer, const qsc_x509_certificate subject, size_t remainingdepth)
	Check whether one certificate may issue another.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_verify (const qsc_x509_certificate certificate, const qsc_x509_certificate issuer, const qsc_asn1_time now, qsc_x509_signature_verify_callback callback, void state)
	Verify a certificate against its issuer.
QSC_EXPORT_API bool	qsc_x509_chain_is_anchored (const qsc_x509_chain chain, const qsc_x509_store store)
	Test whether a chain terminates at a trusted anchor.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_chain_verify (const qsc_x509_chain chain, const qsc_x509_store store, const qsc_asn1_time now, qsc_x509_signature_verify_callback callback, void state)
	Verify a certification chain.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_certificate_verify_ex (const qsc_x509_certificate certificate, const qsc_x509_certificate issuer, const qsc_asn1_time now, qsc_x509_signature_verify_callback callback, void state, const qsc_x509_verify_options *options)
	Verify a certificate against its issuer using extended options.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_chain_verify_ex (const qsc_x509_chain chain, const qsc_x509_store store, const qsc_asn1_time now, qsc_x509_signature_verify_callback callback, void state, const qsc_x509_verify_options *options)
	Verify a certification chain using extended options.

Detailed Description

X.509 certificate and certification-path verification interface.

This header defines the status codes, callback types, verification-purpose selectors, option container, and helper functions used to validate X.509 certificates and certification chains. The interface supports algorithm consistency checks, validity-window evaluation, issuer relationship checks, name and endpoint validation, CA and key-usage policy enforcement, signature verification through a caller-supplied callback, and optional revocation processing through the revocation subsystem.

Typedef Documentation

◆ qsc_x509_signature_verify_callback

typedef bool(* qsc_x509_signature_verify_callback) (const qsc_x509_certificate *certificate, const qsc_x509_certificate *issuer, void *state)

Caller-supplied certificate signature verification callback.

This callback performs cryptographic verification of a subject certificate signature using the supplied issuer certificate and caller-defined state.

Parameters

certificate	[const][struct] The certificate whose signature is to be verified.
issuer	[const][struct] The issuer certificate providing the verification key.
state	Caller-defined opaque verification context.

Returns: Returns true if the certificate signature is valid; otherwise returns false.

Enumeration Type Documentation

◆ qsc_x509_verify_purpose_t

enum qsc_x509_verify_purpose_t

Enumerator
QSC_X509_VERIFY_PURPOSE_GENERIC	Apply generic certificate validation without a specialized application usage requirement.
QSC_X509_VERIFY_PURPOSE_TLS_SERVER	Validate the certificate for use as a TLS server certificate.
QSC_X509_VERIFY_PURPOSE_TLS_CLIENT	Validate the certificate for use as a TLS client certificate.

◆ qsc_x509_verify_status_t

enum qsc_x509_verify_status_t

Enumerator
QSC_X509_VERIFY_STATUS_SUCCESS	Verification completed successfully.
QSC_X509_VERIFY_STATUS_INVALID_INPUT	An input parameter was invalid.
QSC_X509_VERIFY_STATUS_INVALID_CERTIFICATE	The certificate structure was malformed or internally inconsistent.
QSC_X509_VERIFY_STATUS_ALGORITHM_MISMATCH	The certificate signature algorithm metadata was inconsistent or incompatible.
QSC_X509_VERIFY_STATUS_EXPIRED	The certificate was expired at the evaluation time.
QSC_X509_VERIFY_STATUS_NOT_YET_VALID	The certificate was not yet valid at the evaluation time.
QSC_X509_VERIFY_STATUS_ISSUER_MISMATCH	The issuer certificate did not match the subject certificate issuer fields.
QSC_X509_VERIFY_STATUS_KEY_IDENTIFIER_MISMATCH	Authority and subject key identifiers did not match as required.
QSC_X509_VERIFY_STATUS_NOT_CA	A certificate expected to act as a CA was not authorized as a certification authority.
QSC_X509_VERIFY_STATUS_PATH_LENGTH_EXCEEDED	A certification path length constraint was exceeded.
QSC_X509_VERIFY_STATUS_KEY_USAGE_REJECTED	Key usage or related policy constraints rejected the requested operation.
QSC_X509_VERIFY_STATUS_SIGNATURE_REJECTED	The certificate or chain signature verification failed.
QSC_X509_VERIFY_STATUS_TRUST_NOT_FOUND	No suitable trust anchor was found.
QSC_X509_VERIFY_STATUS_UNSUPPORTED	A required algorithm, extension, or feature was unsupported.
QSC_X509_VERIFY_STATUS_CALLBACK_FAILURE	A caller-supplied callback failed to execute successfully.
QSC_X509_VERIFY_STATUS_UNSUPPORTED_CRITICAL_EXTENSION	The certificate contained an unsupported critical extension.
QSC_X509_VERIFY_STATUS_PURPOSE_REJECTED	The certificate was not authorized for the requested verification purpose.
QSC_X509_VERIFY_STATUS_REVOKED	The certificate was determined to be revoked.
QSC_X509_VERIFY_STATUS_REVOCATION_UNKNOWN	Certificate revocation status could not be determined.
QSC_X509_VERIFY_STATUS_CHAIN_LOOP	A loop was detected during certification path processing.
QSC_X509_VERIFY_STATUS_NAME_MISMATCH	The certificate identity did not match the requested hostname or address.

Function Documentation

◆ qsc_x509_certificate_allows_client_auth()

QSC_EXPORT_API bool qsc_x509_certificate_allows_client_auth ( const qsc_x509_certificate * certificate )

Test whether a certificate allows TLS client authentication.

Evaluates the certificate key usage and extended key usage constraints for TLS client-auth applicability.

Parameters

certificate [const][struct] The certificate to inspect.

Returns: Returns true if the certificate permits TLS client authentication; otherwise returns false.

◆ qsc_x509_certificate_allows_server_auth()

QSC_EXPORT_API bool qsc_x509_certificate_allows_server_auth ( const qsc_x509_certificate * certificate )

Test whether a certificate allows TLS server authentication.

Evaluates the certificate key usage and extended key usage constraints for TLS server-auth applicability.

Parameters

certificate [const][struct] The certificate to inspect.

Returns: Returns true if the certificate permits TLS server authentication; otherwise returns false.

◆ qsc_x509_certificate_check_algorithms()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_algorithms ( const qsc_x509_certificate * certificate )

Check certificate algorithm consistency.

Validates the internal consistency of certificate signature algorithm metadata, signature encoding constraints, and related algorithm fields.

Parameters

certificate [const][struct] The certificate to inspect.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_check_hostname()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_hostname	(	const qsc_x509_certificate *	certificate,
		const char *	hostname )

Check whether a certificate matches a hostname.

Evaluates the certificate identity information against the supplied DNS host name.

Parameters

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

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_check_ip_address()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_ip_address	(	const qsc_x509_certificate *	certificate,
		const uint8_t *	address,
		size_t	addresslen )

Check whether a certificate matches an IP address.

Evaluates the certificate identity information against the supplied binary IP address.

Parameters

certificate	[const][struct] The certificate to inspect.
address	[const] The binary IP address to match.
addresslen	The length of the IP address in bytes.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_check_issuer()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_issuer	(	const qsc_x509_certificate *	issuer,
		const qsc_x509_certificate *	subject,
		size_t	remainingdepth )

Check whether one certificate may issue another.

Evaluates issuer-subject name relationships, key identifiers, CA status, path-length constraints, and related issuer policy requirements.

Parameters

issuer	[const][struct] The candidate issuer certificate.
subject	[const][struct] The candidate subject certificate.
remainingdepth	The remaining allowable certification-path depth.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_check_purpose()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_purpose	(	const qsc_x509_certificate *	certificate,
		qsc_x509_verify_purpose	purpose )

Check certificate suitability for a requested purpose.

Evaluates the certificate against the requested application purpose, including usage and purpose constraints where applicable.

Parameters

certificate	[const][struct] The certificate to inspect.
purpose	[enum] The requested verification purpose.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_check_structure()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_structure ( const qsc_x509_certificate * certificate )

Check RFC-aligned certificate structural invariants.

Validates certificate-local structural rules that do not require issuer, trust-store, or time context. This includes version and extension compatibility, empty-subject handling, CA and key-usage coherence, and subject public-key algorithm suitability.

Parameters

certificate [const][struct] The certificate to inspect.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_check_validity()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_check_validity	(	const qsc_x509_certificate *	certificate,
		const qsc_asn1_time *	ascnow )

Check certificate validity at a supplied time.

Evaluates the certificate notBefore and notAfter fields relative to the supplied evaluation time.

Parameters

certificate	[const][struct] The certificate to inspect.
ascnow	[const][struct] The evaluation time.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_is_ca()

QSC_EXPORT_API bool qsc_x509_certificate_is_ca ( const qsc_x509_certificate * certificate )

Test whether a certificate is authorized to act as a CA.

Evaluates the Basic Constraints and related policy indicators to determine whether the certificate may act as a certification authority.

Parameters

certificate [const][struct] The certificate to inspect.

Returns: Returns true if the certificate is a CA certificate; otherwise returns false.

◆ qsc_x509_certificate_is_self_issued()

QSC_EXPORT_API bool qsc_x509_certificate_is_self_issued ( const qsc_x509_certificate * certificate )

Test whether a certificate is self-issued.

Determines whether the certificate subject and issuer names are equivalent, indicating that the certificate is self-issued.

Parameters

certificate [const][struct] The certificate to inspect.

Returns: Returns true if the certificate is self-issued; otherwise returns false.

◆ qsc_x509_certificate_is_self_signed()

QSC_EXPORT_API bool qsc_x509_certificate_is_self_signed	(	const qsc_x509_certificate *	certificate,
		qsc_x509_signature_verify_callback	callback,
		void *	state )

Test whether a certificate is self-signed.

Determines whether the certificate is self-issued and whether its signature validates under its own subject public key through the caller-supplied verification callback.

Parameters

certificate	[const][struct] The certificate to inspect.
callback	The caller-supplied signature verification callback.
state	Caller-defined opaque verification context.

Returns: Returns true if the certificate is self-signed; otherwise returns false.

◆ qsc_x509_certificate_verify()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_verify	(	const qsc_x509_certificate *	certificate,
		const qsc_x509_certificate *	issuer,
		const qsc_asn1_time *	now,
		qsc_x509_signature_verify_callback	callback,
		void *	state )

Verify a certificate against its issuer.

Performs core certificate validation, including algorithm checks, validity checks, issuer relationship validation, and cryptographic signature verification through the supplied callback.

Parameters

certificate	[const][struct] The certificate to verify.
issuer	[const][struct] The issuer certificate.
now	[const][struct] The evaluation time.
callback	The caller-supplied signature verification callback.
state	Caller-defined opaque verification context.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_certificate_verify_ex()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_certificate_verify_ex	(	const qsc_x509_certificate *	certificate,
		const qsc_x509_certificate *	issuer,
		const qsc_asn1_time *	now,
		qsc_x509_signature_verify_callback	callback,
		void *	state,
		const qsc_x509_verify_options *	options )

Verify a certificate against its issuer using extended options.

Performs certificate verification with additional policy controls, including requested purpose validation, optional revocation processing, and optional unsupported-critical-extension rejection.

Parameters

certificate	[const][struct] The certificate to verify.
issuer	[const][struct] The issuer certificate.
now	[const][struct] The evaluation time.
callback	The caller-supplied signature verification callback.
state	Caller-defined opaque verification context.
options	[const][struct] Optional extended verification controls.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_chain_is_anchored()

QSC_EXPORT_API bool qsc_x509_chain_is_anchored	(	const qsc_x509_chain *	chain,
		const qsc_x509_store *	store )

Test whether a chain terminates at a trusted anchor.

Determines whether the supplied certification chain is anchored in the provided trust store.

Parameters

chain	[const][struct] The certification chain to inspect.
store	[const][struct] The trust store containing candidate anchors.

Returns: Returns true if the chain is trust-anchored; otherwise returns false.

◆ qsc_x509_chain_verify()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_chain_verify	(	const qsc_x509_chain *	chain,
		const qsc_x509_store *	store,
		const qsc_asn1_time *	now,
		qsc_x509_signature_verify_callback	callback,
		void *	state )

Verify a certification chain.

Performs ordered validation of the certificates in the chain, checks that the path terminates at a trust anchor in the supplied store, and applies cryptographic signature verification through the caller-supplied callback.

Parameters

chain	[const][struct] The certification chain to verify.
store	[const][struct] The trust store containing candidate anchors.
now	[const][struct] The evaluation time.
callback	The caller-supplied signature verification callback.
state	Caller-defined opaque verification context.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_chain_verify_ex()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_chain_verify_ex	(	const qsc_x509_chain *	chain,
		const qsc_x509_store *	store,
		const qsc_asn1_time *	now,
		qsc_x509_signature_verify_callback	callback,
		void *	state,
		const qsc_x509_verify_options *	options )

Verify a certification chain using extended options.

Performs certification-path verification with additional policy controls, including requested purpose validation, optional revocation processing, and optional unsupported-critical-extension rejection.

Parameters

chain	[const][struct] The certification chain to verify.
store	[const][struct] The trust store containing candidate anchors.
now	[const][struct] The evaluation time.
callback	The caller-supplied signature verification callback.
state	Caller-defined opaque verification context.
options	[const][struct] Optional extended verification controls.

Returns: [enum] Returns a qsc_x509_verify_status code.

◆ qsc_x509_verify_options_initialize()

QSC_EXPORT_API void qsc_x509_verify_options_initialize ( qsc_x509_verify_options * options )

Initialize a verification options structure.

Resets the verification options object to a clean default state suitable for subsequent policy configuration.

Parameters

options [struct] The verification options structure to initialize.

Returns: [void] This function does not return a value.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ qsc_x509_signature_verify_callback

Enumeration Type Documentation

◆ qsc_x509_verify_purpose_t

◆ qsc_x509_verify_status_t

Function Documentation

◆ qsc_x509_certificate_allows_client_auth()

◆ qsc_x509_certificate_allows_server_auth()

◆ qsc_x509_certificate_check_algorithms()

◆ qsc_x509_certificate_check_hostname()

◆ qsc_x509_certificate_check_ip_address()

◆ qsc_x509_certificate_check_issuer()

◆ qsc_x509_certificate_check_purpose()

◆ qsc_x509_certificate_check_structure()

◆ qsc_x509_certificate_check_validity()

◆ qsc_x509_certificate_is_ca()

◆ qsc_x509_certificate_is_self_issued()

◆ qsc_x509_certificate_is_self_signed()

◆ qsc_x509_certificate_verify()

◆ qsc_x509_certificate_verify_ex()

◆ qsc_x509_chain_is_anchored()

◆ qsc_x509_chain_verify()

◆ qsc_x509_chain_verify_ex()

◆ qsc_x509_verify_options_initialize()