TLS 1.3 extension encoding, decoding, validation, and selection helpers. More...

#include "qsccommon.h"
#include "tlserrors.h"
#include "tlstypes.h"
#include "tlslimits.h"
#include "tlsstate.h"

Data Structures
struct	qsc_tls_extension_bitmap
	Tracks extension types observed while parsing one TLS handshake message. More...
struct	qsc_tls_psk_identity_view
	Non-owning view of a TLS pre-shared-key identity. More...

Typedefs
typedef struct qsc_tls_extension_bitmap	qsc_tls_extension_bitmap
typedef struct qsc_tls_psk_identity_view	qsc_tls_psk_identity_view

Functions
QSC_EXPORT_API void	qsc_tls_extensions_bitmap_initialize (qsc_tls_extension_bitmap *bitmap)
	Reset a TLS extension appearance bitmap.
QSC_EXPORT_API bool	qsc_tls_extensions_bitmap_set (qsc_tls_extension_bitmap *bitmap, uint16_t extensiontype)
	Mark an extension type as present in an appearance bitmap.
QSC_EXPORT_API bool	qsc_tls_extensions_is_permitted (qsc_tls_handshake_type message, qsc_tls_extension_type extensiontype)
	Test whether an extension is permitted in a handshake message.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_supported_versions_client (uint8_t output, size_t outlen, size_t offset)
	Encode the ClientHello supported_versions extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_supported_versions_server (uint8_t output, size_t outlen, size_t offset)
	Encode the ServerHello supported_versions extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_supported_groups (uint8_t output, size_t outlen, size_t offset, const qsc_tls_named_group *groups, size_t groupcount)
	Encode the supported_groups extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_signature_algorithms (uint8_t output, size_t outlen, size_t offset, const qsc_tls_signature_scheme *schemes, size_t schemecount)
	Encode the signature_algorithms extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_signature_algorithms_cert (uint8_t output, size_t outlen, size_t offset, const qsc_tls_signature_scheme *schemes, size_t schemecount)
	Encode the signature_algorithms_cert extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_key_share_client (uint8_t output, size_t outlen, size_t offset, qsc_tls_named_group group, const uint8_t *publicshare, size_t publicsharelen)
	Encode the ClientHello key_share extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_key_share_server (uint8_t output, size_t outlen, size_t offset, qsc_tls_named_group group, const uint8_t *publicshare, size_t publicsharelen)
	Encode the ServerHello key_share extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_key_share_hello_retry (uint8_t output, size_t outlen, size_t offset, qsc_tls_named_group group)
	Encode the HelloRetryRequest key_share extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_server_name (uint8_t output, size_t outlen, size_t offset, const char *hostname)
	Encode the server_name extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_alpn (uint8_t output, size_t outlen, size_t offset, const qsc_tls_alpn_protocols *alpn)
	Encode the application_layer_protocol_negotiation extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_alpn (const uint8_t input, size_t inplen, qsc_tls_alpn_protocols alpn)
	Decode the application_layer_protocol_negotiation extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_select_alpn (const qsc_tls_alpn_protocols clientalpn, const qsc_tls_alpn_protocols serveralpn, uint8_t selected, size_t selectedcap, size_t selectedlen)
	Select a mutually supported ALPN protocol.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_psk_key_exchange_modes (uint8_t output, size_t outlen, size_t offset, const uint8_t *modes, size_t modecount)
	Encode the psk_key_exchange_modes extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_early_data_empty (uint8_t output, size_t outlen, size_t offset)
	Encode an empty early_data extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_early_data_max (uint8_t output, size_t outlen, size_t offset, uint32_t maxearlydatasize)
	Encode an early_data maximum-size extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_early_data_max (const uint8_t input, size_t inplen, uint32_t maxearlydatasize)
	Decode an early_data maximum-size extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_pre_shared_key_offer (uint8_t output, size_t outlen, size_t offset, const qsc_tls_psk_identity_view identities, size_t identitycount, size_t binderlen, size_t binderoffset)
	Encode a ClientHello pre_shared_key extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_encode_pre_shared_key_server (uint8_t output, size_t outlen, size_t offset, uint16_t selidentity)
	Encode a ServerHello pre_shared_key extension.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_pre_shared_key_offer (const uint8_t input, size_t inplen, qsc_tls_psk_identity_view identities, const uint8_t *binders, size_t binderlens, size_t capacity, size_t count, size_t binderblockoffset)
	Decode a ClientHello pre_shared_key extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_pre_shared_key_server (const uint8_t input, size_t inplen, uint16_t selidentity)
	Decode a ServerHello pre_shared_key extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_supported_versions_client (const uint8_t input, size_t inplen, bool acceptstls13)
	Decode a ClientHello supported_versions extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_supported_versions_server (const uint8_t input, size_t inplen, uint16_t selectedversion)
	Decode a ServerHello supported_versions extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_supported_groups (const uint8_t input, size_t inplen, qsc_tls_named_group groups, size_t groupcapacity, size_t *groupcount)
	Decode a supported_groups extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_signature_algorithms (const uint8_t input, size_t inplen, qsc_tls_signature_scheme schemes, size_t schemecapacity, size_t *schemecount)
	Decode a signature_algorithms extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_key_share_client_hello (const uint8_t input, size_t inplen, qsc_tls_named_group groups, const uint8_t *shares, size_t sharelens, size_t capacity, size_t *count)
	Decode a ClientHello key_share extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_key_share_server_hello (const uint8_t input, size_t inplen, qsc_tls_named_group selectedgroup, const uint8_t *share, size_t sharelen)
	Decode a ServerHello key_share extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_key_share_hello_retry (const uint8_t input, size_t inplen, qsc_tls_named_group requestedgroup)
	Decode a HelloRetryRequest key_share extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_decode_server_name (const uint8_t input, size_t inplen, const char hostname, size_t hostnamelen)
	Decode a server_name extension body.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_select_cipher_suite (const uint8_t clientsuites, size_t clientsuiteslen, const qsc_tls_cipher_suite serverpreference, size_t serverpreferencecount, qsc_tls_cipher_suite *selected)
	Select a mutually supported cipher suite.
