Thread Key Management
=====================

This document describes the key management mechanism in Thread.
Other details about Thread, such as routing protocols, will be
described in subsequent documents.

Introduction
------------


## Goals ##

 * Completely decentralized.
 * Fault-tolerant.
 * Straightforward implementation.


Terminology
-----------

 * `ThreadKey`: PSK used to grant access to the network.

 * `NetworkKey`: Temporary key used to secure and authenticate traffic
   on the network.

 * `NetworkKeyUpdate`: A bundle of information describing the current
   `NetworkKey` and associated information, such as the age of the
   key, when a next rotation is scheduled to occur, and which node
   created the key.

 * "Network Leader": The node which submitted the currently accepted
   `NetworkKey`.

 * `NetworkKeyIndex`: a 24 bit value identifying a specific revision
   of the `NetworkKey`.

 * "Masked index": The bitwise-AND of the `NetworkKeyIndex` and
   `NETWORK_KEY_INDEX_MASK`.

## Notation ##

 * `x | y`: Simple concatenation of `y` after `x`.
 * `UPPER_OCTETS(x, l)`: The upper (first) `l` octets of `x`.
 * `LOWER_OCTETS(x, l)`: The lower (last) `l` octets of `x`.
 * `H(x)`: Cryptographic hash of `x`. Assumed to be SHA256.
 * `HMAC(key, x)`: HMAC of `x` using `k` as the key.
                   Assumed to be HMAC-SHA256.
 * `HKDF-Extract(salt, ikm)`: RFC5869 HKDF Key Extraction.
 * `HKDF-Expand(prk, info, l)`: RFC5869 HKDF Key Expansion.
 * `HKDF(salt, info, ikm, l)`: RFC5869 HKDF Key Extraction and Expansion.
 * `RANDOM_DATA(l)`: Random data `l` octets long.
 * `CRYPT-CCM(nonce, key, x)`: Cryptographic encryption using CCM mode.
                               Assumed to use AES128. rfc3610
 * `DECRYPT-CCM(nonce, key, x)`: Cryptographic encryption using CCM mode.
                                 Assumed to use AES128. rfc3610
 * `PBKDF2(PRF, Password, Salt, c, dkLen)`: RFC2898.

## Constants ##

 * `AES_CCM_KEY_LENGTH`: Length of a AES-CCM key, in octets.
                         Defined to be `16`.
 * `MAC_KEY_LENGTH`: Length of a MAC key, in octets. Value is
                     `AES_CCM_KEY_LENGTH` for 802.15.4.
 * `HASH_LENGTH`: Length of the hash output from the `H()` function.
                  This is `32` for SHA256.
 * `THREAD_KEY_LENGTH`: Length of the thread administrative keys. Value
                        is `HASH_LENGTH`. May be between `MAC_KEY_LENGTH`
                        and `HASH_LENGTH`. Standard length is the same as
                        `MAC_KEY_LENGTH`.
 * `AES_CCM_M`: 8 bytes.
 * `NETWORK_KEY_INDEX_MASK`: 0x7F


Functional Description
----------------------

This key management system features two classes of keys: administrative
keys (hereafter called 'Thread keys') and network keys. Each is calculated
independently and has no mathematical relationship to each other.
The thread key is used to grant access to the network,
whereas the network key is used to secure traffic on the network.

Using the thread key, you can learn the associated
network key from other devices on that network. Once a node learns
the current network key and associated network key index it may
then communicate with other nodes on the network as a peer.

Key rotation is handled automatically on a periodic basis, thus allowing
the network to operate securely without necessitating changing the key
used to grant access to the network.

## Key Classes ##

Network keys are used to secure the contents of packets and provide
confidence that whoever created a given packet also had the same
network key. Since device must have the network key in order to
participate on the network, why don’t we just have a single class of
keys?

Network keys must be rotated on a regular basis in order to retain
the security characteristics of the stream cipher (In this case,
AES-CCM) when used over a large amount of data. Thus, network keys
are ephemeral. If a device misses a key rotation, it must somehow
rediscover the current network key in order to once again be able to
participate on the network.

The thread key is used as a PSK (pre-shared secret) to enable a
node to quickly and securely discover the current network keys from
other nodes. Thread keys do not need to be regularly rotated to maintain
network security. This has a number of benefits:

 * Devices which have been powered off for a long period of
   time are able to quickly rejoin the network.
 * Since only symmetric encryption is used, the implementation can
   be small and efficient.
 * The application doesn't need to concern itself with network
   key rotation, as this is handled automatically.

