TLS (Transport Layer Security) More...

#include "tls.h"
#include "tls_cipher_suites.h"
#include "tls_handshake.h"
#include "tls_common.h"
#include "tls_certificate.h"
#include "tls_transcript_hash.h"
#include "tls_record.h"
#include "tls_misc.h"
#include "tls13_client_misc.h"
#include "tls13_ticket.h"
#include "dtls_record.h"
#include "pkix/pem_import.h"
#include "pkix/x509_cert_parse.h"
#include "debug.h"

Macros
#define	TRACE_LEVEL TLS_TRACE_LEVEL

Functions
TlsContext *	tlsInit (void)
	TLS context initialization. More...

TlsState	tlsGetState (TlsContext *context)
	Retrieve current TLS state. More...

error_t	tlsSetStateChangeCallback (TlsContext *context, TlsStateChangeCallback stateChangeCallback)
	Register TLS state change callback. More...

error_t	tlsSetSocketCallbacks (TlsContext *context, TlsSocketSendCallback socketSendCallback, TlsSocketReceiveCallback socketReceiveCallback, TlsSocketHandle handle)
	Set socket send and receive callbacks. More...

error_t	tlsSetVersion (TlsContext *context, uint16_t versionMin, uint16_t versionMax)
	Set minimum and maximum versions permitted. More...

error_t	tlsSetTransportProtocol (TlsContext *context, TlsTransportProtocol transportProtocol)
	Set the transport protocol to be used. More...

error_t	tlsSetConnectionEnd (TlsContext *context, TlsConnectionEnd entity)
	Set operation mode (client or server) More...

error_t	tlsSetPrng (TlsContext context, const PrngAlgo prngAlgo, void *prngContext)
	Set the pseudo-random number generator to be used. More...

error_t	tlsSetServerName (TlsContext context, const char_t serverName)
	Set the server name. More...

const char_t *	tlsGetServerName (TlsContext *context)
	Get the server name. More...

error_t	tlsSetCache (TlsContext context, TlsCache cache)
	Set session cache. More...

error_t	tlsSetClientAuthMode (TlsContext *context, TlsClientAuthMode mode)
	Set client authentication mode (for servers only) More...

error_t	tlsSetBufferSize (TlsContext *context, size_t txBufferSize, size_t rxBufferSize)
	Set TLS buffer size. More...

error_t	tlsSetMaxFragmentLength (TlsContext *context, size_t maxFragLen)
	Set maximum fragment length. More...

error_t	tlsSetCipherSuites (TlsContext context, const uint16_t cipherSuites, uint_t length)
	Specify the list of allowed cipher suites. More...

error_t	tlsSetSupportedGroups (TlsContext context, const uint16_t groups, uint_t length)
	Specify the list of allowed ECDHE and FFDHE groups. More...

error_t	tlsSetPreferredGroup (TlsContext *context, uint16_t group)
	Specify the preferred ECDHE or FFDHE group. More...

error_t	tlsSetSupportedSignAlgos (TlsContext context, const uint16_t signAlgos, uint_t length)
	Specify the list of allowed signature algorithms. More...

error_t	tlsSetDhParameters (TlsContext context, const char_t params, size_t length)
	Import Diffie-Hellman parameters. More...

error_t	tlsSetEcdhCallback (TlsContext *context, TlsEcdhCallback ecdhCallback)
	Register ECDH key agreement callback function. More...

error_t	tlsSetEcdsaSignCallback (TlsContext *context, TlsEcdsaSignCallback ecdsaSignCallback)
	Register ECDSA signature generation callback function. More...

error_t	tlsSetEcdsaVerifyCallback (TlsContext *context, TlsEcdsaVerifyCallback ecdsaVerifyCallback)
	Register ECDSA signature verification callback function. More...

error_t	tlsSetKeyLogCallback (TlsContext *context, TlsKeyLogCallback keyLogCallback)
	Register key logging callback function (for debugging purpose only) More...

error_t	tlsAllowUnknownAlpnProtocols (TlsContext *context, bool_t allowed)
	Allow unknown ALPN protocols. More...

error_t	tlsSetAlpnProtocolList (TlsContext context, const char_t protocolList)
	Set the list of supported ALPN protocols. More...

error_t	tlsSetAlpnCallback (TlsContext *context, TlsAlpnCallback alpnCallback)
	Register ALPN callback function. More...

const char_t *	tlsGetAlpnProtocol (TlsContext *context)
	Get the name of the selected ALPN protocol. More...

error_t	tlsSetPsk (TlsContext context, const uint8_t psk, size_t length)
	Set the pre-shared key to be used. More...

error_t	tlsSetPskIdentity (TlsContext context, const char_t pskIdentity)
	Set the PSK identity to be used by the client. More...

error_t	tlsSetPskIdentityHint (TlsContext context, const char_t pskIdentityHint)
	Set the PSK identity hint to be used by the server. More...

error_t	tlsSetPskCallback (TlsContext *context, TlsPskCallback pskCallback)
	Register PSK callback function. More...

error_t	tlsSetRpkVerifyCallback (TlsContext *context, TlsRpkVerifyCallback rpkVerifyCallback)
	Register the raw public key verification callback function. More...

error_t	tlsSetTrustedCaList (TlsContext context, const char_t trustedCaList, size_t length)
	Import a trusted CA list. More...

error_t	tlsAddCertificate (TlsContext context, const char_t certChain, size_t certChainLen, const char_t *privateKey, size_t privateKeyLen)
	Add a certificate and the corresponding private key (deprecated) More...

error_t	tlsLoadCertificate (TlsContext context, uint_t index, const char_t certChain, size_t certChainLen, const char_t privateKey, size_t privateKeyLen, const char_t password)
	Load entity's certificate. More...

error_t	tlsSetCertificateVerifyCallback (TlsContext context, TlsCertVerifyCallback certVerifyCallback, void param)
	Register certificate verification callback function. More...

error_t	tlsEnableSessionTickets (TlsContext *context, bool_t enabled)
	Enable session ticket mechanism. More...

error_t	tlsEnableSecureRenegotiation (TlsContext *context, bool_t enabled)
	Enable secure renegotiation. More...

error_t	tlsEnableFallbackScsv (TlsContext *context, bool_t enabled)
	Perform fallback retry (for clients only) More...

error_t	tlsSetTicketCallbacks (TlsContext context, TlsTicketEncryptCallback ticketEncryptCallback, TlsTicketDecryptCallback ticketDecryptCallback, void param)
	Set ticket encryption/decryption callbacks. More...

error_t	tlsSetPmtu (TlsContext *context, size_t pmtu)
	Set PMTU value (for DTLS only) More...

error_t	tlsSetTimeout (TlsContext *context, systime_t timeout)
	Set timeout for blocking calls (for DTLS only) More...

error_t	tlsSetCookieCallbacks (TlsContext context, DtlsCookieGenerateCallback cookieGenerateCallback, DtlsCookieVerifyCallback cookieVerifyCallback, void param)
	Set cookie generation/verification callbacks (for DTLS only) More...

error_t	tlsEnableReplayDetection (TlsContext *context, bool_t enabled)
	Enable anti-replay mechanism (for DTLS only) More...

error_t	tlsSetMaxEarlyDataSize (TlsContext *context, size_t maxEarlyDataSize)
	Send the maximum amount of 0-RTT data the server can accept. More...

error_t	tlsWriteEarlyData (TlsContext context, const void data, size_t length, size_t *written, uint_t flags)
	Send early data to the remote TLS server. More...

error_t	tlsConnect (TlsContext *context)
	Initiate the TLS handshake. More...

TlsEarlyDataStatus	tlsGetEarlyDataStatus (TlsContext *context)
	Check whether the server has accepted or rejected the early data. More...

error_t	tlsWrite (TlsContext context, const void data, size_t length, size_t *written, uint_t flags)
	Send application data to the remote host using TLS. More...

error_t	tlsRead (TlsContext context, void data, size_t size, size_t *received, uint_t flags)
	Receive application data from a the remote host using TLS. More...

bool_t	tlsIsTxReady (TlsContext *context)
	Check whether some data is ready for transmission. More...

bool_t	tlsIsRxReady (TlsContext *context)
	Check whether some data is available in the receive buffer. More...

error_t	tlsShutdown (TlsContext *context)
	Gracefully close TLS session. More...

error_t	tlsShutdownEx (TlsContext *context, bool_t waitForCloseNotify)
	Gracefully close TLS session. More...

void	tlsFree (TlsContext *context)
	Release TLS context. More...

