Mistake on this page? Email us
pal_TLS.h File Reference

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

Go to the source code of this file.

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, bool is_server_ping)
 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, bool skipResume)
 Perform the TLS handshake. This function is blocking. More...
 
palStatus_t pal_setHandShakeTimeOut (palTLSConfHandle_t palTLSConf, uint32_t minTimeout, uint32_t maxTimeout)
 Set the retransmit timeout values for the DTLS handshake. DTLS only, no effect on TLS. 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, palTLSConfHandle_t palTLSConf, 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_store_cid ()
 Stores CID context persistently for DTLS based setup. More...
 
void pal_remove_cid ()
 Removes CID context for DTLS based setup. More...
 
bool pal_is_cid_available ()
 Status of CID availability in client. More...
 
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...
 
void pal_set_cid_value (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf, const uint8_t *data_ptr, const size_t data_len)
 Internal test function. Set CID for current tls session. 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 void(* palSocketCallback_f) (void *)
typedef struct palTLSBuffer palTLSBuffer_t
typedef uintptr_t palTLSConfHandle_t
typedef uintptr_t palTLSHandle_t
typedef struct palTLSSocket palTLSSocket_t

Enumeration Type Documentation

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]entropyCallbackThe 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]palTLSHandleThe 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,
bool  skipResume 
)

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]palTLSHandleThe TLS context.
[in]palTLSConfThe TLS configuration context.
[in]skipResumeIf true, will skip resume. Resume may be active only in UDP DTLS.
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]bufIf 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_sizeIf 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]privateKeyPointer 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,
bool  is_server_ping 
)

Initiate a new TLS context.

Parameters
[in]palTLSConfThe TLS configuration context.
[out]palTLSHandleThe index to the TLS context.
[in]is_server_pingDefines whether the call is for Server ping or not.
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]palTLSConfThe context that holds the TLS configuration.
[in]transportationModeThe 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.
bool pal_is_cid_available ( )

Status of CID availability in client.

Returns
true if CID is available else false.
void pal_remove_cid ( )

Removes CID context for DTLS based setup.

void pal_set_cid_value ( palTLSHandle_t  palTLSHandle,
palTLSConfHandle_t  palTLSConf,
const uint8_t *  data_ptr,
const size_t  data_len 
)

Internal test function. Set CID for current tls session.

Parameters
[in]palTLSHandleThe TLS context.
[in]palTLSConfThe DTLS configuration context.
[in]data_ptrCID
[in]data_lenlength of the CID
palStatus_t pal_setCAChain ( palTLSConfHandle_t  palTLSConf,
palX509_t caChain,
palX509CRL_t caCRL 
)

Set the data required to verify the peer certificate.

Parameters
[in]palTLSConfThe TLS configuration context.
[in]caChainThe trusted CA chain.
[in]caCRLThe 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]palTLSConfThe DTLS configuration context.
[in]socket_callbackCallback function to be called by the user of PAL TLS API.
[in]argumentArgument 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  minTimeout,
uint32_t  maxTimeout 
)

Set the retransmit timeout values for the DTLS handshake. DTLS only, no effect on TLS.

Parameters
[in]palTLSConfThe DTLS configuration context.
[in]minTimeoutThe timeout minimum value in milliseconds.
[in]maxTimeoutThe timeout maxmimum 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]palTLSConfThe TLS configuration context.
[in]ownCertYour 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]palTLSConfThe TLS configuration context.
[in]privateKeyYour 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]palTLSConfThe TLS configuration context.
[in]identityA pointer to the pre-shared key identity.
[in]maxIdentityLenInBytesThe length of the key identity.
[in]pskA pointer to the pre-shared key.
[in]maxPskLenInBytesThe 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]turnOnIf 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_sslGetVerifyResultExtended ( palTLSHandle_t  palTLSHandle,
int32_t *  verifyResult 
)

Return the result of the certificate verification.

Parameters
[in]palTLSHandleThe TLS context.
[out]verifyResultBitmask 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]palTLSHandleThe TLS context.
[out]bufferA buffer that holds the data.
[in]lenThe maximum number of bytes to read.
[out]actualLenThe 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]turnOnIf 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,
palTLSConfHandle_t  palTLSConf,
const void *  buffer,
uint32_t  len,
uint32_t *  bytesWritten 
)

Write the exact length of application data bytes.

Parameters
[in]palTLSHandleThe TLS context.
[in]palTLSConfThe TLS configuration
[in]bufferA buffer holding the data.
[in]lenThe number of bytes to be written.
[out]bytesWrittenThe number of bytes actually written.
Returns
PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
void pal_store_cid ( )

Stores CID context persistently for DTLS based setup.

palStatus_t pal_tlsConfigurationFree ( palTLSConfHandle_t palTLSConf)

Destroy and free the resources of the TLS configurtion context.

Parameters
[in]palTLSConfThe 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]palTLSConfThe TLS configuration context.
[in]socketThe 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.