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 OT_SETTINGS_KEY_BR_ON_LINK_PREFIXES = 0x0010, ///< BR local on-link prefixes. 76 OT_SETTINGS_KEY_BORDER_AGENT_ID = 0x0011, ///< Unique Border Agent/Router ID. 77 78 // Deprecated and reserved key values: 79 // 80 // 0x0006 previously auto-start. 81 // 0x0009 previously OMR prefix. 82 // 0x000a previously on-link prefix. 83 // 0x000e previously NAT64 prefix. 84 85 // Keys in range 0x8000-0xffff are reserved for vendor-specific use. 86 OT_SETTINGS_KEY_VENDOR_RESERVED_MIN = 0x8000, 87 OT_SETTINGS_KEY_VENDOR_RESERVED_MAX = 0xffff, 88 }; 89 90 /** 91 * Performs any initialization for the settings subsystem, if necessary. 92 * 93 * This function also sets the sensitive keys that should be stored in the secure area. 94 * 95 * Note that the memory pointed by @p aSensitiveKeys MUST not be released before @p aInstance is destroyed. 96 * 97 * @param[in] aInstance The OpenThread instance structure. 98 * @param[in] aSensitiveKeys A pointer to an array containing the list of sensitive keys. May be NULL only if 99 * @p aSensitiveKeysLength is 0, which means that there is no sensitive keys. 100 * @param[in] aSensitiveKeysLength The number of entries in the @p aSensitiveKeys array. 101 * 102 */ 103 void otPlatSettingsInit(otInstance *aInstance, const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength); 104 105 /** 106 * Performs any de-initialization for the settings subsystem, if necessary. 107 * 108 * @param[in] aInstance The OpenThread instance structure. 109 * 110 */ 111 void otPlatSettingsDeinit(otInstance *aInstance); 112 113 /** 114 * Fetches the value of a setting. 115 * 116 * This function fetches the value of the setting identified 117 * by @p aKey and write it to the memory pointed to by aValue. 118 * It then writes the length to the integer pointed to by 119 * @p aValueLength. The initial value of @p aValueLength is the 120 * maximum number of bytes to be written to @p aValue. 121 * 122 * This function can be used to check for the existence of 123 * a key without fetching the value by setting @p aValue and 124 * @p aValueLength to NULL. You can also check the length of 125 * the setting without fetching it by setting only aValue 126 * to NULL. 127 * 128 * Note that the underlying storage implementation is not 129 * required to maintain the order of settings with multiple 130 * values. The order of such values MAY change after ANY 131 * write operation to the store. 132 * 133 * @param[in] aInstance The OpenThread instance structure. 134 * @param[in] aKey The key associated with the requested setting. 135 * @param[in] aIndex The index of the specific item to get. 136 * @param[out] aValue A pointer to where the value of the setting should be written. May be set to NULL if 137 * just testing for the presence or length of a setting. 138 * @param[in,out] aValueLength A pointer to the length of the value. When called, this pointer should point to an 139 * integer containing the maximum value size that can be written to @p aValue. At return, 140 * the actual length of the setting is written. This may be set to NULL if performing 141 * a presence check. 142 * 143 * @retval OT_ERROR_NONE The given setting was found and fetched successfully. 144 * @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store. 145 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 146 */ 147 otError otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, uint8_t *aValue, uint16_t *aValueLength); 148 149 /** 150 * Sets or replaces the value of a setting. 151 * 152 * This function sets or replaces the value of a setting 153 * identified by @p aKey. 154 * 155 * Calling this function successfully may cause unrelated 156 * settings with multiple values to be reordered. 157 * 158 * OpenThread stack guarantees to use `otPlatSettingsSet()` 159 * method for a @p aKey that was either previously set using 160 * `otPlatSettingsSet()` (i.e., contains a single value) or 161 * is empty and/or fully deleted (contains no value). 162 * 163 * Platform layer can rely and use this fact for optimizing 164 * its implementation. 165 * 166 * @param[in] aInstance The OpenThread instance structure. 167 * @param[in] aKey The key associated with the setting to change. 168 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL if 169 * @p aValueLength is non-zero. 170 * @param[in] aValueLength The length of the data pointed to by aValue. May be zero. 171 * 172 * @retval OT_ERROR_NONE The given setting was changed or staged. 173 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 174 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 175 */ 176 otError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 177 178 /** 179 * Adds a value to a setting. 180 * 181 * This function adds the value to a setting 182 * identified by @p aKey, without replacing any existing 183 * values. 184 * 185 * Note that the underlying implementation is not required 186 * to maintain the order of the items associated with a 187 * specific key. The added value may be added to the end, 188 * the beginning, or even somewhere in the middle. The order 189 * of any pre-existing values may also change. 190 * 191 * Calling this function successfully may cause unrelated 192 * settings with multiple values to be reordered. 193 * 194 * OpenThread stack guarantees to use `otPlatSettingsAdd()` 195 * method for a @p aKey that was either previously managed by 196 * `otPlatSettingsAdd()` (i.e., contains one or more items) or 197 * is empty and/or fully deleted (contains no value). 198 * 199 * Platform layer can rely and use this fact for optimizing 200 * its implementation. 201 * 202 * @param[in] aInstance The OpenThread instance structure. 203 * @param[in] aKey The key associated with the setting to change. 204 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL 205 * if @p aValueLength is non-zero. 206 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 207 * 208 * @retval OT_ERROR_NONE The given setting was added or staged to be added. 209 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 210 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 211 */ 212 otError otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 213 214 /** 215 * Removes a setting from the setting store. 216 * 217 * This function deletes a specific value from the 218 * setting identified by aKey from the settings store. 219 * 220 * Note that the underlying implementation is not required 221 * to maintain the order of the items associated with a 222 * specific key. 223 * 224 * @param[in] aInstance The OpenThread instance structure. 225 * @param[in] aKey The key associated with the requested setting. 226 * @param[in] aIndex The index of the value to be removed. If set to -1, all values for this @p aKey will be 227 * removed. 228 * 229 * @retval OT_ERROR_NONE The given key and index was found and removed successfully. 230 * @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store. 231 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 232 */ 233 otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex); 234 235 /** 236 * Removes all settings from the setting store. 237 * 238 * This function deletes all settings from the settings 239 * store, resetting it to its initial factory state. 240 * 241 * @param[in] aInstance The OpenThread instance structure. 242 */ 243 void otPlatSettingsWipe(otInstance *aInstance); 244 245 /** 246 * @} 247 * 248 */ 249 250 #ifdef __cplusplus 251 } // extern "C" 252 #endif 253 254 #endif // OPENTHREAD_PLATFORM_SETTINGS_H_ 255