Rotation of the thread key is not precluded, but doing so is not
necessary for the security of the MAC layer. Since the network keys
are not derived from the thread keys, the thread keys can be changed
independently of the network keys, allowing thread keys to be changed
without disrupting network connectivity.

## Initial Provisioning ##

Initial provisioning of thread keys can occur via a number of methods:

 * Out-of-band provisioning, including direct entry on the device
   joining the network (if possible).
 * In-band via EAP tunneled over PANA, similar to how ZigBeeIP nodes
   discover the network key.
 * In-band via a proprietary protocol. (E.g. Weave)

## Comparison with other systems ##

Other systems, such as ZigBeeIP and ConnectIP, use different
mechanisms.

With ZigBeeIP, the joining host obtains the current network key
from the network coordinator using EAP via PANA. The PANA session
is maintained for the duration of the connection to the network.
When the network key needs to be rotated, the coordinator uses
the established PANA sessions to set the next network key. Since
thread has no coordinator, this approach will not work.

In ConnectIP, the joining host obtains the network key using a
secured DTLS exchange, authenticating the peer using a signed
certificate and private ECC key. When the network is joinable, *any*
device which has the appropriate certificate can learn the current
network key, which is concerning. Additionally, if a node misses
two network key rotations, the node has "fallen off the boat", and
must rejoin the network using manual intervention.

While this later part could be considered negavite, having a built-in
self-destruct for network-association is actually desirable for
some applications. However, instead of relying on this as a side-effect
of network key rotation (which is always necessary), it would be more
ideal if such behavior could be decoupled entirely from the network
key rotation process.

By having different classes of keys, you can disassociate such
network-association-self-destruct timing from the rotation of network
keys. For example, you could rotate the network keys every day but only
rotate the thread keys once a month. This way a device would only
"fall off the boat" when out of communication for about a month, but
would have no trouble rejoining the network without intervention if
it were turned off for a week. (There are of course many details
that I am glossing over here, which I will elaborate more on in
other sections)


Protocol Overview
-----------------

The goal of this mechanism is allow a group of homogenous nodes to
securely agree on a shared secret that periodically changes (rotation).
The system is designed to converge quickly in the presence of
inconsistencies and will attempt to always maintain network connectivity
with peers while rotating and converging.

## Network Key Updates ##

The central mechanism behind this key management system is the Network
Key Update. The Network Key Update is a bundle of information which is
broadcast in the clear to a node's immediate peers and describes either
the current state of the `NetworkKey` or a proposed future `NetworkKey`.

Network key updates are broadcast periodically, after specific events,
and upon request from another node. Network key updates, along with
requests for network key updates, are ALWAYS transmitted using link-local
broadcast. This helps the network key state converge more quickly in
cases when there is an inconsistency.

Specifically, a network key update MUST be broadcast under all of the
following conditions:

 1. When a node has restarted and intends to rejoin the network.
 2. When a node has adopted or staged a new network key.
 3. Whenever the age of the currently staged network key passes the
    T=0 threshold.

Upon responding to a broadcast request for a network key update, a node
MUST wait a randomly-determined amount of time before generating and
broadcasting the current network key update. In order to minimize
network congestion, the request for a network key update MUST be
abandoned or ignored if either of the following conditions are true:

 1. While waiting during the random delay, a valid network key update
    broadcast for the same key has been received from a different node.
 2. The node has already broadcast a network key update within the
    past five seconds.

Note that the above restrictions apply ONLY to network key update
broadcasts in response to a request.

## Network Key Update Format ##

The format of the `NetworkKeyUpdate` is as follows:

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---.
    |                                                               |  N |
    +                Network Key Origin Address (EUI-64)            +  O |
    |                                                               |  N |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  C |
    |                     Network Key Long Index                    |  E |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---'
    |                                                               |  |
    +                                                               + <'
    |                      Encrypted Network Key                    |
    +                                                               +
    |          (AES128-CCM using key derived from ThreadKey)        |
    +                                                               +
    |                                                               |
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ---.
    |                                                               |  N |
    +                         Network Key MAC                       +  O |
    |                                                               |  N |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  C |
    |         NetworkKeyAge in 1/10 seconds         |Rotate Interval|  E |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---'
    |                        NetworkKeyAge MAC                      |  |
    +                                                               + <'
    |          (AES128-CCM using key derived from ThreadKey)        |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The key age is a signed 24-bit integer which measures the age of the key
