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