error_t	tlsInitSessionState (TlsSessionState *session)
	Initialize session state. More...

error_t	tlsSaveSessionState (const TlsContext context, TlsSessionState session)
	Save TLS session. More...

error_t	tlsRestoreSessionState (TlsContext context, const TlsSessionState session)
	Restore TLS session. More...

void	tlsFreeSessionState (TlsSessionState *session)
	Properly dispose a session state. More...

Detailed Description

TLS (Transport Layer Security)

License

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

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.

Description

The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery

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

Version: 2.4.4

Definition in file tls.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL TLS_TRACE_LEVEL

Definition at line 38 of file tls.c.

Function Documentation

◆ tlsAddCertificate()

error_t tlsAddCertificate	(	TlsContext *	context,
		const char_t *	certChain,
		size_t	certChainLen,
		const char_t *	privateKey,
		size_t	privateKeyLen
	)

Add a certificate and the corresponding private key (deprecated)

Parameters

[in]	context	Pointer to the TLS context
[in]	certChain	Certificate chain (PEM format). This parameter is taken as reference
[in]	certChainLen	Total length of the certificate chain
[in]	privateKey	Private key (PEM format). This parameter is taken as reference
[in]	privateKeyLen	Total length of the private key

Returns: Error code

Definition at line 1231 of file tls.c.

◆ tlsAllowUnknownAlpnProtocols()

error_t tlsAllowUnknownAlpnProtocols	(	TlsContext *	context,
		bool_t	allowed
	)

Allow unknown ALPN protocols.

Parameters

[in]	context	Pointer to the TLS context
[in]	allowed	Specifies whether unknown ALPN protocols are allowed

Returns: Error code

Definition at line 858 of file tls.c.

◆ tlsConnect()

error_t tlsConnect ( TlsContext * context )

Initiate the TLS handshake.

Parameters

[in] context Pointer to the TLS context

Returns: Error code

Definition at line 1763 of file tls.c.

◆ tlsEnableFallbackScsv()

error_t tlsEnableFallbackScsv	(	TlsContext *	context,
		bool_t	enabled
	)

Perform fallback retry (for clients only)

Parameters

[in]	context	Pointer to the TLS context
[in]	enabled	Specifies whether FALLBACK_SCSV is enabled

Returns: Error code

Definition at line 1489 of file tls.c.

◆ tlsEnableReplayDetection()

error_t tlsEnableReplayDetection	(	TlsContext *	context,
		bool_t	enabled
	)

Enable anti-replay mechanism (for DTLS only)

Parameters

[in]	context	Pointer to the TLS context
[in]	enabled	Specifies whether anti-replay protection is enabled

Returns: Error code

Definition at line 1643 of file tls.c.

◆ tlsEnableSecureRenegotiation()

error_t tlsEnableSecureRenegotiation	(	TlsContext *	context,
		bool_t	enabled
	)

Enable secure renegotiation.

Parameters

[in]	context	Pointer to the TLS context
[in]	enabled	Specifies whether secure renegotiation is allowed

Returns: Error code

Definition at line 1463 of file tls.c.

◆ tlsEnableSessionTickets()

error_t tlsEnableSessionTickets	(	TlsContext *	context,
		bool_t	enabled
	)

Enable session ticket mechanism.

Parameters

[in]	context	Pointer to the TLS context
[in]	enabled	Specifies whether session tickets are allowed

Returns: Error code

Definition at line 1437 of file tls.c.

◆ tlsFree()

void tlsFree ( TlsContext * context )

Release TLS context.

Parameters

[in] context Pointer to the TLS context

Definition at line 2469 of file tls.c.

◆ tlsFreeSessionState()

void tlsFreeSessionState ( TlsSessionState * session )

Properly dispose a session state.

Parameters

[in] session Pointer to the session state to be released

Definition at line 2753 of file tls.c.

◆ tlsGetAlpnProtocol()

const char_t* tlsGetAlpnProtocol ( TlsContext * context )

Get the name of the selected ALPN protocol.

Parameters

[in] context Pointer to the TLS context

Returns: Pointer to the protocol name

Definition at line 958 of file tls.c.

◆ tlsGetEarlyDataStatus()

TlsEarlyDataStatus tlsGetEarlyDataStatus ( TlsContext * context )

Check whether the server has accepted or rejected the early data.

Parameters

