tls13_misc.h File Reference

TLS 1.3 helper functions. More...

Go to the source code of this file.

Macros
#define	TLS13_DHE_KE_SUPPORT   ENABLED
#define	TLS13_ECDHE_KE_SUPPORT   ENABLED
#define	TLS13_PSK_KE_SUPPORT   DISABLED
#define	TLS13_PSK_DHE_KE_SUPPORT   ENABLED
#define	TLS13_PSK_ECDHE_KE_SUPPORT   ENABLED
#define	TLS13_EARLY_DATA_SUPPORT   DISABLED
#define	TLS13_MIDDLEBOX_COMPAT_SUPPORT   ENABLED
#define	TLS13_MAX_COOKIE_SIZE   256
#define	TLS13_MAX_TICKET_SIZE   1024
#define	TLS13_MAX_TICKET_LIFETIME   604800
#define	TLS13_TICKET_AGE_TOLERANCE   5000
#define	TLS13_NEW_SESSION_TICKET_COUNT   2
#define	TLS13_MAX_HKDF_DIGEST_SIZE   48

Typedefs
typedef void *	Tls13EndOfEarlyData
	EndOfEarlyData message. More...

Enumerations
enum	Tls13SignatureScheme {   TLS_SIGN_SCHEME_NONE = 0x0000 , TLS_SIGN_SCHEME_RSA_PKCS1_SHA1 = 0x0201 , TLS_SIGN_SCHEME_RSA_PKCS1_SHA256 = 0x0401 , TLS_SIGN_SCHEME_RSA_PKCS1_SHA384 = 0x0501 ,   TLS_SIGN_SCHEME_RSA_PKCS1_SHA512 = 0x0601 , TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA256 = 0x0804 , TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA384 = 0x0805 , TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA512 = 0x0806 ,   TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA256 = 0x0809 , TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA384 = 0x080A , TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA512 = 0x080B , TLS_SIGN_SCHEME_ECDSA_SHA1 = 0x0203 ,   TLS_SIGN_SCHEME_ECDSA_SECP256R1_SHA256 = 0x0403 , TLS_SIGN_SCHEME_ECDSA_SECP384R1_SHA384 = 0x0503 , TLS_SIGN_SCHEME_ECDSA_SECP521R1_SHA512 = 0x0603 , TLS_SIGN_SCHEME_SM2_SM3 = 0x0708 ,   TLS_SIGN_SCHEME_GOSTR34102012_256A = 0x0709 , TLS_SIGN_SCHEME_GOSTR34102012_256B = 0x070A , TLS_SIGN_SCHEME_GOSTR34102012_256C = 0x070B , TLS_SIGN_SCHEME_GOSTR34102012_256D = 0x070C ,   TLS_SIGN_SCHEME_GOSTR34102012_512A = 0x070D , TLS_SIGN_SCHEME_GOSTR34102012_512B = 0x070E , TLS_SIGN_SCHEME_GOSTR34102012_512C = 0x070F , TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP256R1_TLS13_SHA256 = 0x081A ,   TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP384R1_TLS13_SHA384 = 0x081B , TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP512R1_TLS13_SHA512 = 0x081C , TLS_SIGN_SCHEME_ED25519 = 0x0807 , TLS_SIGN_SCHEME_ED448 = 0x0808 }
	Signature schemes (TLS 1.3) More...
enum	Tls13PskKeyExchMode { TLS_PSK_KEY_EXCH_MODE_PSK_KE = 0 , TLS_PSK_KEY_EXCH_MODE_PSK_DHE_KE = 1 }
	PSK key exchange modes. More...
enum	Tls13KeyUpdateRequest { TLS_KEY_UPDATE_NOT_REQUESTED = 0 , TLS_KEY_UPDATE_REQUESTED = 1 }
	Key update requests. More...

Functions
error_t	tls13ComputePskBinder (TlsContext *context, const void *clientHello, size_t clientHelloLen, size_t truncatedClientHelloLen, const Tls13PskIdentity *identity, uint8_t *binder, size_t binderLen)
	Compute PSK binder value. More...
error_t	tls13GenerateKeyShare (TlsContext *context, uint16_t namedGroup)
	Key share generation. More...
error_t	tls13GenerateSharedSecret (TlsContext *context, const uint8_t *keyShare, size_t length)
	(EC)DHE shared secret generation More...
error_t	tls13ComputeMac (TlsContext *context, TlsEncryptionEngine *encryptionEngine, void *record, const uint8_t *data, size_t dataLen, uint8_t *mac)
	Compute message authentication code. More...
