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

#include "pal_TLS.h"

Typedefs
typedef enum palDTLSSide	palDTLSSide_t

typedef enum palTLSAuthMode	palTLSAuthMode_t
	Server mode. More...

typedef enum palTLSSuites	palTLSSuites_t
	This is the list of the available cipher suites. More...

typedef void *	palTLSSocketHandle_t

typedef void *	palTimerCtx_t

typedef int(*	palBIOSend_f) (palTLSSocketHandle_t socket, const unsigned char *buf, size_t len)

typedef int(*	palBIORecv_f) (palTLSSocketHandle_t socket, unsigned char *buf, size_t len)

typedef int(*	palVerifyCallback_f) (void , void , int, uint32_t *)

typedef void(*	palSetTimer_f) (void *data, uint32_t intMs, uint32_t finMs)

typedef int(*	palGetTimer_f) (void *data)

typedef void(*	palLogFunc_f) (void context, int debugLevel, const char fileName, int line, const char *message)

Enumerations
enum	palDTLSSide { PAL_TLS_IS_CLIENT }

enum	palTLSAuthMode { PAL_TLS_VERIFY_NONE, PAL_TLS_VERIFY_OPTIONAL, PAL_TLS_VERIFY_REQUIRED }
	Server mode. More...

enum	palTLSSuites { PAL_TLS_PSK_WITH_AES_128_CCM_8, PAL_TLS_PSK_WITH_AES_256_CCM_8, PAL_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8, PAL_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, PAL_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, PAL_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256 }
	This is the list of the available cipher suites. More...

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

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

palStatus_t	pal_plat_initTLSConf (palTLSConfHandle_t *confCtx, palTLSTransportMode_t transportVersion, palDTLSSide_t methodType)
	Initiate a new configuration context. More...

palStatus_t	pal_plat_tlsConfigurationFree (palTLSConfHandle_t *palTLSConf)
	Destroy and release resources for the TLS configuration context. More...

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

palStatus_t	pal_plat_freeTLS (palTLSHandle_t *palTLSHandle)
	Destroy and release resources for the TLS context. More...

palStatus_t	pal_plat_addEntropySource (palEntropySource_f entropyCallback)
	Add an entropy source to the TLS/DTLS library. More...

palStatus_t	pal_plat_setCipherSuites (palTLSConfHandle_t sslConf, palTLSSuites_t palSuite)
	Set the supported cipher suites to the configuration context. More...

palStatus_t	pal_plat_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t *verifyResult)
	Return the result of the certificate verification. The handshake API calls this. More...

palStatus_t	pal_plat_sslRead (palTLSHandle_t palTLSHandle, void buffer, uint32_t len, uint32_t actualLen)
	Read at most 'len' application data bytes. More...

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

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

palStatus_t	pal_plat_sslSetup (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
	Set up a TLS context for use. More...

palStatus_t	pal_plat_handShake (palTLSHandle_t palTLSHandle, uint64_t *serverTime)
	Perform the TLS handshake. More...

palStatus_t	pal_plat_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
	Set the socket for the TLS configuration context. More...

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

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

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

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

palStatus_t	pal_plat_setAuthenticationMode (palTLSConfHandle_t sslConf, palTLSAuthMode_t authMode)
	Set the certificate verification mode. More...

palStatus_t	pal_plat_sslSetDebugging (palTLSConfHandle_t palTLSConf, uint8_t turnOn)
	Turn the TLS library debugging on or off for the given configuration handle. More...

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

palStatus_t	pal_plat_setTimeCB (palTLSHandle_t *palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer)
	Set the timer callbacks. More...

palStatus_t	pal_plat_SetLoggingCb (palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext)
	Set the logging function. More...

void	pal_plat_SetDTLSSocketCallback (palTLSConfHandle_t palTLSConf, palSocketCallback_f cb, void *argument)
	Set the socket callback. More...

Detailed Description

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

Typedef Documentation

typedef int(* palBIORecv_f) (palTLSSocketHandle_t socket, unsigned char *buf, size_t len)

typedef int(* palBIOSend_f) (palTLSSocketHandle_t socket, const unsigned char *buf, size_t len)

typedef enum palDTLSSide palDTLSSide_t

typedef int(* palGetTimer_f) (void *data)

typedef void(* palLogFunc_f) (void *context, int debugLevel, const char *fileName, int line, const char *message)

typedef void(* palSetTimer_f) (void *data, uint32_t intMs, uint32_t finMs)

typedef void* palTimerCtx_t

typedef enum palTLSAuthMode palTLSAuthMode_t

Server mode.

typedef void* palTLSSocketHandle_t

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.

typedef int(* palVerifyCallback_f) (void *, void *, int, uint32_t *)

Enumeration Type Documentation

enum palDTLSSide

Enumerator
PAL_TLS_IS_CLIENT

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.

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.

Enumerator
PAL_TLS_PSK_WITH_AES_128_CCM_8
PAL_TLS_PSK_WITH_AES_256_CCM_8
PAL_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
PAL_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
PAL_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
PAL_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

void pal_plat_SetDTLSSocketCallback	(	palTLSConfHandle_t	palTLSConf,
		palSocketCallback_f	cb,
		void *	argument
	)

Set the socket callback.

Parameters

[in]	palTLSHandle	The TLS context.
[in]	callback	The socket handler callback.
[in]	argument	Argument which will be passed along with the callback function.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Documentation

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation