PAL TLS/DTLS - platform. This file contains TLS/DTLS APIs that need to be implemented in the platform layer. More...

Typedefs
typedef enum palTLSAuthMode	palTLSAuthMode_t
	Server mode.
typedef enum palTLSSuites	palTLSSuites_t
	This is the list of the available cipher suites.
Enumerations
enum	palTLSAuthMode { PAL_TLS_VERIFY_NONE, PAL_TLS_VERIFY_OPTIONAL, PAL_TLS_VERIFY_REQUIRED }
	Server mode. More...
enum	palTLSSuites
	This is the list of the available cipher suites. More...
Functions
palStatus_t	pal_plat_initTLSLibrary (void)
	Initiate the TLS library.
palStatus_t	pal_plat_cleanupTLS (void)
	Free resources for the TLS library.
palStatus_t	pal_plat_initTLSConf (palTLSConfHandle_t *confCtx, palTLSTransportMode_t transportVersion, palDTLSSide_t methodType)
	Initiate a new configuration context.
palStatus_t	pal_plat_tlsConfigurationFree (palTLSConfHandle_t *palTLSConf)
	Destroy and release resources for the TLS configuration context.
palStatus_t	pal_plat_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t *palTLSHandle)
	Initiate a new TLS context.
palStatus_t	pal_plat_freeTLS (palTLSHandle_t *palTLSHandle)
	Destroy and release resources for the TLS context.
palStatus_t	pal_plat_addEntropySource (palEntropySource_f entropyCallback)
	Add an entropy source to the TLS/DTLS library.
palStatus_t	pal_plat_setCipherSuites (palTLSConfHandle_t sslConf, palTLSSuites_t palSuite)
	Set the supported cipher suites to the configuration context.
palStatus_t	pal_plat_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t *verifyResult)
	Return the result of the certificate verification. The handshake API calls this.
palStatus_t	pal_plat_sslRead (palTLSHandle_t palTLSHandle, void buffer, uint32_t len, uint32_t actualLen)
	Read at most 'len' application data bytes.
palStatus_t	pal_plat_sslWrite (palTLSHandle_t palTLSHandle, const void buffer, uint32_t len, uint32_t bytesWritten)
	Try to write exactly 'len' application data bytes.
palStatus_t	pal_plat_setHandShakeTimeOut (palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec)
	Set the retransmit timeout values for the DTLS handshake. DTLS only, no effect on TLS.
palStatus_t	pal_plat_sslSetup (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
	Set up a TLS context for use.
palStatus_t	pal_plat_handShake (palTLSHandle_t palTLSHandle, uint64_t *serverTime)
	Perform the TLS handshake.
palStatus_t	pal_plat_renegotiate (palTLSHandle_t palTLSHandle, uint64_t serverTime)
	Perform the TLS handshake renegotiation.
palStatus_t	pal_plat_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
	Set the socket for the TLS configuration context.
palStatus_t	pal_plat_setOwnCertAndPrivateKey (palTLSConfHandle_t palTLSConf, palX509_t ownCert, palPrivateKey_t privateKey)
	Set your own certificate chain and private key.
palStatus_t	pal_plat_setOwnCertChain (palTLSConfHandle_t palTLSConf, palX509_t *ownCert)
	Set your own certificate chain.
palStatus_t	pal_plat_setOwnPrivateKey (palTLSConfHandle_t palTLSConf, palPrivateKey_t *privateKey)
	Set your own private key.
palStatus_t	pal_plat_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t caChain, palX509CRL_t caCRL)
	Set the data required to verify a peer certificate.
palStatus_t	pal_plat_setPSK (palTLSConfHandle_t sslConf, const unsigned char identity, uint32_t maxIdentityLenInBytes, const unsigned char psk, uint32_t maxPskLenInBytes)
	Set the Pre-Shared Key (PSK) and the expected identity name.
palStatus_t	pal_plat_setAuthenticationMode (palTLSConfHandle_t sslConf, palTLSAuthMode_t authMode)
	Set the certificate verification mode.
palStatus_t	pal_plat_sslSetDebugging (palTLSConfHandle_t palTLSConf, uint8_t turnOn)
	Turn the TLS library debugging on or off for the given configuration handle.
palStatus_t	pal_plat_sslSetIOCallBacks (palTLSConfHandle_t palTLSConf, palTLSSocket_t *palIOCtx, palBIOSend_f palBIOSend, palBIORecv_f palBIORecv)
	Set the IO callbacks for the TLS context.
