extlibs/tinydtls/dtls_hal.h

   1 /*
   2 Copyright (c) 2015 Atmel Corporation. All rights reserved.
   3
   4 Redistribution and use in source and binary forms, with or without
   5 modification, are permitted provided that the following conditions are met:
   6
   7 1. Redistributions of source code must retain the above copyright notice, this
   8 list of conditions and the following disclaimer.
   9
  10 2. Redistributions in binary form must reproduce the above copyright notice,
  11 this list of conditions and the following disclaimer in the documentation
  12 and/or other materials provided with the distribution.
  13
  14 3.  Neither the name of Atmel nor the names of its contributors may be used to
  15 endorse or promote products derived from this software without specific
  16 prior written permission.
  17
  18 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  20 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  22 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  23 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  24 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  26 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28  */
  29
  30 /**
  31  * @file dtls_hal.h
  32  * @brief DTLS Hardware Abstraction Layer API and visible structures.
  33  */
  34
  35 #ifndef _DTLS_DTLS_HAL_H_
  36 #define _DTLS_DTLS_HAL_H_
  37
  38 #include <stdint.h>
  39 #include <stdbool.h>
  40
  41 // Define return values for HAL
  42 #define HAL_SUCCESS (1)
  43 #define HAL_FAILURE (0)
  44 #define ENC_KEY_SIZE (32)
  45
  46 /**
  47  * This structure contains callback functions used by tinydtls to
  48  * provide a hardware abstraction layer for secure storage .
  49  */
  50 typedef struct {
  51
  52   /**
  53    * Call this function during application initialization to create HAL related resources.
  54    *
  55    * @param[in] ctx  The current DTLS context.
  56    * @return HAL_SUCCESS or HAL_FAILURE
  57    */
  58   int (*HAL_init)(struct dtls_context_t *ctx);
  59
  60   /**
  61    * Call this function during application shut down to clean up any HAL related resources.
  62    *
  63    * @param[in] ctx  The current DTLS context.
  64    * @return HAL_SUCCESS or HAL_FAILURE
  65    */
  66   int (*HAL_finish)(struct dtls_context_t *ctx);
  67
  68   /**
  69    * Call this function to store unsecured data on hardware.
  70    *
  71    * @param[in] ctx  The current DTLS context.
  72    * @param[in] p_location_handle  The handle to the hardware location to store p_data.
  73    * @param[in] p_data  The data to store.
  74    * @param[in] data_size  The size of the data to store.
  75    * @return HAL_SUCCESS or HAL_FAILURE
  76    */
  77   int (*HAL_write_mem)(struct dtls_context_t *ctx,
  78                        const uint8_t* p_location,
  79                        const uint8_t* p_data,
  80                        size_t data_size);
  81
  82   /**
  83    * Call this function to read data from unsecured storage from hardware.
  84    *
  85    * @param[in] ctx  The current DTLS context.
  86    * @param[in] p_location_handle  The handle to the hardware location to read p_data.
  87    * @param[in] p_data  The data to read.
  88    * @param[inout] data_size  IN: The size of the buffer to receive data.  OUT: The actual number of bytes read.
  89    * @return HAL_SUCCESS or HAL_FAILURE
  90    */
  91   int (*HAL_read_mem)(struct dtls_context_t *ctx,
  92                       const uint8_t* p_location,
  93                       uint8_t* p_data,
  94                       size_t* dataSize);
  95
  96   /**
  97    * Call this function to store sensitive data in secure hardware.
  98    * Data will be securely stored and encrypted on the wire
  99    *
 100    * @param[in] ctx  The current DTLS context.
 101    * @param[in] p_location_handle  The handle to the hardware location to store p_data.
 102    * @param[in] p_data  The data to store securely.
 103    * @param[in] data_size  The size of the data to store securely.
 104    * @return HAL_SUCCESS or HAL_FAILURE
 105    */
 106   int (*HAL_write_mem_enc)(struct dtls_context_t *ctx,
 107                            const uint8_t* p_location,
 108                            const uint8_t* p_data,
 109                            size_t data_size);
 110
 111   /**
 112    * Call this function to read sensitive data from secure hardware.
 113    * Data will be read from secure storage and encrypted on the wire
 114    *
 115    * @param[in] ctx  The current DTLS context.
 116    * @param[in] p_location_handle  The handle to the hardware location to read p_data.
 117    * @param[in] p_data  The data to read securely.
 118    * @param[inout] data_size  IN: The size of the buffer to receive data.  OUT: The actual number of bytes read.
 119    * @return HAL_SUCCESS or HAL_FAILURE
 120    */
 121   int (*HAL_read_mem_enc)(struct dtls_context_t *ctx,
 122                           const uint8_t* p_location,
 123                           uint8_t* p_data,
 124                           size_t* dataSize);
 125
 126   /**
 127    * Call this function to generate a unique encryption key that will be used for secure storage.
 128    * This encryption key should be stored as a platform resource
 129    *
 130    * @param[in] ctx  The current DTLS context.
 131    * @param[out] p_enc_key_out  The internally generated unique encryption key that will be used for secure storage.
 132    *    This key needs to be stored on the platform.
 133    * @return HAL_SUCCESS or HAL_FAILURE
 134    */
 135   int (*HAL_init_enckey)(struct dtls_context_t *ctx,
 136                          uint8_t p_enc_key_out[ENC_KEY_SIZE]);
 137
 138   /**
 139    * Call this function to set a unique encryption key that will be used for secure storage.
 140    * This encryption key should be stored as a platform resource
 141    *
 142    * @param[in] ctx  The current DTLS context.
 143    * @param[in] p_enc_key_in  The encryption key that will be used for secure storage.
 144    *    This key needs to be stored on the platform.
 145    * @return HAL_SUCCESS or HAL_FAILURE
 146    */
 147   int (*HAL_set_enckey)(struct dtls_context_t *ctx,
 148                         const uint8_t p_enc_key_in[ENC_KEY_SIZE]);
 149
 150   /**
 151    * This function is called internally from HAL_read_mem_enc and HAL_write_mem_enc.
 152    * The platform must implement this function to return the encryption key that was
 153    *   returned by HAL_init_enckey or HAL_set_enckey.
 154    *
 155    * @param[in] ctx  The current DTLS context.
 156    * @param[out] p_enc_key_out  The encryption key that is used for secure storage.
 157    *    Retrieve from platform in this function.
 158    * @return HAL_SUCCESS or HAL_FAILURE
 159    */
 160   int (*HAL_get_enckey)(struct dtls_context_t *ctx,
 161                         uint8_t p_enc_key_out[ENC_KEY_SIZE]);
 162
 163   /**
 164    * Call this function to use the hardware to calculate a SHA256
 165    *
 166    * @param[in] ctx  The current DTLS context.
 167    * @param[in] p_msg  The message to calculate the SHA256.
 168    * @param[in] msg_size  The size of the message to hash.
 169    * @param[out] p_hash  The hash of p_msg.
 170    * @return HAL_SUCCESS or HAL_FAILURE
 171    */
 172   int (*HAL_sha2_calc)(struct dtls_context_t *ctx,
 173                        uint8_t *p_msg,
 174                        size_t msg_size,
 175                        uint8_t p_hash[SHA256_DIGEST_LENGTH]);
 176
 177   /**
 178    * Call this function to use the hardware key derivation function (KDF)
 179    *
 180    * @param[in] ctx  The current DTLS context.
 181    * @param[in] p_seed  The seed used to produce the key.
 182    * @param[in] seed_size  The size of the message to hash.
 183    * @param[out] p_keyout  The key produced by the KDF.
 184    * @param[in] key_size  The size of the key to be returned.
 185    * @return HAL_SUCCESS or HAL_FAILURE
 186    */
 187   int (*HAL_kdf_calc)(struct dtls_context_t *ctx,
 188                       const uint8_t* p_seed,
 189                       const size_t seed_size,
 190                       uint8_t* p_keyout,
 191                       const size_t key_size);
 192
 193   /**
 194    * Call this function to retrieve the specified certificate from hardware
 195    *
 196    * @param[in] ctx  The current DTLS context.
 197    * @param[in] cert_id  An index into the certificate to returned.
 198    * @param[inout] cert  The certificate to be returned.
 199    * @param[inout] cert_size  The size of the certificate.
 200    * @return HAL_SUCCESS or HAL_FAILURE
 201    */
 202   int (*HAL_get_x509_cert)(struct dtls_context_t *ctx,
 203                            uint32_t cert_ref,
 204                            uint8_t **cert,
 205                            size_t *cert_size);
 206
 207 } dtls_hal_handler_t;
 208
 209
 210 #endif /* _DTLS_DTLS_HAL_H_ */
 211