storage.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 
00017 #ifndef __STORAGE_H__
00018 #define __STORAGE_H__
00019 
00020 #include <inttypes.h>
00021 #include "key_config_manager.h"
00022 #include "kcm_internal.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 
00029 /* === Initialization and Finalization === */
00030 
00031 /** Initializes storage so that it can be used.
00032 *   Must be called once after boot.
00033 *   Existing data in storage would not compromised.
00034 *
00035 *   @returns
00036 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00037 */
00038 kcm_status_e storage_init(void);
00039 
00040 
00041 /** Finalize storage.
00042 *   Must be called once to close all storage resources.
00043 *
00044 *   @returns
00045 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00046 */
00047 kcm_status_e storage_finalize(void);
00048 
00049 /** Resets storage to an empty state.
00050 *
00051 *   @returns
00052 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00053 */
00054 kcm_status_e storage_reset(void);
00055 
00056 
00057 /** Resets storage to a factory state.
00058 *
00059 *   @returns
00060 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00061 */
00062 kcm_status_e storage_factory_reset(void);
00063 
00064 
00065 /* === File Operations === */
00066 
00067 /** Create a new file
00068 *
00069 *   @param KCM operation context.
00070 *   @param file_name A binary blob that uniquely identifies the file
00071 *   @param file_name_length The binary blob length in bytes.
00072 *   @param is_factory A factory flag.
00073 *   @param is_encrypted Encryption flag
00074 *
00075 *   @returns
00076 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00077 */
00078 kcm_status_e storage_file_create(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length, bool is_factory, bool is_encrypted);
00079 
00080 /** Open existing file
00081 *
00082 *   @param KCM operation context.
00083 *   @param file_name A binary blob that uniquely identifies the file
00084 *   @param file_name_length The binary blob length in bytes.
00085 *
00086 *   @returns
00087 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00088 */
00089 kcm_status_e storage_file_open(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length);
00090 
00091 /** Close file in storage
00092 *
00093 *   @param ctx KCM operation context.
00094 *
00095 *   @returns
00096 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00097 */
00098 kcm_status_e storage_file_close(kcm_ctx_s *ctx);
00099 
00100 /** Write data to previously opened file in storage
00101 *
00102 *   @param ctx KCM operation context.
00103 *   @param data A pointer to memory with the data to write into the newly created file. Can be NULL if data_length is 0.
00104 *   @param data_length The data length in bytes. Can be 0 if we wish to write an empty file.
00105 *
00106 *   @returns
00107 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00108 */
00109 kcm_status_e storage_file_write_with_ctx(kcm_ctx_s *ctx, const uint8_t *data, size_t data_length);
00110 
00111 
00112 /** Writes a new file to storage
00113 *
00114 *   @param ctx KCM operation context.
00115 *   @param file_name A binary blob that uniquely identifies the file
00116 *   @param file_name_length The binary blob length in bytes.
00117 *   @param data A pointer to memory with the data to write into the newly created file. Can be NULL if data_length is 0.
00118 *   @param data_length The data length in bytes. Can be 0 if we wish to write an empty file.
00119     @param is_factory True if KCM item is factory item, or false otherwise
00120     @param is_encrypted True if KCM item should be encrypted, or false otherwise
00121 *
00122 *   @returns
00123 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00124 */
00125 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, bool is_factory, bool is_encrypted);
00126 
00127 
00128 /** Returns the size of the data in a file
00129 *
00130 *   @param ctx KCM operation context.
00131 *   @param file_name A binary blob that uniquely identifies the file
00132 *   @param file_name_length The binary blob length in bytes
00133 *   @param file_size_out A pointer to hold the size of the data in the file
00134 *
00135 *   @returns
00136 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00137 */
00138 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);
00139 
00140 /** Reads data from a file.
00141 *
00142 *   @param ctx KCM operation context.
00143 *   @param file_name A binary blob that uniquely identifies the file
00144 *   @param file_name_length The binary blob length in bytes
00145 *   @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.
00146 *   @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.
00147 *   @param buffer_actual_size_out The effective bytes size read from the file.
00148 *
00149 *   @returns
00150 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00151 */
00152 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);
00153 
00154 /** Returns the size of the data in a file. The file should be opened by storage_file_open()
00155 *
00156 *   @param ctx KCM operation context.
00157 *   @param file_size_out A pointer to hold the size of the data in the file
00158 *
00159 *   @returns
00160 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00161 */
00162 kcm_status_e storage_file_size_get_with_ctx(kcm_ctx_s *ctx, size_t *file_size_out);
00163 
00164 /** Reads data from a file. The file should be opened by storage_file_open().
00165 *
00166 *   @param ctx KCM operation context.
00167 *   @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.
00168 *   @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.
00169 *   @param buffer_actual_size_out The effective bytes size read from the file.
00170 *
00171 *   @returns
00172 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00173 */
00174 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);
00175 /** Deletes the file from storage
00176 *
00177 *   @param ctx KCM operation context.
00178 *   @param file_name A binary blob that uniquely identifies the file
00179 *   @param file_name_length The binary blob length in bytes
00180 *
00181 *   @returns
00182 *       KCM_STATUS_SUCCESS in case of success otherwise one of kcm_status_e errors
00183 */
00184 kcm_status_e storage_file_delete(kcm_ctx_s *ctx, const uint8_t *file_name, size_t file_name_length);
00185 
00186 
00187 #ifdef __cplusplus
00188 }
00189 #endif
00190 
00191 #endif //__STORAGE_H__