error_t	tls13DigestClientHello1 (TlsContext *context)
	Hash ClientHello1 in the transcript when HelloRetryRequest is used. More...
bool_t	tls13IsPskValid (TlsContext *context)
	Check whether an externally established PSK is valid. More...
bool_t	tls13IsGroupSupported (TlsContext *context, uint16_t namedGroup)
	Check whether a given named group is supported. More...
bool_t	tls13IsEcdheGroupSupported (TlsContext *context, uint16_t namedGroup)
	Check whether a given ECDHE group is supported. More...
bool_t	tls13IsFfdheGroupSupported (TlsContext *context, uint16_t namedGroup)
	Check whether a given FFDHE group is supported. More...
error_t	tls13CheckDuplicateKeyShare (uint16_t namedGroup, const uint8_t *p, size_t length)
	Check whether the specified key share group is a duplicate. More...
error_t	tls13FormatCertExtensions (uint8_t *p, size_t *written)
	Format certificate extensions. More...
error_t	tls13ParseCertExtensions (const uint8_t *p, size_t length, size_t *consumed)
	Parse certificate extensions. More...

Variables
typedef	__packed_struct
	Cookie. More...
uint8_t	value []
	Tls13Cookie
uint16_t	length
uint8_t	keyExchange []
	Tls13KeyShareEntry
	Tls13KeyShareList
	Tls13PskKeModeList
	Tls13PskIdentity
	Tls13PskIdentityList
	Tls13PskBinder
	Tls13PskBinderList
	Tls13CertRequestContext
	Tls13DigitalSignature
uint8_t	random [32]
uint8_t	sessionIdLen
uint8_t	sessionId []
	Tls13HelloRetryRequest
uint8_t	extensions []
	Tls13EncryptedExtensions
uint32_t	ticketAgeAdd
	Random value used to obscure the age of the ticket. More...
uint8_t	ticketNonceLen
uint8_t	ticketNonce []
	A per-ticket value that is unique across all tickets issued. More...
	Tls13NewSessionTicket
	Tls13KeyUpdate
uint8_t	data []
	Tls13Ticket
uint16_t	cipherSuite
	Cipher suite identifier. More...
systime_t	ticketTimestamp
	Timestamp to manage ticket lifetime. More...
uint32_t	ticketLifetime
	Lifetime of the ticket. More...
size_t	ticketPskLen
	Length of the PSK associated with the ticket. More...
uint8_t	ticketPsk [TLS13_MAX_HKDF_DIGEST_SIZE]
	PSK associated with the ticket. More...
	Tls13PlaintextSessionState
const uint8_t	tls11DowngradeRandom [8]
const uint8_t	tls12DowngradeRandom [8]
const uint8_t	tls13HelloRetryRequestRandom [32]

Detailed Description

TLS 1.3 helper functions.

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2010-2023 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneSSL Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author

Oryx Embedded SARL (www.oryx-embedded.com)

Version

2.3.2

Definition in file tls13_misc.h.

Macro Definition Documentation

TLS13_DHE_KE_SUPPORT

#define TLS13_DHE_KE_SUPPORT   ENABLED

Definition at line 36 of file tls13_misc.h.

TLS13_EARLY_DATA_SUPPORT

#define TLS13_EARLY_DATA_SUPPORT   DISABLED

Definition at line 71 of file tls13_misc.h.

TLS13_ECDHE_KE_SUPPORT

#define TLS13_ECDHE_KE_SUPPORT   ENABLED

Definition at line 43 of file tls13_misc.h.

TLS13_MAX_COOKIE_SIZE

#define TLS13_MAX_COOKIE_SIZE   256

Definition at line 85 of file tls13_misc.h.

TLS13_MAX_HKDF_DIGEST_SIZE

#define TLS13_MAX_HKDF_DIGEST_SIZE   48

Definition at line 120 of file tls13_misc.h.

TLS13_MAX_TICKET_LIFETIME

#define TLS13_MAX_TICKET_LIFETIME   604800

Definition at line 99 of file tls13_misc.h.

TLS13_MAX_TICKET_SIZE

#define TLS13_MAX_TICKET_SIZE   1024

Definition at line 92 of file tls13_misc.h.

TLS13_MIDDLEBOX_COMPAT_SUPPORT

#define TLS13_MIDDLEBOX_COMPAT_SUPPORT   ENABLED

Definition at line 78 of file tls13_misc.h.

