Documentation

Mistake on this page? Email us
Typedefs | Enumerations | Functions
pal_plat_TLS.h File Reference

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

#include "pal_TLS.h"

Go to the source code of this file.

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

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

Server mode.

typedef void* palTLSSocketHandle_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

Enumerator
PAL_TLS_IS_CLIENT 

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.

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]entropyCallbackThe 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]palTLSHandleThe 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]palTLSHandleThe TLS context.
[out]serverTimeThe 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]palTLSConfThe TLS configuration context.
[out]palTLSHandleThe 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]confCtxThe TLS configuration context.
[in]transportVersionThe palTLSTransportMode_t type deciding the transportation version, for example tlsv1.2.
[in]methodTypeThe 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]sslConfThe TLS configuration context.
[in]authModeThe 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]palTLSConfThe TLS configuration context.
[in]caChainThe trusted CA chain.
[in]caCRLThe 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]sslConfThe TLS configuration context.
[in]palSuiteThe supported cipher suites to be added.
Returns
PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
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]palTLSConfThe DTLS configuration context.
[in]timeoutInMilliSecThe 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]palTLSConfThe TLS configuration context.
[in]palLogFunctionA pointer to the logging function.
[in]logContextThe 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]palTLSConfThe TLS configuration context.
[in]ownCertYour 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]palTLSConfThe TLS configuration context.
[in]privateKeyYour 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]sslConfThe TLS configuration context.
[in]identityA pointer to the PSK identity.
[in]maxIdentityLenInBytesThe maximum length of the identity key in bytes.
[in]pskA pointer to the PSK.
[in]maxPskLenInBytesThe 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]palTLSHandleThe TLS context.
[in]timerCtxThe shared context by BIO callbacks.
[in]setTimerThe set timer callback.
[in]getTimerThe 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]palTLSHandleThe TLS context.
[out]verifyResultbitmask 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]palTLSHandleThe TLS context.
[out]bufferA buffer holding the data.
[in]lenThe maximum number of bytes to read.
[out]actualLenThe 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]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_plat_sslSetIOCallBacks ( palTLSConfHandle_t  palTLSConf,
palTLSSocket_t palIOCtx,
palBIOSend_f  palBIOSend,
palBIORecv_f  palBIORecv 
)

Set the IO callbacks for the TLS context.

Parameters
[in]palTLSConfThe TLS configuration context.
[in]palIOCtxThe shared context by BIO callbacks.
[in]palBIOSendA pointer to send BIO function.
[in]palBIORecvA 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]palTLSHandleThe TLS context.
[in]palTLSConfThe 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]palTLSHandleThe TLS context.
[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. 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]palTLSConfThe 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]palTLSConfThe TLS configuration context.
[in]socketThe socket for the TLS context.
Returns
PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.