TLS certificate bridge types and validation callbacks. More...

#include "qsccommon.h"
#include "tlstypes.h"
#include "tlserrors.h"
#include "x509types.h"
#include "x509time.h"
#include "x509store.h"
#include "x509verify.h"

Data Structures
struct	qsc_tls_certificate_view
	A non-owning view over a single encoded certificate. More...
struct	qsc_tls_certificate_validation_context
	Certificate validation context supplied to chain validators. More...
struct	qsc_tls_certificate_interface
	Certificate validation and signature verification callback set. More...
struct	qsc_tls_peer_certificate_summary
	Fixed peer-certificate identity summary retained by the built-in QSC X.509 TLS bridge. More...
struct	qsc_tls_client_authorization_info
	Bounded client-certificate identity information supplied to an mTLS authorization callback. More...
struct	qsc_tls_qsc_x509_context
	Context for the built-in bridge between TLS and the QSC X.509 layer. More...

Macros
#define	QSC_TLS_CERTIFICATE_FINGERPRINT_SIZE 32U
	Size in bytes of the retained peer certificate fingerprint.

Typedefs
typedef struct qsc_tls_certificate_view	qsc_tls_certificate_view
	A non-owning view over a single encoded certificate.
typedef struct qsc_tls_certificate_validation_context	qsc_tls_certificate_validation_context
	Certificate validation context supplied to chain validators.
typedef bool(*	qsc_tls_certificate_chain_validate_callback) (const qsc_tls_certificate_view chain, size_t chainlength, const qsc_tls_certificate_validation_context context, void *state)
	Validate a peer certificate chain.
typedef bool(*	qsc_tls_certificate_verify_callback) (qsc_tls_signature_scheme scheme, const uint8_t input, size_t inputlen, const uint8_t signature, size_t signaturelen, const qsc_tls_certificate_view signer, void state)
	Verify the TLS CertificateVerify signature.
typedef bool(*	qsc_tls_certificate_sign_callback) (qsc_tls_signature_scheme scheme, const uint8_t input, size_t inputlen, uint8_t signature, size_t signaturelen, void state)
	Produce a TLS 1.3 CertificateVerify signature.
typedef struct qsc_tls_certificate_interface	qsc_tls_certificate_interface
	Certificate validation and signature verification callback set.
typedef struct qsc_tls_peer_certificate_summary	qsc_tls_peer_certificate_summary
	Fixed peer-certificate identity summary retained by the built-in QSC X.509 TLS bridge.
typedef struct qsc_tls_client_authorization_info	qsc_tls_client_authorization_info
typedef bool(*	qsc_tls_client_authorization_callback) (const qsc_tls_client_authorization_info info, void state)
	Authorize a cryptographically valid mTLS client certificate.
typedef struct qsc_tls_qsc_x509_context	qsc_tls_qsc_x509_context
	Context for the built-in bridge between TLS and the QSC X.509 layer.

Functions
QSC_EXPORT_API qsc_tls_status	qsc_tls_certificate_decode_message (const uint8_t input, size_t inlen, const uint8_t requestcontext, size_t requestcontextlen, qsc_tls_certificate_view chain, size_t chaincapacity, size_t chainlength)
	Decode a TLS Certificate message.
QSC_EXPORT_API qsc_tls_status	qsc_tls_certificate_encode_message (const uint8_t requestcontext, size_t requestcontextlen, const qsc_tls_certificate_view chain, size_t chainlength, uint8_t output, size_t outlen, size_t offset)
	Encode a TLS Certificate message.
QSC_EXPORT_API void	qsc_tls_certificate_interface_initialize (qsc_tls_certificate_interface iface, qsc_tls_certificate_chain_validate_callback validatechain, qsc_tls_certificate_verify_callback verifycertificateverify, void state)
	Initialize a certificate callback interface.
QSC_EXPORT_API bool	qsc_tls_certificate_interface_is_valid (const qsc_tls_certificate_interface *iface)
	Determine whether a certificate callback interface is complete.
QSC_EXPORT_API qsc_tls_status	qsc_tls_x509_context_initialize (qsc_tls_qsc_x509_context context, const qsc_x509_store truststore, const qsc_x509_certificate intermediates, size_t intermediatecount, const qsc_x509_time validationtime, uint8_t *verifybuffer, size_t verifybufferlen)
	Initialize a QSC X.509 bridge context.
QSC_EXPORT_API qsc_tls_alert_description	qsc_tls_certificate_interface_get_last_alert (const qsc_tls_certificate_interface *iface, bool verifyphase)
	Query the most recent alert reason from a certificate interface.
QSC_EXPORT_API qsc_tls_status	qsc_tls_certificate_interface_initialize_qsc_x509 (qsc_tls_certificate_interface iface, qsc_tls_qsc_x509_context context)
	Initialize a certificate callback interface using the QSC X.509 bridge.
QSC_EXPORT_API qsc_tls_status	qsc_tls_certificate_request_decode (const uint8_t input, size_t inlen, const uint8_t requestcontext, size_t requestcontextlen, const uint8_t *extensionsblock, size_t extensionsblocklen)
	Decode a TLS CertificateRequest message.
QSC_EXPORT_API qsc_tls_status	qsc_tls_certificate_request_encode (const uint8_t requestcontext, size_t requestcontextlen, const uint8_t extensionsblock, size_t extensionsblocklen, uint8_t output, size_t outlen, size_t offset)
	Encode a TLS CertificateRequest message.
QSC_EXPORT_API qsc_tls_alert_description	qsc_tls_x509_alert_from_verify_status (qsc_x509_verify_status status)
	Map a QSC X.509 verification result to a TLS alert description.
QSC_EXPORT_API qsc_x509_signature_algorithm	qsc_tls_x509_signature_algorithm_from_tls (qsc_tls_signature_scheme scheme)
	Map a TLS signature scheme to a QSC X.509 signature algorithm identifier.
QSC_EXPORT_API bool	qsc_tls_x509_validate_chain (const qsc_tls_certificate_view chain, size_t chainlength, const qsc_tls_certificate_validation_context context, void *state)
	Validate a peer certificate chain using the QSC X.509 bridge.
QSC_EXPORT_API bool	qsc_tls_x509_verify_certificate_verify (qsc_tls_signature_scheme scheme, const uint8_t input, size_t inputlen, const uint8_t signature, size_t signaturelen, const qsc_tls_certificate_view signer, void state)
	Verify a TLS CertificateVerify signature using the QSC X.509 bridge.

Detailed Description

TLS certificate bridge types and validation callbacks.

This header defines the lightweight certificate views, validation context, callback interfaces, and QSC X.509 bridge context used by the TLS implementation when validating peer certificate chains and CertificateVerify signatures.

Typedef Documentation

◆ qsc_tls_certificate_chain_validate_callback

typedef bool(* qsc_tls_certificate_chain_validate_callback) (const qsc_tls_certificate_view *chain, size_t chainlength, const qsc_tls_certificate_validation_context *context, void *state)

Validate a peer certificate chain.

Parameters

chain	[struct*] The certificate chain entries in leaf-first order.
chainlength	[size_t] The number of certificate entries in the chain.
context	[struct*] The certificate validation context.
state	[void*] The caller-supplied callback state.

Returns: [bool] Returns true if the certificate chain is accepted.

◆ qsc_tls_certificate_sign_callback

typedef bool(* qsc_tls_certificate_sign_callback) (qsc_tls_signature_scheme scheme, const uint8_t *input, size_t inputlen, uint8_t *signature, size_t *signaturelen, void *state)

Produce a TLS 1.3 CertificateVerify signature.

Parameters

scheme	[enum] The TLS signature scheme used to sign the input.
input	[const uint8_t*] The formatted TLS 1.3 CertificateVerify input bytes.
inputlen	[size_t] The length of the formatted input in bytes.
signature	[uint8_t*] The destination signature buffer.
signaturelen	[size_t*] On input, the available signature buffer size; on success, the encoded signature length.
state	[void*] The caller-supplied callback state.

Returns: [bool] Returns true if the signature was produced successfully.