palStatus_t	pal_plat_setTimeCB (palTLSHandle_t *palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer)
	Set the timer callbacks.
palStatus_t	pal_plat_SetLoggingCb (palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext)
	Set the logging function.

Detailed Description

PAL TLS/DTLS - platform. This file contains TLS/DTLS APIs that need to be implemented in the platform layer.

Definition in file pal_plat_TLS.h.

Typedef Documentation

typedef enum palTLSAuthMode palTLSAuthMode_t

Server mode.

typedef enum palTLSSuites palTLSSuites_t

This is the list of the available cipher suites.

This code MUST be defined in the `pal_plat_TLS.c` with the proper values for the SSL platform.

Enumeration Type Documentation

enum palTLSAuthMode

Server mode.

Enumerator:

PAL_TLS_VERIFY_NONE	The peer certificate is not verified. For client mode, this is insecure!
PAL_TLS_VERIFY_OPTIONAL	The handshake continues even if the peer certificate verification fails.
PAL_TLS_VERIFY_REQUIRED	The peer certificate verification MUST pass.

Definition at line 38 of file pal_plat_TLS.h.

enum palTLSSuites

This is the list of the available cipher suites.

This code MUST be defined in the `pal_plat_TLS.c` with the proper values for the SSL platform.

Definition at line 49 of file pal_plat_TLS.h.

Function Documentation

palStatus_t pal_plat_addEntropySource ( palEntropySource_f entropyCallback )

Add an entropy source to the TLS/DTLS library.

Note:: This function is available ONLY when the TLS/DTLS platform supports this functionality. In other platforms, PAL_ERR_NOT_SUPPORTED should be returned.

Parameters:

[in] entropyCallback,: The entropy callback to be used in the TLS/DTLS handshake.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code or PAL_ERR_NOT_SUPPORTED in case of failure.

Definition at line 282 of file pal_plat_TLS.c.

palStatus_t pal_plat_cleanupTLS ( void )

Free resources for the TLS library.

Note:: You must call this function in the general PAL cleanup function.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Try to catch the Mutex in order to prevent situation of deleteing under use mutex

Definition at line 247 of file pal_plat_TLS.c.

palStatus_t pal_plat_freeTLS ( palTLSHandle_t * palTLSHandle )

Destroy and release resources for the TLS context.

Parameters:

[in,out] palTLSHandle,: The TLS context to free.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 467 of file pal_plat_TLS.c.

palStatus_t pal_plat_handShake	(	palTLSHandle_t	palTLSHandle,
		uint64_t *	serverTime
	)

Perform the TLS handshake.

Parameters:

[in]	palTLSHandle,:	The TLS context.
[out]	serverTime,:	The server time received in the server hello message during handshake.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 723 of file pal_plat_TLS.c.

palStatus_t pal_plat_initTLS	(	palTLSConfHandle_t	palTLSConf,
		palTLSHandle_t *	palTLSHandle
	)

Initiate a new TLS context.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[out]	palTLSHandle,:	The index to the TLS context.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 443 of file pal_plat_TLS.c.

palStatus_t pal_plat_initTLSConf	(	palTLSConfHandle_t *	confCtx,
		palTLSTransportMode_t	transportVersion,
		palDTLSSide_t	methodType
	)

Initiate a new configuration context.

Parameters:

[out]	confCtx,:	The TLS configuration context.
[in]	transportVersion,:	The `palTLSTransportMode_t` type deciding the transportation version, for example tlsv1.2.
[in]	methodType,:	The `palDTLSSide_t` type deciding the endpoint type (server or client).

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 310 of file pal_plat_TLS.c.

palStatus_t pal_plat_initTLSLibrary ( void )

Initiate the TLS library.

This API is not required for each TLS library. For example, for mbed TLS it will be an empty function.

Note:: You must call this function in the general PAL initialization function.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 207 of file pal_plat_TLS.c.

palStatus_t pal_plat_renegotiate	(	palTLSHandle_t	palTLSHandle,
		uint64_t	serverTime
	)

Perform the TLS handshake renegotiation.

Parameters:

[in]	palTLSHandle,:	The TLS context.
[in]	serverTime,:	The server time used to update the TLS time during handshake renegotiation.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

need to change the code for multi-threading mode (Erez)