QSC_EXPORT_API qsc_tls_status	qsc_tls_extensions_select_key_share (const qsc_tls_named_group groups, size_t groupcount, const qsc_tls_named_group serverpreference, size_t serverpreferencecount, qsc_tls_named_group *selected)
	Select a mutually supported key-share group.

Detailed Description

TLS 1.3 extension encoding, decoding, validation, and selection helpers.

This header defines the extension-layer utility interface used by the QSC TLS 1.3 implementation. The functions in this interface encode supported TLS extension bodies into caller-owned handshake buffers, decode received extension bodies into bounded output structures, enforce extension placement rules, track duplicate extension appearances, and select mutually supported cipher suites and key-share groups.

Encoders write complete extension records, including the extension type and extension-data length field. Decoders generally expect the extension body only, after the extension type and extension-data length have already been parsed by the caller. Span-returning decoders return pointers into the supplied input buffer; those pointers remain valid only while the original input buffer remains valid.

Function Documentation

◆ qsc_tls_extensions_bitmap_initialize()

QSC_EXPORT_API void qsc_tls_extensions_bitmap_initialize ( qsc_tls_extension_bitmap * bitmap )

Reset a TLS extension appearance bitmap.

Clears all extension tracking masks in the supplied bitmap. The bitmap is used while parsing a single handshake message to detect duplicate extensions.

Parameters

bitmap [qsc_tls_extension_bitmap*] Pointer to the extension bitmap to initialize.

◆ qsc_tls_extensions_bitmap_set()

QSC_EXPORT_API bool qsc_tls_extensions_bitmap_set	(	qsc_tls_extension_bitmap *	bitmap,
		uint16_t	extensiontype )

Mark an extension type as present in an appearance bitmap.

Sets the bit associated with an extension type and reports whether the extension was newly recorded. This function is used to enforce the TLS 1.3 rule that an extension shall not appear more than once in the same extension block.

Parameters

bitmap	[qsc_tls_extension_bitmap*] Pointer to the extension appearance bitmap.
extensiontype	[uint16_t] The numeric TLS extension type to mark.

Returns: [bool] Returns true if the extension was newly added; otherwise returns false if the extension was already present or the bitmap is NULL.

◆ qsc_tls_extensions_decode_alpn()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_alpn	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_alpn_protocols *	alpn )

Decode the application_layer_protocol_negotiation extension body.

Parses an ALPN ProtocolNameList extension body into a bounded output policy container. Zero-length protocol identifiers, overlong identifiers, duplicate identifiers, and excess protocol entries are rejected.

Parameters

input	[const uint8_t*] Pointer to the ALPN extension body.
inplen	[size_t] Length, in bytes, of the ALPN extension body.
alpn	[struct*] Pointer to the output ALPN protocol-list container.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_early_data_max()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_early_data_max	(	const uint8_t *	input,
		size_t	inplen,
		uint32_t *	maxearlydatasize )

Decode an early_data maximum-size extension body.

Parses a NewSessionTicket early_data extension body and returns the max_early_data_size value.

Parameters

input	[const uint8_t*] Pointer to the encoded early_data extension body.
inplen	[size_t] Length, in bytes, of the encoded extension body.
maxearlydatasize	[uint32_t*] Pointer receiving the decoded maximum early-data size.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_key_share_client_hello()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_key_share_client_hello	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_named_group *	groups,
		const uint8_t **	shares,
		size_t *	sharelens,
		size_t	capacity,
		size_t *	count )

Decode a ClientHello key_share extension body.

Parses a ClientHello key_share vector into non-owning group and public-share spans. The share pointers refer directly to the supplied input buffer.

Parameters

input	[const uint8_t*] Pointer to the encoded key_share extension body.
inplen	[size_t] Length, in bytes, of the encoded body.
groups	[qsc_tls_named_group*] Pointer to the output named-group array.
shares	[const uint8_t**] Pointer to the output public-share pointer array.
sharelens	[size_t*] Pointer to the output public-share length array.
capacity	[size_t] Maximum number of key-share entries that may be written to the output arrays.
count	[size_t*] Pointer receiving the number of decoded key-share entries.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_key_share_hello_retry()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_key_share_hello_retry	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_named_group *	requestedgroup )

Decode a HelloRetryRequest key_share extension body.

Parses the requested named group from a HelloRetryRequest key_share extension body.

Parameters

input	[const uint8_t*] Pointer to the encoded key_share extension body.
inplen	[size_t] Length, in bytes, of the encoded body.
requestedgroup	[qsc_tls_named_group*] Pointer receiving the requested named group.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_key_share_server_hello()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_key_share_server_hello	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_named_group *	selectedgroup,
		const uint8_t **	share,
		size_t *	sharelen )

Decode a ServerHello key_share extension body.

Parses the selected named group and server public-share span from a ServerHello key_share extension body. The returned share pointer refers directly to the supplied input buffer.

Parameters

input	[const uint8_t*] Pointer to the encoded key_share extension body.
inplen	[size_t] Length, in bytes, of the encoded body.
selectedgroup	[qsc_tls_named_group*] Pointer receiving the selected named group.
share	[const uint8_t**] Pointer receiving the public-share span.
sharelen	[size_t*] Pointer receiving the public-share length, in bytes.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_pre_shared_key_offer()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_pre_shared_key_offer	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_psk_identity_view *	identities,
		const uint8_t **	binders,
		size_t *	binderlens,
		size_t	capacity,
		size_t *	count,
		size_t *	binderblockoffset )

Decode a ClientHello pre_shared_key extension body.