[in] context Pointer to the TLS context

Returns: TLS_EARLY_DATA_ACCEPTED if the early data was accepted, else TLS_EARLY_DATA_REJECT if the early data was rejected

Definition at line 1811 of file tls.c.

◆ tlsGetServerName()

const char_t* tlsGetServerName ( TlsContext * context )

Get the server name.

Parameters

[in] context Pointer to the TLS context

Returns: Fully qualified domain name of the server

Definition at line 453 of file tls.c.

◆ tlsGetState()

TlsState tlsGetState ( TlsContext * context )

Retrieve current TLS state.

Parameters

[in] context Pointer to the TLS context

Returns: Current TLS state

Definition at line 203 of file tls.c.

◆ tlsInit()

TlsContext* tlsInit ( void )

TLS context initialization.

Returns: Handle referencing the fully initialized TLS context

Definition at line 65 of file tls.c.

◆ tlsInitSessionState()

error_t tlsInitSessionState ( TlsSessionState * session )

Initialize session state.

Parameters

[in] session Pointer to the session state

Returns: Error code

Definition at line 2610 of file tls.c.

◆ tlsIsRxReady()

bool_t tlsIsRxReady ( TlsContext * context )

Check whether some data is available in the receive buffer.

Parameters

[in] context Pointer to the TLS context

Returns: The function returns TRUE if some data is pending and can be read immediately without blocking. Otherwise, FALSE is returned

Definition at line 2262 of file tls.c.

◆ tlsIsTxReady()

bool_t tlsIsTxReady ( TlsContext * context )

Check whether some data is ready for transmission.

Parameters

[in] context Pointer to the TLS context

Returns: The function returns TRUE if some data is ready for transmission. Otherwise, FALSE is returned

Definition at line 2228 of file tls.c.

◆ tlsLoadCertificate()

error_t tlsLoadCertificate	(	TlsContext *	context,
		uint_t	index,
		const char_t *	certChain,
		size_t	certChainLen,
		const char_t *	privateKey,
		size_t	privateKeyLen,
		const char_t *	password
	)

Load entity's certificate.

Parameters

[in]	context	Pointer to the TLS context
[in]	index	Zero-based index identifying a slot
[in]	certChain	Certificate chain (PEM format). This parameter is taken as reference
[in]	certChainLen	Length of the certificate chain
[in]	privateKey	Private key (PEM format). This parameter is taken as reference
[in]	privateKeyLen	Length of the private key
[in]	password	NULL-terminated string containing the password. This parameter is required if the private key is encrypted

Returns: Error code

Definition at line 1275 of file tls.c.

◆ tlsRead()

error_t tlsRead	(	TlsContext *	context,
		void *	data,
		size_t	size,
		size_t *	received,
		uint_t	flags
	)

Receive application data from a the remote host using TLS.

Parameters

[in]	context	Pointer to the TLS context
[out]	data	Buffer into which received data will be placed
[in]	size	Maximum number of bytes that can be received
[out]	received	Number of bytes that have been received
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 1989 of file tls.c.

◆ tlsRestoreSessionState()

error_t tlsRestoreSessionState	(	TlsContext *	context,
		const TlsSessionState *	session
	)

Restore TLS session.

Parameters

[in]	context	Pointer to the TLS context
[in]	session	Pointer to the session state to be restored

Returns: Error code

Definition at line 2700 of file tls.c.

◆ tlsSaveSessionState()

error_t tlsSaveSessionState	(	const TlsContext *	context,
		TlsSessionState *	session
	)

Save TLS session.

Parameters

[in]	context	Pointer to the TLS context
[out]	session	Pointer to the session state

Returns: Error code

Definition at line 2631 of file tls.c.

◆ tlsSetAlpnCallback()

error_t tlsSetAlpnCallback	(	TlsContext *	context,
		TlsAlpnCallback	alpnCallback
	)

Register ALPN callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	alpnCallback	ALPN callback function

Returns: Error code

Definition at line 933 of file tls.c.

◆ tlsSetAlpnProtocolList()

error_t tlsSetAlpnProtocolList	(	TlsContext *	context,
		const char_t *	protocolList
	)

Set the list of supported ALPN protocols.

Parameters

[in]	context	Pointer to the TLS context
[in]	protocolList	Comma-delimited list of supported protocols

Returns: Error code