Definition at line 751 of file pal_plat_TLS.c.

palStatus_t pal_plat_setAuthenticationMode	(	palTLSConfHandle_t	sslConf,
		palTLSAuthMode_t	authMode
	)

Set the certificate verification mode.

Parameters:

[in]	sslConf,:	The TLS configuration context.
[in]	authMode,:	The authentication mode.

Note:: In some platforms, a verification callback MAY be needed. In this case, it must be provided by the porting side.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 489 of file pal_plat_TLS.c.

palStatus_t pal_plat_setCAChain	(	palTLSConfHandle_t	palTLSConf,
		palX509_t *	caChain,
		palX509CRL_t *	caCRL
	)

Set the data required to verify a peer certificate.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	caChain,:	The trusted CA chain.
[in]	caCRL,:	The trusted CA CRLs.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 884 of file pal_plat_TLS.c.

palStatus_t pal_plat_setCipherSuites	(	palTLSConfHandle_t	sslConf,
		palTLSSuites_t	palSuite
	)

Set the supported cipher suites to the configuration context.

Parameters:

[in]	sslConf,:	The TLS configuration context.
[in]	palSuite,:	The supported cipher suites to be added.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 516 of file pal_plat_TLS.c.

palStatus_t pal_plat_setHandShakeTimeOut	(	palTLSConfHandle_t	palTLSConf,
		uint32_t	timeoutInMilliSec
	)

Set the retransmit timeout values for the DTLS handshake. DTLS only, no effect on TLS.

Parameters:

[in]	palTLSConf,:	The DTLS configuration context.
[in]	timeoutInMilliSec,:	The maximum timeout value in milliseconds.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

faster dividing by 2

Since mbedTLS algorithm for UDP handshake algorithm is as follow: wait 'minTimeout' ..=> 'minTimeout = 2*minTimeout' while 'minTimeout < maxTimeout' if 'minTimeout >= maxTimeout' them wait 'maxTimeout'. The whole waiting time is the sum of the different intervals waited. Therefore we need divide the 'timeoutInMilliSec' by 2 to give a close approximation of the desired 'timeoutInMilliSec' 1 + 2 + ... + 'timeoutInMilliSec/2' ~= 'timeoutInMilliSec'

Definition at line 658 of file pal_plat_TLS.c.

palStatus_t pal_plat_SetLoggingCb	(	palTLSConfHandle_t	palTLSConf,
		palLogFunc_f	palLogFunction,
		void *	logContext
	)

Set the logging function.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	palLogFunction,:	A pointer to the logging function.
[in]	logContext,:	The context for the logging function.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 980 of file pal_plat_TLS.c.

palStatus_t pal_plat_setOwnCertAndPrivateKey	(	palTLSConfHandle_t	palTLSConf,
		palX509_t *	ownCert,
		palPrivateKey_t *	privateKey
	)

Set your own certificate chain and private key.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	ownCert,:	Your own public certificate chain.
[in]	privateKey,:	Your own private key.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 798 of file pal_plat_TLS.c.

palStatus_t pal_plat_setOwnCertChain	(	palTLSConfHandle_t	palTLSConf,
		palX509_t *	ownCert
	)

Set your own certificate chain.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	ownCert,:	Your own public certificate chain.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 857 of file pal_plat_TLS.c.

palStatus_t pal_plat_setOwnPrivateKey	(	palTLSConfHandle_t	palTLSConf,
		palPrivateKey_t *	privateKey
	)

Set your own private key.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	privateKey,:	Your own private key.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 834 of file pal_plat_TLS.c.

palStatus_t pal_plat_setPSK	(	palTLSConfHandle_t	sslConf,
		const unsigned char *	identity,
		uint32_t	maxIdentityLenInBytes,
		const unsigned char *	psk,
		uint32_t	maxPskLenInBytes
	)

Set the Pre-Shared Key (PSK) and the expected identity name.

Parameters:

[in]	sslConf,:	The TLS configuration context.
[in]	identity,:	A pointer to the PSK identity.
[in]	maxIdentityLenInBytes,:	The maximum length of the identity key in bytes.
[in]	psk,:	A pointer to the PSK.
[in]	maxPskLenInBytes,:	The maximum length of the PSK in bytes.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 906 of file pal_plat_TLS.c.