Parses an OfferedPsks body into PSK identity views and binder spans. The views point directly into the supplied input buffer and remain valid only while that buffer remains valid. The function also returns the offset of the binders-list length prefix so the caller can recompute binders over the correctly truncated ClientHello transcript.

Parameters

input	[const uint8_t*] Pointer to the encoded pre_shared_key extension body.
inplen	[size_t] Length, in bytes, of the encoded extension body.
identities	[qsc_tls_psk_identity_view*] Pointer to the output identity view array.
binders	[const uint8_t**] Pointer to the output binder span array.
binderlens	[size_t*] Pointer to the output binder-length array.
capacity	[size_t] Maximum number of identities and binders that can be written to the output arrays.
count	[size_t*] Pointer receiving the number of identities and binders parsed.
binderblockoffset	[size_t*] Pointer receiving the offset of the binders-list length prefix within input.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_pre_shared_key_server()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_pre_shared_key_server	(	const uint8_t *	input,
		size_t	inplen,
		uint16_t *	selidentity )

Decode a ServerHello pre_shared_key extension body.

Parses a ServerHello pre_shared_key extension body and returns the selected PSK identity index.

Parameters

input	[const uint8_t*] Pointer to the encoded pre_shared_key extension body.
inplen	[size_t] Length, in bytes, of the encoded extension body.
selidentity	[uint16_t*] Pointer receiving the selected PSK identity index.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_server_name()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_server_name	(	const uint8_t *	input,
		size_t	inplen,
		const char **	hostname,
		size_t *	hostnamelen )

Decode a server_name extension body.

Parses a server_name extension containing a host_name entry. The returned hostname pointer refers directly to the supplied input buffer and is not NULL-terminated.

Parameters

input	[const uint8_t*] Pointer to the encoded server_name extension body.
inplen	[size_t] Length, in bytes, of the encoded body.
hostname	[const char**] Pointer receiving the hostname span.
hostnamelen	[size_t*] Pointer receiving the hostname length, in bytes.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_signature_algorithms()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_signature_algorithms	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_signature_scheme *	schemes,
		size_t	schemecapacity,
		size_t *	schemecount )

Decode a signature_algorithms extension body.

Parses a signature-scheme vector and writes the decoded schemes to the caller-provided output array. This decoder is suitable for both signature_algorithms and signature_algorithms_cert bodies when the wire format is identical.

Parameters

input	[const uint8_t*] Pointer to the encoded signature-scheme vector body.
inplen	[size_t] Length, in bytes, of the encoded body.
schemes	[qsc_tls_signature_scheme*] Pointer to the output scheme array.
schemecapacity	[size_t] Maximum number of scheme entries that may be written to schemes.
schemecount	[size_t*] Pointer receiving the number of decoded schemes.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_supported_groups()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_supported_groups	(	const uint8_t *	input,
		size_t	inplen,
		qsc_tls_named_group *	groups,
		size_t	groupcapacity,
		size_t *	groupcount )

Decode a supported_groups extension body.

Parses the named-group vector from a supported_groups extension body and writes the decoded groups to the caller-provided output array.

Parameters

input	[const uint8_t*] Pointer to the encoded supported_groups body.
inplen	[size_t] Length, in bytes, of the encoded body.
groups	[qsc_tls_named_group*] Pointer to the output named-group array.
groupcapacity	[size_t] Maximum number of group entries that may be written to groups.
groupcount	[size_t*] Pointer receiving the number of decoded groups.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_supported_versions_client()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_supported_versions_client	(	const uint8_t *	input,
		size_t	inplen,
		bool *	acceptstls13 )

Decode a ClientHello supported_versions extension body.

Parses the ClientHello supported_versions vector and reports whether TLS 1.3 is present in the advertised version list.

Parameters

input	[const uint8_t*] Pointer to the encoded supported_versions body.
inplen	[size_t] Length, in bytes, of the encoded body.
acceptstls13	[bool*] Pointer receiving true if TLS 1.3 is advertised.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_decode_supported_versions_server()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_decode_supported_versions_server	(	const uint8_t *	input,
		size_t	inplen,
		uint16_t *	selectedversion )

Decode a ServerHello supported_versions extension body.

Parses the selected protocol version from a ServerHello supported_versions extension body.

Parameters

input	[const uint8_t*] Pointer to the encoded supported_versions body.
inplen	[size_t] Length, in bytes, of the encoded body.
selectedversion	[uint16_t*] Pointer receiving the selected protocol version.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_alpn()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_alpn	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const qsc_tls_alpn_protocols *	alpn )

Encode the application_layer_protocol_negotiation extension.

Writes an ALPN extension containing the ordered protocol identifiers stored in the supplied bounded policy. Each protocol identifier is encoded as an opaque ProtocolName vector and must have non-zero length.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
alpn	[const struct*] Pointer to the bounded ALPN protocol-list policy.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_early_data_empty()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_early_data_empty	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset )

Encode an empty early_data extension.

Writes an early_data extension with a zero-length body. This form is used in ClientHello and EncryptedExtensions contexts.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_early_data_max()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_early_data_max	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		uint32_t	maxearlydatasize )

Encode an early_data maximum-size extension.

Writes an early_data extension containing the max_early_data_size value used in a NewSessionTicket context.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
maxearlydatasize	[uint32_t] Maximum permitted early-data size, in bytes.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_key_share_client()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_key_share_client	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		qsc_tls_named_group	group,
		const uint8_t *	publicshare,
		size_t	publicsharelen )

Encode the ClientHello key_share extension.

Writes a ClientHello key_share extension containing one KeyShareEntry. The entry contains the named group identifier and the public key-exchange share.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
group	[qsc_tls_named_group] The named group associated with the public share.
publicshare	[const uint8_t*] Pointer to the public key-exchange share.
publicsharelen	[size_t] Length, in bytes, of the public share.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_key_share_hello_retry()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_key_share_hello_retry	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		qsc_tls_named_group	group )

Encode the HelloRetryRequest key_share extension.

Writes a key_share extension in HelloRetryRequest form. The encoded body contains only the requested named group identifier.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
group	[qsc_tls_named_group] The named group requested by the server.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_key_share_server()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_key_share_server	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		qsc_tls_named_group	group,
		const uint8_t *	publicshare,
		size_t	publicsharelen )

Encode the ServerHello key_share extension.

Writes a ServerHello key_share extension containing the selected named group and the server public key-exchange share.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
group	[qsc_tls_named_group] The selected named group.
publicshare	[const uint8_t*] Pointer to the server public share.
publicsharelen	[size_t] Length, in bytes, of the public share.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_pre_shared_key_offer()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_pre_shared_key_offer	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const qsc_tls_psk_identity_view *	identities,
		size_t	identitycount,
		size_t	binderlen,
		size_t *	binderoffset )

Encode a ClientHello pre_shared_key extension.

Writes a ClientHello pre_shared_key extension body containing OfferedPsks. The identities vector is encoded first, followed by a binders vector. Binder entries are emitted as zero-filled placeholders of the requested length. The caller must compute and backpatch the real binder values after hashing the truncated ClientHello transcript.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
identities	[const qsc_tls_psk_identity_view*] Pointer to the PSK identity view array.
identitycount	[size_t] Number of PSK identities to encode.
binderlen	[size_t] Length, in bytes, of each binder placeholder.
binderoffset	[size_t*] Pointer receiving the absolute output offset of the first binder byte.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_pre_shared_key_server()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_pre_shared_key_server	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		uint16_t	selidentity )

Encode a ServerHello pre_shared_key extension.

Writes a ServerHello pre_shared_key extension containing the selected PSK identity index.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
selidentity	[uint16_t] The selected PSK identity index.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_psk_key_exchange_modes()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_psk_key_exchange_modes	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const uint8_t *	modes,
		size_t	modecount )

Encode the psk_key_exchange_modes extension.

Writes a psk_key_exchange_modes extension containing the supplied list of PSK key exchange mode identifiers.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
modes	[const uint8_t*] Pointer to the PSK key exchange mode list.
modecount	[size_t] Number of mode identifiers in the list.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_server_name()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_server_name	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const char *	hostname )

Encode the server_name extension.

Writes a server_name extension containing a single host_name entry. The hostname is copied without a terminating NULL byte.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
hostname	[const char*] Pointer to the NULL-terminated hostname string.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_signature_algorithms()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_signature_algorithms	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const qsc_tls_signature_scheme *	schemes,
		size_t	schemecount )

Encode the signature_algorithms extension.

Writes a signature_algorithms extension containing the supplied ordered list of supported signature schemes.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
schemes	[const qsc_tls_signature_scheme*] Pointer to the signature scheme list.
schemecount	[size_t] Number of entries in the signature scheme list.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_signature_algorithms_cert()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_signature_algorithms_cert	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const qsc_tls_signature_scheme *	schemes,
		size_t	schemecount )

Encode the signature_algorithms_cert extension.

Writes a signature_algorithms_cert extension containing the supplied ordered list of supported certificate signature schemes.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
schemes	[const qsc_tls_signature_scheme*] Pointer to the certificate signature scheme list.
schemecount	[size_t] Number of entries in the certificate signature scheme list.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_supported_groups()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_supported_groups	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset,
		const qsc_tls_named_group *	groups,
		size_t	groupcount )

Encode the supported_groups extension.

Writes a supported_groups extension containing the supplied ordered list of named groups.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.
groups	[const qsc_tls_named_group*] Pointer to the named-group list.
groupcount	[size_t] Number of entries in the named-group list.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_encode_supported_versions_client()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_supported_versions_client	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset )

Encode the ClientHello supported_versions extension.

Writes a TLS supported_versions extension in ClientHello format. The encoded extension advertises TLS 1.3 as the supported protocol version.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success,.

◆ qsc_tls_extensions_encode_supported_versions_server()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_encode_supported_versions_server	(	uint8_t *	output,
		size_t	outlen,
		size_t *	offset )

Encode the ServerHello supported_versions extension.

Writes a TLS supported_versions extension in ServerHello format. The encoded extension contains the selected TLS 1.3 protocol version.

Parameters

output	[uint8_t*] Pointer to the destination extension buffer.
outlen	[size_t] Size, in bytes, of the destination buffer.
offset	[size_t*] Pointer to the current write offset; updated on success.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_is_permitted()

QSC_EXPORT_API bool qsc_tls_extensions_is_permitted	(	qsc_tls_handshake_type	message,
		qsc_tls_extension_type	extensiontype )

Test whether an extension is permitted in a handshake message.

Applies TLS 1.3 extension placement rules for the extension types supported by this implementation. The function returns true only when the specified extension type is valid for the supplied handshake message type.

Parameters

message	[qsc_tls_handshake_type] The TLS handshake message type being parsed or constructed.
extensiontype	[qsc_tls_extension_type] The TLS extension type to test.

Returns: [bool] Returns true if the extension is permitted in the specified message; otherwise returns false.

◆ qsc_tls_extensions_select_alpn()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_select_alpn	(	const qsc_tls_alpn_protocols *	clientalpn,
		const qsc_tls_alpn_protocols *	serveralpn,
		uint8_t *	selected,
		size_t	selectedcap,
		size_t *	selectedlen )

Select a mutually supported ALPN protocol.

Selects the first server-preferred protocol that appears in the client protocol list.

Parameters

clientalpn	[const struct*] Pointer to the decoded client ALPN list.
serveralpn	[const struct*] Pointer to the server ALPN policy.
selected	[uint8_t*] Pointer to the selected protocol output buffer.
selectedcap	[size_t] Size, in bytes, of the selected protocol output buffer.
selectedlen	[size_t*] Receives the selected protocol length in bytes.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_select_cipher_suite()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_select_cipher_suite	(	const uint8_t *	clientsuites,
		size_t	clientsuiteslen,
		const qsc_tls_cipher_suite *	serverpreference,
		size_t	serverpreferencecount,
		qsc_tls_cipher_suite *	selected )

Select a mutually supported cipher suite.

Selects the first server-preferred cipher suite that appears in the serialized client cipher-suite vector. The client vector is expected to contain the inner cipher-suite list bytes, encoded as two-byte suite identifiers.

Parameters

clientsuites	[const uint8_t*] Pointer to the serialized client cipher-suite list.
clientsuiteslen	[size_t] Length, in bytes, of the client cipher-suite list.
serverpreference	[const qsc_tls_cipher_suite*] Pointer to the ordered server cipher-suite preference list.
serverpreferencecount	[size_t] Number of entries in the server preference list.
selected	[qsc_tls_cipher_suite*] Pointer receiving the selected cipher suite.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

◆ qsc_tls_extensions_select_key_share()

QSC_EXPORT_API qsc_tls_status qsc_tls_extensions_select_key_share	(	const qsc_tls_named_group *	groups,
		size_t	groupcount,
		const qsc_tls_named_group *	serverpreference,
		size_t	serverpreferencecount,
		qsc_tls_named_group *	selected )

Select a mutually supported key-share group.

Selects the first server-preferred named group that appears in the client group list.

Parameters

groups	[const qsc_tls_named_group*] Pointer to the client named-group list.
groupcount	[size_t] Number of entries in the client named-group list.
serverpreference	[const qsc_tls_named_group*] Pointer to the ordered server named-group preference list.
serverpreferencecount	[size_t] Number of entries in the server preference list.
selected	[qsc_tls_named_group*] Pointer receiving the selected named group.

Returns: [qsc_tls_status] Returns qsc_tls_status_success on success.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation

◆ qsc_tls_extensions_bitmap_initialize()

◆ qsc_tls_extensions_bitmap_set()

◆ qsc_tls_extensions_decode_alpn()

◆ qsc_tls_extensions_decode_early_data_max()

◆ qsc_tls_extensions_decode_key_share_client_hello()

◆ qsc_tls_extensions_decode_key_share_hello_retry()

◆ qsc_tls_extensions_decode_key_share_server_hello()

◆ qsc_tls_extensions_decode_pre_shared_key_offer()

◆ qsc_tls_extensions_decode_pre_shared_key_server()

◆ qsc_tls_extensions_decode_server_name()

◆ qsc_tls_extensions_decode_signature_algorithms()

◆ qsc_tls_extensions_decode_supported_groups()

◆ qsc_tls_extensions_decode_supported_versions_client()

◆ qsc_tls_extensions_decode_supported_versions_server()

◆ qsc_tls_extensions_encode_alpn()

◆ qsc_tls_extensions_encode_early_data_empty()

◆ qsc_tls_extensions_encode_early_data_max()

◆ qsc_tls_extensions_encode_key_share_client()

◆ qsc_tls_extensions_encode_key_share_hello_retry()

◆ qsc_tls_extensions_encode_key_share_server()

◆ qsc_tls_extensions_encode_pre_shared_key_offer()

◆ qsc_tls_extensions_encode_pre_shared_key_server()

◆ qsc_tls_extensions_encode_psk_key_exchange_modes()

◆ qsc_tls_extensions_encode_server_name()

◆ qsc_tls_extensions_encode_signature_algorithms()

◆ qsc_tls_extensions_encode_signature_algorithms_cert()

◆ qsc_tls_extensions_encode_supported_groups()

◆ qsc_tls_extensions_encode_supported_versions_client()

◆ qsc_tls_extensions_encode_supported_versions_server()

◆ qsc_tls_extensions_is_permitted()

◆ qsc_tls_extensions_select_alpn()

◆ qsc_tls_extensions_select_cipher_suite()

◆ qsc_tls_extensions_select_key_share()