The Constrained Join Protocol (CoJP) is a lightweight protocol over CoAP [
RFC 7252] and a secure channel provided by OSCORE [
RFC 8613]. CoJP allows a (6LBR) pledge to request admission into a network managed by the JRC. It enables the JRC to configure the pledge with the necessary parameters. The JRC may update the parameters at any time, by reaching out to the joined node that formerly acted as a (6LBR) pledge. For example, network-wide rekeying can be implemented by updating the keying material on each node.
CoJP relies on the security properties provided by OSCORE. This includes end-to-end confidentiality, data authenticity, replay protection, and a secure binding of responses to requests.
+-----------------------------------+
| Constrained Join Protocol (CoJP) |
+-----------------------------------+
+-----------------------------------+ \
| Requests / Responses | |
|-----------------------------------| |
| OSCORE | | CoAP
|-----------------------------------| |
| Messaging Layer | |
+-----------------------------------+ /
+-----------------------------------+
| UDP |
+-----------------------------------+
When a (6LBR) pledge requests admission to a given network, it undergoes the CoJP join exchange that consists of:
-
The Join Request message, sent by the (6LBR) pledge to the JRC, potentially proxied by the JP. The Join Request message and its mapping to CoAP is specified in Section 8.1.1.
-
The Join Response message, sent by the JRC to the (6LBR) pledge, if the JRC successfully processes the Join Request using OSCORE and it determines through a mechanism that is out of scope of this specification that the (6LBR) pledge is authorized to join the network. The Join Response message is potentially proxied by the JP. The Join Response message and its mapping to CoAP is specified in Section 8.1.2.
When the JRC needs to update the parameters of a joined node that formerly acted as a (6LBR) pledge, it executes the CoJP parameter update exchange that consists of the following:
-
The Parameter Update message, sent by the JRC to the joined node that formerly acted as a (6LBR) pledge. The Parameter Update message and its mapping to CoAP is specified in Section 8.2.1.
The payload of CoJP messages is encoded with CBOR [
RFC 8949]. The CBOR data structures that may appear as the payload of different CoJP messages are specified in
Section 8.4.
This section specifies the messages exchanged when the (6LBR) pledge requests admission and configuration parameters from the JRC.
The Join Request message that the (6LBR) pledge sends
SHALL be mapped to a CoAP request:
-
The request method is POST.
-
The type is Confirmable (CON).
-
The Proxy-Scheme option is set to "coap".
-
The Uri-Host option is set to "6tisch.arpa". This is an anycast type of identifier of the JRC that is resolved to its IPv6 address by the JP or the 6LBR pledge.
-
The Uri-Path option is set to "j".
-
The OSCORE option SHALL be set according to [RFC 8613]. The OSCORE security context used is the one derived in Section 7.3. The OSCORE 'kid context' allows the JRC to retrieve the security context for a given pledge.
-
The payload is a Join_Request CBOR object, as defined in Section 8.4.1.
Since the Join Request is a confirmable message, the transmission at (6LBR) pledge will be controlled by CoAP's retransmission mechanism. The JP, when operating in a stateless manner, forwards this Join Request as a non-confirmable (NON) CoAP message, as specified in
Section 7. If the CoAP implementation at the (6LBR) pledge declares the message transmission a failure, the (6LBR) pledge
SHOULD attempt to join a 6TiSCH network advertised with a different network identifier. See
Section 7.2 for recommended values of CoAP settings to use during the join exchange.
If all join attempts to advertised networks have failed, the (6LBR) pledge
SHOULD signal the presence of an error condition, through some out-of-band mechanism.
BCP 190 [
RFC 8820] provides guidelines on URI design and ownership. It recommends that whenever a third party wants to mandate a URI to web authority that it
SHOULD go under "/.well-known" (per [
RFC 8615]). In the case of CoJP, the Uri-Host option is always set to "6tisch.arpa", and based upon the recommendations in
Section 1 of
RFC 8820, it is asserted that this document is the owner of the CoJP service. As such, the concerns of [
RFC 8820] do not apply, and thus the Uri-Path is only "j".
The Join Response message that the JRC sends
SHALL be mapped to a CoAP response:
-
The Response Code is 2.04 (Changed).
-
The payload is a Configuration CBOR object, as defined in Section 8.4.2.
During the network lifetime, parameters returned as part of the Join Response may need to be updated. One typical example is the update of link-layer keying material for the network, a process known as rekeying. This section specifies a generic mechanism when this parameter update is initiated by the JRC.
At the time of the join, the (6LBR) pledge acts as a CoAP client and requests the network parameters through a representation of the "/j" resource exposed by the JRC. In order for the update of these parameters to happen, the JRC needs to asynchronously contact the joined node. The use of the CoAP Observe option for this purpose is not feasible due to the change in the IPv6 address when the pledge becomes the joined node and obtains a global address.
Instead, once the (6LBR) pledge receives and successfully validates the Join Response and so becomes a joined node, it becomes a CoAP server. The joined node creates a CoAP service at the Uri-Host value of "6tisch.arpa", and the joined node exposes the "/j" resource that is used by the JRC to update the parameters. Consequently, the JRC operates as a CoAP client when updating the parameters. The request/response exchange between the JRC and the (6LBR) pledge happens over the already-established OSCORE secure channel.
The Parameter Update message that the JRC sends to the joined node
SHALL be mapped to a CoAP request:
-
The request method is POST.
-
The type is Confirmable (CON).
-
The Uri-Host option is set to "6tisch.arpa".
-
The Uri-Path option is set to "j".
-
The OSCORE option SHALL be set according to [RFC 8613]. The OSCORE security context used is the one derived in Section 7.3. When a joined node receives a request with the Sender ID set to 0x4a5243 (ID of the JRC), it is able to correctly retrieve the security context with the JRC.
-
The payload is a Configuration CBOR object, as defined in Section 8.4.2.
The JRC has implicit knowledge of the global IPv6 address of the joined node, as it knows the pledge identifier that the joined node used when it acted as a pledge and the IPv6 network prefix. The JRC uses this implicitly derived IPv6 address of the joined node to directly address CoAP messages to it.
If the JRC does not receive a response to a Parameter Update message, it attempts multiple retransmissions as configured by the underlying CoAP retransmission mechanism triggered for confirmable messages. Finally, if the CoAP implementation declares the transmission a failure, the JRC may consider this as a hint that the joined node is no longer in the network. How the JRC decides when to stop attempting to contact a previously joined node is out of scope of this specification, but the security considerations on the reuse of assigned resources apply, as discussed in
Section 9.
CoJP CBOR objects are transported within both CoAP requests and responses. This section describes handling the cases in which certain CoJP CBOR object parameters are not supported by the implementation or their processing fails. See
Section 7.3.2 for the handling of errors that may be raised by the underlying OSCORE implementation.
When such a parameter is detected in a CoAP request (Join Request message, Parameter Update message), a Diagnostic Response message
MUST be returned. A Diagnostic Response message maps to a CoAP response and is specified in
Section 8.3.2.
When a parameter that cannot be acted upon is encountered while processing a CoJP object in a CoAP response (Join Response message), a (6LBR) pledge
SHOULD reattempt to join. In this case, the (6LBR) pledge
SHOULD include the Unsupported Configuration CBOR object within the Join Request object in the following Join Request message. The Unsupported Configuration CBOR object is self-contained and enables the (6LBR) pledge to signal any parameters that the implementation of the networking stack may not support. A (6LBR) pledge
MUST NOT attempt more than COJP_MAX_JOIN_ATTEMPTS number of attempts to join if the processing of the Join Response message fails each time. If the COJP_MAX_JOIN_ATTEMPTS number of attempts is reached without success, the (6LBR) pledge
SHOULD signal the presence of an error condition through some out-of-band mechanism.
Note that COJP_MAX_JOIN_ATTEMPTS relates to the application-layer handling of the CoAP response and is different from CoAP's MAX_RETRANSMIT setting, which drives the retransmission mechanism of the underlying CoAP message.
The Diagnostic Response message is returned for any CoJP request when the processing of the payload failed. The Diagnostic Response message is protected by OSCORE as any other CoJP message.
The Diagnostic Response message
SHALL be mapped to a CoAP response:
-
The Response Code is 4.00 (Bad Request).
-
The payload is an Unsupported Configuration CBOR object, as defined in Section 8.4.5, containing more information about the parameter that triggered the sending of this message.
The parameter update exchange may be triggered at any time during the network lifetime, which may span several years. During this period, a joined node or the JRC may experience unexpected events such as reboots or complete failures.
This document mandates that the mutable parameters in the security context are written to persistent memory (see
Section 7.3.1) by both the JRC and pledges (joined nodes). As the pledge (joined node) is typically a constrained device that handles the write operations to persistent memory in a predictable manner, the retrieval of mutable security-context parameters is feasible across reboots such that there is no risk of AEAD nonce reuse due to reinitialized Sender Sequence Numbers or of a replay attack due to the reinitialized Replay Window. The JRC may be hosted on a generic machine where the write operation to persistent memory may lead to unpredictable delays due to caching. If a reboot event occurs at the JRC before the cached data is written to persistent memory, the loss of mutable security-context parameters is likely, which consequently poses the risk of AEAD nonce reuse.
In the event of a complete device failure, where the mutable security-context parameters cannot be retrieved, it is expected that a failed joined node will be replaced with a new physical device, using a new pledge identifier and a PSK. When such a failure event occurs at the JRC, it is possible that the static information on provisioned pledges, like PSKs and pledge identifiers, can be retrieved through available backups. However, it is likely that the information about joined nodes, their assigned short identifiers and mutable security-context parameters, is lost. If this is the case, the network administrator
MUST force all the networks managed by the failed JRC to rejoin through out-of-band means during the process of JRC reinitialization, e.g., reinitialize the 6LBR nodes and freshly generate dynamic cryptographic keys and other parameters that influence the security properties of the network.
In order to recover from such a failure event, the reinitialized JRC can trigger the renegotiation of the OSCORE security context through the procedure described in
Appendix B.2 of
RFC 8613. Aware of the failure event, the reinitialized JRC responds to the first Join Request of each pledge it is managing with a 4.01 (Unauthorized) error and a random nonce. The pledge verifies the error response and then initiates the CoJP join exchange using a new OSCORE security context derived from an ID Context consisting of the concatenation of two nonces, one that it received from the JRC and the other that the pledge generates locally. After verifying the Join Request with the new ID Context and the derived OSCORE security context, the JRC should consequently map the new ID Context to the previously used pledge identifier. How the JRC handles this mapping is out of scope of this document.
The use of the procedure specified in
Appendix B.2 of
RFC 8613 is
RECOMMENDED in order to handle the failure events or any other event that may lead to the loss of mutable security-context parameters. The length of nonces exchanged using this procedure
MUST be at least 8 bytes.
The procedure requires both the pledge and the JRC to have good sources of randomness. While this is typically not an issue at the JRC side, the constrained device hosting the pledge may pose limitations in this regard. If the procedure outlined in
Appendix B.2 of
RFC 8613 is not supported by the pledge, the network administrator
MUST reprovision the concerned devices with freshly generated parameters through out-of-band means.
This section specifies the structure of CoJP CBOR objects that may be carried as the payload of CoJP messages. Some of these objects may be received both as part of the CoJP join exchange when the device operates as a (CoJP) pledge or as part of the parameter update exchange when the device operates as a joined (6LBR) node.
The Join_Request structure is built on a CBOR map object.
The set of parameters that can appear in a Join_Request object is summarized below. The labels can be found in the "Constrained Join Protocol (CoJP) Parameters" registry,
Section 11.1.
-
role:
-
The identifier of the role that the pledge requests to play in the network once it joins, encoded as an unsigned integer.Possible values are specified in Table 3.This parameter MAY be included.If the parameter is omitted, the default value of 0, i.e., the role "6TiSCH Node", MUST be assumed.
-
network identifier:
-
The identifier of the network, as discussed in Section 3, encoded as a CBOR byte string.When present in the Join_Request, it hints to the JRC which network the pledge is requesting to join, enabling the JRC to manage multiple networks.The pledge obtains the value of the network identifier from the received EB frames.This parameter MUST be included in a Join_Request object regardless of the role parameter value.
-
unsupported configuration:
-
The identifier of the parameters that are not supported by the implementation, encoded as an Unsupported_Configuration object described in Section 8.4.5.This parameter MAY be included.If a (6LBR) pledge previously attempted to join and received a valid Join Response message over OSCORE but failed to act on its payload (Configuration object), it SHOULD include this parameter to facilitate the recovery and debugging.
Table 2 summarizes the parameters that may appear in a Join_Request object.
Name |
Label |
CBOR Type |
role |
1 |
unsigned integer |
network identifier |
5 |
byte string |
unsupported configuration |
8 |
array |
Table 2: Summary of Join_Request parameters.
The CDDL fragment that represents the text above for the Join_Request follows:
Join_Request = {
? 1 : uint, ; role
5 : bstr, ; network identifier
? 8 : Unsupported_Configuration ; unsupported configuration
}
Name |
Value |
Description |
Reference |
6TiSCH Node |
0 |
The pledge requests to play the role of a regular 6TiSCH node, i.e., non-6LBR node. |
RFC 9031 |
6LBR |
1 |
The pledge requests to play the role of 6LoWPAN Border Router (6LBR). |
RFC 9031 |
Table 3: Role values.
The Configuration structure is built on a CBOR map object. The set of parameters that can appear in a Configuration object is summarized below. The labels can be found in "Constrained Join Protocol (CoJP) Parameters" registry,
Section 11.1.
-
link-layer key set:
-
An array encompassing a set of cryptographic keys and their identifiers that are currently in use in the network or that are scheduled to be used in the future.The encoding of individual keys is described in Section 8.4.3.The link-layer key set parameter MAY be included in a Configuration object.When present, the link-layer key set parameter MUST contain at least one key.This parameter is also used to implement rekeying in the network.The installation and use of keys differs for the 6LBR and other (regular) nodes, and this is explained in Sections [8.4.3.1] and [8.4.3.2].
-
short identifier:
-
A compact identifier assigned to the pledge.The short identifier structure is described in Section 8.4.4.The short identifier parameter MAY be included in a Configuration object.
-
JRC address:
-
The IPv6 address of the JRC, encoded as a byte string, with the length of 16 bytes.If the length of the byte string is different from 16, the parameter MUST be discarded.If the JRC is not co-located with the 6LBR and has a different IPv6 address than the 6LBR, this parameter MUST be included.In the special case where the JRC is co-located with the 6LBR and has the same IPv6 address as the 6LBR, this parameter MAY be included.If the JRC address parameter is not present in the Configuration object, this indicates that the JRC has the same IPv6 address as the 6LBR.The joined node can then discover the IPv6 address of the JRC through network control traffic.See Section 6.
-
blacklist:
-
An array encompassing a list of pledge identifiers that are blacklisted by the JRC, with each pledge identifier encoded as a byte string.The blacklist parameter MAY be included in a Configuration object.When present, the array MUST contain zero or more byte strings encoding pledge identifiers.The joined node MUST silently drop any link-layer frames originating from the pledge identifiers enclosed in the blacklist parameter.When this parameter is received, its value MUST overwrite any previously set values.This parameter allows the JRC to configure the node acting as a JP to filter out traffic from misconfigured or malicious pledges before their traffic is forwarded into the network.If the JRC decides to remove a given pledge identifier from a blacklist, it omits the pledge identifier in the blacklist parameter value it sends next.Since the blacklist parameter carries the pledge identifiers, privacy considerations apply.See Section 10.
-
join rate:
-
The average data rate (in units of bytes/second) of join traffic forwarded into the network that should not be exceeded when a joined node operates as a JP, encoded as an unsigned integer.The join rate parameter MAY be included in a Configuration object.This parameter allows the JRC to configure different nodes in the network to operate as JP and to act in case of an attack by throttling the rate at which JP forwards unauthenticated traffic into the network.When this parameter is present in a Configuration object, the value MUST be used to set the PROBING_RATE of CoAP at the joined node for communication with the JRC.If this parameter is set to zero, a joined node MUST silently drop any join traffic coming from unauthenticated pledges.If this parameter is omitted, the value of positive infinity SHOULD be assumed.A node operating as a JP MAY use another mechanism that is out of scope of this specification to configure the PROBING_RATE of CoAP in the absence of a join rate parameter from the Configuration object.
Table 4 summarizes the parameters that may appear in a Configuration object.
Name |
Label |
CBOR Type |
link-layer key set |
2 |
array |
short identifier |
3 |
array |
JRC address |
4 |
byte string |
blacklist |
6 |
array |
join rate |
7 |
unsigned integer |
Table 4: Summary of Configuration parameters.
The CDDL fragment that represents the text above for the Configuration follows. The structures Link_Layer_Key and Short_Identifier are specified in Sections [
8.4.3] and [
8.4.4], respectively.
Configuration = {
? 2 : [ +Link_Layer_Key ], ; link-layer key set
? 3 : Short_Identifier, ; short identifier
? 4 : bstr, ; JRC address
? 6 : [ *bstr ], ; blacklist
? 7 : uint ; join rate
}
Name |
Label |
CBOR type |
Description |
Reference |
role |
1 |
unsigned integer |
Identifies the role parameter |
RFC 9031 |
link-layer key set |
2 |
array |
Identifies the array carrying one or more link-layer cryptographic keys |
RFC 9031 |
short identifier |
3 |
array |
Identifies the assigned short identifier |
RFC 9031 |
JRC address |
4 |
byte string |
Identifies the IPv6 address of the JRC |
RFC 9031 |
network identifier |
5 |
byte string |
Identifies the network identifier parameter |
RFC 9031 |
blacklist |
6 |
array |
Identifies the blacklist parameter |
RFC 9031 |
join rate |
7 |
unsigned integer |
Identifier the join rate parameter |
RFC 9031 |
unsupported configuration |
8 |
array |
Identifies the unsupported configuration parameter |
RFC 9031 |
Table 5: CoJP parameters map labels.
The Link_Layer_Key structure encompasses the parameters needed to configure the link-layer security module: the key identifier; the value of the cryptographic key; the link-layer algorithm identifier and the security level and the frame types with which it should be used for both outgoing and incoming security operations; and any additional information that may be needed to configure the key.
For encoding compactness, the Link_Layer_Key object is not enclosed in a top-level CBOR object. Rather, it is transported as a sequence of CBOR elements [
RFC 8742], some being optional.
The set of parameters that can appear in a Link_Layer_Key object is summarized below, in order:
-
key_id:
-
The identifier of the key, encoded as a CBOR unsigned integer.This parameter MUST be included.If the decoded CBOR unsigned integer value is larger than the maximum link-layer key identifier, the key is considered invalid.If the key is considered invalid, the key MUST be discarded,and the implementation MUST signal the error as specified in Section 8.3.1.
-
key_usage:
-
The identifier of the link-layer algorithm, security level, and link-layer frame types that can be used with the key, encoded as an integer.This parameter MAY be included.Possible values and the corresponding link-layer settings are specified in theIANA "Constrained Join Protocol (CoJP) Key Usage" registry (Section 11.2).If the parameter is omitted, the default value of 0 (6TiSCH-K1K2-ENC-MIC32) from Table 6 MUST be assumed.This default value has been chosen because it results in byte savings in the most constrained settings; its selection does not imply a recommendation for its general usage.
-
key_value:
-
The value of the cryptographic key, encoded as a byte string.This parameter MUST be included.If the length of the byte string is different than the corresponding key length for a given algorithm specified by the key_usage parameter, the key MUST be discarded, and the implementation MUST signal the error as specified in Section 8.3.1.
-
key_addinfo:
-
Additional information needed to configure the link-layer key, encoded as a byte string.This parameter MAY be included.The processing of this parameter is dependent on the link-layer technology in use and a particular keying mode.
To be able to decode the keys that are present in the link-layer key set and to identify individual parameters of a single Link_Layer_Key object, the CBOR decoder needs to differentiate between elements based on the CBOR type. For example, a uint that follows a byte string signals to the decoder that a new Link_Layer_Key object is being processed.
The CDDL fragment for the Link_Layer_Key that represents the text above follows:
Link_Layer_Key = (
key_id : uint,
? key_usage : int,
key_value : bstr,
? key_addinfo : bstr,
)
Name |
Value |
Algorithm |
Description |
6TiSCH-K1K2-ENC-MIC32 |
0 |
IEEE802154-AES-CCM-128 |
Use MIC-32 for EBs, ENC-MIC-32 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K1K2-ENC-MIC64 |
1 |
IEEE802154-AES-CCM-128 |
Use MIC-64 for EBs, ENC-MIC-64 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K1K2-ENC-MIC128 |
2 |
IEEE802154-AES-CCM-128 |
Use MIC-128 for EBs, ENC-MIC-128 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K1K2-MIC32 |
3 |
IEEE802154-AES-CCM-128 |
Use MIC-32 for EBs, DATA and ACKNOWLEDGMENT. |
6TiSCH-K1K2-MIC64 |
4 |
IEEE802154-AES-CCM-128 |
Use MIC-64 for EBs, DATA and ACKNOWLEDGMENT. |
6TiSCH-K1K2-MIC128 |
5 |
IEEE802154-AES-CCM-128 |
Use MIC-128 for EBs, DATA and ACKNOWLEDGMENT. |
6TiSCH-K1-MIC32 |
6 |
IEEE802154-AES-CCM-128 |
Use MIC-32 for EBs. |
6TiSCH-K1-MIC64 |
7 |
IEEE802154-AES-CCM-128 |
Use MIC-64 for EBs. |
6TiSCH-K1-MIC128 |
8 |
IEEE802154-AES-CCM-128 |
Use MIC-128 for EBs. |
6TiSCH-K2-MIC32 |
9 |
IEEE802154-AES-CCM-128 |
Use MIC-32 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K2-MIC64 |
10 |
IEEE802154-AES-CCM-128 |
Use MIC-64 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K2-MIC128 |
11 |
IEEE802154-AES-CCM-128 |
Use MIC-128 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K2-ENC-MIC32 |
12 |
IEEE802154-AES-CCM-128 |
Use ENC-MIC-32 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K2-ENC-MIC64 |
13 |
IEEE802154-AES-CCM-128 |
Use ENC-MIC-64 for DATA and ACKNOWLEDGMENT. |
6TiSCH-K2-ENC-MIC128 |
14 |
IEEE802154-AES-CCM-128 |
Use ENC-MIC-128 for DATA and ACKNOWLEDGMENT. |
Table 6: Key Usage values.
When the 6LBR receives the Configuration object containing a link-layer key set, it
MUST immediately install and start using the new keys for all outgoing traffic and remove any old keys it has installed from the previous key set after a delay of COJP_REKEYING_GUARD_TIME has passed. This mechanism is used by the JRC to force the 6LBR to start sending traffic with the new key. The decision is made by the JRC when it has determined that the new key has been made available to all (or some overwhelming majority) of nodes. Any node that the JRC has not yet reached at that point is either nonfunctional or in extended sleep such that it will not be reached. To get the key update, such a node will need to go through the join process anew.
When a regular 6LN receives the Configuration object with a link-layer key set, it
MUST install the new keys. The 6LN will use both the old and the new keys to decrypt and authenticate any incoming traffic that arrives based upon the key identifier in the packet. It
MUST continue to use the old keys for all outgoing traffic until it has detected that the network has switched to the new key set.
The detection of the network switch is based upon the receipt of traffic secured with the new keys. Upon the reception and the successful security processing of a link-layer frame secured with a key from the new key set, a 6LN
MUST then switch to sending all outgoing traffic using the keys from the new set. The 6LN
MUST remove any keys it had installed from the previous key set after waiting COJP_REKEYING_GUARD_TIME since it started using the new key set.
Sending traffic with the new keys signals to other downstream nodes to switch to their new key, causing a ripple of key updates around each 6LBR.
When Link_Layer_Key is used in the context of [
IEEE802.15.4], the following considerations apply.
Signaling of different keying modes of [
IEEE802.15.4] is done based on the parameter values present in a Link_Layer_Key object. For instance, the value of the key_id parameter in combination with key_addinfo denotes which of the four Key ID modes of [
IEEE802.15.4] is used and how.
-
Key ID Mode 0x00 (Implicit, pairwise):
-
The key_id parameter MUST be set to 0.The key_addinfo parameter MUST be present.The key_addinfo parameter MUST be set to the link-layer address(es) of a single peer with whom the key should be used.Depending on the configuration of the network, key_addinfo may carry the peer's long link-layer address (i.e., pledge identifier), short link-layer address, or their concatenation with the long address being encoded first.Which address type(s) is carried is determined from the length of the byte string.
-
Key ID Mode 0x01 (Key Index):
-
The key_id parameter MUST be set to a value different from 0.The key_addinfo parameter MUST NOT be present.
-
Key ID Mode 0x02 (4-byte Explicit Key Source):
-
The key_id parameter MUST be set to a value different from 0.The key_addinfo parameter MUST be present.The key_addinfo parameter MUST be set to a byte string, exactly 4 bytes long.The key_addinfo parameter carries the Key Source parameter used to configure [IEEE802.15.4].
-
Key ID Mode 0x03 (8-byte Explicit Key Source):
-
The key_id parameter MUST be set to a value different from 0.The key_addinfo parameter MUST be present.The key_addinfo parameter MUST be set to a byte string, exactly 8 bytes long.The key_addinfo parameter carries the Key Source parameter used to configure [IEEE802.15.4].
In all cases, the key_usage parameter determines how a particular key should be used with respect to incoming and outgoing security policies.
For Key ID Modes 0x01 through 0x03, the key_id parameter sets the "secKeyIndex" parameter of [
IEEE802.15.4] that is signaled in all outgoing frames secured with a given key. The maximum value that key_id can have is 254. The value of 255 is reserved in [
IEEE802.15.4] and is therefore considered invalid.
Key ID Mode 0x00 (Implicit, pairwise) enables the JRC to act as a trusted third party and assign pairwise keys between nodes in the network. How the JRC learns about the network topology is out of scope of this specification, but it could be done through 6LBR-JRC signaling, for example. Pairwise keys could also be derived through a key agreement protocol executed between the peers directly, where the authentication is based on the symmetric cryptographic material provided to both peers by the JRC. Such a protocol is out of scope of this specification.
Implementations
MUST use different link-layer keys when using different authentication tag (MIC) lengths, as using the same key with different authentication tag lengths might be unsafe. For example, this prohibits the usage of the same key for both MIC-32 and MIC-64 levels. See Annex B.4.3 of [
IEEE802.15.4] for more information.
The Short_Identifier object represents an identifier assigned to the pledge. It is encoded as a CBOR array object and contains, in order:
-
identifier:
-
The short identifier assigned to the pledge, encoded as a byte string.This parameter MUST be included.The identifier MUST be unique in the set of all identifiers assigned in a network that is managed by a JRC.If the identifier is invalid, the decoder MUST silently ignore the Short_Identifier object.
-
lease_time:
-
The validity of the identifier in hours after the reception of the CBOR object, encoded as a CBOR unsigned integer.This parameter MAY be included.The node MUST stop using the assigned short identifier after the expiry of the lease_time interval.It is up to the JRC to renew the lease before the expiry of the previous interval.The JRC updates the lease by executing the parameter update exchange with the node and including the Short_Identifier in the Configuration object, as described in Section 8.2.If the lease expires, then the node SHOULD initiate a new join exchange, as described in Section 8.1.If this parameter is omitted, then the value of positive infinity MUST be assumed, meaning that the identifier is valid for as long as the node participates in the network.
The CDDL fragment for the Short_Identifier that represents the text above follows:
Short_Identifier = [
identifier : bstr,
? lease_time : uint
]
When the Short_Identifier is used in the context of [
IEEE802.15.4], the following considerations apply.
The identifier
MUST be used to set the short address of the IEEE Std 802.15.4 module. When operating in TSCH mode, the identifier
MUST be unique in the set of all identifiers assigned in multiple networks that share link-layer key(s). If the length of the byte string corresponding to the identifier parameter is different from 2, the identifier is considered invalid. The values 0xfffe and 0xffff are reserved by [
IEEE802.15.4], and their use is considered invalid.
The security properties offered by the [
IEEE802.15.4] link-layer in TSCH mode are conditioned on the uniqueness requirement of the short identifier (i.e., short address). The short address is one of the inputs in the construction of the nonce, which is used to protect link-layer frames. If a misconfiguration occurs, and the same short address is assigned twice under the same link-layer key, the loss of security properties is imminent. For this reason, practices where the pledge generates the short identifier locally are not safe and are likely to result in the loss of link-layer security properties.
The JRC
MUST ensure that at any given time there are never two of the same short identifiers being used under the same link-layer key. If the lease_time parameter of a given Short_Identifier object is set to positive infinity, care needs to be taken that the corresponding identifier is not assigned to another node until the JRC is certain that it is no longer in use, potentially through out-of-band signaling. If the lease_time parameter expires for any reason, the JRC should take into consideration potential ongoing transmissions by the joined node, which may be hanging in the queues, before assigning the same identifier to another node.
Care needs to be taken on how the pledge (joined node) configures the expiration of the lease. Since units of the lease_time parameter are in hours after the reception of the CBOR object, the pledge needs to convert the received time to the corresponding Absolute Slot Number in the network. The joined node (pledge)
MUST only use the Absolute Slot Number as the appropriate reference of time to determine whether the assigned short identifier is still valid.
The Unsupported_Configuration object is encoded as a CBOR array, containing at least one Unsupported_Parameter object. Each Unsupported_Parameter object is a sequence of CBOR elements without an enclosing top-level CBOR object for compactness. The set of parameters that appear in an Unsupported_Parameter object is summarized below, in order:
-
code:
-
Indicates the capability of acting on the parameter signaled by parameter_label, encoded as an integer.This parameter MUST be included.Possible values of this parameter are specified in the IANA "Constrained Join Protocol (CoJP) Unsupported Configuration Codes" registry (Section 11.3).
-
parameter_label:
-
Indicates the parameter. This parameter MUST be included. Possible values of this parameter are specified in the label column of the IANA "Constrained Join Protocol (CoJP) Parameters" registry" (Section 11.1).
-
parameter_addinfo:
-
Additional information about the parameter that cannot be acted upon.This parameter MUST be included.If the code is set to "Unsupported", parameter_addinfo gives additional information to the JRC.If the parameter indicated by parameter_label cannot be acted upon regardless of its value, parameter_addinfo MUST be set to null, signaling to the JRC that it SHOULD NOT attempt to configure the parameter again.If the pledge can act on the parameter, but cannot configure the setting indicated by the parameter value, the pledge can hint this to the JRC.In this case, parameter_addinfo MUST be set to the value of the parameter that cannot be acted upon following the normative parameter structure specified in this document.For example, it is possible to include the link-layer key set object, signaling that either a subset or the entire key set that was received cannot be acted upon. In that case, the value of parameter_addinfo follows the link-layer key set structure defined in Section 8.4.2.If the code is set to "Malformed", parameter_addinfo MUST be set to null, signaling to the JRC that it SHOULD NOT attempt to configure the parameter again.
The CDDL fragment for the Unsupported_Configuration and Unsupported_Parameter objects that represents the text above follows:
Unsupported_Configuration = [
+ parameter : Unsupported_Parameter
]
Unsupported_Parameter = (
code : int,
parameter_label : int,
parameter_addinfo : nil / any
)
Name |
Value |
Description |
Reference |
Unsupported |
0 |
The indicated setting is not supported by the networking stack implementation. |
RFC 9031 |
Malformed |
1 |
The indicated parameter value is malformed. |
RFC 9031 |
Table 7: Unsupported Configuration code values.
This section gives
RECOMMENDED values of CoJP settings.
Name |
Default Value |
COJP_MAX_JOIN_ATTEMPTS |
4 |
COJP_REKEYING_GUARD_TIME |
12 seconds |
Table 8: Recommended CoJP settings.
The COJP_REKEYING_GUARD_TIME value
SHOULD take into account possible retransmissions at the link layer due to imperfect wireless links.