◆ qsc_tls_certificate_verify_callback

typedef bool(* qsc_tls_certificate_verify_callback) (qsc_tls_signature_scheme scheme, const uint8_t *input, size_t inputlen, const uint8_t *signature, size_t signaturelen, const qsc_tls_certificate_view *signer, void *state)

Verify the TLS CertificateVerify signature.

Parameters

scheme	[enum] The negotiated TLS signature scheme.
input	[const uint8_t*] The formatted TLS 1.3 CertificateVerify input bytes covered by the signature.
inputlen	[size_t] The length of the formatted input buffer in bytes.
signature	[const uint8_t*] The encoded signature bytes.
signaturelen	[size_t] The length of the signature in bytes.
signer	[struct*] The leaf certificate that provides the public key.
state	[void*] The caller-supplied callback state.

Returns: [bool] Returns true if the signature is valid.

◆ qsc_tls_client_authorization_callback

typedef bool(* qsc_tls_client_authorization_callback) (const qsc_tls_client_authorization_info *info, void *state)

Authorize a cryptographically valid mTLS client certificate.

Parameters

info	[const struct*] Bounded peer-certificate authorization information.
state	[void*] Caller-supplied authorization state.

Returns: [bool] Returns true when the application authorizes the peer.

◆ qsc_tls_peer_certificate_summary

typedef struct qsc_tls_peer_certificate_summary qsc_tls_peer_certificate_summary

Fixed peer-certificate identity summary retained by the built-in QSC X.509 TLS bridge.

The summary contains bounded, zero-terminated diagnostic identity fields copied from the decoded leaf certificate during certificate-chain validation. The structure does not retain DER pointers or heap ownership. It is intended for post-handshake status inspection by higher-level TLS socket callers.

Function Documentation

◆ qsc_tls_certificate_decode_message()

QSC_EXPORT_API qsc_tls_status qsc_tls_certificate_decode_message	(	const uint8_t *	input,
		size_t	inlen,
		const uint8_t **	requestcontext,
		size_t *	requestcontextlen,
		qsc_tls_certificate_view *	chain,
		size_t	chaincapacity,
		size_t *	chainlength )

Decode a TLS Certificate message.

Parses a TLS 1.3 Certificate handshake message and extracts the certificate request context and certificate chain entries as spans into the input buffer.

Parameters

input	[const uint8_t*] Pointer to encoded message buffer
inlen	[size_t] Length of input buffer in bytes
requestcontext	[const uint8_t**] Pointer to decoded request context span
requestcontextlen	[size_t*] Length of request context
chain	[struct] Output array of certificate views
chaincapacity	[size_t] Maximum number of entries in chain array
chainlength	[size_t*] Number of decoded certificates

Returns: qsc_tls_status: Operation status code

◆ qsc_tls_certificate_encode_message()

QSC_EXPORT_API qsc_tls_status qsc_tls_certificate_encode_message	(	const uint8_t *	requestcontext,
		size_t	requestcontextlen,
		const qsc_tls_certificate_view *	chain,
		size_t	chainlength,
		uint8_t *	output,
		size_t	outlen,
		size_t *	offset )

Encode a TLS Certificate message.

Serializes a TLS 1.3 Certificate handshake message containing a certificate request context and a certificate chain. Each certificate entry is encoded as a vector24 with an empty extensions block.

Parameters

requestcontext	[const uint8_t*] Pointer to the certificate request context buffer
requestcontextlen	[size_t] Length of the request context in bytes (<= 255)
chain	[const struct] Pointer to an array of certificate views
chainlength	[size_t] Number of certificates in the chain
output	[uint8_t*] Output buffer for encoded message
outlen	[size_t] Size of the output buffer in bytes
offset	[size_t*] Pointer to current write offset in output buffer

Returns: qsc_tls_status: Operation status code

◆ qsc_tls_certificate_interface_get_last_alert()

QSC_EXPORT_API qsc_tls_alert_description qsc_tls_certificate_interface_get_last_alert	(	const qsc_tls_certificate_interface *	iface,
		bool	verifyphase )

