1 /* 2 * Copyright (c) 2016, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file includes platform abstraction for non-volatile storage of settings. 33 */ 34 35 #ifndef OPENTHREAD_PLATFORM_SETTINGS_H_ 36 #define OPENTHREAD_PLATFORM_SETTINGS_H_ 37 38 #include <openthread/instance.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @addtogroup plat-settings 46 * 47 * @brief 48 * This module includes the platform abstraction for non-volatile storage of settings. 49 * 50 * @{ 51 * 52 */ 53 54 /** 55 * This enumeration defines the keys of settings. 56 * 57 * Note: When adding a new settings key, if the settings corresponding to the key contains security sensitive 58 * information, the developer MUST add the key to the array `aSensitiveKeys` which is passed in 59 * `otPlatSettingsInit()`. 60 * 61 */ 62 enum 63 { 64 OT_SETTINGS_KEY_ACTIVE_DATASET = 0x0001, ///< Active Operational Dataset. 65 OT_SETTINGS_KEY_PENDING_DATASET = 0x0002, ///< Pending Operational Dataset. 66 OT_SETTINGS_KEY_NETWORK_INFO = 0x0003, ///< Thread network information. 67 OT_SETTINGS_KEY_PARENT_INFO = 0x0004, ///< Parent information. 68 OT_SETTINGS_KEY_CHILD_INFO = 0x0005, ///< Child information. 69 OT_SETTINGS_KEY_SLAAC_IID_SECRET_KEY = 0x0007, ///< SLAAC key to generate semantically opaque IID. 70 OT_SETTINGS_KEY_DAD_INFO = 0x0008, ///< Duplicate Address Detection (DAD) information. 71 OT_SETTINGS_KEY_SRP_ECDSA_KEY = 0x000b, ///< SRP client ECDSA public/private key pair. 72 OT_SETTINGS_KEY_SRP_CLIENT_INFO = 0x000c, ///< The SRP client info (selected SRP server address). 73 OT_SETTINGS_KEY_SRP_SERVER_INFO = 0x000d, ///< The SRP server info (UDP port). 74 OT_SETTINGS_KEY_BR_ULA_PREFIX = 0x000f, ///< BR ULA prefix. 75 76 // Deprecated and reserved key values: 77 // 78 // 0x0006 previously auto-start. 79 // 0x0009 previously OMR prefix. 80 // 0x000a previously on-link prefix. 81 // 0x000e previously NAT64 prefix. 82 83 // Keys in range 0x8000-0xffff are reserved for vendor-specific use. 84 OT_SETTINGS_KEY_VENDOR_RESERVED_MIN = 0x8000, 85 OT_SETTINGS_KEY_VENDOR_RESERVED_MAX = 0xffff, 86 }; 87 88 /** 89 * Performs any initialization for the settings subsystem, if necessary. 90 * 91 * This function also sets the sensitive keys that should be stored in the secure area. 92 * 93 * Note that the memory pointed by @p aSensitiveKeys MUST not be released before @p aInstance is destroyed. 94 * 95 * @param[in] aInstance The OpenThread instance structure. 96 * @param[in] aSensitiveKeys A pointer to an array containing the list of sensitive keys. May be NULL only if 97 * @p aSensitiveKeysLength is 0, which means that there is no sensitive keys. 98 * @param[in] aSensitiveKeysLength The number of entries in the @p aSensitiveKeys array. 99 * 100 */ 101 void otPlatSettingsInit(otInstance *aInstance, const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength); 102 103 /** 104 * Performs any de-initialization for the settings subsystem, if necessary. 105 * 106 * @param[in] aInstance The OpenThread instance structure. 107 * 108 */ 109 void otPlatSettingsDeinit(otInstance *aInstance); 110 111 /** 112 * Fetches the value of a setting. 113 * 114 * This function fetches the value of the setting identified 115 * by @p aKey and write it to the memory pointed to by aValue. 116 * It then writes the length to the integer pointed to by 117 * @p aValueLength. The initial value of @p aValueLength is the 118 * maximum number of bytes to be written to @p aValue. 119 * 120 * This function can be used to check for the existence of 121 * a key without fetching the value by setting @p aValue and 122 * @p aValueLength to NULL. You can also check the length of 123 * the setting without fetching it by setting only aValue 124 * to NULL. 125 * 126 * Note that the underlying storage implementation is not 127 * required to maintain the order of settings with multiple 128 * values. The order of such values MAY change after ANY 129 * write operation to the store. 130 * 131 * @param[in] aInstance The OpenThread instance structure. 132 * @param[in] aKey The key associated with the requested setting. 133 * @param[in] aIndex The index of the specific item to get. 134 * @param[out] aValue A pointer to where the value of the setting should be written. May be set to NULL if 135 * just testing for the presence or length of a setting. 136 * @param[in,out] aValueLength A pointer to the length of the value. When called, this pointer should point to an 137 * integer containing the maximum value size that can be written to @p aValue. At return, 138 * the actual length of the setting is written. This may be set to NULL if performing 139 * a presence check. 140 * 141 * @retval OT_ERROR_NONE The given setting was found and fetched successfully. 142 * @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store. 143 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 144 */ 145 otError otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, uint8_t *aValue, uint16_t *aValueLength); 146 147 /** 148 * Sets or replaces the value of a setting. 149 * 150 * This function sets or replaces the value of a setting 151 * identified by @p aKey. 152 * 153 * Calling this function successfully may cause unrelated 154 * settings with multiple values to be reordered. 155 * 156 * OpenThread stack guarantees to use `otPlatSettingsSet()` 157 * method for a @p aKey that was either previously set using 158 * `otPlatSettingsSet()` (i.e., contains a single value) or 159 * is empty and/or fully deleted (contains no value). 160 * 161 * Platform layer can rely and use this fact for optimizing 162 * its implementation. 163 * 164 * @param[in] aInstance The OpenThread instance structure. 165 * @param[in] aKey The key associated with the setting to change. 166 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL if 167 * @p aValueLength is non-zero. 168 * @param[in] aValueLength The length of the data pointed to by aValue. May be zero. 169 * 170 * @retval OT_ERROR_NONE The given setting was changed or staged. 171 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 172 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 173 */ 174 otError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 175 176 /** 177 * Adds a value to a setting. 178 * 179 * This function adds the value to a setting 180 * identified by @p aKey, without replacing any existing 181 * values. 182 * 183 * Note that the underlying implementation is not required 184 * to maintain the order of the items associated with a 185 * specific key. The added value may be added to the end, 186 * the beginning, or even somewhere in the middle. The order 187 * of any pre-existing values may also change. 188 * 189 * Calling this function successfully may cause unrelated 190 * settings with multiple values to be reordered. 191 * 192 * OpenThread stack guarantees to use `otPlatSettingsAdd()` 193 * method for a @p aKey that was either previously managed by 194 * `otPlatSettingsAdd()` (i.e., contains one or more items) or 195 * is empty and/or fully deleted (contains no value). 196 * 197 * Platform layer can rely and use this fact for optimizing 198 * its implementation. 199 * 200 * @param[in] aInstance The OpenThread instance structure. 201 * @param[in] aKey The key associated with the setting to change. 202 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL 203 * if @p aValueLength is non-zero. 204 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 205 * 206 * @retval OT_ERROR_NONE The given setting was added or staged to be added. 207 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 208 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 209 */ 210 otError otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 211 212 /** 213 * Removes a setting from the setting store. 214 * 215 * This function deletes a specific value from the 216 * setting identified by aKey from the settings store. 217 * 218 * Note that the underlying implementation is not required 219 * to maintain the order of the items associated with a 220 * specific key. 221 * 222 * @param[in] aInstance The OpenThread instance structure. 223 * @param[in] aKey The key associated with the requested setting. 224 * @param[in] aIndex The index of the value to be removed. If set to -1, all values for this @p aKey will be 225 * removed. 226 * 227 * @retval OT_ERROR_NONE The given key and index was found and removed successfully. 228 * @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store. 229 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 230 */ 231 otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex); 232 233 /** 234 * Removes all settings from the setting store. 235 * 236 * This function deletes all settings from the settings 237 * store, resetting it to its initial factory state. 238 * 239 * @param[in] aInstance The OpenThread instance structure. 240 */ 241 void otPlatSettingsWipe(otInstance *aInstance); 242 243 /** 244 * @} 245 * 246 */ 247 248 #ifdef __cplusplus 249 } // extern "C" 250 #endif 251 252 #endif // OPENTHREAD_PLATFORM_SETTINGS_H_ 253