Z3 network: join with install-code-derived link key

by <a href="http://community.silabs.com/t5/Welcome-and-Announcements/Community-Ranking-System-and-Recognition-Program/m-p/140490#U140490"><font color="#000000"><font size="2">Hero Employee</font></font> </a> yuxiao on ‎03-10-2017 01:55 PM - edited on ‎03-20-2017 05:24 PM by <a href="http://community.silabs.com/t5/Welcome-and-Announcements/Community-Ranking-System-and-Recognition-Program/m-p/140490#U140490"><font color="#000000"><font size="2">Hero Employee</font></font> </a> RonB

In this exercise, you can follow these steps using command line options to join a Z3 Light to a Z3 Gateway using an install-code-derived link key.


We assume that you have already built a SoC-based Z3 Light sample app (default configurations), and a Z3 Gateway app on an NCP+Host setup (make sure the link key table size, which can be configured under the "NCP Configuration" plugin on the host side, is at least one entry) based on EmberZNet stack version 5.8.1 or higher. You can use either the EM358x or EFR32MG platform. 


1. First make sure the Z3 Light is not on any network (issue "network leave" if it is).

2. Come up with an install codes of 6, 8, 12 or 16 bytes. In this example, I used 1122334455667788.

Save this into a text file in this format:

Install Code: 1122334455667788

In this example I named the file "inst_001.txt" 

3. Following the instructions in AN714, specifically sections 4 and 5, to program this install code to the Z3 Light device.

On my EFR32MG1 radio module on WSTK with serial # 440030469, the command (run it in a generic Windows command prompt from a directory where your Simplicity Commander is installed) is:

>commander flash –-tokengroup znet –-tokenfile inst_001.txt -–serialno 440030469

You will see the follwoing output:

Writing 2048 bytes starting at address 0x0fe04000
Comparing range 0x0FE04000 - 0x0FE047FF (2 KB)
Erasing range 0x0FE04000 - 0x0FE047FF (1 sector, 2 KB)
Programming range 0x0FE04240 - 0x0FE0435F (288 Bytes)
Programming range 0x0FE04360 - 0x0FE04487 (296 Bytes)
Verifying range 0x0FE04000 - 0x0FE047FF (2 KB)


To verify the install code, run the following: 

>commander tokendump –-tokengroup znet -–serialno 440030469


The output will have the following important sections:

# The token data can be in one of three main forms: byte-array, integer, or string.
# Byte-arrays are a series of hexadecimal numbers of the required length.
# Integers are BIG endian hexadecimal numbers.
# String data is a quoted set of ASCII characters.
# MFG_EMBER_EUI_64 : E3A907FEFF570B00

#'MFG_INSTALLATION_CODE (Smart Energy Install Code)' token group
# Install Code Flags : 0x0000
Install Code : 1122334455667788
# CRC : 0xF74A


4. On the Z3 Gateway, form a centralized network with Z3 security using this command on the CLI:

plugin network-creator start 1


5. Derive a link key from the install code, and store that into the Z3 Gateway which acts as the Trust Center for the centralized network. For example:

option install-code 0 {00 0B 57 FF FE 07 A9 E3} {11 22 33 44 55 66 77 88 4A F7}

The first argument after "option install-code" is the link key table index.


The next argument is the EUI64 of the joining node (i.e. Z3 Light).
Tip: you can find this information by running the "info" command on Z3 Light; note the string "node [(>)000B57FFFE07A9E3]". (Your EUI64 will be different from mine, though!).

You can also get it in the EUI64 from the output of the token dump, but note that it is outputted in little endian format.  You will need to reverse the bytes to get the proper output.


The last argument is the install code with the 2-byte CRC appended at the end.

Tip: if you don't want to calculate the CRC yourself, you can simply find out from running the "tokendump" command in step 3 above. Note the CRC displayed just below the install code is outputted in little endian format and reverse the bytes to big-endian when you feed it to the "option install-code ..." CLI. BTW, the white spaces inside the curly brackets are not mandatory and you can do a straight copy/paste without the spaces; they just help to view the data a little better.

If the link key is added successfully, you can type the "keys print" CLI to see it. Your link key table should look something like this:

Now you see what the actual link key is that you derived from the install code. You will also see the network key displayed.


6. Optional step which I highly recommend: at this point, you have all the information the Network Analyzer would need to decrypt future transactions between the Z3 Gateway and Z3 Light. Enter both the network key and the link key to the list of security keys under Network Analyzer decoding preferences. Start a new network capture from the Z3 Light and/or Z3 Gateway. If you are in a "noisy" environment, you may choose to only capture on the specific PAN.

7. Now set the transient link key (the same link key that you derived from the install code) on the Trust Center:

plugin network-creator-security set-joining-link-key {eui64} {linkkey}

For example:

plugin network-creator-security set-joining-link-key {00 0B 57 FF FE 07 A9 E3} {41 61 8F C0 C8 3B 0E 14 A5 89 95 4B 16 E3 14 66}

8. Open the Gateway network for joining:

plugin network-creator-security open-network

9. Then on the joining device enter this CLI to use the Network Steering plugin to join the network:

plugin network-steering start 0

With the transient link key being used, it should join the network. If you have started a network capture in step 6, now you should see the full transactions live, and see the Z3 Light is initially let on the network using the transient link key. The TC transports the network key encrypted with the transient link key in a "Transport Key (NWK)" frame. Subsequently, the Z3 Light requests a new link key, and the TC transports the link key in a "Transport Key (Link)" frame.