Definition at line 884 of file tls.c.

◆ tlsSetBufferSize()

error_t tlsSetBufferSize	(	TlsContext *	context,
		size_t	txBufferSize,
		size_t	rxBufferSize
	)

Set TLS buffer size.

Parameters

[in]	context	Pointer to the TLS context
[in]	txBufferSize	TX buffer size
[in]	rxBufferSize	RX buffer size

Returns: Error code

Definition at line 521 of file tls.c.

◆ tlsSetCache()

error_t tlsSetCache	(	TlsContext *	context,
		TlsCache *	cache
	)

Set session cache.

Parameters

[in]	context	Pointer to the TLS context
[in]	cache	Session cache that will be used to save/resume TLS sessions

Returns: Error code

Definition at line 478 of file tls.c.

◆ tlsSetCertificateVerifyCallback()

error_t tlsSetCertificateVerifyCallback	(	TlsContext *	context,
		TlsCertVerifyCallback	certVerifyCallback,
		void *	param
	)

Register certificate verification callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	certVerifyCallback	Certificate verification callback function
[in]	param	An opaque pointer passed to the callback function

Returns: Error code

Definition at line 1413 of file tls.c.

◆ tlsSetCipherSuites()

error_t tlsSetCipherSuites	(	TlsContext *	context,
		const uint16_t *	cipherSuites,
		uint_t	length
	)

Specify the list of allowed cipher suites.

Parameters

[in]	context	Pointer to the TLS context
[in]	cipherSuites	List of allowed cipher suites (most preferred first). This parameter is taken as reference
[in]	length	Number of cipher suites in the list

Returns: Error code

Definition at line 605 of file tls.c.

◆ tlsSetClientAuthMode()

error_t tlsSetClientAuthMode	(	TlsContext *	context,
		TlsClientAuthMode	mode
	)

Set client authentication mode (for servers only)

Parameters

[in]	context	Pointer to the TLS context
[in]	mode	Client authentication mode

Returns: Error code

Definition at line 499 of file tls.c.

◆ tlsSetConnectionEnd()

error_t tlsSetConnectionEnd	(	TlsContext *	context,
		TlsConnectionEnd	entity
	)

Set operation mode (client or server)

Parameters

[in]	context	Pointer to the TLS context
[in]	entity	Specifies whether this entity is considered a client or a server

Returns: Error code

Definition at line 349 of file tls.c.

◆ tlsSetCookieCallbacks()

error_t tlsSetCookieCallbacks	(	TlsContext *	context,
		DtlsCookieGenerateCallback	cookieGenerateCallback,
		DtlsCookieVerifyCallback	cookieVerifyCallback,
		void *	param
	)

Set cookie generation/verification callbacks (for DTLS only)

Parameters

[in]	context	Pointer to the TLS context
[in]	cookieGenerateCallback	Cookie generation callback function
[in]	cookieVerifyCallback	Cookie verification callback function
[in]	param	An opaque pointer passed to the callback functions

Returns: Error code

Definition at line 1607 of file tls.c.

◆ tlsSetDhParameters()

error_t tlsSetDhParameters	(	TlsContext *	context,
		const char_t *	params,
		size_t	length
	)

Import Diffie-Hellman parameters.

Parameters

[in]	context	Pointer to the TLS context
[in]	params	PEM structure that holds Diffie-Hellman parameters. This parameter is taken as reference
[in]	length	Total length of the DER structure

Returns: Error code

Definition at line 723 of file tls.c.

◆ tlsSetEcdhCallback()

error_t tlsSetEcdhCallback	(	TlsContext *	context,
		TlsEcdhCallback	ecdhCallback
	)

Register ECDH key agreement callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	ecdhCallback	ECDH callback function

Returns: Error code

Definition at line 751 of file tls.c.

◆ tlsSetEcdsaSignCallback()

error_t tlsSetEcdsaSignCallback	(	TlsContext *	context,
		TlsEcdsaSignCallback	ecdsaSignCallback
	)

Register ECDSA signature generation callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	ecdsaSignCallback	ECDSA signature generation callback function

Returns: Error code

Definition at line 777 of file tls.c.

◆ tlsSetEcdsaVerifyCallback()

error_t tlsSetEcdsaVerifyCallback	(	TlsContext *	context,
		TlsEcdsaVerifyCallback	ecdsaVerifyCallback
	)

