1 /*
2  *  Copyright (c) 2020, 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 managing Domain Unicast Address feature defined in Thread 1.2.
32  */
33 
34 #ifndef DUA_MANAGER_HPP_
35 #define DUA_MANAGER_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #if OPENTHREAD_CONFIG_DUA_ENABLE || (OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE)
40 
41 #if OPENTHREAD_CONFIG_DUA_ENABLE && (OPENTHREAD_CONFIG_THREAD_VERSION < OT_THREAD_VERSION_1_2)
42 #error "Thread 1.2 or higher version is required for OPENTHREAD_CONFIG_DUA_ENABLE"
43 #endif
44 
45 #if OPENTHREAD_CONFIG_DUA_ENABLE && !OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE
46 #error "OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE is required for OPENTHREAD_CONFIG_DUA_ENABLE"
47 #endif
48 
49 #include "backbone_router/bbr_leader.hpp"
50 #include "coap/coap_message.hpp"
51 #include "common/locator.hpp"
52 #include "common/non_copyable.hpp"
53 #include "common/notifier.hpp"
54 #include "common/tasklet.hpp"
55 #include "common/time.hpp"
56 #include "common/time_ticker.hpp"
57 #include "common/timer.hpp"
58 #include "net/netif.hpp"
59 #include "thread/child.hpp"
60 #include "thread/thread_tlvs.hpp"
61 #include "thread/tmf.hpp"
62 
63 namespace ot {
64 
65 /**
66  * @addtogroup core-dua
67  *
68  * @brief
69  *   This module includes definitions for generating, managing, registering Domain Unicast Address.
70  *
71  * @{
72  *
73  * @defgroup core-dua Dua
74  *
75  * @}
76  *
77  */
78 
79 /**
80  * Implements managing DUA.
81  *
82  */
83 class DuaManager : public InstanceLocator, private NonCopyable
84 {
85     friend class ot::Notifier;
86     friend class ot::TimeTicker;
87     friend class Tmf::Agent;
88 
89 public:
90     /**
91      * Initializes the object.
92      *
93      * @param[in]  aInstance     A reference to the OpenThread instance.
94      *
95      */
96     explicit DuaManager(Instance &aInstance);
97 
98     /**
99      * Notifies Domain Prefix changes.
100      *
101      * @param[in]  aEvent  The Domain Prefix event.
102      *
103      */
104     void HandleDomainPrefixUpdate(BackboneRouter::DomainPrefixEvent aEvent);
105 
106     /**
107      * Notifies Primary Backbone Router status.
108      *
109      * @param[in]  aState   The state or state change of Primary Backbone Router.
110      * @param[in]  aConfig  The Primary Backbone Router service.
111      *
112      */
113     void HandleBackboneRouterPrimaryUpdate(BackboneRouter::Leader::State aState, const BackboneRouter::Config &aConfig);
114 
115 #if OPENTHREAD_CONFIG_DUA_ENABLE
116 
117     /**
118      * Returns a reference to the Domain Unicast Address.
119      *
120      * @returns A reference to the Domain Unicast Address.
121      *
122      */
GetDomainUnicastAddress(void) const123     const Ip6::Address &GetDomainUnicastAddress(void) const { return mDomainUnicastAddress.GetAddress(); }
124 
125     /**
126      * Sets the Interface Identifier manually specified for the Thread Domain Unicast Address.
127      *
128      * @param[in]  aIid        A reference to the Interface Identifier to set.
129      *
130      * @retval kErrorNone          Successfully set the Interface Identifier.
131      * @retval kErrorInvalidArgs   The specified Interface Identifier is reserved.
132      *
133      */
134     Error SetFixedDuaInterfaceIdentifier(const Ip6::InterfaceIdentifier &aIid);
135 
136     /**
137      * Clears the Interface Identifier manually specified for the Thread Domain Unicast Address.
138      *
139      */
140     void ClearFixedDuaInterfaceIdentifier(void);
141 
142     /**
143      * Indicates whether or not there is Interface Identifier manually specified for the Thread
144      * Domain Unicast Address.
145      *
146      * @retval true  If there is Interface Identifier manually specified.
147      * @retval false If there is no Interface Identifier manually specified.
148      *
149      */
IsFixedDuaInterfaceIdentifierSet(void)150     bool IsFixedDuaInterfaceIdentifierSet(void) { return !mFixedDuaInterfaceIdentifier.IsUnspecified(); }
151 
152     /**
153      * Gets the Interface Identifier for the Thread Domain Unicast Address if manually specified.
154      *
155      * @returns A reference to the Interface Identifier.
156      *
157      */
GetFixedDuaInterfaceIdentifier(void) const158     const Ip6::InterfaceIdentifier &GetFixedDuaInterfaceIdentifier(void) const { return mFixedDuaInterfaceIdentifier; }
159 
160     /*
161      * Restores duplicate address detection information from non-volatile memory.
162      *
163      */
164     void Restore(void);
165 
166     /**
167      * Notifies duplicated Domain Unicast Address.
168      *
169      */
170     void NotifyDuplicateDomainUnicastAddress(void);
171 #endif
172 
173 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE
174     /**
175      * Events related to a Child DUA address.
176      *
177      */
178     enum ChildDuaAddressEvent : uint8_t
179     {
180         kAddressAdded,     ///< A new DUA registered by the Child via Address Registration.
181         kAddressChanged,   ///< A different DUA registered by the Child via Address Registration.
182         kAddressRemoved,   ///< DUA registered by the Child is removed and not in Address Registration.
183         kAddressUnchanged, ///< The Child registers the same DUA again.
184     };
185 
186     /**
187      * Handles Child DUA address event.
188      *
189      * @param[in] aChild   A child.
190      * @param[in] aEvent   The DUA address event for @p aChild.
191      *
192      */
193     void HandleChildDuaAddressEvent(const Child &aChild, ChildDuaAddressEvent aEvent);
194 #endif
195 
196 private:
197     static constexpr uint32_t kDuaDadPeriod               = 100; // DAD wait time to become "Preferred" (in sec).
198     static constexpr uint8_t  kNoBufDelay                 = 5;   // In sec.
199     static constexpr uint8_t  KResponseTimeoutDelay       = 30;  // In sec.
200     static constexpr uint8_t  kNewRouterRegistrationDelay = 3;   // Delay (in sec) to establish link for a new router.
201     static constexpr uint8_t  kNewDuaRegistrationDelay    = 1;   // Delay (in sec) for newly added DUA.
202 
203 #if OPENTHREAD_CONFIG_DUA_ENABLE
204     Error GenerateDomainUnicastAddressIid(void);
205     Error Store(void);
206 
207     void AddDomainUnicastAddress(void);
208     void RemoveDomainUnicastAddress(void);
209     void UpdateRegistrationDelay(uint8_t aDelay);
210 #endif
211 
212 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE
213     void SendAddressNotification(Ip6::Address &aAddress, ThreadStatusTlv::DuaStatus aStatus, const Child &aChild);
214 #endif
215 
216     void HandleNotifierEvents(Events aEvents);
217 
218     void HandleTimeTick(void);
219 
220     void UpdateTimeTickerRegistration(void);
221 
222     static void HandleDuaResponse(void                *aContext,
223                                   otMessage           *aMessage,
224                                   const otMessageInfo *aMessageInfo,
225                                   Error                aResult);
226     void        HandleDuaResponse(Coap::Message *aMessage, const Ip6::MessageInfo *aMessageInfo, Error aResult);
227 
228     template <Uri kUri> void HandleTmf(Coap::Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
229 
230     Error ProcessDuaResponse(Coap::Message &aMessage);
231 
232     void PerformNextRegistration(void);
233     void UpdateReregistrationDelay(void);
234     void UpdateCheckDelay(uint8_t aDelay);
235 
236     using RegistrationTask = TaskletIn<DuaManager, &DuaManager::PerformNextRegistration>;
237 
238     RegistrationTask mRegistrationTask;
239     Ip6::Address     mRegisteringDua;
240     bool             mIsDuaPending : 1;
241 
242 #if OPENTHREAD_CONFIG_DUA_ENABLE
243     enum DuaState : uint8_t
244     {
245         kNotExist,    ///< DUA is not available.
246         kToRegister,  ///< DUA is to be registered.
247         kRegistering, ///< DUA is being registered.
248         kRegistered,  ///< DUA is registered.
249     };
250 
251     DuaState  mDuaState;
252     uint8_t   mDadCounter;
253     TimeMilli mLastRegistrationTime; // The time (in milliseconds) when sent last DUA.req or received DUA.rsp.
254     Ip6::InterfaceIdentifier   mFixedDuaInterfaceIdentifier;
255     Ip6::Netif::UnicastAddress mDomainUnicastAddress;
256 #endif
257 
258     union
259     {
260         struct
261         {
262             uint16_t mReregistrationDelay; // Delay (in seconds) for DUA re-registration.
263             uint8_t  mCheckDelay;          // Delay (in seconds) for checking whether or not registration is required.
264 #if OPENTHREAD_CONFIG_DUA_ENABLE
265             uint8_t mRegistrationDelay; // Delay (in seconds) for DUA registration.
266 #endif
267         } mFields;
268         uint32_t mValue; // Non-zero indicates timer should start.
269     } mDelay;
270 
271 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE
272     // TODO: (DUA) may re-evaluate the alternative option of distributing the flags into the child table:
273     //       - Child class itself have some padding - may save some RAM
274     //       - Avoid cross reference between a bit-vector and the child entry
275     ChildMask mChildDuaMask;             // Child Mask for child who registers DUA via Child Update Request.
276     ChildMask mChildDuaRegisteredMask;   // Child Mask for child's DUA that was registered by the parent on behalf.
277     uint16_t  mChildIndexDuaRegistering; // Child Index of the DUA being registered.
278 #endif
279 };
280 
281 DeclareTmfHandler(DuaManager, kUriDuaRegistrationNotify);
282 
283 } // namespace ot
284 
285 #endif // OPENTHREAD_CONFIG_DUA_ENABLE || (OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE)
286 #endif // DUA_MANAGER_HPP_
287