TLS13_NEW_SESSION_TICKET_COUNT

#define TLS13_NEW_SESSION_TICKET_COUNT   2

Definition at line 113 of file tls13_misc.h.

TLS13_PSK_DHE_KE_SUPPORT

#define TLS13_PSK_DHE_KE_SUPPORT   ENABLED

Definition at line 57 of file tls13_misc.h.

TLS13_PSK_ECDHE_KE_SUPPORT

#define TLS13_PSK_ECDHE_KE_SUPPORT   ENABLED

Definition at line 64 of file tls13_misc.h.

TLS13_PSK_KE_SUPPORT

#define TLS13_PSK_KE_SUPPORT   DISABLED

Definition at line 50 of file tls13_misc.h.

TLS13_TICKET_AGE_TOLERANCE

#define TLS13_TICKET_AGE_TOLERANCE   5000

Definition at line 106 of file tls13_misc.h.

Typedef Documentation

Tls13EndOfEarlyData

typedef void* Tls13EndOfEarlyData

EndOfEarlyData message.

Definition at line 325 of file tls13_misc.h.

Enumeration Type Documentation

Tls13KeyUpdateRequest

enum Tls13KeyUpdateRequest

Key update requests.

Enumerator
TLS_KEY_UPDATE_NOT_REQUESTED
TLS_KEY_UPDATE_REQUESTED

Definition at line 183 of file tls13_misc.h.

Tls13PskKeyExchMode

enum Tls13PskKeyExchMode

PSK key exchange modes.

Enumerator
TLS_PSK_KEY_EXCH_MODE_PSK_KE
TLS_PSK_KEY_EXCH_MODE_PSK_DHE_KE

Definition at line 172 of file tls13_misc.h.

Tls13SignatureScheme

enum Tls13SignatureScheme

Signature schemes (TLS 1.3)

Enumerator
TLS_SIGN_SCHEME_NONE
TLS_SIGN_SCHEME_RSA_PKCS1_SHA1
TLS_SIGN_SCHEME_RSA_PKCS1_SHA256
TLS_SIGN_SCHEME_RSA_PKCS1_SHA384
TLS_SIGN_SCHEME_RSA_PKCS1_SHA512
TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA256
TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA384
TLS_SIGN_SCHEME_RSA_PSS_RSAE_SHA512
TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA256
TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA384
TLS_SIGN_SCHEME_RSA_PSS_PSS_SHA512
TLS_SIGN_SCHEME_ECDSA_SHA1
TLS_SIGN_SCHEME_ECDSA_SECP256R1_SHA256
TLS_SIGN_SCHEME_ECDSA_SECP384R1_SHA384
TLS_SIGN_SCHEME_ECDSA_SECP521R1_SHA512
TLS_SIGN_SCHEME_SM2_SM3
TLS_SIGN_SCHEME_GOSTR34102012_256A
TLS_SIGN_SCHEME_GOSTR34102012_256B
TLS_SIGN_SCHEME_GOSTR34102012_256C
TLS_SIGN_SCHEME_GOSTR34102012_256D
TLS_SIGN_SCHEME_GOSTR34102012_512A
TLS_SIGN_SCHEME_GOSTR34102012_512B
TLS_SIGN_SCHEME_GOSTR34102012_512C
TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP256R1_TLS13_SHA256
TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP384R1_TLS13_SHA384
TLS_SIGN_SCHEME_ECDSA_BRAINPOOLP512R1_TLS13_SHA512
TLS_SIGN_SCHEME_ED25519
TLS_SIGN_SCHEME_ED448

Definition at line 135 of file tls13_misc.h.

Function Documentation

tls13CheckDuplicateKeyShare()

error_t tls13CheckDuplicateKeyShare	(	uint16_t	namedGroup,
		const uint8_t *	p,
		size_t	length
	)

Check whether the specified key share group is a duplicate.

Parameters

[in]	namedGroup	Named group
[in]	p	List of key share entries
[in]	length	Length of the list, in bytes

Returns

Error code

Definition at line 691 of file tls13_misc.c.

tls13ComputeMac()

error_t tls13ComputeMac	(	TlsContext *	context,
		TlsEncryptionEngine *	encryptionEngine,
		void *	record,
		const uint8_t *	data,
		size_t	dataLen,
		uint8_t *	mac
	)

Compute message authentication code.

Parameters

[in]	context	Pointer to the TLS context
[in]	encryptionEngine	Pointer to the encryption/decryption engine
[in]	record	Pointer to the TLS record
[in]	data	Pointer to the record data
[in]	dataLen	Length of the data
[out]	mac	The computed MAC value

