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 * Defines the keys of settings. 55 * 56 * Note: When adding a new settings key, if the settings corresponding to the key contains security sensitive 57 * information, the developer MUST add the key to the array `aSensitiveKeys` which is passed in 58 * `otPlatSettingsInit()`. 59 */ 60 enum 61 { 62 OT_SETTINGS_KEY_ACTIVE_DATASET = 0x0001, ///< Active Operational Dataset. 63 OT_SETTINGS_KEY_PENDING_DATASET = 0x0002, ///< Pending Operational Dataset. 64 OT_SETTINGS_KEY_NETWORK_INFO = 0x0003, ///< Thread network information. 65 OT_SETTINGS_KEY_PARENT_INFO = 0x0004, ///< Parent information. 66 OT_SETTINGS_KEY_CHILD_INFO = 0x0005, ///< Child information. 67 OT_SETTINGS_KEY_SLAAC_IID_SECRET_KEY = 0x0007, ///< SLAAC key to generate semantically opaque IID. 68 OT_SETTINGS_KEY_DAD_INFO = 0x0008, ///< Duplicate Address Detection (DAD) information. 69 OT_SETTINGS_KEY_SRP_ECDSA_KEY = 0x000b, ///< SRP client ECDSA public/private key pair. 70 OT_SETTINGS_KEY_SRP_CLIENT_INFO = 0x000c, ///< The SRP client info (selected SRP server address). 71 OT_SETTINGS_KEY_SRP_SERVER_INFO = 0x000d, ///< The SRP server info (UDP port). 72 OT_SETTINGS_KEY_BR_ULA_PREFIX = 0x000f, ///< BR ULA prefix. 73 OT_SETTINGS_KEY_BR_ON_LINK_PREFIXES = 0x0010, ///< BR local on-link prefixes. 74 OT_SETTINGS_KEY_BORDER_AGENT_ID = 0x0011, ///< Unique Border Agent/Router ID. 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 * 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 void otPlatSettingsInit(otInstance *aInstance, const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength); 101 102 /** 103 * Performs any de-initialization for the settings subsystem, if necessary. 104 * 105 * @param[in] aInstance The OpenThread instance structure. 106 */ 107 void otPlatSettingsDeinit(otInstance *aInstance); 108 109 /** 110 * Fetches the value of a setting. 111 * 112 * Fetches the value of the setting identified 113 * by @p aKey and write it to the memory pointed to by aValue. 114 * It then writes the length to the integer pointed to by 115 * @p aValueLength. The initial value of @p aValueLength is the 116 * maximum number of bytes to be written to @p aValue. 117 * 118 * Can be used to check for the existence of 119 * a key without fetching the value by setting @p aValue and 120 * @p aValueLength to NULL. You can also check the length of 121 * the setting without fetching it by setting only aValue 122 * to NULL. 123 * 124 * Note that the underlying storage implementation is not 125 * required to maintain the order of settings with multiple 126 * values. The order of such values MAY change after ANY 127 * write operation to the store. 128 * 129 * @param[in] aInstance The OpenThread instance structure. 130 * @param[in] aKey The key associated with the requested setting. 131 * @param[in] aIndex The index of the specific item to get. 132 * @param[out] aValue A pointer to where the value of the setting should be written. May be set to NULL if 133 * just testing for the presence or length of a setting. 134 * @param[in,out] aValueLength A pointer to the length of the value. When called, this pointer should point to an 135 * integer containing the maximum value size that can be written to @p aValue. At return, 136 * the actual length of the setting is written. This may be set to NULL if performing 137 * a presence check. 138 * 139 * @retval OT_ERROR_NONE The given setting was found and fetched successfully. 140 * @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store. 141 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 142 */ 143 otError otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, uint8_t *aValue, uint16_t *aValueLength); 144 145 /** 146 * Sets or replaces the value of a setting. 147 * 148 * Sets or replaces the value of a setting 149 * identified by @p aKey. 150 * 151 * Calling this function successfully may cause unrelated 152 * settings with multiple values to be reordered. 153 * 154 * OpenThread stack guarantees to use `otPlatSettingsSet()` 155 * method for a @p aKey that was either previously set using 156 * `otPlatSettingsSet()` (i.e., contains a single value) or 157 * is empty and/or fully deleted (contains no value). 158 * 159 * Platform layer can rely and use this fact for optimizing 160 * its implementation. 161 * 162 * @param[in] aInstance The OpenThread instance structure. 163 * @param[in] aKey The key associated with the setting to change. 164 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL if 165 * @p aValueLength is non-zero. 166 * @param[in] aValueLength The length of the data pointed to by aValue. May be zero. 167 * 168 * @retval OT_ERROR_NONE The given setting was changed or staged. 169 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 170 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 171 */ 172 otError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 173 174 /** 175 * Adds a value to a setting. 176 * 177 * Adds the value to a setting 178 * identified by @p aKey, without replacing any existing 179 * values. 180 * 181 * Note that the underlying implementation is not required 182 * to maintain the order of the items associated with a 183 * specific key. The added value may be added to the end, 184 * the beginning, or even somewhere in the middle. The order 185 * of any pre-existing values may also change. 186 * 187 * Calling this function successfully may cause unrelated 188 * settings with multiple values to be reordered. 189 * 190 * OpenThread stack guarantees to use `otPlatSettingsAdd()` 191 * method for a @p aKey that was either previously managed by 192 * `otPlatSettingsAdd()` (i.e., contains one or more items) or 193 * is empty and/or fully deleted (contains no value). 194 * 195 * Platform layer can rely and use this fact for optimizing 196 * its implementation. 197 * 198 * @param[in] aInstance The OpenThread instance structure. 199 * @param[in] aKey The key associated with the setting to change. 200 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL 201 * if @p aValueLength is non-zero. 202 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 203 * 204 * @retval OT_ERROR_NONE The given setting was added or staged to be added. 205 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 206 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 207 */ 208 otError otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 209 210 /** 211 * Removes a setting from the setting store. 212 * 213 * Deletes a specific value from the 214 * setting identified by aKey from the settings store. 215 * 216 * Note that the underlying implementation is not required 217 * to maintain the order of the items associated with a 218 * specific key. 219 * 220 * @param[in] aInstance The OpenThread instance structure. 221 * @param[in] aKey The key associated with the requested setting. 222 * @param[in] aIndex The index of the value to be removed. If set to -1, all values for this @p aKey will be 223 * removed. 224 * 225 * @retval OT_ERROR_NONE The given key and index was found and removed successfully. 226 * @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store. 227 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 228 */ 229 otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex); 230 231 /** 232 * Removes all settings from the setting store. 233 * 234 * Deletes all settings from the settings 235 * store, resetting it to its initial factory state. 236 * 237 * @param[in] aInstance The OpenThread instance structure. 238 */ 239 void otPlatSettingsWipe(otInstance *aInstance); 240 241 /** 242 * @} 243 */ 244 245 #ifdef __cplusplus 246 } // extern "C" 247 #endif 248 249 #endif // OPENTHREAD_PLATFORM_SETTINGS_H_ 250
