tls.h

Go to the documentation of this file.

#ifndef EVE_TLS_H_INCLUDED
#define EVE_TLS_H_INCLUDED
/**********************************************************************/
/*
 * Copyright (c) 2016, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * \brief Header file for TLS interface.
 *
 * \author SE, Jetro AS
 */ /******************************************************************/

#include <net/uiplib.h>

#include <mbedtls/config.h>
#include <mbedtls/net.h>
#include <mbedtls/ssl.h>
#include <mbedtls/entropy.h>
#include <mbedtls/x509_crt.h>
#include <mbedtls/ctr_drbg.h>
#include <mbedtls/debug.h>

#include <core/datapump.h>

/**
 * \defgroup tls mbedtls library interface
 * \ingroup net
 * \{
 *
 */

#ifndef TLS_RSA
  #define TLS_RSA 1  //!< Set to 0 to slightly reduce ram and flash footprint if RSA is not needed (i.e. PSK-only)
#endif

#define DEBUG_ERR 1
#define DEBUG_WARN 2
#define DEBUG_MSG 3
#define DEBUG_ALL 5
#define TLS_DEBUG_LEVEL DEBUG_MSG

#if TLS_DEBUG_LEVEL == 0
  #define TLS_PRINTD(level, FORMAT, args...) do {} while (0)
