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_MLKEM_KE_SUPPORT   DISABLED
 
#define TLS13_HYBRID_KE_SUPPORT   DISABLED
 
#define TLS13_PSK_KE_SUPPORT   DISABLED
 
#define TLS13_PSK_DHE_KE_SUPPORT   ENABLED
 
#define TLS13_PSK_ECDHE_KE_SUPPORT   ENABLED
 
#define TLS13_PSK_MLKEM_KE_SUPPORT   DISABLED
 
#define TLS13_PSK_HYBRID_KE_SUPPORT   DISABLED
 
#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  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 tls13Encapsulate (TlsContext *context, uint16_t namedGroup, const uint8_t *keyShare, size_t length)
 Encapsulation algorithm. More...
 
error_t tls13Decapsulate (TlsContext *context, const uint8_t *keyShare, size_t length)
 Decapsulation algorithm. 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 tls13IsFfdheGroupSupported (TlsContext *context, uint16_t namedGroup)
 Check whether a given FFDHE group is supported. More...
 
bool_t tls13IsEcdheGroupSupported (TlsContext *context, uint16_t namedGroup)
 Check whether a given ECDHE group is supported. More...
 
bool_t tls13IsMlkemGroupSupported (TlsContext *context, uint16_t namedGroup)
 Check whether a given ML-KEM exchange method is supported. More...
 
bool_t tls13IsHybridGroupSupported (TlsContext *context, uint16_t namedGroup)
 Check whether a given hybrid key exchange method is supported. More...
 
const KemAlgotls13GetMlkemAlgo (TlsContext *context, uint16_t namedGroup)
 Get the ML-KEM algorithm that matches the specified named group. More...
 
const EcCurvetls13GetTraditionalAlgo (TlsContext *context, uint16_t namedGroup)
 Get the traditional algorithm used by the hybrid key exchange method. More...
 
const KemAlgotls13GetNextGenAlgo (TlsContext *context, uint16_t namedGroup)
 Get the next-gen algorithm used by the hybrid key exchange method. 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-2025 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.5.0

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 99 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_HYBRID_KE_SUPPORT

#define TLS13_HYBRID_KE_SUPPORT   DISABLED

Definition at line 57 of file tls13_misc.h.

◆ TLS13_MAX_COOKIE_SIZE

#define TLS13_MAX_COOKIE_SIZE   256

Definition at line 113 of file tls13_misc.h.

◆ TLS13_MAX_HKDF_DIGEST_SIZE

#define TLS13_MAX_HKDF_DIGEST_SIZE   48

Definition at line 148 of file tls13_misc.h.

◆ TLS13_MAX_TICKET_LIFETIME

#define TLS13_MAX_TICKET_LIFETIME   604800

Definition at line 127 of file tls13_misc.h.

◆ TLS13_MAX_TICKET_SIZE

#define TLS13_MAX_TICKET_SIZE   1024

Definition at line 120 of file tls13_misc.h.

◆ TLS13_MIDDLEBOX_COMPAT_SUPPORT

#define TLS13_MIDDLEBOX_COMPAT_SUPPORT   ENABLED

Definition at line 106 of file tls13_misc.h.

◆ TLS13_MLKEM_KE_SUPPORT

#define TLS13_MLKEM_KE_SUPPORT   DISABLED

Definition at line 50 of file tls13_misc.h.

◆ TLS13_NEW_SESSION_TICKET_COUNT

#define TLS13_NEW_SESSION_TICKET_COUNT   2

Definition at line 141 of file tls13_misc.h.

◆ TLS13_PSK_DHE_KE_SUPPORT

#define TLS13_PSK_DHE_KE_SUPPORT   ENABLED

Definition at line 71 of file tls13_misc.h.

◆ TLS13_PSK_ECDHE_KE_SUPPORT

#define TLS13_PSK_ECDHE_KE_SUPPORT   ENABLED

Definition at line 78 of file tls13_misc.h.

◆ TLS13_PSK_HYBRID_KE_SUPPORT

#define TLS13_PSK_HYBRID_KE_SUPPORT   DISABLED

Definition at line 92 of file tls13_misc.h.

◆ TLS13_PSK_KE_SUPPORT

#define TLS13_PSK_KE_SUPPORT   DISABLED

Definition at line 64 of file tls13_misc.h.

◆ TLS13_PSK_MLKEM_KE_SUPPORT

#define TLS13_PSK_MLKEM_KE_SUPPORT   DISABLED

Definition at line 85 of file tls13_misc.h.

◆ TLS13_TICKET_AGE_TOLERANCE

#define TLS13_TICKET_AGE_TOLERANCE   5000

Definition at line 134 of file tls13_misc.h.

Typedef Documentation

◆ Tls13EndOfEarlyData

typedef void* Tls13EndOfEarlyData

EndOfEarlyData message.

Definition at line 318 of file tls13_misc.h.

Enumeration Type Documentation

◆ Tls13KeyUpdateRequest

Key update requests.