in 1/10th seconds. T=0 is the point in time at which the key becomes
valid. Negative values are used during key staging and settling,
to account for key creation race conditions.

The rotate interval is an unsigned integer which measures the expected
period of time to pass between key rotations, measured in hours. The
maximum value for this field is 232, or 9.6 days. Larger values for this
field MUST cause the entire network key update to be rejected.

Updates are authenticated via AES-CCM. In each of the two cases where
AES128-CCM is employed, all of the data
prior to the encryption is considered to be the 'header' and is included
in the authentication as such. The TTS MAC is calculated by encrypting
a zero-length message using the indicated nonce. The key used is
derived using HKDF:

    HKDF-Expand( ThreadKey, "NetworkKeyUpdate", AES_CCM_KEY_LENGTH )

When receiving a network key sync update, a series of checks are
performed to determine if the update is valid and what the resulting
action should be.  When a node receives a network sync update, it
can take one of the following four actions:

 * Ignore it.
 * Ignore it and initiate a completely new key rotation.
 * Stage it and begin the settling process.
 * Immediately apply it.

Which action is taken depends on the relative preference of the received
network key update and if we are currently in the middle of rotating keys.

## Network Key Update Preference ##

Key updates are accepted or ignored based on a comparison procedure.

The first step is always to compare the key indexes. If the key index of the
update is less than the current key index, the update is ALWAYS ignored.
The subsequent steps depend on if we are currently rotating keys (the
"settling period") or not.

The second step is always to compare this update to the last received update.
If they have the same key index, key origin hwaddr, and key value, then ignore
the update UNLESS it indicates an older key age than we have calculated by at
least one second.

Then, if we are currently in the middle of a key rotation:

1. If a comparison of the encrypted key contents indicates that the new update
   is lexicographically later to the last received update, then ignore the new
   update.
2. Verify that the update decrypts properly and is authentic. If it does not
   then ignore the new update.
3. Replace the last received update with the new update, possibly leaving
   the key settling period if the age of the key is zero or positive.

Or, if we are NOT currently in the middle of a key rotation:

1. If the key index is equal to our current network key index, but the key
   in the update is different, ignore the update and immediately propose a new
   network key for the next index.
2. Verify that the update decrypts properly and is authentic. If it does not
   then ignore the new update.
3. Replace the last received update with the new update, possibly entering
   a key settling period if the age of the key is negative.

## Network Key Index Mask ##

The network key index used by this protocol is much larger than the
key index field typically used in the link-layer protocols targetted
by this mechanism. A mask, `NETWORK_KEY_INDEX_MASK`, is applied to
the network key index to obtain a value appropriate to use for
such a field.

    NETWORK_KEY_INDEX_MASK = 0x7F

The bitwise-AND of the `NetworkKeyLongIndex` and `NETWORK_KEY_INDEX_MASK`
is the "masked index".

## Network Key Rotation ##

Any node may manually initiate a key rotation by incrementing the
network key index, generating a new network key, and broadcasting
the network key update.

If, after incrementing `NetworkKeyLongIndex`, the bitwise-AND of
`NetworkKeyLongIndex` and `NETWORK_KEY_INDEX_MASK` (the "masked index")
is zero, the `NetworkKeyLongIndex` MUST be incremented again. Network
keys with a masked index of zero are invalid and MUST NEVER be
broadcast.

New keys are always generated with a negative age, typically between
-10 and -15 seconds. This period of time before T=0 is called the
rotation settling period. The purpose of this period is to allow
time for the network to converge to a single network key before
everyone switches over to a new key. This is important when two nodes
which are not directly in radio contact with each other propose
a new key at exactly the same moment.

### Automatic Key Rotation ###

While key rotations can be manually initiated, this is usually
unnecessary due to the automatic key rotation. Automatic key rotation
works as follows:

In order to minimize the contention for the generation of a new key,
the node which generated the most recent network key (the "leader")
is always given the first opportunity to propose a new network key
at the first expiration of the current rotation interval. If the
leader does not propose a new key before the next expected rotation,
then all nodes are free to propose new keys.

## Use of the NetworkKey ##