#else
  #define TLS_PRINTD(level, FORMAT, args...) \
      do { if ((level) <= TLS_DEBUG_LEVEL) printf("[TLS] " FORMAT, ##args); } while(0)
#endif

#define TLS_CHECK_RET(ret, string) \
    do { if (ret) { TLS_PRINTD(1, string " FAILED with error %s0x%04X\n", \
    ((ret)<0) ? "-" : "", ((ret) < 0) ? -(ret) : (ret)); goto exit; } } while(0)

struct md_heap_t;

extern const struct md_heap_t TlsRxBufferHeap; //!< User-defined TLS Rx heap
extern const struct md_heap_t TlsTxBufferHeap; //!< User-defined TLS Tx heap
extern const struct md_heap_t TlsHeap;         //!< User-defined TLS processing

/** TLS instance (client or server) configuration. */
typedef struct tls_cfg_t
{
  int Role;                             /*!< MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER */
  mbedtls_entropy_context Entropy;      /*!< Internal: entropy context */
  mbedtls_ctr_drbg_context Drbg;        /*!< Indernal: DRBG context */
  mbedtls_ssl_config Conf;              /*!< Internal: SSL configuration  */
#if TLS_RSA == 1
  mbedtls_x509_crt X509;                /*!< Internal: X509 certificate */
  mbedtls_pk_context Pk;                /*!< Internal: Private key */
#endif /* TLS_RSA */
} tls_cfg_t;

/** Wrapper type for sockets. */
typedef struct
{
    int Fd;                             /*!< The underlying file descriptor */
} tls_net_ctx_t;

/** TLS connection instance. */
typedef struct tls_conn_t
{
  mbedtls_ssl_context Ssl;              /*!< SSL context */
  tls_net_ctx_t Net;                    /*!< Network context */
} tls_conn_t;

/** TLS datapump */
typedef struct tls_pump_t
{
  tls_conn_t Conn;                      /*!< TLS connection */
  struct datapump_t Pump;               /*!< Datapump */
} tls_pump_t;

/**
 * Initializes TLS subsystem
 */
void TlsPlatformInit(void);

/**
 * Initializes a TLS instance configuration (RSA variant)
 *
 * @param TlsCfg  Pointer to an uninitialized TLS configuration
 * @param Role    MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
 * @param Cert    Pointer to an RSA sertificate
 * @param CertLen RSA certificate length
 * @param Key     Pointer to an RSA private key
 * @param KeyLen  RSA private key length
 * @return 0 if finished successfully, otherwise an mbedtls error code.
 */
int TlsCfgInitRsa(tls_cfg_t* TlsCfg, int Role,
    const uint8_t* Cert, int CertLen,
    const uint8_t* Key, int KeyLen);

/**
 * Initializes a TLS instance configuration (PSK variant)
 *
 * @param TlsCfg  Pointer to an uninitialized TLS configuration
 * @param Role    MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
 * @param Psk     Pointer to a PSK key
 * @param PskLen  PSK key length
 * @param Identity Pointer to PSK identity
 * @param IdentityLen PSK identity length
 * @return 0 if finished successfully, otherwise an mbedtls error code.
 */
int TlsCfgInitPsk(tls_cfg_t* TlsCfg, int Role,
    const uint8_t* Psk, int PskLen,
    const uint8_t* Identity, int IdentityLen);

/**
 * Free a previously allocated TLS instance configuration
 *
 * @param TlsCfg  Pointer to a previously allocated TLS configuration
 */
void TlsCfgFree(tls_cfg_t* TlsCfg);

/**
 * Initializes a TLS connection
 *
 * @param TlsConn Pointer to an uninitialized TLS connection instance
 * @param TlsCfg  Pointer to a TLS instance configuration
 * @return 0 if finished successfully, otherwise an mbedtls error code.
 */
int TlsConnectionInit(tls_conn_t* TlsConn, tls_cfg_t* TlsCfg);

/**
 * Initializes a TLS connection and starts data pump tasks
 *
 * @param TlsPump Pointer to an uninitialized TLS data pump instance
 * @param TlsCfg  Pointer to a TLS instance configuration
 * @param PumpCfg Constant pointer to a data pump configuration
 * @return 0 if finished successfully, otherwise an mbedtls error code.
 */
int TlsPumpInit(tls_pump_t* TlsPump, tls_cfg_t* TlsCfg, const struct datapump_cfg_t *PumpCfg);

/**
 * Deallocates resources, associated with datapump.
 *
 * @param TlsPump Pointer to a data pump instance
 */
void TlsPumpFree(tls_pump_t* TlsPump);

/**
 * Performes a TLS handshake.
 *
 * The function uses sockets directly and thus must be called from a task.
 *
 * @param TlsConn Pointer to a TLS connection instance
 * @param Timeout Timeout (in system ticks)
 * @return 0 if finished successfully, otherwise an mbedtls error code.
 */
int TlsHandshake(tls_conn_t* TlsConn, uint32_t Timeout);

/**
 * Terminates an ongoing TLS connection.
 *
 * The function uses sockets directly and thus must be called from a task
 *
 * @param TlsConn Pointer to a TLS connection instance
 */
void TlsConnectionClose(tls_conn_t* TlsConn);

/**
 * Deallocates resources, associated with a TlsConn.
 *
 * @param TlsConn Pointer to a TLS connection instance
 */
void TlsConnectionFree(tls_conn_t* TlsConn);

/**
 * Receives data from a TLS connection.
 *
 * The function uses sockets directly and thus must be called from a task.
 * It has same semantic as a BSD socket recv() function and can return less
 * bytes than it was requested.
 *
 * @param TlsConn Pointer to a TLS connection instance
 * @param Buffer  A buffer to put data into
 * @param Length  Length of the buffer (max number of bytes to read)
 * @param Timeout Timeout (in system ticks)
 * @return A positive value shows length of the data read,
 *         0 indicates end-of-stream condition,
 *         and an (mbedtls) negative code indicates an error.
 */
int TlsReceive(tls_conn_t* TlsConn, uint8_t* Buffer, size_t Length, uint32_t Timeout);

/**
 * Sends data to a TLS connection.
 *
 * The function uses sockets directly and thus must be called from a task.
 * It has same semantic as a BSD socket send() function and can send less
 * bytes than it was requested.
 *
 * @param TlsConn Pointer to a TLS connection instance
 * @param Buffer  A buffer containing the data to send
 * @param Length  Length of the buffer (max number of bytes to send)
 * @param Timeout Timeout (in system ticks)
 * @return A positive value shows length of the data sent,
 *         0 indicates end-of-stream condition,
 *         and an (mbedtls) negative code indicates an error.
 */
int TlsSend(tls_conn_t* TlsConn, const uint8_t* Buffer, size_t Length, uint32_t Timeout);

/*extern*/ struct md_heap_t;
extern const struct md_heap_t TlsHeap;
extern const struct md_heap_t TlsRxBufferHeap;
extern const struct md_heap_t TlsTxBufferHeap;

enum tls_swap_direction_t
{
  TLS_SWAP_IN,
  TLS_SWAP_OUT,
};

enum tls_swap_target_t
{
  TLS_SWAP_RX,
  TLS_SWAP_TX,
};

struct tls_swap_params_t
{
  enum tls_swap_direction_t Dir;
  enum tls_swap_target_t Target;
  void *Data;
  uint32_t Pos;
  uint32_t Size;
};

extern bool TlsSwapCallback(const struct tls_swap_params_t *Params);

bool TlsRxBufferHeapSwapOut(const struct md_heap_t *RxHeap, uint32_t Pos, const uint8_t **DataPtr, uint32_t Size);
bool TlsRxBufferHeapSwapIn(const struct md_heap_t *RxHeap, uint8_t **DataPtr, uint32_t Pos, uint32_t Size);
bool TlsTxBufferHeapSwapOut(const struct md_heap_t *TxHeap, uint32_t Pos, const uint8_t **DataPtr, uint32_t Size);
bool TlsTxBufferHeapSwapIn(const struct md_heap_t *TxHeap, uint8_t **DataPtr, uint32_t Pos, uint32_t Size);

/* XXX: heuristic */
#ifndef TLS_HEAP_AUX_NUM_ENTRIES
  #define TLS_HEAP_AUX_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets) \
      (MAX(80, ((NumPskConfigs) * 7 + (NumRsaConfigs) * 30)) + 16 * (NumSockets))
#endif /* TLS_HEAP_AUX_NUM_ENTRIES */

/* XXX: heuristic */
#ifndef TLS_HEAP_AUX_RAM_BUFFER_SIZE
  #define TLS_HEAP_AUX_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets) \
      (512 + 1600 + 1000 * (NumPskConfigs) + 3600 * (NumRsaConfigs) + 2200 * (NumSockets))
#endif /* TLS_HEAP_AUX_RAM_BUFFER_SIZE */

#define TLS_HEAP_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets) \
  ((NumSockets) + 4)

#define TLS_HEAP_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets) \
  ((NumSockets) * (1348 + 4) + 4)

#define TLS_HEAP_TINY_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets) \
  ((NumSockets) * 4 + 1348 + 4)

#define TLS_HEAP_EXT_RAM_SIZE(NumSockets) \
  ((NumSockets) * 1348)

#define TLS_HEAP_AUX_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets)  \
  static struct md_descriptor_t TlsHeapEntries[TLS_HEAP_AUX_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets)]; \
  static uint8_t TlsHeapRamBuffer[TLS_HEAP_AUX_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets)];\
  static struct md_state_t TlsHeapState;                                                                  \
  const struct md_heap_t TlsHeap;                                                                         \
  static void TlsHeapCtor(void) __attribute__((constructor));                                             \
  static void TlsHeapCtor(void)                                                                           \
  {                                                                                                       \
    MemInit(&TlsHeap);                                                                                    \
  }                                                                                                       \
  const struct md_heap_t TlsHeap =                                                                        \
  {                                                                                                       \
    .Entries = TlsHeapEntries,                                                                            \
    .NumEntries = TLS_HEAP_AUX_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets),                     \
    .RamBuffer = TlsHeapRamBuffer,                                                                        \
    .RamBufferSize = TLS_HEAP_AUX_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets),              \
    .State = &TlsHeapState,                                                                               \
    .ExtRamSize = 0,                                                                                      \
    .SwapOut = NULL,                                                                                      \
    .SwapIn = NULL,                                                                                       \
  }

