PAL TLS/DTLS. This file contains TLS/DTLS APIs and is a part of the PAL service API. It provides TLS/DTLS handshake functionalities, read/write from peer in a secure way. 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 used as TLS platform library.
Functions
palStatus_t	pal_initTLSLibrary (void)
palStatus_t	pal_cleanupTLS (void)
palStatus_t	pal_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t *palTLSHandle)
palStatus_t	pal_freeTLS (palTLSHandle_t *palTLSHandle)
palStatus_t	pal_addEntropySource (palEntropySource_f entropyCallback)
palStatus_t	pal_initTLSConfiguration (palTLSConfHandle_t *palTLSConf, palTLSTransportMode_t transportationMode)
palStatus_t	pal_tlsConfigurationFree (palTLSConfHandle_t *palTLSConf)
palStatus_t	pal_setOwnCertAndPrivateKey (palTLSConfHandle_t palTLSConf, palX509_t ownCert, palPrivateKey_t privateKey)
palStatus_t	pal_setOwnCertChain (palTLSConfHandle_t palTLSConf, palX509_t *ownCert)
palStatus_t	pal_setOwnPrivateKey (palTLSConfHandle_t palTLSConf, palPrivateKey_t *privateKey)
palStatus_t	pal_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t caChain, palX509CRL_t caCRL)
palStatus_t	pal_setPSK (palTLSConfHandle_t palTLSConf, const unsigned char identity, uint32_t maxIdentityLenInBytes, const unsigned char psk, uint32_t maxPskLenInBytes)
palStatus_t	pal_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
palStatus_t	pal_handShake (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
palStatus_t	pal_setHandShakeTimeOut (palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec)
palStatus_t	pal_sslGetVerifyResult (palTLSHandle_t palTLSHandle)
palStatus_t	pal_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t *verifyResult)
palStatus_t	pal_sslRead (palTLSHandle_t palTLSHandle, void buffer, uint32_t len, uint32_t actualLen)
palStatus_t	pal_sslWrite (palTLSHandle_t palTLSHandle, const void buffer, uint32_t len, uint32_t bytesWritten)
palStatus_t	pal_sslSetDebugging (palTLSConfHandle_t palTLSConf, uint8_t turnOn)
palStatus_t	pal_sslDebugging (uint8_t turnOn)

Detailed Description

PAL TLS/DTLS. This file contains TLS/DTLS APIs and is a part of the PAL service API. It provides TLS/DTLS handshake functionalities, read/write from peer 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 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 65 of file pal_TLS.h.

Function Documentation

palStatus_t pal_addEntropySource ( palEntropySource_f entropyCallback )

Add entropy source to the TLS/DTLS library. (This API may NOT be available in all TLS/DTLS platforms, see note.)

Parameters:

[in] entropyCallback,: The entropy callback to be used in 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.; This function MUST be called (if needed) before calling the `pal_initTLSConfiguration()` function.

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

Definition at line 237 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. A negative value indicating a specific error code in case of failure.

Definition at line 54 of file pal_TLS.c.

palStatus_t pal_freeTLS ( palTLSHandle_t * palTLSHandle )

Destroy and free resources for the TLS context.

Parameters:

[in] 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 122 of file pal_TLS.c.

palStatus_t pal_handShake	(	palTLSHandle_t	palTLSHandle,
		palTLSConfHandle_t	palTLSConf
	)

Perform the TLS handshake (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. 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 412 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. A negative value indicating a specific error code in case of failure.

Definition at line 67 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. A negative value indicating a specific error code in case of failure.

Definition at line 160 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. A negative value indicating a specific error code in case of failure.

Definition at line 39 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. A negative value indicating a specific error code in case of failure.

Definition at line 292 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 TLS configuration context.
[in]	timeoutInMilliSec,:	The timeout value in seconds.

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

Definition at line 532 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. A negative value indicating a specific error code in case of failure.

Definition at line 244 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. A negative value indicating a specific error code in case of failure.

Definition at line 260 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. A negative value indicating a specific error code in case of failure.

Definition at line 276 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. A negative value indicating a specific error code in case of failure.

Definition at line 358 of file pal_TLS.c.

palStatus_t pal_sslDebugging ( uint8_t turnOn )

Turn on/off debugging from the 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 568 of file pal_TLS.c.

palStatus_t pal_sslGetVerifyResult ( palTLSHandle_t palTLSHandle )

Return the result of the certificate verification.

Parameters:

[in] ssl,: The SSL context.

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

Definition at line 516 of file pal_TLS.c.

palStatus_t pal_sslGetVerifyResultExtended	(	palTLSHandle_t	palTLSHandle,
		int32_t *	verifyResult
	)

Return the result of the certificate verification.

Parameters:

[in]	ssl,:	The SSL 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. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`.

in order to turn off the MSB bit.

Definition at line 495 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. A negative value indicating a specific error code in case of failure.

Definition at line 544 of file pal_TLS.c.

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

Definition at line 557 of file pal_TLS.c.

palStatus_t pal_tlsConfigurationFree ( palTLSConfHandle_t * palTLSConf )

Destroy and free resources for the TLS configurtion context.

Parameters:

[in] 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 219 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. A negative value indicating a specific error code in case of failure.

Definition at line 376 of file pal_TLS.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	12 Oct 2018
Imports:	68
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	0
Followers:	2

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