ON Semiconductor / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_comm.md@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
group-onsemi 0:098463de4c5d 1 Commissioning process
group-onsemi 0:098463de4c5d 2 ============
group-onsemi 0:098463de4c5d 3
group-onsemi 0:098463de4c5d 4 The commissioning process has two phases:
group-onsemi 0:098463de4c5d 5
group-onsemi 0:098463de4c5d 6 * Petitioning
group-onsemi 0:098463de4c5d 7 * Joining
group-onsemi 0:098463de4c5d 8
group-onsemi 0:098463de4c5d 9 Petitioning must occur before any joiner can join, that is, there must be one sole authorized commissioner - an authenticator for subsequent joiners.
group-onsemi 0:098463de4c5d 10
group-onsemi 0:098463de4c5d 11 ## Mesh Commissioning Protocol (MeshCoP)
group-onsemi 0:098463de4c5d 12
group-onsemi 0:098463de4c5d 13 The Mesh Commissioning Protocol (MeshCoP) is based on CoAP [RFC 7252](https://tools.ietf.org/html/rfc7252) and performs petitioning, maintenance, management and relay functions. It uses WLAN as an access technology for non-Thread networks whereas within a Thread network it uses the Thread Management Framework.
group-onsemi 0:098463de4c5d 14
group-onsemi 0:098463de4c5d 15 ## Petitioning
group-onsemi 0:098463de4c5d 16
group-onsemi 0:098463de4c5d 17 ### External commissioner candidate
group-onsemi 0:098463de4c5d 18
group-onsemi 0:098463de4c5d 19 If a commissioner candidate uses a WLAN network interface for commissioning or exists outside Thread network, it is known as an external commissioner candidate. An external commissioner has to petition the Thread network through a representative (the Border Router) to become the sole authorized commissioner. The commissioner candidate must use an authentication handshake with the Border Router to prove its eligibility to become the sole authorized commissioner and set up a secure commissioning session. The commissioner candidate petitions the Leader via the Border Router. If petitioning succeeds, the commissioner candidate becomes the sole authorized external commissioner. As the secure commissioning session is set up, the representative Border Router will be made known throughout the Thread network and all subsequent communication with other Thread devices will now be done through the Border Router. A periodic keep-alive message is sent on the secure commissioning session to ensure it remains open with the commissioner.
group-onsemi 0:098463de4c5d 20
group-onsemi 0:098463de4c5d 21 **Figure 2-3 External Commissioner Petitioning**
group-onsemi 0:098463de4c5d 22
group-onsemi 0:098463de4c5d 23 ![nw-arc](img/thread_comm_ext.png)
group-onsemi 0:098463de4c5d 24
group-onsemi 0:098463de4c5d 25 * The process starts with the Border Router being aware of the commissioner credential. This can be entered directly into the Border Router device itself or into any trusted Thread device and sent to the Border Router.
group-onsemi 0:098463de4c5d 26
group-onsemi 0:098463de4c5d 27 * After a while, the same commissioner credential will be entered into the commissioner candidate that will initiate the registration process, starting with a DTLS handshake. If the DTLS handshake is successful, the Border Router will authenticate the commissioner candidate based on the information of the shared commissioner credential.
group-onsemi 0:098463de4c5d 28
group-onsemi 0:098463de4c5d 29 * The Border Router will arbitrate with the Leader on behalf of the commissioner candidate to authorize the commissioner candidate to be the sole commissioner and authenticator for subsequent joiners. If there is already an authorized commissioner, the commissioner candidate will be denied authorization.
group-onsemi 0:098463de4c5d 30
group-onsemi 0:098463de4c5d 31 * The authorized commissioner will keep a secure commissioning session open with the Border Router. The session uses the DTLS record layer for encryption and authentication, based on keys derived from the master key established between the commissioner (as the commissioner candidate) and the Border Router as a result of the DTLS handshake. This commissioning session will be used for various purposes and it communicates CoAP messages carrying petitioning, management and relay messages between the commissioner and the Border Router.
group-onsemi 0:098463de4c5d 32
group-onsemi 0:098463de4c5d 33 **Figure 2-4 External Commissioner Petitioning Sequence**
group-onsemi 0:098463de4c5d 34
group-onsemi 0:098463de4c5d 35 ![nw-arc](img/thread_ext_pet_seq.png)
group-onsemi 0:098463de4c5d 36
group-onsemi 0:098463de4c5d 37 ### Native commissioner candidate
group-onsemi 0:098463de4c5d 38
group-onsemi 0:098463de4c5d 39 If the commissioner candidate uses a Thread Network Interface for commissioning, it is known as a native commissioner. A native commissioner has to petition the Thread network through a representative (the Commissioner Router) to become the sole authorized commissioner. The commissioner candidate must use an authentication handshake with the Commissioner Router to prove it is eligible to become the sole authorized commissioner and set up a secure commissioning session. The candidate petitions the Leader via the Commissioner Router. If petitioning succeeds, the commissioner candidate becomes the sole authorized native commissioner. However, the commissioner subsequently joins the Thread network and becomes an active
group-onsemi 0:098463de4c5d 40 device (on-mesh commissioner) and all communication with other Thread devices takes place directly with the commissioner.
group-onsemi 0:098463de4c5d 41
group-onsemi 0:098463de4c5d 42 **Figure 2-5 Native Commissioner Petitioning**
group-onsemi 0:098463de4c5d 43
group-onsemi 0:098463de4c5d 44 ![nw-arc](img/thread_native_comm_pet.png)
group-onsemi 0:098463de4c5d 45
group-onsemi 0:098463de4c5d 46 * The process starts with the Commissioner Router being aware of the commissioner credential. This can be entered directly into the Commissioner Router device itself or into any trusted Thread device and sent to the Commissioner Router.
group-onsemi 0:098463de4c5d 47
group-onsemi 0:098463de4c5d 48 * After a while, the same commissioner credential will be entered into the commissioner candidate and it will initiate the registration process, starting with a DTLS handshake. If the DTLS handshake is successful, the Commissioner Router will authenticate the commissioner candidate based on the information of the shared commissioner credential.
group-onsemi 0:098463de4c5d 49
group-onsemi 0:098463de4c5d 50 * The Commissioner Router will arbitrate with the Leader on behalf of the commissioner candidate to authorize the commissioner candidate to be the sole commissioner and authenticator for subsequent joiners. If there is already an authorized commissioner, the commissioner candidate will be denied authorization.
group-onsemi 0:098463de4c5d 51
group-onsemi 0:098463de4c5d 52 * The authorized commissioner will subsequently join the Thread network and thus be able to communicate directly with all Thread devices.
group-onsemi 0:098463de4c5d 53
group-onsemi 0:098463de4c5d 54 **Figure 2-6 Native Commissioner Petitioning Sequence**
group-onsemi 0:098463de4c5d 55
group-onsemi 0:098463de4c5d 56 ![nw-arc](img/thread_nat_pet_seq.png)
group-onsemi 0:098463de4c5d 57
group-onsemi 0:098463de4c5d 58 ### Petitioning authorization
group-onsemi 0:098463de4c5d 59
group-onsemi 0:098463de4c5d 60 When a Border Router or Commissioner Router receives a petitioning request from the commissioner candidate, the Border Router or Commissioner Router relays the petitioning request to the Leader with the ID of the commissioner candidate. The Leader will respond by accepting or rejecting the request and the Border Router will relay the response accordingly. If the commissioner candidate is external, the Leader will also advertise the Border Router acting on behalf of the commissioner to the rest of the Thread network so any potential Joiner Router knows where to relay the DTLS handshake messages originating by the joiner. In addition, the beacon information will be updated through a notification so all Thread Routers alter their beacon, assisting the steering of the joiner.
group-onsemi 0:098463de4c5d 61
group-onsemi 0:098463de4c5d 62 **Figure 2-7 Petitioning Authorization**
group-onsemi 0:098463de4c5d 63
group-onsemi 0:098463de4c5d 64 ![nw-arc](img/thread_pet_auth_seq.png)
group-onsemi 0:098463de4c5d 65
group-onsemi 0:098463de4c5d 66 ## Joining Process
group-onsemi 0:098463de4c5d 67
group-onsemi 0:098463de4c5d 68 When there is an authorized commissioner associated with the Thread network, Thread devices are allowed to join the Thread network securely. These devices are known as joiners. The actual joining process depends on the system topology that can be identified as one of the following scenarios:
group-onsemi 0:098463de4c5d 69
group-onsemi 0:098463de4c5d 70 * External commissioner is connected via WLAN
group-onsemi 0:098463de4c5d 71 * Border Router is not a Joiner Router
group-onsemi 0:098463de4c5d 72 * Border Router is a Joiner Router
group-onsemi 0:098463de4c5d 73
group-onsemi 0:098463de4c5d 74 * Native commissioner is connected via Thread network
group-onsemi 0:098463de4c5d 75 * Joiner Router is not a commissioner
group-onsemi 0:098463de4c5d 76 * Joiner Router is a commissioner
group-onsemi 0:098463de4c5d 77
group-onsemi 0:098463de4c5d 78
group-onsemi 0:098463de4c5d 79 This implies that the commissioner will be in one of the following states:
group-onsemi 0:098463de4c5d 80
group-onsemi 0:098463de4c5d 81 ### External commissioner
group-onsemi 0:098463de4c5d 82
group-onsemi 0:098463de4c5d 83 In this case, the petitioning process as described in [External commissioner candidate](#external-commissioner-candidate) must have taken place initially to provide a secure commissioning session from Border Router to commissioner bound to the petitioning process. This secure session is then used in the joining process to relay the joining DTLS handshake through to the commissioner. Once the joiner has received the network parameters it needs to attach to the Thread network. This closes the secure commissioning session.
group-onsemi 0:098463de4c5d 84
group-onsemi 0:098463de4c5d 85 **Case 1: Border Router is not a Joiner Router**
group-onsemi 0:098463de4c5d 86
group-onsemi 0:098463de4c5d 87 This is the most complex case out of the four presented scenarios. In this case, there are three separate and distinct paths the authentication traffic (the DTLS handshakes) has to go through:
group-onsemi 0:098463de4c5d 88
group-onsemi 0:098463de4c5d 89 * Joiner to Joiner Router point-to-point
group-onsemi 0:098463de4c5d 90 * Joiner Router to Border Router through Thread network
group-onsemi 0:098463de4c5d 91 * Border Router to commissioner through WLAN
group-onsemi 0:098463de4c5d 92
group-onsemi 0:098463de4c5d 93 These paths are effectively connected to each other and the Joiner Router and Border Router's relay agents and client-server bindings manage the authentication traffic accordingly.
group-onsemi 0:098463de4c5d 94
group-onsemi 0:098463de4c5d 95 **Figure 2-8 External commissioner connected to the WLAN, Border Router is not a Joiner Router**
group-onsemi 0:098463de4c5d 96
group-onsemi 0:098463de4c5d 97 ![nw-arc](img/thread_case1.png)
group-onsemi 0:098463de4c5d 98
group-onsemi 0:098463de4c5d 99 **Case 2: Border Router is a Joiner Router**
group-onsemi 0:098463de4c5d 100
group-onsemi 0:098463de4c5d 101 This case is simpler because there is no need to relay from a Joiner Router to a Border Router. However, the Border Router uses its relay agent to police unauthenticated traffic as a Joiner Router. There are two separate and distinct paths the authentication traffic (the DTLS handshakes) have to go through:
group-onsemi 0:098463de4c5d 102
group-onsemi 0:098463de4c5d 103 * Joiner to Border Router point-to-point.
group-onsemi 0:098463de4c5d 104 * Border Router to commissioner through WLAN.
group-onsemi 0:098463de4c5d 105
group-onsemi 0:098463de4c5d 106 **Figure 2-9 External commissioner connected to the WLAN, Border Router is a Joiner Router**
group-onsemi 0:098463de4c5d 107
group-onsemi 0:098463de4c5d 108 ![nw-arc](img/thread_case3.png)
group-onsemi 0:098463de4c5d 109
group-onsemi 0:098463de4c5d 110 ### Native commissioner
group-onsemi 0:098463de4c5d 111
group-onsemi 0:098463de4c5d 112 In this case, either the petitioning process as described in [Native commissioner candidate](#native-commissioner-candidate)
group-onsemi 0:098463de4c5d 113 must have taken place initially, or the commissioner has already joined the Thread network, either by starting it or by using an out-of-band process. Once the joiner has received the network parameters it needs to attach to the Thread network. This closes the secure commissioning session.
group-onsemi 0:098463de4c5d 114
group-onsemi 0:098463de4c5d 115 **Case 1: Joiner Router Is Not a commissioner**
group-onsemi 0:098463de4c5d 116
group-onsemi 0:098463de4c5d 117 This case is simpler as there is no need to relay from the Border Router to the commissioner. There are two separate and distinct paths the authentication traffic (the DTLS handshakes) has to go through:
group-onsemi 0:098463de4c5d 118
group-onsemi 0:098463de4c5d 119 * Joiner to Joiner Router point-to-point.
group-onsemi 0:098463de4c5d 120 * Joiner Router to commissioner through Thread network.
group-onsemi 0:098463de4c5d 121
group-onsemi 0:098463de4c5d 122 **Figure 2-10 Native commissioner connected to the Thread network, Joiner Router is not a commissioner**
group-onsemi 0:098463de4c5d 123
group-onsemi 0:098463de4c5d 124 ![nw-arc](img/thread_case2.png)
group-onsemi 0:098463de4c5d 125
group-onsemi 0:098463de4c5d 126 **Case 2: Joiner Router is a commissioner**
group-onsemi 0:098463de4c5d 127
group-onsemi 0:098463de4c5d 128 This case is the simplest because there is no need to relay from the Border Router to the commissioner and there is not a distinct Joiner Router. There is only one distinct path the DTLS handshake has to go through:
group-onsemi 0:098463de4c5d 129
group-onsemi 0:098463de4c5d 130 * Joiner to Border Router point-to-point.
group-onsemi 0:098463de4c5d 131
group-onsemi 0:098463de4c5d 132 **Figure 2-11 Native commissioner connected to Thread network, Joiner Router is a commissioner**
group-onsemi 0:098463de4c5d 133
group-onsemi 0:098463de4c5d 134 ![nw-arc](img/thread_case4.png)
group-onsemi 0:098463de4c5d 135
group-onsemi 0:098463de4c5d 136