Enumerator
TLS_KEY_UPDATE_NOT_REQUESTED 
TLS_KEY_UPDATE_REQUESTED 

Definition at line 174 of file tls13_misc.h.

◆ Tls13PskKeyExchMode

PSK key exchange modes.

Enumerator
TLS_PSK_KEY_EXCH_MODE_PSK_KE 
TLS_PSK_KEY_EXCH_MODE_PSK_DHE_KE 

Definition at line 163 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]namedGroupNamed group
[in]pList of key share entries
[in]lengthLength of the list, in bytes
Returns
Error code

Definition at line 1394 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]contextPointer to the TLS context
[in]encryptionEnginePointer to the encryption/decryption engine
[in]recordPointer to the TLS record
[in]dataPointer to the record data
[in]dataLenLength of the data
[out]macThe computed MAC value
Returns
Error code

Definition at line 846 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]contextPointer to the TLS context
[in]clientHelloPointer to the ClientHello message
[in]clientHelloLenLength of the ClientHello message
[in]truncatedClientHelloLenLength of the partial ClientHello message
[in]identityPointer to the PSK identity
[out]binderBuffer where to store the resulting PSK binder
[in]binderLenExpected length of the PSK binder
Returns
Error code

Definition at line 86 of file tls13_misc.c.

◆ tls13Decapsulate()

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

Decapsulation algorithm.

Parameters
[in]contextPointer to the TLS context
[in]keySharePointer to the server's key share
[in]lengthLength of the client's key share, in bytes
Returns
Error code

Definition at line 696 of file tls13_misc.c.

◆ tls13DigestClientHello1()

error_t tls13DigestClientHello1 ( TlsContext context)

Hash ClientHello1 in the transcript when HelloRetryRequest is used.

Parameters
[in]contextPointer to the TLS context
Returns
Error code

Definition at line 888 of file tls13_misc.c.

◆ tls13Encapsulate()

error_t tls13Encapsulate ( TlsContext context,
uint16_t  namedGroup,
const uint8_t *  keyShare,
size_t  length 
)

Encapsulation algorithm.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed group
[in]keySharePointer to the client's key share
[in]lengthLength of the client's key share, in bytes
Returns
Error code

Definition at line 521 of file tls13_misc.c.

◆ tls13FormatCertExtensions()

error_t tls13FormatCertExtensions ( uint8_t *  p,
size_t *  written 
)

Format certificate extensions.

Parameters
[in]pOutput stream where to write the list of extensions
[out]writtenTotal number of bytes that have been written
Returns
Error code

Definition at line 1440 of file tls13_misc.c.

◆ tls13GenerateKeyShare()

error_t tls13GenerateKeyShare ( TlsContext context,
uint16_t  namedGroup 
)

Key share generation.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed 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]contextPointer to the TLS context
[in]keySharePointer to the peer's (EC)DHE parameters
[in]lengthLength of the (EC)DHE parameters, in bytes
Returns
Error code

Definition at line 423 of file tls13_misc.c.

◆ tls13GetMlkemAlgo()

const KemAlgo* tls13GetMlkemAlgo ( TlsContext context,
uint16_t  namedGroup 
)

Get the ML-KEM algorithm that matches the specified named group.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupHybrid key exchange method
Returns
ML-KEM algorithm

Definition at line 1193 of file tls13_misc.c.

◆ tls13GetNextGenAlgo()

const KemAlgo* tls13GetNextGenAlgo ( TlsContext context,
uint16_t  namedGroup 
)

Get the next-gen algorithm used by the hybrid key exchange method.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupHybrid key exchange method
Returns
Next-gen algorithm

Definition at line 1330 of file tls13_misc.c.

◆ tls13GetTraditionalAlgo()

const EcCurve* tls13GetTraditionalAlgo ( TlsContext context,
uint16_t  namedGroup 
)

Get the traditional algorithm used by the hybrid key exchange method.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupHybrid key exchange method
Returns
Traditional algorithm

Definition at line 1261 of file tls13_misc.c.

◆ tls13IsEcdheGroupSupported()

bool_t tls13IsEcdheGroupSupported ( TlsContext context,
uint16_t  namedGroup 
)

Check whether a given ECDHE group is supported.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed group
Returns
TRUE is the ECDHE group is supported, else FALSE

Definition at line 1052 of file tls13_misc.c.

◆ tls13IsFfdheGroupSupported()

bool_t tls13IsFfdheGroupSupported ( TlsContext context,
uint16_t  namedGroup 
)

Check whether a given FFDHE group is supported.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed group
Returns
TRUE is the FFDHE group is supported, else FALSE

Definition at line 1012 of file tls13_misc.c.

◆ tls13IsGroupSupported()

bool_t tls13IsGroupSupported ( TlsContext context,
uint16_t  namedGroup 
)

Check whether a given named group is supported.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed group
Returns
TRUE is the named group is supported, else FALSE

Definition at line 971 of file tls13_misc.c.

◆ tls13IsHybridGroupSupported()

