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

Typedefs
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(*	palBIOSend_f )(palTLSSocketHandle_t socket, const unsigned char *buf, size_t len)
	This prototype can be re-defined by the platform side.
Enumerations
enum	palTLSAuthMode { , PAL_TLS_VERIFY_OPTIONAL, PAL_TLS_VERIFY_REQUIRED }
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: More...
Functions
palStatus_t	pal_plat_initTLSLibrary (void)
palStatus_t	pal_plat_cleanupTLS (void)
palStatus_t	pal_plat_initTLSConf (palTLSConfHandle_t *confCtx, palTLSTransportMode_t transportVersion, palDTLSSide_t methodType)
palStatus_t	pal_plat_tlsConfigurationFree (palTLSConfHandle_t *palTLSConf)
palStatus_t	pal_plat_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t *palTLSHandle)
palStatus_t	pal_plat_freeTLS (palTLSHandle_t *palTLSHandle)
palStatus_t	pal_plat_addEntropySource (palEntropySource_f entropyCallback)
palStatus_t	pal_plat_setCipherSuites (palTLSConfHandle_t sslConf, palTLSSuites_t palSuite)
palStatus_t	pal_plat_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t *verifyResult)
palStatus_t	pal_plat_sslRead (palTLSHandle_t palTLSHandle, void buffer, uint32_t len, uint32_t actualLen)
palStatus_t	pal_plat_sslWrite (palTLSHandle_t palTLSHandle, const void buffer, uint32_t len, uint32_t bytesWritten)
palStatus_t	pal_plat_setHandShakeTimeOut (palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec)
palStatus_t	pal_plat_sslSetup (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
palStatus_t	pal_plat_handShake (palTLSHandle_t palTLSHandle, uint64_t *serverTime)
palStatus_t	pal_plat_renegotiate (palTLSHandle_t palTLSHandle, uint64_t sreverTime)
palStatus_t	pal_plat_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
palStatus_t	pal_plat_setOwnCertAndPrivateKey (palTLSConfHandle_t palTLSConf, palX509_t ownCert, palPrivateKey_t privateKey)
palStatus_t	pal_plat_setOwnCertChain (palTLSConfHandle_t palTLSConf, palX509_t *ownCert)
palStatus_t	pal_plat_setOwnPrivateKey (palTLSConfHandle_t palTLSConf, palPrivateKey_t *privateKey)
palStatus_t	pal_plat_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t caChain, palX509CRL_t caCRL)
palStatus_t	pal_plat_setPSK (palTLSConfHandle_t sslConf, const unsigned char identity, uint32_t maxIdentityLenInBytes, const unsigned char psk, uint32_t maxPskLenInBytes)
palStatus_t	pal_plat_setAuthenticationMode (palTLSConfHandle_t sslConf, palTLSAuthMode_t authMode)
palStatus_t	pal_plat_sslSetDebugging (palTLSConfHandle_t palTLSConf, uint8_t turnOn)
palStatus_t	pal_plat_sslSetIOCallBacks (palTLSConfHandle_t palTLSConf, palTLSSocket_t *palIOCtx, palBIOSend_f palBIOSend, palBIORecv_f palBIORecv)
palStatus_t	pal_plat_setTimeCB (palTLSHandle_t *palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer)
palStatus_t	pal_plat_SetLoggingCb (palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext)

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 int(* palBIOSend_f)(palTLSSocketHandle_t socket, const unsigned char *buf, size_t len)

This prototype can be re-defined by the platform side.

Consider moving them to separate header.

Definition at line 60 of file pal_plat_TLS.h.

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

Enumerator:

PAL_TLS_VERIFY_OPTIONAL

Server mode: The peer certificate is not verified. For client mode, this is insecure!

PAL_TLS_VERIFY_REQUIRED

The peer certificate verification can be failed and handshake continues.

The peer certificate verification MUST pass.

Definition at line 36 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 44 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 (this API may NOT be available in all TLS/DTLS platforms, see the note).

Parameters:

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

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

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 256 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 221 of file pal_plat_TLS.c.

palStatus_t pal_plat_freeTLS ( palTLSHandle_t * palTLSHandle )

Destroy and release resources for the TLS context.

Parameters:

inout] ssl: 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 441 of file pal_plat_TLS.c.

palStatus_t pal_plat_handShake	(	palTLSHandle_t	palTLSHandle,
		uint64_t *	serverTime
	)

Perform the TLS handshake.

Parameters:

[in]	ssl,:	The TLS context.
[out]	serverTime,:	The server time recieved 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 690 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 417 of file pal_plat_TLS.c.

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

Initiate new configuration context.

Parameters:

[out]	palTLSConf,:	The TLS configuration context.
[in]	tranportVersion,:	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 284 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 initializtion function.

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

Definition at line 181 of file pal_plat_TLS.c.

palStatus_t pal_plat_renegotiate	(	palTLSHandle_t	palTLSHandle,
		uint64_t	sreverTime
	)

Perform the TLS handshake renegotiation.

Parameters:

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

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 717 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 463 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 850 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]	palTLSConf,:	The TLS configuration context.
[in]	palSuites,:	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 490 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 TLS 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 638 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 946 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 764 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 823 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 800 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 pre-shared key identity.
[in]	maxIdentityLenInBytes,:	The maximum length of the identity key.
[in]	psk,:	A pointer to the pre-shared key.
[in]	maxPskLenInBytes,:	The maximum length of the pre-shared key.

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

Definition at line 872 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]	ssl,:	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`.

Note:: In case 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 534 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]	ssl,:	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 582 of file pal_plat_TLS.c.

palStatus_t pal_plat_sslSetDebugging	(	palTLSConfHandle_t	palTLSConf,
		uint8_t	turnOn
	)

Turn on/off the TLS library debugging 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 930 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 902 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]	ssl: The TLS context.
[in]	palTLSConf,:	The TLS configuration context.

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

Definition at line 662 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]	ssl,:	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 610 of file pal_plat_TLS.c.

palStatus_t pal_plat_tlsConfigurationFree ( palTLSConfHandle_t * palTLSConf )

Destroy and release resources for the TLS configuration context.

Parameters:

inout] 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 380 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 894 of file pal_plat_TLS.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	25 Oct 2018
Imports:	1
Forks:	0
Commits:	5
Dependents:	0
Dependencies:	1
Followers:	1

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

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