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_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_sslDebugging (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 58 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 255 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 216 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 457 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 716 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 411 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 283 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 178 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 743 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 496 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 828 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 523 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 663 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 932 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 790 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 852 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_sslDebugging ( uint8_t turnOn )

Turn on or off debugging from the TLS library. If the debugging is on, the logs will be sent via the PAL Logger (mbedTrace?!). In release mode, an error will be returned.

Parameters:

[in] turnOn,: Sets the status of the debugging prints.

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

Definition at line 908 of file pal_plat_TLS.c.

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 559 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 607 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 882 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 687 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 635 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 374 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 874 of file pal_plat_TLS.c.

Type:	Library
Created:	02 Jul 2018
Imports:	1
Forks:	0
Commits:	3
Dependents:	1
Dependencies:	0
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