Returns

Error code

Definition at line 457 of file tls13_misc.c.

tls13ComputePskBinder()

error_t tls13ComputePskBinder	(	TlsContext *	context,
		const void *	clientHello,
		size_t	clientHelloLen,
		size_t	truncatedClientHelloLen,
		const Tls13PskIdentity *	identity,
		uint8_t *	binder,
		size_t	binderLen
	)

Compute PSK binder value.

Parameters

[in]	context	Pointer to the TLS context
[in]	clientHello	Pointer to the ClientHello message
[in]	clientHelloLen	Length of the ClientHello message
[in]	truncatedClientHelloLen	Length of the partial ClientHello message
[in]	identity	Pointer to the PSK identity
[out]	binder	Buffer where to store the resulting PSK binder
[in]	binderLen	Expected length of the PSK binder

Returns

Error code

Definition at line 86 of file tls13_misc.c.

tls13DigestClientHello1()

error_t tls13DigestClientHello1

(

TlsContext *

context

)

Hash ClientHello1 in the transcript when HelloRetryRequest is used.

Parameters

[in]

context

Pointer to the TLS context

Returns

Error code

Definition at line 499 of file tls13_misc.c.

tls13FormatCertExtensions()

error_t tls13FormatCertExtensions	(	uint8_t *	p,
		size_t *	written
	)

Format certificate extensions.

Parameters

[in]	p	Output stream where to write the list of extensions
[out]	written	Total number of bytes that have been written

Returns

Error code

Definition at line 737 of file tls13_misc.c.

tls13GenerateKeyShare()

error_t tls13GenerateKeyShare	(	TlsContext *	context,
		uint16_t	namedGroup
	)

Key share generation.

Parameters

[in]	context	Pointer to the TLS context
[in]	namedGroup	Named group

Returns

Error code

Definition at line 260 of file tls13_misc.c.

tls13GenerateSharedSecret()

error_t tls13GenerateSharedSecret	(	TlsContext *	context,
		const uint8_t *	keyShare,
		size_t	length
	)

(EC)DHE shared secret generation

Parameters

[in]	context	Pointer to the TLS context
[in]	keyShare	Pointer to the peer's (EC)DHE parameters
[in]	length	Length of the (EC)DHE parameters, in bytes

Returns

Error code

Definition at line 353 of file tls13_misc.c.

tls13IsEcdheGroupSupported()

bool_t tls13IsEcdheGroupSupported	(	TlsContext *	context,
		uint16_t	namedGroup
	)

Check whether a given ECDHE group is supported.

Parameters

[in]	context	Pointer to the TLS context
[in]	namedGroup	Named group

Returns

TRUE is the ECDHE group is supported, else FALSE

Definition at line 615 of file tls13_misc.c.

tls13IsFfdheGroupSupported()

bool_t tls13IsFfdheGroupSupported	(	TlsContext *	context,
		uint16_t	namedGroup
	)

Check whether a given FFDHE group is supported.

Parameters

[in]	context	Pointer to the TLS context
[in]	namedGroup	Named group

Returns

TRUE is the FFDHE group is supported, else FALSE

Definition at line 653 of file tls13_misc.c.

tls13IsGroupSupported()

bool_t tls13IsGroupSupported	(	TlsContext *	context,
		uint16_t	namedGroup
	)

Check whether a given named group is supported.

Parameters

[in]	context	Pointer to the TLS context
[in]	namedGroup	Named group

Returns

TRUE is the named group is supported, else FALSE

Definition at line 582 of file tls13_misc.c.

tls13IsPskValid()

bool_t tls13IsPskValid

(

TlsContext *

context

)

Check whether an externally established PSK is valid.

Parameters

[in]

context

Pointer to the TLS context

Returns

TRUE is the PSK is valid, else FALSE

Definition at line 544 of file tls13_misc.c.

tls13ParseCertExtensions()

error_t tls13ParseCertExtensions	(	const uint8_t *	p,
		size_t	length,
		size_t *	consumed
	)

Parse certificate extensions.

Parameters

[in]	p	Input stream where to read the list of extensions
[in]	length	Number of bytes available in the input stream
[out]	consumed	Total number of bytes that have been consumed

Returns

Error code

Definition at line 766 of file tls13_misc.c.

Variable Documentation

__packed_struct

typedef __packed_struct

Initial value:

