tlsgroups.h File Reference

TLS named-group descriptors and key-share helper routines. More...

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

Go to the source code of this file.

Data Structures
struct	qsc_tls_group_descriptor
	Describes one supported TLS named group and its wire-format sizes. More...
struct	qsc_tls_key_exchange_state
	Stores ephemeral client-side state for a TLS key exchange. More...

Typedefs
typedef struct qsc_tls_group_descriptor	qsc_tls_group_descriptor
typedef struct qsc_tls_key_exchange_state	qsc_tls_key_exchange_state

Functions
QSC_EXPORT_API const qsc_tls_group_descriptor *	qsc_tls_groups_descriptor_get (qsc_tls_named_group group)
	Get the descriptor for a named group.
QSC_EXPORT_API bool	qsc_tls_groups_is_supported (qsc_tls_named_group group)
	Determine whether a named group is supported in the current build.
QSC_EXPORT_API qsc_tls_status	qsc_tls_groups_generate_client_keypair (qsc_tls_key_exchange_state *state, qsc_tls_named_group group)
	Generate a client ephemeral key pair for a named group.
QSC_EXPORT_API qsc_tls_status	qsc_tls_groups_client_derive_shared_secret (qsc_tls_key_exchange_state *state, const uint8_t *serverkeyshare, size_t serverkeysharelen, uint8_t *sharedsecret, size_t sharedsecretlen, size_t *written)
	Derive the client-side shared secret from the peer server key share.
QSC_EXPORT_API qsc_tls_status	qsc_tls_groups_server_respond (qsc_tls_named_group group, const uint8_t *clientkeyshare, size_t clientkeysharelen, uint8_t *serverkeyshare, size_t serverkeysharelen, size_t *serverkeysharewritten, uint8_t *sharedsecret, size_t sharedsecretlen, size_t *sharedsecretwritten)
	Generate the server response key share and shared secret for an offered client key share.
QSC_EXPORT_API void	qsc_tls_groups_key_exchange_state_dispose (qsc_tls_key_exchange_state *state)
	Dispose of a key-exchange state and zeroize retained key material.

Detailed Description

TLS named-group descriptors and key-share helper routines.

This header maps supported TLS named groups onto the underlying QSC key-exchange primitives. A group may be classical, KEM-based, or hybrid. The descriptor table records the canonical wire sizes used by the ClientHello and ServerHello key-share extensions so callers can validate key-share spans before invoking the primitive.

Function Documentation

qsc_tls_groups_client_derive_shared_secret()

QSC_EXPORT_API qsc_tls_status qsc_tls_groups_client_derive_shared_secret	(	qsc_tls_key_exchange_state *	state,
		const uint8_t *	serverkeyshare,
		size_t	serverkeysharelen,
		uint8_t *	sharedsecret,
		size_t	sharedsecretlen,
		size_t *	written )

Derive the client-side shared secret from the peer server key share.

Validates the server key-share length against the descriptor for the active named group and derives the shared secret or hybrid secret concatenation into the caller-supplied output buffer.

Parameters

state	[struct*] The initialized client key-exchange state.
serverkeyshare	[const uint8_t*] The peer server key-share bytes.
serverkeysharelen	[size_t] The server key-share length in bytes.
sharedsecret	[uint8_t*] The destination buffer for the derived shared secret.
sharedsecretlen	[size_t] The destination buffer length in bytes.
written	[size_t*] Receives the number of bytes written to sharedsecret.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_groups_descriptor_get()

QSC_EXPORT_API const qsc_tls_group_descriptor * qsc_tls_groups_descriptor_get

(

qsc_tls_named_group

group

)

Get the descriptor for a named group.

Parameters

group

[enum] The TLS named group.

Returns

[const qsc_tls_group_descriptor*] Returns a pointer to the descriptor, or NULL if the group is unknown.

qsc_tls_groups_generate_client_keypair()

QSC_EXPORT_API qsc_tls_status qsc_tls_groups_generate_client_keypair	(	qsc_tls_key_exchange_state *	state,
		qsc_tls_named_group	group )

Generate a client ephemeral key pair for a named group.

Clears the state structure, generates the ephemeral private key material, emits the corresponding client key share into the publicshare buffer, and records the selected group and lengths for later shared-secret derivation.

Parameters

state	[struct*] The key-exchange state to initialize.
group	[enum] The named group to generate.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_groups_is_supported()

QSC_EXPORT_API bool qsc_tls_groups_is_supported

(

qsc_tls_named_group

group

)

Determine whether a named group is supported in the current build.

Parameters

group

[enum] The TLS named group.

Returns

[bool] Returns true if the named group is available.

qsc_tls_groups_key_exchange_state_dispose()

QSC_EXPORT_API void qsc_tls_groups_key_exchange_state_dispose

(

qsc_tls_key_exchange_state *

state

)

Dispose of a key-exchange state and zeroize retained key material.

Parameters

state

[struct*] The key-exchange state to clear.

qsc_tls_groups_server_respond()

QSC_EXPORT_API qsc_tls_status qsc_tls_groups_server_respond	(	qsc_tls_named_group	group,
		const uint8_t *	clientkeyshare,
		size_t	clientkeysharelen,
		uint8_t *	serverkeyshare,
		size_t	serverkeysharelen,
		size_t *	serverkeysharewritten,
		uint8_t *	sharedsecret,
		size_t	sharedsecretlen,
		size_t *	sharedsecretwritten )

Generate the server response key share and shared secret for an offered client key share.

Implements the server-side half of the named-group primitive. Depending on the selected group, the function may perform Diffie-Hellman key generation, KEM encapsulation, or a hybrid composition that concatenates multiple component outputs.

Parameters

group	[enum] The negotiated named group.
clientkeyshare	[const uint8_t*] The client key-share bytes.
clientkeysharelen	[size_t] The client key-share length in bytes.
serverkeyshare	[uint8_t*] The destination buffer for the encoded server response key share.
serverkeysharelen	[size_t] The destination buffer length in bytes.
serverkeysharewritten	[size_t*] Receives the number of bytes written to serverkeyshare.
sharedsecret	[uint8_t*] The destination buffer for the derived shared secret.
sharedsecretlen	[size_t] The destination buffer length in bytes.
sharedsecretwritten	[size_t*] Receives the number of bytes written to sharedsecret.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.