Skip to main content

Security Requirements

When the Helium Community passed HIP19, it was made clear that open and easy access to the swarm_key is not permitted at this time. This helps insure that the Miner is running on real hardware and increases the barriers to dishonest actors.

info

The swarm_key is an ECC Compact Key used by the Miner to sign all blockchain and libp2p transactions. The three word animal name (e.g. angry-purple-tiger) is actually derived from the public key of the swarm_key.

While formalizing the audit process, the Helium Foundation has determined that the only approved approach to guaranteeing this at this time is using the ECC608 to generate and store the key during manufacturing. Other approaches are possible, but they would require case-by-case consideration and the potentially a third-party audit.

Securing the swarm_key with the ECC608

Helium has open-sourced their ECC608 provisioning utility from their own manufacturing process here. By using this utility, not only do you automatically comply with the ECC608 provisioning process, but you also create compatability with the Helium Miner with no modifications (other than some configuration to the Docker overlay).

You are free to compile the gateway_mfr repository from source or use the Docker image available here (for aarch64 only).

You will want to do the following:

docker load -i gateway_mfr.tar
docker run -d --device /dev/i2c-1 --name provision gateway_mfr:arm64

With the Docker container running, you are now able to interact with the utility and complete the provisioning.

Throughout this process, you might get some errors because the ECC608 can frequently go to sleep. You may see something like this:

docker exec provision gateway_mfr ecc onboarding
ecc_asleep

It is just fine to liberally retry commands until they work.

First, verify that the ECC608 is untouched:

$ docker exec provision gateway_mfr ecc test
+--------------------+-------------------------------+
|        name        |            result             |
+--------------------+-------------------------------+
|     serial_num     |              ok               |
|{zone_locked,config}|       {error,unlocked}        |
| {zone_locked,data} |       {error,unlocked}        |
|    slot_config     |{error,{invalid_slot_config,0}}|
|     key_config     |{error,{invalid_key_config,3}} |
|     miner_key      |{error,ecc_response_exec_error}|
+--------------------+-------------------------------+

This is a failing test, which is good in this case. Next, you will want to run the actual provision command:

$ docker exec provision gateway_mfr ecc provision
{zone_locked,[{config,true},{data,true}]}
+--------------------+------+
|        name        |result|
+--------------------+------+
|     serial_num     |  ok  |
|{zone_locked,config}|  ok  |
| {zone_locked,data} |  ok  |
|    slot_config     |  ok  |
|     key_config     |  ok  |
|     miner_key      |  ok  |
+--------------------+------+

You can run the test from the end of the provision command to verify the table at any time:

docker exec provision gateway_mfr ecc test
+--------------------+------+
|        name        |result|
+--------------------+------+
|     serial_num     |  ok  |
|{zone_locked,config}|  ok  |
| {zone_locked,data} |  ok  |
|    slot_config     |  ok  |
|     key_config     |  ok  |
|     miner_key      |  ok  |
+--------------------+------+

And finally, you will want to extract the onboarding_key which is also called the Miner's "swarm_key":

docker exec provision gateway_mfr ecc onboarding
112xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This is what you will want to provide to the onboarding server.