The network key is used to derive additional keys that are used
for securing and authenticating traffic on the network, such as
the `MACKey` and `MLEKey`.

The keys for MAC and MLE are derived from the `NetworkKey` in a way
which is compatible with the MAC/MLE key derivation in ZigBeeIP.
While additional work must be done to allow for future ZigBeeIP
compatibility, we can avoid preventing it outright by using their
MAC key derivation mechanism. The keys are derived as follows:

    MACKey = UPPER_OCTETS(
               HMAC(UPPER_OCTETS(NetworkKey,16), "ZigBeeIP"),
               MAC_KEY_LENGTH
             )

    MLEKey = LOWER_OCTETS(
               HMAC(UPPER_OCTETS(NetworkKey,16), "ZigBeeIP"),
               MAC_KEY_LENGTH
             )

## State Machine ##

The thread key management state machine is relatively simple and
is described below in pseudocode:

    // We can't do anything until we are provisioned.
    WAIT_UNTIL(thread_keys_are_set());

    timeout_value = 5;

    // Periodically request network keys while we wait to receive them.
    while (!network_keys_are_set()) {
        send_network_key_request();

        timeout_value = timeout_value * 2;

        if (timeout_value > 60)
            timeout_value = 60;

        WAIT_UNTIL(
            seconds_have_elapsed(timeout_value)
            OR network_keys_are_set()
        );
    }

    // Normal idle state.
    while (network_keys_are_set())
    {
        timeout_value = KEY_ROTATION_PERIOD;

        if (we_are_the_thread_leader())
        {
            timeout_value = timeout_value * 2;
        }

        WAIT_UNTIL(
            seconds_have_elapsed(timeout_value)
            OR received_and_staged_network_key_update()
        );

        if (seconds_have_elapsed(timeout_value))
        {
            begin_and_stage_network_key_rotation();
        }

        /* Now enter the network key sync settling period */
        if (!key_rotation_has_settled())
        {
            while (!key_rotation_has_settled())
            {
                WAIT_UNTIL(
                    seconds_have_elapsed(time_to_settle())
                    OR received_network_key_update()
                );

                if (!received_network_key_update())
                    break;
            }

            /* Finished key rotation settling period. */
            apply_staged_network_key_update();
        }
    }

    start_over();

The driving events of the state machine are:

 * Setting of the thread key (provisioning)
 * Timeouts
 * Receiving network key sync updates

## Thread Key Generation ##

In cases where the thread network is created by an automated process
and will never have the need to be accessed using a user-entered
password, the `ThreadKey` may be generated using any appropriate
key generation mechanism. However, in cases where a password to the
network is desired, the following procedure MUST be used to derive
`ThreadKey`:

    ThreadKey   = PBKDF2(
                    HMAC-SHA256,
                    ThreadPassword,
                    NetworkName | NetworkXPANID,
                    4096,
                    THREAD_KEY_LENGTH
                )


Security Considerations
-----------------------

### Importance of proper NetworkKey generation ###

Typical sources of entropy, including hardware random number generators,
tend to produce less than one bit of entropy per bit. As a result, the
use of the following prodecure using HKDF to derive new network keys
is STRONGLY RECOMMENDED:

    NetworkKey    = HKDF(
                     LocalHardwareAddress | NetworkKeyLongIndex,
                     "NetworkKey",
                     RANDOM_DATA(THREAD_KEY_LENGTH*2),
                     THREAD_KEY_LENGTH
                    )

### Replay attack resistance ##

Replaying network key updates, even an old one, will have no effect on the
network. Replayed packets will be ignored by all nodes that have already
received a subsequent key update.

### Tamper resistance ###

Every byte in the network key update is authenticated using AES-CCM.
An attacker who does not have the thread key would be unable to change
parameters like age or key rotation period in a way that would be accepted
by other nodes.

### Auth-counter unnecessary ###

An auth-counter is unnecessary because each node can propose no more than one
single key per key index. This makes the nonce value of the hardware address
plus the key index sufficient to secure the key.

### Key-index rollover ###

While over a long enough period of time the key index will roll over, this
is in practice not a problem. You could rotate the key every hour for half
a million years before even getting close to reusing a key index. (Note, we
may want to consider changing the key index to a 24-bit number, which would
give us nearly two-thousand years of hourly key rotations before reusing
a key index. This would give us an extra byte for "future" use).


