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