{
   uint16_t length

Cookie.

Session state information.

Session ticket.

KeyUpdate message.

NewSessionTicket message (TLS 1.3)

EncryptedExtensions message.

HelloRetryRequest message.

Digitally-signed element (TLS 1.3)

Certificate request context.

List of PSK binders.

PSK binder.

List of PSK identities.

PSK identity.

List of PSK key exchange modes.

List of key shares.

Key share entry.

Protocol version

Definition at line 200 of file tls13_misc.h.

cipherSuite

uint16_t cipherSuite

Cipher suite identifier.

Definition at line 380 of file tls13_misc.h.

data

uint8_t data[]

Definition at line 369 of file tls13_misc.h.

extensions

uint8_t extensions[]

Definition at line 335 of file tls13_misc.h.

keyExchange

uint8_t keyExchange[]

Definition at line 215 of file tls13_misc.h.

length

uint16_t length

Definition at line 214 of file tls13_misc.h.

random

uint8_t random[32]

Definition at line 315 of file tls13_misc.h.

sessionId

uint8_t sessionId[]

Definition at line 317 of file tls13_misc.h.

sessionIdLen

uint8_t sessionIdLen

Definition at line 316 of file tls13_misc.h.

ticketAgeAdd

uint32_t ticketAgeAdd

Random value used to obscure the age of the ticket.

Definition at line 346 of file tls13_misc.h.

ticketLifetime

uint32_t ticketLifetime

Lifetime of the ticket.

Definition at line 382 of file tls13_misc.h.

ticketNonce

uint8_t ticketNonce

A per-ticket value that is unique across all tickets issued.

Definition at line 348 of file tls13_misc.h.

ticketNonceLen

uint8_t ticketNonceLen

Definition at line 347 of file tls13_misc.h.

ticketPsk

uint8_t ticketPsk[TLS13_MAX_HKDF_DIGEST_SIZE]

PSK associated with the ticket.

Definition at line 386 of file tls13_misc.h.

ticketPskLen

size_t ticketPskLen

Length of the PSK associated with the ticket.

Definition at line 385 of file tls13_misc.h.

ticketTimestamp

systime_t ticketTimestamp

Timestamp to manage ticket lifetime.

Definition at line 381 of file tls13_misc.h.

tls11DowngradeRandom

const uint8_t tls11DowngradeRandom[8]

extern

Definition at line 53 of file tls13_misc.c.

tls12DowngradeRandom

const uint8_t tls12DowngradeRandom[8]

extern

Definition at line 59 of file tls13_misc.c.

Tls13CertRequestContext

Tls13CertRequestContext

Definition at line 293 of file tls13_misc.h.

Tls13Cookie

Tls13Cookie

Definition at line 204 of file tls13_misc.h.

Tls13DigitalSignature

Tls13DigitalSignature

Definition at line 305 of file tls13_misc.h.

Tls13EncryptedExtensions

Tls13EncryptedExtensions

Definition at line 336 of file tls13_misc.h.

Tls13HelloRetryRequest

Tls13HelloRetryRequest

Definition at line 318 of file tls13_misc.h.

tls13HelloRetryRequestRandom

const uint8_t tls13HelloRetryRequestRandom[32]

extern

Definition at line 65 of file tls13_misc.c.

Tls13KeyShareEntry

Tls13KeyShareEntry

Definition at line 216 of file tls13_misc.h.

Tls13KeyShareList

Tls13KeyShareList

Definition at line 227 of file tls13_misc.h.

Tls13KeyUpdate

Tls13KeyUpdate

Definition at line 359 of file tls13_misc.h.

Tls13NewSessionTicket

Tls13NewSessionTicket

Definition at line 349 of file tls13_misc.h.

Tls13PlaintextSessionState

Tls13PlaintextSessionState

Definition at line 387 of file tls13_misc.h.

Tls13PskBinder

Tls13PskBinder

Definition at line 271 of file tls13_misc.h.

Tls13PskBinderList

Tls13PskBinderList

Definition at line 282 of file tls13_misc.h.

Tls13PskIdentity

Tls13PskIdentity

Definition at line 249 of file tls13_misc.h.

Tls13PskIdentityList

Tls13PskIdentityList

Definition at line 260 of file tls13_misc.h.

Tls13PskKeModeList

Tls13PskKeModeList

Definition at line 238 of file tls13_misc.h.

Tls13Ticket

Tls13Ticket

Definition at line 370 of file tls13_misc.h.

value

uint8_t value[]

Definition at line 203 of file tls13_misc.h.