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