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  *   This file includes definitions for IPv6 datagram filtering.
32  */
33 
34 #ifndef IP6_FILTER_HPP_
35 #define IP6_FILTER_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #include "common/array.hpp"
40 #include "common/locator.hpp"
41 #include "common/message.hpp"
42 #include "common/non_copyable.hpp"
43 
44 namespace ot {
45 namespace Ip6 {
46 
47 /**
48  * @addtogroup core-ipv6
49  *
50  * @brief
51  *   This module includes definitions for IPv6 datagram filtering.
52  *
53  * @{
54  *
55  */
56 
57 /**
58  * This class implements an IPv6 datagram filter.
59  *
60  */
61 class Filter : public InstanceLocator, private NonCopyable
62 {
63 public:
64     /**
65      * This constructor initializes the Filter object.
66      *
67      * @param[in]  aInstance  A reference to the OpenThread instance.
68      *
69      */
Filter(Instance & aInstance)70     explicit Filter(Instance &aInstance)
71         : InstanceLocator(aInstance)
72     {
73     }
74 
75     /**
76      * This method indicates whether or not the IPv6 datagram passes the filter.
77      *
78      * @param[in]  aMessage  The IPv6 datagram to process.
79      *
80      * @retval TRUE   Accept the IPv6 datagram.
81      * @retval FALSE  Reject the IPv6 datagram.
82      *
83      */
84     bool Accept(Message &aMessage) const;
85 
86     /**
87      * This method adds a port to the allowed unsecured port list.
88      *
89      * @param[in]  aPort  The port value.
90      *
91      * @retval kErrorNone         The port was successfully added to the allowed unsecure port list.
92      * @retval kErrorInvalidArgs  The port is invalid (value 0 is reserved for internal use).
93      * @retval kErrorNoBufs       The unsecure port list is full.
94      *
95      */
AddUnsecurePort(uint16_t aPort)96     Error AddUnsecurePort(uint16_t aPort) { return UpdateUnsecurePorts(kAdd, aPort); }
97 
98     /**
99      * This method removes a port from the allowed unsecure port list.
100      *
101      * @param[in]  aPort  The port value.
102      *
103      * @retval kErrorNone         The port was successfully removed from the allowed unsecure port list.
104      * @retval kErrorInvalidArgs  The port is invalid (value 0 is reserved for internal use).
105      * @retval kErrorNotFound     The port was not found in the unsecure port list.
106      *
107      */
RemoveUnsecurePort(uint16_t aPort)108     Error RemoveUnsecurePort(uint16_t aPort) { return UpdateUnsecurePorts(kRemove, aPort); }
109 
110     /**
111      * This method checks whether a port is in the unsecure port list.
112      *
113      * @param[in]  aPort  The port value.
114      *
115      * @returns Whether the given port is in the unsecure port list.
116      *
117      */
IsUnsecurePort(uint16_t aPort)118     bool IsUnsecurePort(uint16_t aPort) { return mUnsecurePorts.Contains(aPort); }
119 
120     /**
121      * This method removes all ports from the allowed unsecure port list.
122      *
123      */
RemoveAllUnsecurePorts(void)124     void RemoveAllUnsecurePorts(void) { mUnsecurePorts.Clear(); }
125 
126     /**
127      * This method returns a pointer to the unsecure port list.
128      *
129      * @note Port value 0 is used to indicate an invalid entry.
130      *
131      * @param[out]  aNumEntries  The number of entries in the list.
132      *
133      * @returns A pointer to the unsecure port list.
134      *
135      */
GetUnsecurePorts(uint8_t & aNumEntries) const136     const uint16_t *GetUnsecurePorts(uint8_t &aNumEntries) const
137     {
138         aNumEntries = mUnsecurePorts.GetLength();
139 
140         return &mUnsecurePorts[0];
141     }
142 
143 private:
144     static constexpr uint16_t kMaxUnsecurePorts = 2;
145 
146     enum Action : uint8_t
147     {
148         kAdd,
149         kRemove,
150     };
151 
152     Error UpdateUnsecurePorts(Action aAction, uint16_t aPort);
153 
154     Array<uint16_t, kMaxUnsecurePorts> mUnsecurePorts;
155 };
156 
157 } // namespace Ip6
158 } // namespace ot
159 
160 #endif // IP6_FILTER_HPP_
161