Register ECDSA signature verification callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	ecdsaVerifyCallback	ECDSA signature verification callback function

Returns: Error code

Definition at line 804 of file tls.c.

◆ tlsSetKeyLogCallback()

error_t tlsSetKeyLogCallback	(	TlsContext *	context,
		TlsKeyLogCallback	keyLogCallback
	)

Register key logging callback function (for debugging purpose only)

Parameters

[in]	context	Pointer to the TLS context
[in]	keyLogCallback	Key logging callback function

Returns: Error code

Definition at line 831 of file tls.c.

◆ tlsSetMaxEarlyDataSize()

error_t tlsSetMaxEarlyDataSize	(	TlsContext *	context,
		size_t	maxEarlyDataSize
	)

Send the maximum amount of 0-RTT data the server can accept.

Parameters

[in]	context	Pointer to the TLS context
[in]	maxEarlyDataSize	Maximum amount of 0-RTT data that the client is allowed to send

Returns: Error code

Definition at line 1671 of file tls.c.

◆ tlsSetMaxFragmentLength()

error_t tlsSetMaxFragmentLength	(	TlsContext *	context,
		size_t	maxFragLen
	)

Set maximum fragment length.

Parameters

[in]	context	Pointer to the TLS context
[in]	maxFragLen	Maximum fragment length

Returns: Error code

Definition at line 569 of file tls.c.

◆ tlsSetPmtu()

error_t tlsSetPmtu	(	TlsContext *	context,
		size_t	pmtu
	)

Set PMTU value (for DTLS only)

Parameters

[in]	context	Pointer to the TLS context
[in]	pmtu	PMTU value

Returns: Error code

Definition at line 1549 of file tls.c.

◆ tlsSetPreferredGroup()

error_t tlsSetPreferredGroup	(	TlsContext *	context,
		uint16_t	group
	)

Specify the preferred ECDHE or FFDHE group.

Parameters

[in]	context	Pointer to the TLS context
[in]	group	Preferred ECDHE or FFDHE named group

Returns: Error code

Definition at line 661 of file tls.c.

◆ tlsSetPrng()

error_t tlsSetPrng	(	TlsContext *	context,
		const PrngAlgo *	prngAlgo,
		void *	prngContext
	)

Set the pseudo-random number generator to be used.

Parameters

[in]	context	Pointer to the TLS context
[in]	prngAlgo	PRNG algorithm
[in]	prngContext	Pointer to the PRNG context

Returns: Error code

Definition at line 375 of file tls.c.

◆ tlsSetPsk()

error_t tlsSetPsk	(	TlsContext *	context,
		const uint8_t *	psk,
		size_t	length
	)

Set the pre-shared key to be used.

Parameters

[in]	context	Pointer to the TLS context
[in]	psk	Pointer to the pre-shared key
[in]	length	Length of the pre-shared key, in bytes

Returns: Error code

Definition at line 986 of file tls.c.

◆ tlsSetPskCallback()

error_t tlsSetPskCallback	(	TlsContext *	context,
		TlsPskCallback	pskCallback
	)

Register PSK callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	pskCallback	PSK callback function

Returns: Error code

Definition at line 1145 of file tls.c.

◆ tlsSetPskIdentity()

error_t tlsSetPskIdentity	(	TlsContext *	context,
		const char_t *	pskIdentity
	)

Set the PSK identity to be used by the client.

Parameters

[in]	context	Pointer to the TLS context
[in]	pskIdentity	NULL-terminated string that contains the PSK identity

Returns: Error code

Definition at line 1047 of file tls.c.

◆ tlsSetPskIdentityHint()

error_t tlsSetPskIdentityHint	(	TlsContext *	context,
		const char_t *	pskIdentityHint
	)

Set the PSK identity hint to be used by the server.

Parameters

[in]	context	Pointer to the TLS context
[in]	pskIdentityHint	NULL-terminated string that contains the PSK identity hint

Returns: Error code

Definition at line 1096 of file tls.c.

◆ tlsSetRpkVerifyCallback()

error_t tlsSetRpkVerifyCallback	(	TlsContext *	context,
		TlsRpkVerifyCallback	rpkVerifyCallback
	)

Register the raw public key verification callback function.

Parameters

[in]	context	Pointer to the TLS context
[in]	rpkVerifyCallback	RPK verification callback function