Example Operation
-----------------

Commissioning:

    Node A                                Node B
    ------                                ------
       |                                     |
       +-----------------------------------> |
       | 802.15.4 Beacon Request             |
       |                                     |
       |                                     |
       | <-----------------------------------+
       |                     802.14.5 Beacon |
       |                                     |
       :                                     :
         === [Weave/PANA Authentication] ===
       :                                     :
       |                                     |
       * ThreadKey obtained.                 |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update Request    |
       |                                     |
       |                                     |
       | <-----------------------------------+
       |         Bcast Network Key Update #1 |
       |                                     |
       * Key update #1 accepted              |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #1         |
       :                                     :


Resuming after missing key rotations:

    Node A                                Node B
    ------                                ------
       :                                     |
       :                                     |
       * Power On, at key #2                 |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update Request    |
       |                                     |
       |                                     |
       | <-----------------------------------+
       |         Bcast Network Key Update #5 |
       |                                     |
       * Key update #5 accepted              |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #5         |
       :                                     :


Two nodes resuming with out-of-sync keys:

    Node A                                Node B
    ------                                ------
       :                                     :
       :                                     :
       * Power On, at key #2                 :
       |                                     :
       +-----------------------------------> :
       | Bcast Network Key Update Request    :
       |                                     :
       |                                     :
       +-----------------------------------> :
       | Bcast Network Key Update #2         :
       |                                     :
       |                                     :
       |                 Power On, at Key #5 *
       |                                     |
       |                                     |
       | <---------------------------------- |
       |    Bcast Network Key Update Request |
       |                                     |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #2         |
       |                                     |
       |      Key update #2 ignored: too old *
       |                                     |
       | <-----------------------------------+
       |         Bcast Network Key Update #5 |
       |                                     |
       * Key update #5 accepted              |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #5         |
       :                                     :


Standard key rotation:

    Node A                                Node B
    ------                                ------
       |                                     |
       * Using key #5           Using key #5 *
       |                                     |
       :                                     :
       |                                     |
       |             Generates key update #6 *
       |                                     |
       | <-----------------------------------+
       |         Bcast Network Key Update #6 |
       |                                     |
       * Key update #6 accepted              |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #6         |
       |                                     |
       :                                     :
         ======= [Key Settling Period] =====
       :                                     :
       |                                     |
       + <---------------------------------> +
       |     Bcast Network Key Update #6     |
       |                                     |
       :                                     :


Key update conflict (assume #6.c calculates as preferable to #6.a):

    Node A                           Node B                            Node C
    ------                           ------                            ------
       |                                |                                 |
       * Generates key update #6.a      |                                 |
       |                                |                                 |
       |                                |                                 |
       +------------------------------> |                                 |
       | Bcast Network Key Update #6.a  |       Generates key update #6.c *
       |                                |                                 |
       |       Key update #6.a accepted *                                 |
       |                                |                                 |
       | <------------------------------+-------------------------------> |
       |  Bcast Network Key Update #6.a | Bcast Network Key Update #6.a   |
       |                                |                                 |
       |                                |   Key update #6.a ignored: pref *
       |                                |                                 |
       |                                | <-------------------------------+
       |                                |   Bcast Network Key Update #6.c |
       |                                |                                 |
       |                                * Key update #6.c accepted        |
       |                                |                                 |
       | <------------------------------+-------------------------------> |
       |  Bcast Network Key Update #6.c | Bcast Network Key Update #6.c   |
       |                                |                                 |
       * Key update #6.c accepted       |                                 |
       |                                |                                 |
       +------------------------------> |                                 |
       | Bcast Network Key Update #6.c  |                                 |
       |                                |                                 |
       :                                :                                 :
         ==== [Key Settling Period] ===   ==== [Key Settling Period] ====
       :                                :                                 :
       |                                |                                 |
       + <----------------------------> + <-----------------------------> +
       | Bcast Network Key  Update #6.c |  Bcast Network Key Update #6.c  |
       |                                |                                 |
       :                                :                                 :


Fork merging (different keys, same key index, one or both are settled):

    Node A                                Node B
    ------                                ------
       |                                     |
       * Using #5.a               Using #5.b *
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #5.a       |
       |                                     |
       |       Key update #5.a ignored: fork *
       |                                     |
       |             Generates key update #6 *
       |                                     |
       | <-----------------------------------+
       |         Bcast Network Key Update #6 |
       |                                     |
       * Key update #6 accepted              |
       |                                     |
       +-----------------------------------> |
       | Bcast Network Key Update #6         |
       |                                     |
       :                                     :
         ======= [Key Settling Period] =====
       :                                     :
       |                                     |
       + <---------------------------------> +
       |     Bcast Network Key Update #6     |
       |                                     |
       :                                     :


----------------------------------------------------------------------------

SCRATCHPAD


Overview
--------


### Justification for Key Classes ###

THIS SECTION IS A WORK IN PROGRESS.


Functional Explanation
----------------------


The current network key is encrypted the thread
key and distributed to other nodes without additional encryption.
This bundle of information is called the `NetworkKeySyncUpdate`.
Nodes wishing to join the network first broadcast a query for the
most recent `NetworkKeySyncUpdate`.  Once they receive it, they can
decrypt the network key and begin participating on the network
as a peer. Key rotation is also implemented using this
structure, and is described in more detail below.

Key Rotation
============

A node with infrastructure credentials that isn't the leader may
initiate a new rotation and become the leader when it notices that
the Thread leader has missed two or more key rotations.

The network keys are synchronized using `NetworkKeySyncUpdate`s. They are
formatted as follows:

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---.
    |                                                               |  N |
    +                Network Key Origin Address (EUI-64)            +  O |
    |                                                               |  N |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  C |
    |                     Network Key Long Index                    |  E |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---'
    |                                                               |  |
    +                                                               + <'
    |                      Encrypted Network Key                    |
    +                                                               +
    |          (AES128-CCM using key derived from ThreadKey)        |
    +                                                               +
    |                                                               |
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ---.
    |                                                               |  N |
    +                         Network Key MAC                       +  O |
    |                                                               |  N |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+  C |
    |            Key age in 1/10 seconds            |Rotate Interval|  E |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---'
    |                      Key age/interval MAC                     |  |
    +                                                               + <'
    |          (AES128-CCM using key derived from ThreadKey)        |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Notation
--------


Network Properties
------------------

A Thread network has the following long-term non-derived properties:

 * `NetworkName`: (16 bytes) Human-readable network identifier.
                  UTF-8 encoded.
 * `NetworkXPANID`: (8 bytes) Randomly-chosen value used for network
                    disambiguation. Must be changed whenever the thread
                    keys change.
 * One of the following:
   - `ThreadPassword`: (n Bytes) Key material used for deriving the
                            `ThreadKey`. Never directly stored
                            on a device on the network.
   - `ThreadKey`: On networks that don't have passwords,
                                this key is generated directly.

Additionally, a Thread network has the following short-term non-derived
properties:

 * `NetworkKeyLongIndex`: (4 Bytes) Identifies which key is being used.
                          Increments on key rotation.
 * `NetworkKey`: Randomly generated by the 'thread leader'. All other
                       network keys are ultimately derived from this key.
 * `ThreadLeaderHWAddr`: The hardware address of the device which last
                         initiated a successful key rotation.
 * `NetworkKeyAge`: The age of the network key. May be negative during the settling period.

The following properties are derived from the above properties:

    ThreadKey                   = PBKDF2(
                                    HMAC-SHA256,
                                    ThreadPassword,
                                    NetworkName | NetworkXPANID,
                                    4096,
                                    THREAD_KEY_LENGTH
                                )


Of all of these properties, the following properties are required
for a device to join an already established thread network as a
host without any additional user actions:

 * `NetworkName`
 * `ThreadKey`


Property Propagation
--------------------

The following properties are presented in network beacons:

 * `NetworkName`
 * `NetworkXPANID`

These properties will be discovered via un-secured MLE:

 * `NetworkKeySyncUpdate`, Which contains:
   - `NetworkKeyLongIndex`
   - `ThreadLeaderHWAddr`
   - `NetworkKeyAge`
   - `NetworkKey` (Encrypted By `ThreadKey`)

In addition to all of the above properties, a node stores these
additional properties:

 * `ThreadtKey`
 * `NetworkKey`

To change the administrative credentials for the network, you must
have `ThreadAdminKey`. `ThreadAdminPassword` SHOULD NOT be stored
directly by any node because it is only used indirectly thru
`ThreadAdminKey`. Whenever authentication credentials change, a new
randomly-generated `ThreadNonce` value should be chosen.


Security
========