x509store.h File Reference

X.509 trust-anchor store and certificate chain construction interface. More...

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

Go to the source code of this file.

Functions
QSC_EXPORT_API void	qsc_x509_store_initialize (qsc_x509_store *store, qsc_x509_trust_anchor *anchors, size_t capacity)
	Initialize a certificate store.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_store_add_anchor (qsc_x509_store *store, const qsc_x509_certificate *certificate, bool selfsigned)
	Add a trust anchor to a store from a certificate.
QSC_EXPORT_API const qsc_x509_trust_anchor *	qsc_x509_store_find_anchor_for_certificate (const qsc_x509_store *store, const qsc_x509_certificate *certificate)
	Find a trust anchor applicable to a certificate.
QSC_EXPORT_API const qsc_x509_trust_anchor *	qsc_x509_store_find_anchor_by_subject (const qsc_x509_store *store, const qsc_x509_name *subject)
	Find a trust anchor by subject name.
QSC_EXPORT_API const qsc_x509_trust_anchor *	qsc_x509_store_find_anchor_by_subject_key_identifier (const qsc_x509_store *store, const uint8_t *keyidentifier, size_t keyidentifierlen)
	Find a trust anchor by Subject Key Identifier.
QSC_EXPORT_API bool	qsc_x509_store_contains_anchor (const qsc_x509_store *store, const qsc_x509_certificate *certificate)
	Test whether a store contains a certificate as a trust anchor.
QSC_EXPORT_API const qsc_x509_certificate *	qsc_x509_store_find_issuer (const qsc_x509_store *store, const qsc_x509_certificate *certificate)
	Find an issuer certificate in the trust store.
QSC_EXPORT_API qsc_x509_verify_status	qsc_x509_chain_build (const qsc_x509_certificate *leaf, const qsc_x509_certificate *intermediates, size_t intermediatecount, const qsc_x509_store *store, qsc_x509_certificate *output, size_t outputcount, qsc_x509_chain *chain)
	Build a certification chain from a leaf certificate to a trust anchor.

Detailed Description

X.509 trust-anchor store and certificate chain construction interface.

This header defines helper functions used to initialize and query a trust store composed of X.509 trust anchors, to add anchors derived from certificates, to locate anchors and issuers by subject and key identifier, and to build a candidate certification path from a leaf certificate through intermediates to a trusted anchor.

The store interface operates on caller-supplied trust-anchor storage and does not allocate memory internally. Chain construction similarly writes the resulting certificate path into caller-managed output storage and a chain descriptor object.

Function Documentation

qsc_x509_chain_build()

QSC_EXPORT_API qsc_x509_verify_status qsc_x509_chain_build	(	const qsc_x509_certificate *	leaf,
		const qsc_x509_certificate *	intermediates,
		size_t	intermediatecount,
		const qsc_x509_store *	store,
		qsc_x509_certificate *	output,
		size_t	outputcount,
		qsc_x509_chain *	chain )

Build a certification chain from a leaf certificate to a trust anchor.

Attempts to construct a certificate path beginning at the supplied leaf certificate, proceeding through the provided intermediate certificates, and terminating at a trusted anchor in the store. The resulting ordered path is written to the caller-supplied output certificate array and summarized in the destination chain object.

Parameters

leaf	[const][struct] The leaf certificate from which path construction begins.
intermediates	[const][struct] The intermediate certificate array available for path building.
intermediatecount	The number of certificates in intermediates.
store	[const][struct] The trust store containing candidate trust anchors.
output	[struct] The destination certificate array receiving the constructed path.
outputcount	The number of certificate elements available in output.
chain	[struct] The destination chain descriptor object.

Returns

[enum] Returns a qsc_x509_verify_status code describing the chain build result.

qsc_x509_store_add_anchor()

QSC_EXPORT_API qsc_asn1_status qsc_x509_store_add_anchor	(	qsc_x509_store *	store,
		const qsc_x509_certificate *	certificate,
		bool	selfsigned )

Add a trust anchor to a store from a certificate.

Converts the supplied certificate into a trust-anchor representation and adds it to the store, subject to the specified anchor storage capacity. The caller indicates whether the certificate should be treated as self-signed for anchor construction purposes.

Parameters

store	[struct] The destination trust store.
certificate	[const][struct] The certificate to add as a trust anchor.
selfsigned	Indicates whether the certificate is self-signed.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_store_contains_anchor()

QSC_EXPORT_API bool qsc_x509_store_contains_anchor	(	const qsc_x509_store *	store,
		const qsc_x509_certificate *	certificate )

Test whether a store contains a certificate as a trust anchor.

Compares the supplied certificate against the anchors present in the store and reports whether an equivalent anchor is already available.

Parameters

store	[const][struct] The trust store to inspect.
certificate	[const][struct] The certificate to test.

Returns

Returns true if the store contains a matching trust anchor; otherwise returns false.

qsc_x509_store_find_anchor_by_subject()

QSC_EXPORT_API const qsc_x509_trust_anchor * qsc_x509_store_find_anchor_by_subject	(	const qsc_x509_store *	store,
		const qsc_x509_name *	subject )

Find a trust anchor by subject name.

Searches the store for a trust anchor whose subject distinguished name matches the supplied X.509 name object.

Parameters

store	[const][struct] The trust store to search.
subject	[const][struct] The subject distinguished name to match.

Returns

Returns a pointer to the matching trust anchor, or NULL if no match is found.

qsc_x509_store_find_anchor_by_subject_key_identifier()

QSC_EXPORT_API const qsc_x509_trust_anchor * qsc_x509_store_find_anchor_by_subject_key_identifier	(	const qsc_x509_store *	store,
		const uint8_t *	keyidentifier,
		size_t	keyidentifierlen )

Find a trust anchor by Subject Key Identifier.

Searches the store for a trust anchor whose Subject Key Identifier matches the supplied key identifier byte string.

Parameters

store	[const][struct] The trust store to search.
keyidentifier	[const] The Subject Key Identifier bytes to match.
keyidentifierlen	The length of the key identifier in bytes.

Returns

Returns a pointer to the matching trust anchor, or NULL if no match is found.

qsc_x509_store_find_anchor_for_certificate()

QSC_EXPORT_API const qsc_x509_trust_anchor * qsc_x509_store_find_anchor_for_certificate	(	const qsc_x509_store *	store,
		const qsc_x509_certificate *	certificate )

Find a trust anchor applicable to a certificate.

Searches the store for a trust anchor that matches the issuer or trust relationship requirements of the supplied certificate.

Parameters

store	[const][struct] The trust store to search.
certificate	[const][struct] The certificate for which a matching anchor is sought.

Returns

Returns a pointer to the matching trust anchor, or NULL if no suitable anchor is found.

qsc_x509_store_find_issuer()

QSC_EXPORT_API const qsc_x509_certificate * qsc_x509_store_find_issuer	(	const qsc_x509_store *	store,
		const qsc_x509_certificate *	certificate )

Find an issuer certificate in the trust store.

Searches the trust store for a certificate that can act as the issuer of the supplied certificate, typically by subject and authority key identifier matching.

Parameters

store	[const][struct] The trust store to search.
certificate	[const][struct] The certificate whose issuer is sought.

Returns

Returns a pointer to the matching issuer certificate, or NULL if no issuer is found.

qsc_x509_store_initialize()

QSC_EXPORT_API void qsc_x509_store_initialize	(	qsc_x509_store *	store,
		qsc_x509_trust_anchor *	anchors,
		size_t	capacity )

Initialize a certificate store.

Initializes a certificate store with a caller-provided buffer. The store starts empty. Anchors must be added using qsc_x509_store_add_anchor().

Parameters

store	[struct] Store instance.
anchors	[array] Caller-allocated array of anchor pointers.
capacity	[size_t] Number of entries the array can hold.