Returns: Error code

Definition at line 1171 of file tls.c.

◆ tlsSetServerName()

error_t tlsSetServerName	(	TlsContext *	context,
		const char_t *	serverName
	)

Set the server name.

Parameters

[in]	context	Pointer to the TLS context
[in]	serverName	Fully qualified domain name of the server

Returns: Error code

Definition at line 403 of file tls.c.

◆ tlsSetSocketCallbacks()

error_t tlsSetSocketCallbacks	(	TlsContext *	context,
		TlsSocketSendCallback	socketSendCallback,
		TlsSocketReceiveCallback	socketReceiveCallback,
		TlsSocketHandle	handle
	)

Set socket send and receive callbacks.

Parameters

[in]	context	Pointer to the TLS context
[in]	socketSendCallback	Send callback function
[in]	socketReceiveCallback	Receive callback function
[in]	handle	Socket handle

Returns: Error code

Definition at line 253 of file tls.c.

◆ tlsSetStateChangeCallback()

error_t tlsSetStateChangeCallback	(	TlsContext *	context,
		TlsStateChangeCallback	stateChangeCallback
	)

Register TLS state change callback.

Parameters

[in]	context	Pointer to the TLS context
[in]	stateChangeCallback	TLS state change callback

Returns: Error code

Definition at line 229 of file tls.c.

◆ tlsSetSupportedGroups()

error_t tlsSetSupportedGroups	(	TlsContext *	context,
		const uint16_t *	groups,
		uint_t	length
	)

Specify the list of allowed ECDHE and FFDHE groups.

Parameters

[in]	context	Pointer to the TLS context
[in]	groups	List of named groups (most preferred first). This parameter is taken as reference
[in]	length	Number of named groups in the list

Returns: Error code

Definition at line 634 of file tls.c.

◆ tlsSetSupportedSignAlgos()

error_t tlsSetSupportedSignAlgos	(	TlsContext *	context,
		const uint16_t *	signAlgos,
		uint_t	length
	)

Specify the list of allowed signature algorithms.

Parameters

[in]	context	Pointer to the TLS context
[in]	signAlgos	List of signature algorithms (most preferred first). This parameter is taken as reference
[in]	length	Number of signature algorithms in the list

Returns: Error code

Definition at line 689 of file tls.c.

◆ tlsSetTicketCallbacks()

error_t tlsSetTicketCallbacks	(	TlsContext *	context,
		TlsTicketEncryptCallback	ticketEncryptCallback,
		TlsTicketDecryptCallback	ticketDecryptCallback,
		void *	param
	)

Set ticket encryption/decryption callbacks.

Parameters

[in]	context	Pointer to the TLS context
[in]	ticketEncryptCallback	Ticket encryption callback function
[in]	ticketDecryptCallback	Ticket decryption callback function
[in]	param	An opaque pointer passed to the callback functions

Returns: Error code

Definition at line 1517 of file tls.c.

◆ tlsSetTimeout()

error_t tlsSetTimeout	(	TlsContext *	context,
		systime_t	timeout
	)

Set timeout for blocking calls (for DTLS only)

Parameters

[in]	context	Pointer to the TLS context
[in]	timeout	Maximum time to wait

Returns: Error code

Definition at line 1579 of file tls.c.

◆ tlsSetTransportProtocol()

error_t tlsSetTransportProtocol	(	TlsContext *	context,
		TlsTransportProtocol	transportProtocol
	)

Set the transport protocol to be used.

Parameters

[in]	context	Pointer to the TLS context
[in]	transportProtocol	Transport protocol to be used

Returns: Error code

Definition at line 319 of file tls.c.

◆ tlsSetTrustedCaList()

error_t tlsSetTrustedCaList	(	TlsContext *	context,
		const char_t *	trustedCaList,
		size_t	length
	)

Import a trusted CA list.

Parameters

[in]	context	Pointer to the TLS context
[in]	trustedCaList	List of trusted CA (PEM format)
[in]	length	Total length of the list

Returns: Error code

Definition at line 1199 of file tls.c.

◆ tlsSetVersion()

error_t tlsSetVersion	(	TlsContext *	context,
		uint16_t	versionMin,
		uint16_t	versionMax
	)

Set minimum and maximum versions permitted.

Parameters