bool_t tls13IsHybridGroupSupported ( TlsContext context,
uint16_t  namedGroup 
)

Check whether a given hybrid key exchange method is supported.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed group
Returns
TRUE is the hybrid key exchange is supported, else FALSE

Definition at line 1151 of file tls13_misc.c.

◆ tls13IsMlkemGroupSupported()

bool_t tls13IsMlkemGroupSupported ( TlsContext context,
uint16_t  namedGroup 
)

Check whether a given ML-KEM exchange method is supported.

Parameters
[in]contextPointer to the TLS context
[in]namedGroupNamed group
Returns
TRUE is the ML-KEM key exchange is supported, else FALSE

Definition at line 1110 of file tls13_misc.c.

◆ tls13IsPskValid()

bool_t tls13IsPskValid ( TlsContext context)

Check whether an externally established PSK is valid.

Parameters
[in]contextPointer to the TLS context
Returns
TRUE is the PSK is valid, else FALSE

Definition at line 933 of file tls13_misc.c.

◆ tls13ParseCertExtensions()

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

Parse certificate extensions.

Parameters
[in]pInput stream where to read the list of extensions
[in]lengthNumber of bytes available in the input stream
[out]consumedTotal number of bytes that have been consumed
Returns
Error code

Definition at line 1469 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 193 of file tls13_misc.h.

◆ cipherSuite

uint16_t cipherSuite

Cipher suite identifier.

Definition at line 373 of file tls13_misc.h.

◆ data

uint8_t data[]

Definition at line 362 of file tls13_misc.h.

◆ extensions

uint8_t extensions[]

Definition at line 328 of file tls13_misc.h.

◆ keyExchange

uint8_t keyExchange[]

Definition at line 208 of file tls13_misc.h.

◆ length

uint16_t length

Definition at line 207 of file tls13_misc.h.

◆ random

uint8_t random[32]

Definition at line 308 of file tls13_misc.h.

◆ sessionId

uint8_t sessionId[]

Definition at line 310 of file tls13_misc.h.

◆ sessionIdLen

uint8_t sessionIdLen

Definition at line 309 of file tls13_misc.h.

◆ ticketAgeAdd

uint32_t ticketAgeAdd

Random value used to obscure the age of the ticket.

Definition at line 339 of file tls13_misc.h.

◆ ticketLifetime

uint32_t ticketLifetime

Lifetime of the ticket.

Definition at line 375 of file tls13_misc.h.

◆ ticketNonce

uint8_t ticketNonce

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

Definition at line 341 of file tls13_misc.h.

◆ ticketNonceLen

uint8_t ticketNonceLen

Definition at line 340 of file tls13_misc.h.

◆ ticketPsk

uint8_t ticketPsk[TLS13_MAX_HKDF_DIGEST_SIZE]

PSK associated with the ticket.

Definition at line 379 of file tls13_misc.h.

◆ ticketPskLen

size_t ticketPskLen

Length of the PSK associated with the ticket.

Definition at line 378 of file tls13_misc.h.

◆ ticketTimestamp

systime_t ticketTimestamp

Timestamp to manage ticket lifetime.

Definition at line 374 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 286 of file tls13_misc.h.

◆ Tls13Cookie

Tls13Cookie

Definition at line 197 of file tls13_misc.h.

◆ Tls13DigitalSignature

Tls13DigitalSignature

Definition at line 298 of file tls13_misc.h.

◆ Tls13EncryptedExtensions

Tls13EncryptedExtensions

Definition at line 329 of file tls13_misc.h.

◆ Tls13HelloRetryRequest

Tls13HelloRetryRequest

Definition at line 311 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 209 of file tls13_misc.h.

◆ Tls13KeyShareList

Tls13KeyShareList

Definition at line 220 of file tls13_misc.h.

◆ Tls13KeyUpdate

Tls13KeyUpdate

Definition at line 352 of file tls13_misc.h.

◆ Tls13NewSessionTicket

Tls13NewSessionTicket

Definition at line 342 of file tls13_misc.h.

◆ Tls13PlaintextSessionState

Tls13PlaintextSessionState

Definition at line 380 of file tls13_misc.h.

◆ Tls13PskBinder

Tls13PskBinder

Definition at line 264 of file tls13_misc.h.

◆ Tls13PskBinderList

Tls13PskBinderList

Definition at line 275 of file tls13_misc.h.

◆ Tls13PskIdentity

Tls13PskIdentity

Definition at line 242 of file tls13_misc.h.

◆ Tls13PskIdentityList

Tls13PskIdentityList

Definition at line 253 of file tls13_misc.h.

◆ Tls13PskKeModeList

Tls13PskKeModeList

Definition at line 231 of file tls13_misc.h.

◆ Tls13Ticket

Tls13Ticket

Definition at line 363 of file tls13_misc.h.

◆ value

uint8_t value[]

Definition at line 196 of file tls13_misc.h.

uint16_t length
Definition: tls13_misc.h:207