Query the most recent alert reason from a certificate interface.

Returns a certificate-specific TLS alert when the interface uses the built-in QSC X.509 bridge. For custom callbacks, this helper falls back to a generic certificate or CertificateVerify alert according to the verification phase.

Parameters

iface	[struct*] The certificate interface.
verifyphase	[bool] Set true when the failure occurred during CertificateVerify processing.

Returns: [enum] Returns the mapped TLS alert description.

◆ qsc_tls_certificate_interface_initialize()

QSC_EXPORT_API void qsc_tls_certificate_interface_initialize	(	qsc_tls_certificate_interface *	iface,
		qsc_tls_certificate_chain_validate_callback	validatechain,
		qsc_tls_certificate_verify_callback	verifycertificateverify,
		void *	state )

Initialize a certificate callback interface.

Parameters

iface	[struct] The interface structure to initialize.
validatechain	[function] The chain validation callback.
verifycertificateverify	[function] The CertificateVerify callback.
state	[void*] The caller-supplied callback state.

◆ qsc_tls_certificate_interface_initialize_qsc_x509()

QSC_EXPORT_API qsc_tls_status qsc_tls_certificate_interface_initialize_qsc_x509	(	qsc_tls_certificate_interface *	iface,
		qsc_tls_qsc_x509_context *	context )

Initialize a certificate callback interface using the QSC X.509 bridge.

Parameters

iface	[struct] The interface structure to initialize.
context	[struct] The X.509 bridge context.

Returns: [qsc_tls_status] Returns the operation status.

◆ qsc_tls_certificate_interface_is_valid()

QSC_EXPORT_API bool qsc_tls_certificate_interface_is_valid ( const qsc_tls_certificate_interface * iface )

Determine whether a certificate callback interface is complete.

Parameters

iface [struct*] The interface to inspect.

Returns: [bool] Returns true if the required callbacks are present.

◆ qsc_tls_certificate_request_decode()

QSC_EXPORT_API qsc_tls_status qsc_tls_certificate_request_decode	(	const uint8_t *	input,
		size_t	inlen,
		const uint8_t **	requestcontext,
		size_t *	requestcontextlen,
		const uint8_t **	extensionsblock,
		size_t *	extensionsblocklen )

Decode a TLS CertificateRequest message.

Parses a TLS 1.3 CertificateRequest handshake message and extracts the request context and extensions block as spans into the input buffer.

Parameters

input	[const uint8_t*] Pointer to encoded message buffer
inlen	[size_t] Length of input buffer
requestcontext	[const uint8_t**] Pointer to request context span
requestcontextlen	[size_t*] Length of request context
extensionsblock	[const uint8_t**] Pointer to extensions block span
extensionsblocklen	[size_t*] Length of extensions block

Returns: qsc_tls_status: Operation status code

◆ qsc_tls_certificate_request_encode()

QSC_EXPORT_API qsc_tls_status qsc_tls_certificate_request_encode	(	const uint8_t *	requestcontext,
		size_t	requestcontextlen,
		const uint8_t *	extensionsblock,
		size_t	extensionsblocklen,
		uint8_t *	output,
		size_t	outlen,
		size_t *	offset )

Encode a TLS CertificateRequest message.

Serializes a TLS 1.3 CertificateRequest handshake message containing a request context and a pre-encoded extensions block.

Parameters

requestcontext	[const uint8_t*] Pointer to request context buffer
requestcontextlen	[size_t] Length of request context in bytes (<= 255)
extensionsblock	[const uint8_t*] Pointer to extensions block buffer
extensionsblocklen	[size_t] Length of extensions block in bytes
output	[uint8_t*] Output buffer for encoded message
outlen	[size_t] Size of output buffer
offset	[size_t*] Pointer to current write offset

Returns: qsc_tls_status: Operation status code

◆ qsc_tls_x509_alert_from_verify_status()

QSC_EXPORT_API qsc_tls_alert_description qsc_tls_x509_alert_from_verify_status ( qsc_x509_verify_status status )

Map a QSC X.509 verification result to a TLS alert description.

Parameters

status [enum] The QSC X.509 verification status.

Returns: [enum] Returns the mapped TLS alert description.

◆ qsc_tls_x509_context_initialize()

QSC_EXPORT_API qsc_tls_status qsc_tls_x509_context_initialize	(	qsc_tls_qsc_x509_context *	context,
		const qsc_x509_store *	truststore,
		const qsc_x509_certificate *	intermediates,
		size_t	intermediatecount,
		const qsc_x509_time *	validationtime,
		uint8_t *	verifybuffer,
		size_t	verifybufferlen )

Initialize a QSC X.509 bridge context.

Parameters

context	[struct] The context structure to initialize.
truststore	[struct*] The trust store containing the trust anchors.
intermediates	[struct*] Optional intermediate certificates.
intermediatecount	[size_t] The number of intermediate certificates supplied.
validationtime	[struct*] Validation time used during certificate verification.
verifybuffer	[uint8_t*] Scratch buffer used during verification.
verifybufferlen	[size_t] The length of the scratch buffer in bytes.

◆ qsc_tls_x509_signature_algorithm_from_tls()

QSC_EXPORT_API qsc_x509_signature_algorithm qsc_tls_x509_signature_algorithm_from_tls ( qsc_tls_signature_scheme scheme )

Map a TLS signature scheme to a QSC X.509 signature algorithm identifier.

Parameters

scheme [enum] The TLS signature scheme.

Returns: [qsc_x509_signature_algorithm] Returns the mapped X.509 algorithm identifier.

◆ qsc_tls_x509_validate_chain()

QSC_EXPORT_API bool qsc_tls_x509_validate_chain	(	const qsc_tls_certificate_view *	chain,
		size_t	chainlength,
		const qsc_tls_certificate_validation_context *	context,
		void *	state )

Validate a peer certificate chain using the QSC X.509 bridge.

Parameters

chain	[struct*] The certificate chain entries in leaf-first order.
chainlength	[size_t] The number of certificate entries.
context	[struct*] The certificate validation context.
state	[void*] The caller-supplied bridge context.

Returns: [bool] Returns true if the chain is accepted.

◆ qsc_tls_x509_verify_certificate_verify()

QSC_EXPORT_API bool qsc_tls_x509_verify_certificate_verify	(	qsc_tls_signature_scheme	scheme,
		const uint8_t *	input,
		size_t	inputlen,
		const uint8_t *	signature,
		size_t	signaturelen,
		const qsc_tls_certificate_view *	signer,
		void *	state )

Verify a TLS CertificateVerify signature using the QSC X.509 bridge.

Parameters

scheme	[enum] The TLS signature scheme.
transcript	[const uint8_t*] The transcript bytes covered by the signature.
transcriptlen	[size_t] The length of the transcript in bytes.
signature	[const uint8_t*] The encoded signature bytes.
signaturelen	[size_t] The length of the signature in bytes.
signer	[struct*] The signer certificate view.
state	[void*] The caller-supplied bridge context.

Returns: [bool] Returns true if the signature is valid.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ qsc_tls_certificate_chain_validate_callback

◆ qsc_tls_certificate_sign_callback

◆ qsc_tls_certificate_verify_callback

◆ qsc_tls_client_authorization_callback

◆ qsc_tls_peer_certificate_summary

Function Documentation

◆ qsc_tls_certificate_decode_message()

◆ qsc_tls_certificate_encode_message()

◆ qsc_tls_certificate_interface_get_last_alert()

◆ qsc_tls_certificate_interface_initialize()

◆ qsc_tls_certificate_interface_initialize_qsc_x509()

◆ qsc_tls_certificate_interface_is_valid()

◆ qsc_tls_certificate_request_decode()

◆ qsc_tls_certificate_request_encode()

◆ qsc_tls_x509_alert_from_verify_status()

◆ qsc_tls_x509_context_initialize()

◆ qsc_tls_x509_signature_algorithm_from_tls()

◆ qsc_tls_x509_validate_chain()

◆ qsc_tls_x509_verify_certificate_verify()