Toyomasa Watarai / simple-mbed-cloud-client

Simple interface for Mbed Cloud Client

Dependents:  

Embed: (wiki syntax)

« Back to documentation index

pal_TLS.h File Reference
Typedefs | Functions

pal_TLS.h File Reference

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

Go to the source code of this file.

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_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_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 240 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 384 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 264 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 504 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 247 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 330 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
Returns:
PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.

Definition at line 540 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 488 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 467 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 516 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 529 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 222 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 348 of file pal_TLS.c.

Generated on Tue Jul 12 2022 19:01:38 by  doxygen 1.7.2