SecureStore.h

00001 /*
00002  * Copyright (c) 2018 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_SECURESTORE_H
00018 #define MBED_SECURESTORE_H
00019 
00020 #if !defined(MBEDTLS_CONFIG_FILE)
00021 #include "mbedtls/config.h"
00022 #else
00023 #include MBEDTLS_CONFIG_FILE
00024 #endif
00025 
00026 #include "features/device_key/source/DeviceKey.h"
00027 
00028 #define SECURESTORE_ENABLED 1
00029 
00030 // Whole class is not supported if entropy, device key or required mbed TLS features are not enabled
00031 #if !defined(MBEDTLS_ENTROPY_C) || !defined(MBEDTLS_CIPHER_MODE_CTR) || !defined(MBEDTLS_CMAC_C) || !DEVICEKEY_ENABLED
00032 #undef SECURESTORE_ENABLED
00033 #define SECURESTORE_ENABLED 0
00034 #endif
00035 
00036 #if SECURESTORE_ENABLED || defined(DOXYGEN_ONLY)
00037 
00038 #include <stdint.h>
00039 #include <stdio.h>
00040 #include "KVStore.h"
00041 #include "PlatformMutex.h"
00042 
00043 // Forward declarations
00044 struct  mbedtls_entropy_context;
00045 
00046 namespace mbed {
00047 
00048 /** TDBStore class
00049  *
00050  *  Lightweight Key Value storage over a block device
00051  */
00052 
00053 class SecureStore : public KVStore {
00054 public:
00055 
00056     /**
00057      * @brief Class constructor
00058      *
00059      * @param[in]  underlying_kv        KVStore that will hold the data.
00060      * @param[in]  rbp_kv               Additional KVStore used for rollback protection.
00061      *
00062      * @returns none
00063      */
00064     SecureStore(KVStore *underlying_kv, KVStore *rbp_kv = 0);
00065 
00066     /**
00067      * @brief Class destructor
00068      *
00069      * @returns none
00070      */
00071     virtual ~SecureStore();
00072 
00073     /**
00074      * @brief Initialize SecureStore class. It will also initialize
00075      *        the underlying KVStore and the rollback protection KVStore.
00076      *
00077      * @returns MBED_SUCCESS                        Success.
00078      *          or any other error from underlying KVStore instances.
00079      */
00080     virtual int init();
00081 
00082     /**
00083      * @brief Deinitialize SecureStore class, free handles and memory allocations.
00084      *
00085      * @returns MBED_SUCCESS                        Success.
00086      *          or any other error from underlying KVStore instances.
00087      */
00088     virtual int deinit();
00089 
00090 
00091     /**
00092      * @brief Reset KVStore contents (clear all keys)
00093      *        Warning: This function is not thread safe.
00094      *
00095      * @returns MBED_SUCCESS                        Success.
00096      *          MBED_ERROR_NOT_READY                Not initialized.
00097      *          or any other error from underlying KVStore instances.
00098      */
00099     virtual int reset();
00100 
00101     /**
00102      * @brief Set one KVStore item, given key and value.
00103      *
00104      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00105      * @param[in]  buffer               Value data buffer.
00106      * @param[in]  size                 Value data size.
00107      * @param[in]  create_flags         Flag mask - WRITE_ONCE_FLAG|REQUIRE_CONFIDENTIALITY_FLAG|
00108      *                                  REQUIRE_INTEGRITY_FLAG|REQUIRE_REPLAY_PROTECTION_FLAG
00109      *
00110      * @returns MBED_SUCCESS                        Success.
00111      *          MBED_ERROR_NOT_READY                Not initialized.
00112      *          MBED_ERROR_READ_FAILED              Unable to read from media.
00113      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00114      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00115      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00116      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00117      *          or any other error from underlying KVStore instances.
00118      */
00119     virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags);
00120 
00121     /**
00122      * @brief Get one KVStore item, given key.
00123      *
00124      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00125      * @param[in]  buffer               Value data buffer.
00126      * @param[in]  buffer_size          Value data buffer size.
00127      * @param[out] actual_size          Actual read size.
00128      * @param[in]  offset               Offset to read from in data.
00129      *
00130      * @returns MBED_SUCCESS                        Success.
00131      *          MBED_ERROR_NOT_READY                Not initialized.
00132      *          MBED_ERROR_READ_FAILED              Unable to read from media.
00133      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00134      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00135      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00136      *          MBED_ERROR_ITEM_NOT_FOUND           No such key.
00137      *          MBED_ERROR_AUTHENTICATION_FAILED    Data authentication failed.
00138      *          MBED_ERROR_AUTHENTICATION_RBP_FAILED
00139      *                                              Rollback protection data authentication failed.
00140      *          or any other error from underlying KVStore instances.
00141      */
00142     virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL,
00143                     size_t offset = 0);
00144 
00145     /**
00146      * @brief Get information of a given key.
00147      *
00148      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00149      * @param[out] info                 Returned information structure containing size and flags.
00150      *
00151      * @returns MBED_SUCCESS                        Success.
00152      *          MBED_ERROR_NOT_READY                Not initialized.
00153      *          MBED_ERROR_READ_FAILED              Unable to read from media.
00154      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00155      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00156      *          MBED_ERROR_ITEM_NOT_FOUND           No such key.
00157      *          MBED_ERROR_AUTHENTICATION_FAILED    Data authentication failed.
00158      *          MBED_ERROR_AUTHENTICATION_RBP_FAILED
00159      *                                              Rollback protection data authentication failed.
00160      *          or any other error from underlying KVStore instances.
00161      */
00162     virtual int get_info(const char *key, info_t *info);
00163 
00164     /**
00165      * @brief Remove a KVStore item, given key.
00166      *
00167      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00168      *
00169      * @returns MBED_SUCCESS                        Success.
00170      *          MBED_ERROR_NOT_READY                Not initialized.
00171      *          MBED_ERROR_READ_FAILED              Unable to read from media.
00172      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00173      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00174      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00175      *          or any other error from underlying KVStore instances.
00176      */
00177     virtual int remove(const char *key);
00178 
00179 
00180     /**
00181      * @brief Start an incremental KVStore set sequence. This operation is blocking other operations.
00182      *        Any get/set/remove/iterator operation will be blocked until set_finalize is called.
00183      *
00184      * @param[out] handle               Returned incremental set handle.
00185      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00186      * @param[in]  final_data_size      Final value data size.
00187      * @param[in]  create_flags         Flag mask - WRITE_ONCE_FLAG|REQUIRE_CONFIDENTIALITY_FLAG|
00188      *                                  REQUIRE_INTEGRITY_FLAG|REQUIRE_REPLAY_PROTECTION_FLAG
00189      *
00190      * @returns MBED_SUCCESS                        Success.
00191      *          MBED_ERROR_NOT_READY                Not initialized.
00192      *          MBED_ERROR_READ_FAILED              Unable to read from media.
00193      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00194      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00195      *          MBED_ERROR_WRITE_PROTECTED          Already stored with "write once" flag.
00196      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00197      *          or any other error from underlying KVStore instances.
00198      */
00199     virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags);
00200 
00201     /**
00202      * @brief Add data to incremental KVStore set sequence. This operation is blocking other operations.
00203      *        Any get/set/remove operation will be blocked until set_finalize is called.
00204      *
00205      * @param[in]  handle               Incremental set handle.
00206      * @param[in]  value_data           value data to add.
00207      * @param[in]  data_size            value data size.
00208      *
00209      * @returns MBED_SUCCESS                        Success.
00210      *          MBED_ERROR_NOT_READY                Not initialized.
00211      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00212      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00213      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00214      *          or any other error from underlying KVStore instances.
00215      */
00216     virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size);
00217 
00218     /**
00219      * @brief Finalize an incremental KVStore set sequence.
00220      *
00221      * @param[in]  handle               Incremental set handle.
00222      *
00223      * @returns MBED_SUCCESS                        Success.
00224      *          MBED_ERROR_NOT_READY                Not initialized.
00225      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00226      *          MBED_ERROR_INVALID_SIZE             Invalid size given in function arguments.
00227      *          MBED_ERROR_FAILED_OPERATION         Internal error.
00228      *          or any other error from underlying KVStore instances.
00229      */
00230     virtual int set_finalize(set_handle_t handle);
00231 
00232     /**
00233      * @brief Start an iteration over KVStore keys.
00234      *        There are no issue with any other operation while iterator is open.
00235      *
00236      * @param[out] it                   Returned iterator handle.
00237      * @param[in]  prefix               Key prefix (null for all keys).
00238      *
00239      * @returns MBED_SUCCESS                        Success.
00240      *          MBED_ERROR_NOT_READY                Not initialized.
00241      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00242      *          or any other error from underlying KVStore instances.
00243      */
00244     virtual int iterator_open(iterator_t *it, const char *prefix = NULL);
00245 
00246     /**
00247      * @brief Get next key in iteration.
00248      *        There are no issue with any other operation while iterator is open.
00249      *
00250      * @param[in]  it                   Iterator handle.
00251      * @param[in]  key                  Buffer for returned key.
00252      * @param[in]  key_size             Key buffer size.
00253      *
00254      * @returns MBED_SUCCESS                        Success.
00255      *          MBED_ERROR_NOT_READY                Not initialized.
00256      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00257      *          or any other error from underlying KVStore instances.
00258      */
00259     virtual int iterator_next(iterator_t it, char *key, size_t key_size);
00260 
00261     /**
00262      * @brief Close iteration.
00263      *
00264      * @returns MBED_SUCCESS                        Success.
00265      *          MBED_ERROR_NOT_READY                Not initialized.
00266      *          MBED_ERROR_INVALID_ARGUMENT         Invalid argument given in function arguments.
00267      *          or any other error from underlying KVStore instances.
00268      *
00269      * @returns 0 on success or a negative error code on failure
00270      */
00271     virtual int iterator_close(iterator_t it);
00272 
00273 #if !defined(DOXYGEN_ONLY)
00274 private:
00275     // Forward declaration
00276     struct inc_set_handle_t;
00277 
00278     PlatformMutex _mutex;
00279     bool _is_initialized;
00280     KVStore *_underlying_kv, *_rbp_kv;
00281     mbedtls_entropy_context *_entropy;
00282     inc_set_handle_t *_ih;
00283     uint8_t *_scratch_buf;
00284 
00285     /**
00286      * @brief Actual get function, serving get and get_info APIs.
00287      *
00288      * @param[in]  key                  Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
00289      * @param[in]  buffer               Value data buffer.
00290      * @param[in]  buffer_size          Value data buffer size.
00291      * @param[out] actual_size          Actual read size.
00292      * @param[in]  offset               Offset to read from in data.
00293      * @param[out] info                 Returned information structure.
00294      *
00295      * @returns 0 on success or a negative error code on failure
00296      */
00297     int do_get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL,
00298                size_t offset = 0, info_t *info = 0);
00299 #endif
00300 };
00301 /** @}*/
00302 
00303 } // namespace mbed
00304 
00305 #endif
00306 #endif