pal_sst.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifdef MBED_CONF_MBED_CLOUD_CLIENT_EXTERNAL_SST_SUPPORT
00020 
00021 #ifndef _PAL_SST_H
00022 #define _PAL_SST_H
00023 
00024 #ifndef _PAL_H
00025     #error "Do not include this file directly. Use pal.h instead."
00026 #endif
00027 
00028 #include <stdint.h>
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif
00033 
00034 /*! \file pal_sst.h
00035 *  \brief PAL SST.
00036 *   This file contains Secure Storage APIs and is part of the PAL Service API.
00037 *   It provides read/write functionalities to SST and iterator capabilities.
00038 */
00039 
00040 /*
00041 * Pal SST item iterator
00042 */
00043 typedef uintptr_t palSSTIterator_t;
00044 
00045 /*
00046 * Pal SST flags
00047 */
00048 
00049 /*
00050 * Write once flag. 
00051 * When the flag is used, the item can only be written once and cannot be removed.
00052 */
00053 #define PAL_SST_WRITE_ONCE_FLAG         (1 << 0)
00054 
00055 /* 
00056 * Confidentiality (encryption) flag.
00057 */
00058 #define PAL_SST_CONFIDENTIALITY_FLAG    (1 << 1)
00059 
00060 /*
00061 * Replay protection flag.
00062 * When this flag is used, the item cannot be physically removed (outside pal_SST APIs). 
00063 */
00064 #define PAL_SST_REPLAY_PROTECTION_FLAG  (1 << 3)
00065 
00066 /*
00067 * PAL SST item info structure
00068 */
00069 typedef struct palSSTItemInfo {
00070     size_t itemSize;          //!< PAL item size
00071     uint32_t SSTFlagsBitmap;  //!< PAL SST flags bitmap
00072 } palSSTItemInfo_t;
00073 
00074 /*! Writes a new item to storage. 
00075 *
00076 * The API supports writing empty items. When you write an item that has already been set, the API overwrites the set value, unless the write-once flag is turned on for the item.
00077 *
00078 * @param[in] itemName: The item name. Pelion client expects that the API support:
00079 *                      - Name length of at least 120 characters.
00080 *                      - Alphanumeric and '.', '-', '_' characters in the name.
00081 * @param[in] itemBuffer: A pointer to the location in memory with the item to write.
00082 *                        Can be NULL if ::itemBufferSize is 0.
00083 * @param[in] itemBufferSize: The data length of the item in bytes.
00084 *                            Can be 0 if ::itemBuffer is NULL.
00085 * @param[in] SSTFlagsBitmap: PAL SST flag bitmap.
00086 *
00087 * \returns
00088 *        PAL_SUCCESS on success.
00089 *        PAL_ERR_SST_WRITE_PROTECTED when trying to set write-once value.
00090 *        Other negative value indicating a specific error code in the event of failure.
00091 */
00092 palStatus_t pal_SSTSet (const char *itemName, const void *itemBuffer, size_t itemBufferSize, uint32_t SSTFlagsBitmap);
00093 
00094 /*! Reads an item's data from storage.
00095 *
00096 * The API supports reading empty items.
00097 * @param[in] itemName: The item name. Pelion client expects that the API support:
00098 *                      - Name length of at least 120 characters. 
00099 *                      - Alphanumeric and '.', '-', '_' characters in the name.
00100 * @param[in/out] itemBuffer: A pointer to a memory buffer where the item will be read from storage.
00101 *                            Can be NULL if ::itemBufferSize is 0.
00102 * @param[in] itemBufferSize: The memory buffer in bytes.
00103 *                            Can be 0 if ::itemBuffer is NULL.
00104 * @param[out] actualItemSize: The actual size of the item.
00105 *
00106 * \return
00107 *        PAL_SUCCESS on success.
00108 *        PAL_ERR_SST_ITEM_NOT_FOUND if the item does not exist.
00109 *        Other negative value indicating a specific error code in the event of failure.
00110 */
00111 palStatus_t pal_SSTGet (const char *itemName, void *itemBuffer, size_t itemBufferSize, size_t *actualItemSize);
00112 
00113 /*! Gets item information.
00114 *
00115 * @param[in] itemName: The item name. Pelion client expects that the API support:
00116 *                      - Name length of at least 120 characters.
00117 *                      - Alphanumeric and '.', '-', '_' characters in the name.
00118 * @param[out] palItemInfo: The item info.
00119 *
00120 * \return
00121 *        PAL_SUCCESS on success.
00122 *        PAL_ERR_SST_ITEM_NOT_FOUND if the item does not exist.
00123 *        Other negative value indicating a specific error code in the event of failure.
00124 */
00125 palStatus_t pal_SSTGetInfo (const char *itemName, palSSTItemInfo_t *palItemInfo);
00126 
00127 /*! Removes an item from storage, unless the write-once flag is turned on for the item.
00128 *
00129 * @param[in] itemName: The item name. Pelion client expects that the API support:
00130 *                      - Name length of at least 120 characters. 
00131 *                      - Alphanumeric and '.', '-', '_' characters in the name.
00132 *
00133 * \return
00134 *        PAL_SUCCESS on success.
00135 *        PAL_ERR_SST_WRITE_PROTECTED when trying to remove a write-once value.
00136 *        Other negative value indicating a specific error code in the event of failure.
00137 */
00138 palStatus_t pal_SSTRemove (const char *itemName);
00139 
00140 /*! Opens item iterator.
00141 *
00142 * @param[out] palSSTIterator: A pointer to the item iterator.
00143 * @param[in] itemPrefix:  The prefix of the item name.
00144 *
00145 * \return PAL_SUCCESS on success. A negative value indicating a specific error code in the event of failure.
00146 */
00147 palStatus_t pal_SSTIteratorOpen (palSSTIterator_t *palSSTIterator, const char *itemPrefix);
00148 
00149 /*! Iterates to next item.
00150 *
00151 * @param[in/out] palSSTIterator: A pointer to item iterator.
00152 * @param[in/out] itemName:  A pointer to the item name buffer populated by the iterator. Must be supplied by the user.
00153 * @param[in] itemNameSize: The size of the supplied item name buffer. Must be at least the length of itemName.
00154 *
00155 * \return
00156 *        PAL_SUCCESS on success.
00157 *        PAL_ERR_SST_ITEM_NOT_FOUND if the item does not exist.
00158 *        Other negative value indicating a specific error code in the event of failure.
00159 */
00160 palStatus_t pal_SSTIteratorNext (palSSTIterator_t palSSTIterator, char *itemNameBuffer, size_t itemNameBufferSize);
00161 
00162 /*! Closes item iterator.
00163 *
00164 * @param[in/out] palSSTIterator: A pointer to item iterator.
00165 * @param[in] itemPrefix:  The prefix of the item name.
00166 * 
00167 * \return PAL_SUCCESS on success. A negative value indicating a specific error code in the event of failure.
00168 */
00169 palStatus_t pal_SSTIteratorClose (palSSTIterator_t palSSTIterator);
00170 
00171 /*! Remove all items and related data.
00172  *
00173  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in the event of failure.
00174  */
00175 palStatus_t pal_SSTReset (void);
00176 
00177 #ifdef __cplusplus
00178 }
00179 #endif
00180 
00181 // endif
00182 
00183 
00184 #endif //_PAL_SST_H
00185 
00186 #endif //MBED_CONF_MBED_CLOUD_CLIENT_EXTERNAL_SST_SUPPORT