#define TLS_HEAP_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets, Direction) \
  static struct md_descriptor_t Tls ## Direction ## BufferHeapEntries[TLS_HEAP_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets)];  \
  static uint8_t Tls ## Direction ## BufferHeapRamBuffer[TLS_HEAP_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets)];           \
  static struct md_state_t Tls ## Direction ## BufferHeapState;                                           \
  const struct md_heap_t Tls ## Direction ## BufferHeap;                                                  \
  static void Tls ## Direction ## BufferHeapCtor(void) __attribute__((constructor));                      \
  static void Tls ## Direction ## BufferHeapCtor(void)                                                    \
  {                                                                                                       \
    MemInit(&Tls ## Direction ## BufferHeap);                                                             \
  }                                                                                                       \
  const struct md_heap_t Tls ## Direction ## BufferHeap =                                                 \
  {                                                                                                       \
    .Entries = Tls ## Direction ## BufferHeapEntries,                                                     \
    .NumEntries = TLS_HEAP_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets),                         \
    .RamBuffer = Tls ## Direction ## BufferHeapRamBuffer,                                                 \
    .RamBufferSize = TLS_HEAP_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets),                  \
    .State = &Tls ## Direction ## BufferHeapState,                                                        \
    .ExtRamSize = 0,                                                                                      \
    .SwapOut = NULL,                                                                                      \
    .SwapIn = NULL,                                                                                       \
  }
#define TLS_HEAP(NumRsaConfigs, NumPskConfigs, NumSockets)            \
    TLS_HEAP_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets, Rx);      \
    TLS_HEAP_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets, Tx);      \
    TLS_HEAP_AUX_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets)

#define TLS_TINY_HEAP_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets, Direction) \
  static struct md_descriptor_t Tls ## Direction ## BufferHeapEntries[TLS_HEAP_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets)];  \
  static uint8_t Tls ## Direction ## BufferHeapRamBuffer[TLS_HEAP_TINY_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets)];      \
  static struct md_state_t Tls ## Direction ## BufferHeapState;                                           \
  const struct md_heap_t Tls ## Direction ## BufferHeap;                                                  \
  static void Tls ## Direction ## BufferHeapCtor(void) __attribute__((constructor));                      \
  static void Tls ## Direction ## BufferHeapCtor(void)                                                    \
  {                                                                                                       \
    MemInit(&Tls ## Direction ## BufferHeap);                                                             \
  }                                                                                                       \
  const struct md_heap_t Tls ## Direction ## BufferHeap =                                                 \
  {                                                                                                       \
    .Entries = Tls ## Direction ## BufferHeapEntries,                                                     \
    .NumEntries = TLS_HEAP_NUM_ENTRIES(NumRsaConfigs, NumPskConfigs, NumSockets),                         \
    .RamBuffer = Tls ## Direction ## BufferHeapRamBuffer,                                                 \
    .RamBufferSize = TLS_HEAP_TINY_RAM_BUFFER_SIZE(NumRsaConfigs, NumPskConfigs, NumSockets),             \
    .State = &Tls ## Direction ## BufferHeapState,                                                        \
    .ExtRamSize = TLS_HEAP_EXT_RAM_SIZE(NumSockets),                                                      \
    .SwapOut = Tls ## Direction ## BufferHeapSwapOut,                                                     \
    .SwapIn = Tls ## Direction ## BufferHeapSwapIn,                                                       \
  }
#define TLS_TINY_HEAP(NumRsaConfigs, NumPskConfigs, NumSockets)       \
    TLS_TINY_HEAP_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets, Rx); \
    TLS_TINY_HEAP_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets, Tx); \
    TLS_HEAP_AUX_IMPL(NumRsaConfigs, NumPskConfigs, NumSockets)

/** \} */

#endif // EVE_TLS_H_INCLUDED