storage_esfs.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2017 ARM Ltd.
00003 //
00004 // Licensed under the Apache License, Version 2.0 (the "License");
00005 // you may 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,
00012 // WITHOUT 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 #ifndef MBED_CONF_MBED_CLOUD_CLIENT_EXTERNAL_SST_SUPPORT
00017 #ifndef __STORAGE_ESFS_H__
00018 #define __STORAGE_ESFS_H__
00019 
00020 #include <inttypes.h>
00021 #include "key_config_manager.h"
00022 #include "kcm_defs.h"
00023 #include "esfs.h"
00024 #include "cs_hash.h"
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 
00031 #define KCM_FILE_PREFIX_MAX_SIZE 12
00032 //ESFS defines
00033 #define STORAGE_FILENAME_MAX_SIZE ESFS_MAX_NAME_LENGTH
00034 typedef enum {
00035     KCM_CERT_CHAIN_LEN_MD_TYPE,
00036     KCM_MD_TYPE_MAX_SIZE // can't be bigger than ESFS_MAX_TYPE_LENGTH_VALUES
00037 } kcm_meta_data_type_e;
00038 
00039 #if ESFS_MAX_TYPE_LENGTH_VALUES < KCM_MD_TYPE_MAX_SIZE
00040 #error "KCM_MD_TYPE_MAX_SIZE can't be greater than ESFS_MAX_TYPE_LENGTH_VALUES"
00041 #endif
00042 
00043 typedef struct kcm_meta_data_ {
00044     kcm_meta_data_type_e type;
00045     size_t data_size;
00046     uint8_t *data;
00047 } kcm_meta_data_s;
00048 
00049 typedef struct kcm_meta_data_list_ {
00050     // allocate a single meta data for each type
00051     kcm_meta_data_s meta_data[KCM_MD_TYPE_MAX_SIZE];
00052     size_t meta_data_count;
00053 } kcm_meta_data_list_s;
00054 
00055 typedef struct kcm_ctx_ {
00056     esfs_file_t esfs_file_h;
00057     size_t file_size;
00058     bool is_file_size_checked;
00059 } kcm_ctx_s;
00060 
00061 /* === File Operations === */
00062 
00063 /** Create a new file
00064 *
00065 *   @param KCM operation context.
00066 *   @param file_name A binary blob that uniquely identifies the file
00067 *   @param file_name_length The binary blob length in bytes.
00068 *   @param meta_data_list A pointer to structure with single meta data for each type
00069 *   @param is_factory A factory flag.
00070 *   @param is_encrypted Encryption flag
00071 *
00072 *   @returns
00073 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00074 */
00075 kcm_status_e  storage_file_create(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length, const kcm_meta_data_list_s *kcm_meta_data_list, bool is_factory, bool is_encrypted);
00076 
00077 /** Open existing file
00078 *
00079 *   @param KCM operation context.
00080 *   @param file_name A binary blob that uniquely identifies the file
00081 *   @param file_name_length The binary blob length in bytes.
00082 *
00083 *   @returns
00084 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00085 */
00086 kcm_status_e  storage_file_open(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length);
00087 
00088 /** Close file in storage
00089 *
00090 *   @param ctx KCM operation context.
00091 *
00092 *   @returns
00093 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00094 */
00095 kcm_status_e  storage_file_close(kcm_ctx_s *ctx);
00096 
00097 /** Write data to previously opened file in storage
00098 *
00099 *   @param ctx KCM operation context.
00100 *   @param data A pointer to memory with the data to write into the newly created file. Can be NULL if data_length is 0.
00101 *   @param data_length The data length in bytes. Can be 0 if we wish to write an empty file.
00102 *
00103 *   @returns
00104 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00105 */
00106 kcm_status_e  storage_file_write_with_ctx(kcm_ctx_s *ctx, const uint8_t *data, size_t data_length);
00107 
00108 
00109 /** Writes a new file to storage
00110 *
00111 *   @param ctx KCM operation context.
00112 *   @param file_name A binary blob that uniquely identifies the file
00113 *   @param file_name_length The binary blob length in bytes.
00114 *   @param data A pointer to memory with the data to write into the newly created file. Can be NULL if data_length is 0.
00115 *   @param data_length The data length in bytes. Can be 0 if we wish to write an empty file.
00116 *   @param meta_data_list A pointer to structure with single meta data for each type
00117 *   @param is_factory True if KCM item is factory item, or false otherwise
00118 *   @param is_encrypted True if KCM item should be encrypted, or false otherwise
00119 *
00120 *   @returns
00121 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00122 */
00123 kcm_status_e  storage_file_write(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length, const uint8_t *data, size_t data_length, const kcm_meta_data_list_s *kcm_meta_data_list, bool is_factory, bool is_encrypted);
00124 
00125 
00126 /** Returns the size of the data in a file
00127 *
00128 *   @param ctx KCM operation context.
00129 *   @param file_name A binary blob that uniquely identifies the file
00130 *   @param file_name_length The binary blob length in bytes
00131 *   @param file_size_out A pointer to hold the size of the data in the file
00132 *
00133 *   @returns
00134 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00135 */
00136 kcm_status_e  storage_file_size_get(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length, size_t *file_size_out);
00137 
00138 /** Reads data from a file.
00139 *
00140 *   @param ctx KCM operation context.
00141 *   @param file_name A binary blob that uniquely identifies the file
00142 *   @param file_name_length The binary blob length in bytes
00143 *   @param buffer_out A pointer to memory buffer where the data will be read from the file. Can be NULL if buffer_size is 0.
00144 *   @param buffer_size The number of bytes to be read. Buffer must be big enough to contain this size. Can be 0 if we wish to read an empty file.
00145 *   @param buffer_actual_size_out The effective bytes size read from the file.
00146 *
00147 *   @returns
00148 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00149 */
00150 kcm_status_e  storage_file_read(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length, uint8_t *buffer_out, size_t buffer_size, size_t *buffer_actual_size_out);
00151 
00152 /** Returns the size of the data in a file. The file should be opened by storage_file_open()
00153 *
00154 *   @param ctx KCM operation context.
00155 *   @param file_size_out A pointer to hold the size of the data in the file
00156 *
00157 *   @returns
00158 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00159 */
00160 kcm_status_e  storage_file_size_get_with_ctx(kcm_ctx_s *ctx, size_t *file_size_out);
00161 
00162 /** Reads data from a file. The file should be opened by storage_file_open().
00163 *
00164 *   @param ctx KCM operation context.
00165 *   @param buffer_out A pointer to memory buffer where the data will be read from the file. Can be NULL if buffer_size is 0.
00166 *   @param buffer_size The number of bytes to be read. Buffer must be big enough to contain this size. Can be 0 if we wish to read an empty file.
00167 *   @param buffer_actual_size_out The effective bytes size read from the file.
00168 *
00169 *   @returns
00170 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00171 */
00172 kcm_status_e  storage_file_read_with_ctx(kcm_ctx_s *ctx, uint8_t *buffer_out, size_t buffer_size, size_t *buffer_actual_size_out);
00173 /** Deletes the file from storage
00174 *
00175 *   @param ctx KCM operation context.
00176 *   @param file_name A binary blob that uniquely identifies the file
00177 *   @param file_name_length The binary blob length in bytes
00178 *
00179 *   @returns
00180 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00181 */
00182 kcm_status_e  storage_file_delete(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length);
00183 
00184 /** Get the size of the stored meta data type. The file should be opened by storage_file_open().
00185 *
00186 *   @param ctx KCM operation context.
00187 *   @param type the meta data type to get size for.
00188 *   @param metadata_size_out A pointer to hold the size of the meta data
00189 *
00190 *   @returns
00191 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00192 */
00193 kcm_status_e  storage_file_get_meta_data_size(kcm_ctx_s *ctx, kcm_meta_data_type_e type, size_t *meta_data_size_out);
00194 
00195 /** Reads meta data into a kcm_meta_data
00196 *
00197 *   @param ctx KCM operation context.
00198 *   @param type the meta data type to get size for.
00199 *   @param buffer_out A pointer to memory buffer where the meta data will be read to.
00200 *   @param buffer_size The number of bytes to be read. Buffer must be big enough to contain this size.
00201 *   @param buffer_actual_size_out The effective bytes size read from the file.
00202 *
00203 *   @returns
00204 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00205 */
00206 kcm_status_e  storage_file_read_meta_data_by_type(kcm_ctx_s *ctx, kcm_meta_data_type_e type, uint8_t *buffer_out, size_t buffer_size, size_t *buffer_actual_size_out);
00207 
00208 #ifdef __cplusplus
00209 }
00210 #endif
00211 #endif //__STORAGE_ESFS_H__
00212 #endif//MBED_CONF_MBED_CLOUD_CLIENT_EXTERNAL_SST_SUPPORT