palStatus_t pal_plat_setTimeCB	(	palTLSHandle_t *	palTLSHandle,
		palTimerCtx_t	timerCtx,
		palSetTimer_f	setTimer,
		palGetTimer_f	getTimer
	)

Set the timer callbacks.

Parameters:

[in]	palTLSHandle,:	The TLS context.
[in]	timerCtx,:	The shared context by BIO callbacks.
[in]	setTimer,:	The set timer callback.
[in]	getTimer,:	The get timer callback.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

palStatus_t pal_plat_sslGetVerifyResultExtended	(	palTLSHandle_t	palTLSHandle,
		int32_t *	verifyResult
	)

Return the result of the certificate verification. The handshake API calls this.

Parameters:

[in]	palTLSHandle,:	The TLS context.
[out]	verifyResult,:	bitmask of errors that cause the failure. This value is relevant ONLY in case the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.

Note:: In case the platform doesn't support multipule errors for certificate verification, please return `PAL_ERR_X509_CERT_VERIFY_FAILED` and the reason should be specified in the `verifyResult`

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

please DO NOT change errors order

Definition at line 554 of file pal_plat_TLS.c.

palStatus_t pal_plat_sslRead	(	palTLSHandle_t	palTLSHandle,
		void *	buffer,
		uint32_t	len,
		uint32_t *	actualLen
	)

Read at most 'len' application data bytes.

Parameters:

[in]	palTLSHandle,:	The TLS context.
[out]	buffer,:	A buffer holding the data.
[in]	len,:	The maximum number of bytes to read.
[out]	actualLen,:	The actual number of bytes read.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 602 of file pal_plat_TLS.c.

palStatus_t pal_plat_sslSetDebugging	(	palTLSConfHandle_t	palTLSConf,
		uint8_t	turnOn
	)

Turn the TLS library debugging on or off for the given configuration handle.

The logs are sent via the mbedTrace. In case of release mode, an error will be returned.

Parameters:

[in]	palTLSConf	: the TLS confuguraiton to modify
[in]	turnOn,:	if greater than 0 turn on debugging, otherwise turn it off

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 964 of file pal_plat_TLS.c.

palStatus_t pal_plat_sslSetIOCallBacks	(	palTLSConfHandle_t	palTLSConf,
		palTLSSocket_t *	palIOCtx,
		palBIOSend_f	palBIOSend,
		palBIORecv_f	palBIORecv
	)

Set the IO callbacks for the TLS context.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	palIOCtx,:	The shared context by BIO callbacks.
[in]	palBIOSend,:	A pointer to send BIO function.
[in]	palBIORecv,:	A pointer to receive BIO function.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 936 of file pal_plat_TLS.c.

palStatus_t pal_plat_sslSetup	(	palTLSHandle_t	palTLSHandle,
		palTLSConfHandle_t	palTLSConf
	)

Set up a TLS context for use.

Parameters:

[in,out]	palTLSHandle,:	The TLS context.
[in]	palTLSConf,:	The TLS configuration context.

Returns:: The function returns `palTLSHandle_t`, the index to the TLS context.

Definition at line 682 of file pal_plat_TLS.c.

palStatus_t pal_plat_sslWrite	(	palTLSHandle_t	palTLSHandle,
		const void *	buffer,
		uint32_t	len,
		uint32_t *	bytesWritten
	)

Try to write exactly 'len' application data bytes.

Parameters:

[in]	palTLSHandle,:	The TLS context.
[in]	buffer,:	A buffer holding the data.
[in]	len,:	The number of bytes to be written.
[out]	bytesWritten,:	The number of bytes actually written.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 630 of file pal_plat_TLS.c.

palStatus_t pal_plat_tlsConfigurationFree ( palTLSConfHandle_t * palTLSConf )

Destroy and release resources for the TLS configuration context.

Parameters:

[in,out] palTLSConf,: The TLS configuration context to free.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 406 of file pal_plat_TLS.c.

palStatus_t pal_plat_tlsSetSocket	(	palTLSConfHandle_t	palTLSConf,
		palTLSSocket_t *	socket
	)

Set the socket for the TLS configuration context.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	socket,:	The socket for the TLS context.

Returns:: PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 928 of file pal_plat_TLS.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	19 Nov 2019
Imports:	1
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	2
Followers:	1

Important changes to repositories hosted on mbed.com

pal_plat_TLS.h File Reference

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

pal_plat_TLS.h File Reference

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning