PAL TLS/DTLS. This file contains TLS and DTLS APIs and is a part of the PAL service API. More...

Typedefs
typedef int(*	palEntropySource_f )(void data, unsigned char output, size_t len, size_t *olen)
	This callback is useful ONLY when mbed TLS is used as TLS platform library.
Functions
palStatus_t	pal_initTLSLibrary (void)
	Initiate the TLS library.
palStatus_t	pal_cleanupTLS (void)
	Free resources for the TLS library.
palStatus_t	pal_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t *palTLSHandle)
	Initiate a new TLS context.
palStatus_t	pal_freeTLS (palTLSHandle_t *palTLSHandle)
	Destroy and free the resources of the TLS context.
palStatus_t	pal_addEntropySource (palEntropySource_f entropyCallback)
	Add an entropy source to the TLS/DTLS library. NOT available in all TLS/DTLS platforms, see note.
palStatus_t	pal_initTLSConfiguration (palTLSConfHandle_t *palTLSConf, palTLSTransportMode_t transportationMode)
	Initiate a new configuration context.
palStatus_t	pal_tlsConfigurationFree (palTLSConfHandle_t *palTLSConf)
	Destroy and free the resources of the TLS configurtion context.
palStatus_t	pal_setOwnCertAndPrivateKey (palTLSConfHandle_t palTLSConf, palX509_t ownCert, palPrivateKey_t privateKey)
	Set your own certificate chain and private key.
palStatus_t	pal_setOwnCertChain (palTLSConfHandle_t palTLSConf, palX509_t *ownCert)
	Set your own certificate chain.
palStatus_t	pal_setOwnPrivateKey (palTLSConfHandle_t palTLSConf, palPrivateKey_t *privateKey)
	Set your own private key.
palStatus_t	pal_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t caChain, palX509CRL_t caCRL)
	Set the data required to verify the peer certificate.
palStatus_t	pal_setPSK (palTLSConfHandle_t palTLSConf, 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_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
	Set the socket used by the TLS configuration context.
palStatus_t	pal_handShake (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
	Perform the TLS handshake. This function is blocking.
palStatus_t	pal_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_sslGetVerifyResult (palTLSHandle_t palTLSHandle)
	Return the result of the certificate verification.
palStatus_t	pal_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t *verifyResult)
	Return the result of the certificate verification.
palStatus_t	pal_sslRead (palTLSHandle_t palTLSHandle, void buffer, uint32_t len, uint32_t actualLen)
	Read the application data bytes (the max number of bytes).
palStatus_t	pal_sslWrite (palTLSHandle_t palTLSHandle, const void buffer, uint32_t len, uint32_t bytesWritten)
	Write the exact length of application data bytes.
palStatus_t	pal_sslSetDebugging (palTLSConfHandle_t palTLSConf, uint8_t turnOn)
	Turn the debugging on or off for the given TLS library configuration handle. The logs are sent via the `mbedTrace`. In case of release mode, an error will be returned.
palStatus_t	pal_sslDebugging (uint8_t turnOn)

Detailed Description

PAL TLS/DTLS. This file contains TLS and DTLS APIs and is a part of the PAL service API.

It provides Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) handshake functionalities, allowing read and write from peers in a secure way.

Definition in file pal_TLS.h.

Typedef Documentation

typedef int(* palEntropySource_f)(void *data, unsigned char *output, size_t len, size_t *olen)

This callback is useful ONLY when mbed TLS is used as TLS platform library.

In other platforms, you should NOT use this callback in the code. The related function is not supported in other platforms than mbedTLS.

Definition at line 70 of file pal_TLS.h.

Function Documentation

palStatus_t pal_addEntropySource ( palEntropySource_f entropyCallback )

Add an entropy source to the TLS/DTLS library. NOT available in all TLS/DTLS platforms, see note.

Parameters:

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

Note:: This function is available ONLY when the TLS or DTLS platform supports this functionality. In other platforms, PAL_ERR_NOT_SUPPORTED should be returned.; This function MUST be called (if needed) before calling the `pal_initTLSConfiguration()` function.

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

Definition at line 242 of file pal_TLS.c.

palStatus_t pal_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, or a negative value indicating a specific error code in case of failure.

Definition at line 60 of file pal_TLS.c.

palStatus_t pal_freeTLS ( palTLSHandle_t * palTLSHandle )

Destroy and free the resources of the TLS context.

Parameters:

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

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

Definition at line 128 of file pal_TLS.c.