[in]	context	Pointer to the TLS context
[in]	versionMin	Minimum version accepted by the TLS implementation
[in]	versionMax	Maximum version accepted by the TLS implementation

Returns: Error code

Definition at line 285 of file tls.c.

◆ tlsShutdown()

error_t tlsShutdown ( TlsContext * context )

Gracefully close TLS session.

Parameters

[in] context Pointer to the TLS context

Definition at line 2307 of file tls.c.

◆ tlsShutdownEx()

error_t tlsShutdownEx	(	TlsContext *	context,
		bool_t	waitForCloseNotify
	)

Gracefully close TLS session.

Parameters

[in]	context	Pointer to the TLS context
[in]	waitForCloseNotify	Wait for the close notify alert from the peer

Definition at line 2320 of file tls.c.

◆ tlsWrite()

error_t tlsWrite	(	TlsContext *	context,
		const void *	data,
		size_t	length,
		size_t *	written,
		uint_t	flags
	)

Send application data to the remote host using TLS.

Parameters

[in]	context	Pointer to the TLS context
[in]	data	Pointer to a buffer containing the data to be transmitted
[in]	length	Number of bytes to be transmitted
[out]	written	Actual number of bytes written (optional parameter)
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 1854 of file tls.c.

◆ tlsWriteEarlyData()

error_t tlsWriteEarlyData	(	TlsContext *	context,
		const void *	data,
		size_t	length,
		size_t *	written,
		uint_t	flags
	)

Send early data to the remote TLS server.

Parameters

[in]	context	Pointer to the TLS context
[in]	data	Pointer to a buffer containing the data to be transmitted
[in]	length	Number of bytes to be transmitted
[out]	written	Actual number of bytes written (optional parameter)
[in]	flags	Set of flags that influences the behavior of this function

Returns: Error code

Definition at line 1700 of file tls.c.

Macros

Functions

Detailed Description

License

Description

Macro Definition Documentation

◆ TRACE_LEVEL

Function Documentation

◆ tlsAddCertificate()

◆ tlsAllowUnknownAlpnProtocols()

◆ tlsConnect()

◆ tlsEnableFallbackScsv()

◆ tlsEnableReplayDetection()

◆ tlsEnableSecureRenegotiation()

◆ tlsEnableSessionTickets()

◆ tlsFree()

◆ tlsFreeSessionState()

◆ tlsGetAlpnProtocol()

◆ tlsGetEarlyDataStatus()

◆ tlsGetServerName()

◆ tlsGetState()

◆ tlsInit()

◆ tlsInitSessionState()

◆ tlsIsRxReady()

◆ tlsIsTxReady()

◆ tlsLoadCertificate()

◆ tlsRead()

◆ tlsRestoreSessionState()

◆ tlsSaveSessionState()

◆ tlsSetAlpnCallback()

◆ tlsSetAlpnProtocolList()

◆ tlsSetBufferSize()

◆ tlsSetCache()

◆ tlsSetCertificateVerifyCallback()

◆ tlsSetCipherSuites()

◆ tlsSetClientAuthMode()

◆ tlsSetConnectionEnd()

◆ tlsSetCookieCallbacks()

◆ tlsSetDhParameters()

◆ tlsSetEcdhCallback()

◆ tlsSetEcdsaSignCallback()

◆ tlsSetEcdsaVerifyCallback()

◆ tlsSetKeyLogCallback()

◆ tlsSetMaxEarlyDataSize()

◆ tlsSetMaxFragmentLength()

◆ tlsSetPmtu()

◆ tlsSetPreferredGroup()

◆ tlsSetPrng()

◆ tlsSetPsk()

◆ tlsSetPskCallback()

◆ tlsSetPskIdentity()

◆ tlsSetPskIdentityHint()

◆ tlsSetRpkVerifyCallback()

◆ tlsSetServerName()

◆ tlsSetSocketCallbacks()

◆ tlsSetStateChangeCallback()

◆ tlsSetSupportedGroups()

◆ tlsSetSupportedSignAlgos()

◆ tlsSetTicketCallbacks()

◆ tlsSetTimeout()

◆ tlsSetTransportProtocol()

◆ tlsSetTrustedCaList()

◆ tlsSetVersion()

◆ tlsShutdown()

◆ tlsShutdownEx()

◆ tlsWrite()

◆ tlsWriteEarlyData()