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

Data Structures
struct	palTLSSocket

struct	palTLSBuffer

Typedefs
typedef uintptr_t	palTLSHandle_t

typedef uintptr_t	palTLSConfHandle_t

typedef enum palTLSTranportMode	palTLSTransportMode_t

typedef struct palTLSSocket	palTLSSocket_t

typedef struct palTLSBuffer	palTLSBuffer_t

typedef palTLSBuffer_t	palX509_t

typedef palTLSBuffer_t	palX509CRL_t

typedef palTLSBuffer_t	palPrivateKey_t

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. More...

typedef void(*	palSocketCallback_f) (void *)

Enumerations
enum	palTLSTranportMode { PAL_DTLS_MODE }

Functions
palStatus_t	pal_initTLSLibrary (void)
	Initiate the TLS library. More...

palStatus_t	pal_cleanupTLS (void)
	Free resources for the TLS library. More...

palStatus_t	pal_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t *palTLSHandle)
	Initiate a new TLS context. More...

palStatus_t	pal_freeTLS (palTLSHandle_t *palTLSHandle)
	Destroy and free the resources of the TLS context. More...

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. More...

palStatus_t	pal_initTLSConfiguration (palTLSConfHandle_t *palTLSConf, palTLSTransportMode_t transportationMode)
	Initiate a new configuration context. More...

palStatus_t	pal_tlsConfigurationFree (palTLSConfHandle_t *palTLSConf)
	Destroy and free the resources of the TLS configurtion context. More...

palStatus_t	pal_setOwnCertChain (palTLSConfHandle_t palTLSConf, palX509_t *ownCert)
	Set your own certificate chain. More...

palStatus_t	pal_initPrivateKey (const void buf, size_t buf_size, palPrivateKey_t privateKey)

palStatus_t	pal_setOwnPrivateKey (palTLSConfHandle_t palTLSConf, palPrivateKey_t *privateKey)
	Set your own private key. More...

palStatus_t	pal_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t caChain, palX509CRL_t caCRL)
	Set the data required to verify the peer certificate. More...

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. More...

palStatus_t	pal_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
	Set the socket used by the TLS configuration context. More...

palStatus_t	pal_handShake (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
	Perform the TLS handshake. This function is blocking. More...

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. More...

palStatus_t	pal_sslGetVerifyResult (palTLSHandle_t palTLSHandle)
	Return the result of the certificate verification. More...

palStatus_t	pal_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t *verifyResult)
	Return the result of the certificate verification. More...

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). More...

palStatus_t	pal_sslWrite (palTLSHandle_t palTLSHandle, const void buffer, uint32_t len, uint32_t bytesWritten)
	Write the exact length of application data bytes. More...

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. More...

palStatus_t	pal_sslDebugging (uint8_t turnOn)

void	pal_setDTLSSocketCallback (palTLSConfHandle_t palTLSConf, palSocketCallback_f callback, void *argument)
	Set the socket callback function pointer for the DTLS handshake retransmission. DTLS only, no effect on TLS. More...

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.

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.

typedef palTLSBuffer_t palPrivateKey_t

typedef void(* palSocketCallback_f) (void *)

typedef struct palTLSBuffer palTLSBuffer_t

typedef uintptr_t palTLSConfHandle_t

typedef uintptr_t palTLSHandle_t

typedef struct palTLSSocket palTLSSocket_t

typedef enum palTLSTranportMode palTLSTransportMode_t

typedef palTLSBuffer_t palX509_t

typedef palTLSBuffer_t palX509CRL_t

Enumeration Type Documentation

enum palTLSTranportMode

Enumerator
PAL_DTLS_MODE

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.

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.

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.

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.

palStatus_t pal_initPrivateKey	(	const void *	buf,
		size_t	buf_size,
		palPrivateKey_t *	privateKey
	)

Initialize a private key object

Parameters

[in]	buf	If MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT is defined - pointer to a `uintptr_t` type, which contains the PSA handle. If MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT is not defined - pointer to a private key.
[in]	buf_size	If MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT is defined - not relevant, as it is expected that buf points to a `uintptr_t` type. If MBED_CONF_MBED_CLOUD_CLIENT_PSA_SUPPORT is not defined - the size of the private key pointed to by buf.
[out]	privateKey	Pointer to an uninitialized `palPrivateKey_t` object.

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

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.

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.

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.

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.

void pal_setDTLSSocketCallback	(	palTLSConfHandle_t	palTLSConf,
		palSocketCallback_f	callback,
		void *	argument
	)

Set the socket callback function pointer for the DTLS handshake retransmission. DTLS only, no effect on TLS.

Parameters

[in]	palTLSConf	The DTLS configuration context.
[in]	socket_callback	Callback function to be called by the user of PAL TLS API.
[in]	argument	Argument which will be passed along with the callback function.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Documentation

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation