1 /* 2 * Copyright (c) 2017, 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 * This file includes definitions for IEEE 802.15.4 frame filtering based on MAC address. 32 */ 33 34 #ifndef MAC_FILTER_HPP_ 35 #define MAC_FILTER_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #if OPENTHREAD_CONFIG_MAC_FILTER_ENABLE 40 41 #include <stdint.h> 42 43 #include "common/as_core_type.hpp" 44 #include "common/const_cast.hpp" 45 #include "common/non_copyable.hpp" 46 #include "mac/mac_frame.hpp" 47 48 namespace ot { 49 50 class Neighbor; 51 52 namespace Mac { 53 54 /** 55 * @addtogroup core-mac 56 * 57 * @{ 58 * 59 */ 60 61 /** 62 * Implements Mac Filter on IEEE 802.15.4 frames. 63 * 64 */ 65 class Filter : private NonCopyable 66 { 67 public: 68 /** 69 * Represents a Mac Filter entry (used during iteration). 70 * 71 */ 72 typedef otMacFilterEntry Entry; 73 74 /** 75 * Represents an iterator used to iterate through filter entries. 76 * 77 * See `GetNextAddress()` and `GetNextRssIn()`. 78 * 79 */ 80 typedef otMacFilterIterator Iterator; 81 82 /** 83 * Type represents the MAC Filter mode. 84 * 85 */ 86 enum Mode : uint8_t 87 { 88 kModeRssInOnly = OT_MAC_FILTER_ADDRESS_MODE_DISABLED, ///< No address filtering. RSS-In update only. 89 kModeAllowlist = OT_MAC_FILTER_ADDRESS_MODE_ALLOWLIST, ///< Enable allowlist address filter mode. 90 kModeDenylist = OT_MAC_FILTER_ADDRESS_MODE_DENYLIST, ///< Enable denylist address filter mode. 91 }; 92 93 static constexpr int8_t kFixedRssDisabled = OT_MAC_FILTER_FIXED_RSS_DISABLED; ///< Value when no fixed RSS is set. 94 95 /** 96 * Initializes the filter. 97 * 98 */ 99 Filter(void); 100 101 /** 102 * Gets the MAC Filter mode. 103 * 104 * @returns the Filter mode. 105 * 106 */ GetMode(void) const107 Mode GetMode(void) const { return mMode; } 108 109 /** 110 * Sets the address mode of the filter. 111 * 112 * @param[in] aMode The new Filter mode. 113 * 114 */ SetMode(Mode aMode)115 void SetMode(Mode aMode) { mMode = aMode; } 116 117 /** 118 * Adds an Extended Address to filter. 119 * 120 * @param[in] aExtAddress A reference to the Extended Address. 121 * 122 * @retval kErrorNone Successfully added @p aExtAddress to the filter. 123 * @retval kErrorNoBufs No available entry exists. 124 * 125 */ 126 Error AddAddress(const ExtAddress &aExtAddress); 127 128 /** 129 * Removes an Extended Address from the filter. 130 * 131 * No action is performed if there is no existing entry in the filter list matching the given Extended Address. 132 * 133 * @param[in] aExtAddress A reference to the Extended Address to remove. 134 * 135 */ 136 void RemoveAddress(const ExtAddress &aExtAddress); 137 138 /** 139 * Clears all Extended Addresses from the filter. 140 * 141 */ 142 void ClearAddresses(void); 143 144 /** 145 * Iterates through filter entries. 146 * 147 * @param[in,out] aIterator A reference to the MAC filter iterator context. 148 * To get the first in-use address filter, set it to OT_MAC_FILTER_ITERATOR_INIT. 149 * @param[out] aEntry A reference to where the information is placed. 150 * 151 * @retval kErrorNone Successfully retrieved the next address filter entry. 152 * @retval kErrorNotFound No subsequent entry exists. 153 * 154 */ 155 Error GetNextAddress(Iterator &aIterator, Entry &aEntry) const; 156 157 /** 158 * Adds a fixed received signal strength entry for the messages from a given Extended Address. 159 * 160 * @param[in] aExtAddress An Extended Address 161 * @param[in] aRss The received signal strength to set. 162 * 163 * @retval kErrorNone Successfully set @p aRss for @p aExtAddress. 164 * @retval kErrorNoBufs No available entry exists. 165 * 166 */ 167 Error AddRssIn(const ExtAddress &aExtAddress, int8_t aRss); 168 169 /** 170 * Removes a fixed received signal strength entry for a given Extended Address. 171 * 172 * No action is performed if there is no existing entry in the filter list matching the given Extended Address. 173 * 174 * @param[in] aExtAddress A Extended Address. 175 * 176 */ 177 void RemoveRssIn(const ExtAddress &aExtAddress); 178 179 /** 180 * Sets the default received signal strength. 181 * 182 * The default RSS value is used for all received frames from addresses for which there is no explicit RSS-IN entry 183 * in the Filter list (added using `AddRssIn()`). 184 * 185 * @param[in] aRss The default received signal strength to set. 186 * 187 */ SetDefaultRssIn(int8_t aRss)188 void SetDefaultRssIn(int8_t aRss) { mDefaultRssIn = aRss; } 189 190 /** 191 * Clears the default received signal strength. 192 * 193 */ ClearDefaultRssIn(void)194 void ClearDefaultRssIn(void) { mDefaultRssIn = kFixedRssDisabled; } 195 196 /** 197 * Clears all the received signal strength settings (including the default RSS-In). 198 * 199 */ 200 void ClearAllRssIn(void); 201 202 /** 203 * Iterates through RssIn filter entry. 204 * 205 * @param[in,out] aIterator A reference to the MAC filter iterator context. To get the first in-use RssIn 206 * filter entry, it should be set to OT_MAC_FILTER_ITERATOR_INIT. 207 * @param[out] aEntry A reference to where the information is placed. The last entry would have the 208 * Extended Address as all 0xff to indicate the default received signal strength 209 * if it was set. 210 * 211 * @retval kErrorNone Successfully retrieved the next RssIn filter entry. 212 * @retval kErrorNotFound No subsequent entry exists. 213 * 214 */ 215 Error GetNextRssIn(Iterator &aIterator, Entry &aEntry) const; 216 217 /** 218 * Applies the filter rules on a given Extended Address. 219 * 220 * @param[in] aExtAddress A reference to the Extended Address. 221 * @param[out] aRss A reference to where the received signal strength to be placed. 222 * 223 * @retval kErrorNone Successfully applied the filter rules on @p aExtAddress. 224 * @retval kErrorAddressFiltered Address filter (allowlist or denylist) is enabled and @p aExtAddress is filtered. 225 * 226 */ 227 Error Apply(const ExtAddress &aExtAddress, int8_t &aRss) const; 228 229 /** 230 * Applies the filter rules to a received frame from a given Extended Address. 231 * 232 * Can potentially update the signal strength value on the received frame @p aRxFrame. If @p aNeighbor 233 * is not `nullptr` and filter applies a fixed RSS to the @p aRxFrame, this method will also clear the current RSS 234 * average on @p aNeighbor to ensure that the new fixed RSS takes effect quickly. 235 * 236 * @param[out] aRxFrame The received frame. 237 * @param[in] aExtAddress The extended address from which @p aRxFrame was received. 238 * @param[in] aNeighbor A pointer to the neighbor (can be `nullptr` if not known). 239 * 240 * @retval kErrorNone Successfully applied the filter, @p aRxFrame RSS may be updated. 241 * @retval kErrorAddressFiltered Address filter (allowlist or denylist) is enabled and @p aExtAddress is filtered. 242 * 243 */ 244 Error ApplyToRxFrame(RxFrame &aRxFrame, const ExtAddress &aExtAddress, Neighbor *aNeighbor = nullptr) const; 245 246 private: 247 static constexpr uint16_t kMaxEntries = OPENTHREAD_CONFIG_MAC_FILTER_SIZE; 248 249 struct FilterEntry 250 { 251 bool mFiltered; // Indicates whether or not this entry is filtered (allowlist/denylist modes). 252 int8_t mRssIn; // The RssIn value for this entry or `kFixedRssDisabled`. 253 ExtAddress mExtAddress; // IEEE 802.15.4 Extended Address. 254 IsInUseot::Mac::Filter::FilterEntry255 bool IsInUse(void) const { return mFiltered || (mRssIn != kFixedRssDisabled); } 256 }; 257 258 FilterEntry *FindAvailableEntry(void); 259 const FilterEntry *FindEntry(const ExtAddress &aExtAddress) const; FindEntry(const ExtAddress & aExtAddress)260 FilterEntry *FindEntry(const ExtAddress &aExtAddress) { return AsNonConst(AsConst(this)->FindEntry(aExtAddress)); } 261 262 Mode mMode; 263 int8_t mDefaultRssIn; 264 FilterEntry mFilterEntries[kMaxEntries]; 265 }; 266 267 /** 268 * @} 269 * 270 */ 271 272 } // namespace Mac 273 274 DefineMapEnum(otMacFilterAddressMode, Mac::Filter::Mode); 275 276 } // namespace ot 277 278 #endif // OPENTHREAD_CONFIG_MAC_FILTER_ENABLE 279 280 #endif // MAC_FILTER_HPP_ 281