Documentation

Mistake on this page? Email us
Docs › Porting devices › Porting the modules › TLS/DTLS

TLS/DTLS

Module scope

The TLS module is responsible for:

  • Providing the handshake protocol for TCP and UDP socket types (TLS and DTLS handshake).
  • Reading and writing using a secured connection.

The pal_plat_TLS.h header declares the TLS/DTLS APIs.

Prerequisites for this porting stage

For a successful port, a platform needs to:

  • Successfully port the PAL modules:
    • RTOS.
    • Networking.
    • Crypto.
    • Internal flash.
  • Certificate functionalities:
    • Parse and add CA certificate to be used during handshake.
    • Set its own public certificate chain and private key.
    • Use a pre-shared key for handshake verification.
    • The TLS library must process time certificate verification (some of the TLS libraries require the user to provide time callback).
  • Ciphersuites:
    • The TLS library must allow configuration to support only a specific cipher suite (or group of suites).
    • The TLS library must support one of the following cipher suites (cipher names can be slightly different in different TLS libraries):
      • ECDHE_ECDSA_WITH_AES_128_CCM_8
      • ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      • ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      • PSK_WITH_AES_128_CCM_8
      • PSK_WITH_AES_256_CCM_8
      • PSK_WITH_AES_128_CBC_SHA256
  • TLS/DTLS handshakes must be able to:
    • Set a timeout for a UDP handshake.
    • Extract server time during handshake from serverHello message.
    • Support SSL handshake renegotiation.
  • Provide send and receive functions using the PAL networking APIs.
  • Read and write encrypted data.
  • The TLS library must connect to a strong entropy source.
  • Provide time callback function to the TLS/Crypto library - Thread safe.

Porting result

After successfully porting the TLS module, all PAL TLS tests need to pass. Please see the Tests section for more information.

Porting notes

This section covers non-trivial functionality that the platform needs for a successful port.

Your Mbed Client port must include either the Mbed TLS library or another functionally equivalent library. If you use Mbed TLS, PAL handles most of the porting work for you.

Secure Time

To keep the device time updated, during each handshake the device will update its time according to the server time (if the server is certified). Therefore, the SSL handshake needs to extract the server time sent in the serverHello message and pass it to the service layer. In some cases, SSL renegotiation is required. SSL renegotiation expects the server time as a parameter (the parameter you get from previous handshake), which must be used as the TLS time during the handshake renegotiation.

Important implementation details related to this feature:

  • palStatus_t pal_plat_handShake(palTLSHandle_t palTLSHandle, uint64_t* serverTime)

    • This API has an output parameter serverTime, which is the server time sent in the serverHello message in the handshake process.

  • palStatus_t pal_plat_renegotiate(palTLSHandle_t palTLSHandle, uint64_t serverTime) processes the SSL renegotiation during which it must set the serverTime as the TLS time to be used for certificate verification.

    • Before the function returns, it must set back the TLS source time to the current device time.

  • Time callback for TLS/Crypto library.

    • This is a thread-safe time function, which returns the device time pal_osGetTime().
    • During the renegotiation, the callback must use the server time.
    • Other threads must not be affected by this temporary time change.
      • See the reference implementation of PAL_PRIVATE mbedtls_time_t pal_mbedtlsTimeCB(mbedtls_time_t* timer).

  • palStatus_t pal_plat_sslGetVerifyResult(palTLSHandle_t palTLSHandle) returns an informative error code. The list of expected errors (the order is important):

      `PAL_ERR_X509_BADCERT_NOT_TRUSTED` \
  `PAL_ERR_X509_BADCERT_BAD_KEY`\
  `PAL_ERR_X509_BADCERT_BAD_PK`\
  `PAL_ERR_X509_BADCERT_BAD_MD`\
  `PAL_ERR_X509_BADCERT_EXPIRED`\
  `PAL_ERR_X509_BADCERT_FUTURE`\
  `PAL_ERR_X509_CERT_VERIFY_FAILED`

Using Mbed TLS

If you use Mbed TLS (you either already have it, or are porting it to your platform as part of your Izuma Device Management Client port), you can use the PAL API for this library. It implements both the cryptography and TLS platform APIs using Mbed TLS.

Note: We recommend using Mbed TLS when porting PAL because porting the PAL platforms Cryptography and TLS modules over a different library may be a nontrivial task.

General notes

  • PAL_MAX_NUM_OF_TLS_CTX limits the numbers of TLS/DTLS contexts initiated simultaneously, as defined in pal_configuration.h.
  • The default TLS/DTLS mode is client. You can activate server mode by enabling PAL_TLS_SUPPORT_SERVER_MODE in pal_configuration.h.
  • For send and receive functions, PAL provides palTLSSocket_t in pal_TLS.h. The pal_tlsSetSocket() API also uses it. You must implement the send and receive functions above the PAL networking APIs.
  • The logging function must meet the declared signature palLogFunc_f() in pal_plat_TLS.h.
  • pal_plat_sslSetup() is called for each pal_handShake() call. You can't use pal_plat_sslSetup() more than once for a single SSL context.

Reference implementations

PAL provides a reference implementation for the Mbed TLS library: pal_plat_TLS.c located in the folder Source/Port/Reference-Impl/Lib_Specific/mbedTLS/TLS.

Previous Next