palStatus_t pal_handShake	(	palTLSHandle_t	palTLSHandle,
		palTLSConfHandle_t	palTLSConf
	)

Perform the TLS handshake. This function is blocking.

This function sets the TLS configuration context into the TLS context and performs the handshake with the peer.

Parameters:

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

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

if we are not proccessing handshake with the time trusted server we

will use PAL_TLS_VERIFY_REQUIRED authentication mode

We ignore the pal_updateTime() result, because it should not cause a failure to the handshake process. Logs are printed in the pal_updateTime() function in case of failure.

Definition at line 417 of file pal_TLS.c.

palStatus_t pal_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, or a negative value indicating a specific error code in case of failure.

Definition at line 73 of file pal_TLS.c.

palStatus_t pal_initTLSConfiguration	(	palTLSConfHandle_t *	palTLSConf,
		palTLSTransportMode_t	transportationMode
	)

Initiate a new configuration context.

Parameters:

[out]	palTLSConf,:	The context that holds the TLS configuration.
[in]	transportationMode,:	The connection type: TLS or DTLS. See `palTranportVersion_t`.

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

Definition at line 166 of file pal_TLS.c.

palStatus_t pal_initTLSLibrary ( void )

Initiate the TLS library.

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

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

Definition at line 45 of file pal_TLS.c.

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

Set the data required to verify the 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, or a negative value indicating a specific error code in case of failure.

Definition at line 297 of file pal_TLS.c.

palStatus_t pal_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 timeout value in milliseconds.

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

Definition at line 537 of file pal_TLS.c.

palStatus_t pal_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, or a negative value indicating a specific error code in case of failure.

Definition at line 249 of file pal_TLS.c.

palStatus_t pal_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, or a negative value indicating a specific error code in case of failure.

Definition at line 265 of file pal_TLS.c.

palStatus_t pal_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, or a negative value indicating a specific error code in case of failure.

Definition at line 281 of file pal_TLS.c.

palStatus_t pal_setPSK	(	palTLSConfHandle_t	palTLSConf,
		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]	palTLSConf,:	The TLS configuration context.
[in]	identity,:	A pointer to the pre-shared key identity.
[in]	maxIdentityLenInBytes,:	The length of the key identity.
[in]	psk,:	A pointer to the pre-shared key.
[in]	maxPskLenInBytes,:	The length of the pre-shared key.

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

Definition at line 363 of file pal_TLS.c.

palStatus_t pal_sslDebugging ( uint8_t turnOn )

Turn debugging on or off for the whole TLS library. The logs are sent via the `mbedTrace`. In case of release mode, an error will be returned.

Parameters:

[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 573 of file pal_TLS.c.

palStatus_t pal_sslGetVerifyResult ( palTLSHandle_t palTLSHandle )

Return the result of the certificate verification.

Parameters:

[in] palTLSHandle,: The TLS context.

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

Definition at line 521 of file pal_TLS.c.

palStatus_t pal_sslGetVerifyResultExtended	(	palTLSHandle_t	palTLSHandle,
		int32_t *	verifyResult
	)

Return the result of the certificate verification.

Parameters:

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

Returns:: PAL_SUCCESS on success.; PAL_ERR_X509_CERT_VERIFY_FAILED in case of failure.

in order to turn off the MSB bit.

Definition at line 500 of file pal_TLS.c.

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

Read the application data bytes (the max number of bytes).

Parameters:

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

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

Definition at line 549 of file pal_TLS.c.

palStatus_t pal_sslSetDebugging	(	palTLSConfHandle_t	palTLSConf,
		uint8_t	turnOn
	)

Turn the debugging on or off for the given TLS library 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 579 of file pal_TLS.c.

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

Write the exact length of 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, or a negative value indicating a specific error code in case of failure.

Definition at line 562 of file pal_TLS.c.

palStatus_t pal_tlsConfigurationFree ( palTLSConfHandle_t * palTLSConf )

Destroy and free the resources of the TLS configurtion context.

Parameters:

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

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

Definition at line 224 of file pal_TLS.c.

palStatus_t pal_tlsSetSocket	(	palTLSConfHandle_t	palTLSConf,
		palTLSSocket_t *	socket
	)

Set the socket used by the TLS configuration context.

Parameters:

[in]	palTLSConf,:	The TLS configuration context.
[in]	socket,:	The socket to be used by the TLS context.

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

Definition at line 381 of file pal_TLS.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	04 May 2021
Imports:	4
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

pal_TLS.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

pal_TLS.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning