tlsrecord.h File Reference

TLS record formatting and protection helpers. More...

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

Go to the source code of this file.

Functions
QSC_EXPORT_API void	qsc_tls_record_state_initialize (qsc_tls_record_state *state, qsc_tls_cipher_suite suite, const uint8_t *key, size_t keylen, const uint8_t *iv, size_t ivlen)
	Initialize a TLS record protection state.
QSC_EXPORT_API void	qsc_tls_record_state_dispose (qsc_tls_record_state *state)
	Dispose of a TLS record protection state.
QSC_EXPORT_API qsc_tls_status	qsc_tls_record_state_install_keys (qsc_tls_record_state *state, qsc_tls_cipher_suite suite, const uint8_t *key, size_t keylen, const uint8_t *iv, size_t ivlen)
	Install or replace traffic keys on an existing record state, resetting the sequence.
QSC_EXPORT_API uint64_t	qsc_tls_record_state_get_sequence (const qsc_tls_record_state *state)
	Read the current sequence number. Returns 0 when state is NULL or uninitialized.
QSC_EXPORT_API qsc_tls_status	qsc_tls_record_encode_plaintext (uint8_t *output, size_t outlen, size_t *written, qsc_tls_record_content_type type, const uint8_t *input, size_t inlen)
	Encode a plaintext TLS record.
QSC_EXPORT_API qsc_tls_status	qsc_tls_record_decode_plaintext (const uint8_t *input, size_t inlen, qsc_tls_record_content_type *type, const uint8_t **payload, size_t *payloadlen)
	Decode a plaintext TLS record.
QSC_EXPORT_API qsc_tls_status	qsc_tls_record_try_get_span_length (const uint8_t *input, size_t inlen, size_t *recordlen, bool *complete)
	Determine the full span length of a TLS record.
QSC_EXPORT_API qsc_tls_status	qsc_tls_record_encrypt (qsc_tls_record_state *state, uint8_t *output, size_t outlen, size_t *written, qsc_tls_record_content_type inner_type, const uint8_t *input, size_t inlen)
	Protect a TLSInnerPlaintext payload as a TLSCiphertext record.
QSC_EXPORT_API qsc_tls_status	qsc_tls_record_decrypt (qsc_tls_record_state *state, uint8_t *output, size_t outlen, size_t *written, qsc_tls_record_content_type *inner_type, const uint8_t *input, size_t inlen)
	Decrypt a protected TLSCiphertext record.

Detailed Description

TLS record formatting and protection helpers.

Function Documentation

qsc_tls_record_decode_plaintext()

QSC_EXPORT_API qsc_tls_status qsc_tls_record_decode_plaintext	(	const uint8_t *	input,
		size_t	inlen,
		qsc_tls_record_content_type *	type,
		const uint8_t **	payload,
		size_t *	payloadlen )

Decode a plaintext TLS record.

Parameters

input	[const uint8_t*] The source record buffer.
inlen	[size_t] The source buffer length in bytes.
type	[enum] Receives the decoded outer record content type.
payload	[const uint8_t**] Receives a pointer to the decoded payload span.
payloadlen	[size_t*] Receives the decoded payload length in bytes.

Returns

Returns a TLS status code.

qsc_tls_record_decrypt()

QSC_EXPORT_API qsc_tls_status qsc_tls_record_decrypt	(	qsc_tls_record_state *	state,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written,
		qsc_tls_record_content_type *	inner_type,
		const uint8_t *	input,
		size_t	inlen )

Decrypt a protected TLSCiphertext record.

Parameters

state	[struct] The active read-side record protection state.
output	[uint8_t*] The destination plaintext buffer.
outlen	[size_t] The destination buffer length in bytes.
written	[size_t*] Receives the number of plaintext bytes written.
inner_type	[enum] Receives the decoded inner content type.
input	[const uint8_t*] The protected record buffer.
inlen	[size_t] The protected record length in bytes.

Returns

Returns a TLS status code.

qsc_tls_record_encode_plaintext()

QSC_EXPORT_API qsc_tls_status qsc_tls_record_encode_plaintext	(	uint8_t *	output,
		size_t	outlen,
		size_t *	written,
		qsc_tls_record_content_type	type,
		const uint8_t *	input,
		size_t	inlen )

Encode a plaintext TLS record.

Parameters

output	[uint8_t*] The destination record buffer.
outlen	[size_t] The destination buffer length in bytes.
written	[size_t*] Receives the number of bytes written.
type	[enum] The outer record content type.
input	[const uint8_t*] The plaintext payload buffer.
inlen	[size_t] The plaintext payload length in bytes.

Returns

Returns a TLS status code.

qsc_tls_record_encrypt()

QSC_EXPORT_API qsc_tls_status qsc_tls_record_encrypt	(	qsc_tls_record_state *	state,
		uint8_t *	output,
		size_t	outlen,
		size_t *	written,
		qsc_tls_record_content_type	inner_type,
		const uint8_t *	input,
		size_t	inlen )

Protect a TLSInnerPlaintext payload as a TLSCiphertext record.

Parameters

state	[struct] The active write-side record protection state.
output	[uint8_t*] The destination record buffer.
outlen	[size_t] The destination buffer length in bytes.
written	[size_t*] Receives the number of bytes written.
inner_type	[enum] The inner content type trailer.
input	[const uint8_t*] The plaintext payload buffer.
inlen	[size_t] The plaintext payload length in bytes.

Returns

Returns a TLS status code.

qsc_tls_record_state_dispose()

QSC_EXPORT_API void qsc_tls_record_state_dispose

(

qsc_tls_record_state *

state

)

Dispose of a TLS record protection state.

Parameters

state

[struct] The record state to clear.

qsc_tls_record_state_get_sequence()

QSC_EXPORT_API uint64_t qsc_tls_record_state_get_sequence

(

const qsc_tls_record_state *

state

)

Read the current sequence number. Returns 0 when state is NULL or uninitialized.

Parameters

state

[const struct*] The record state.

Returns

[uint64_t] Current 64-bit sequence counter.

qsc_tls_record_state_initialize()

QSC_EXPORT_API void qsc_tls_record_state_initialize	(	qsc_tls_record_state *	state,
		qsc_tls_cipher_suite	suite,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	iv,
		size_t	ivlen )

Initialize a TLS record protection state.

Parameters

state	[struct] The record state to initialize.
key	[const uint8_t*] The traffic key buffer.
keylen	[size_t] The traffic key length in bytes.
iv	[const uint8_t*] The static traffic IV buffer.
ivlen	[size_t] The static traffic IV length in bytes.

qsc_tls_record_state_install_keys()

QSC_EXPORT_API qsc_tls_status qsc_tls_record_state_install_keys	(	qsc_tls_record_state *	state,
		qsc_tls_cipher_suite	suite,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	iv,
		size_t	ivlen )

Install or replace traffic keys on an existing record state, resetting the sequence.

Intended for epoch transitions (handshake to application keys) and for KeyUpdate. The existing key material is zeroized via qsc_memutils_secure_erase before the new key and IV are installed. Equivalent in effect to qsc_tls_record_state_dispose followed by qsc_tls_record_state_initialize but presented as a single atomic operation so callers cannot observe a partially-cleared state.

Parameters

state	[struct*] The record state to update.
suite	[enum] The cipher suite.
key	[const uint8_t*] The new traffic key.
keylen	[size_t] The new key length; must match the suite.
iv	[const uint8_t*] The new 12-byte static IV.
ivlen	[size_t] The IV length; must be 12.

Returns

[qsc_tls_status] Returns qsc_tls_status_success on success.

qsc_tls_record_try_get_span_length()

QSC_EXPORT_API qsc_tls_status qsc_tls_record_try_get_span_length	(	const uint8_t *	input,
		size_t	inlen,
		size_t *	recordlen,
		bool *	complete )

Determine the full span length of a TLS record.

Parameters

input	[const uint8_t*] The source buffer.
inlen	[size_t] The source buffer length in bytes.
recordlen	[size_t*] Receives the full record span length in bytes.
complete	[bool*] Receives true if the full record is present in the source buffer.

Returns

Returns a TLS status code.