wiki:SCU

Version 10 (modified by fornasiero, 13 years ago) (diff)

--

Folder structure

scu
 |
 +-- lib
 |     Contains Bouncy Castle java library
 |
 +-- scu-contrib
 |     Contains developed TinyOS code for Secure Code Update
 |
 +-- tinyos-2.x
 |     Contains a minimal TinyOS source tree, necessary for compilation and running of the developed software
 |
 +-- init_variables.sh
 |      Inits environment variables
 +-- quick_start.sh
        Simple script that execute a guided step-by step deployment, followed by a Secure Code Update operation.

Shortest HOWTO:

Execute quick_start.sh and follow instructions. The scripts executes automatically all the steps described below, asking for the path and the id of the application that must be disseminated

Short HOWTO:

  • First of all, open a shell console in this folder and init the environment variables executing

source init_variables.sh

  • Then you can compile the tools used for Secure Code Update, executing

java net.tinyos.signet.SecureSynapseInterface? -compile-tools

  • Now the nodes of the network can be deployed, i.e., the keys necessary for security operations must be installed in the nodes' external flash memory, and the Synapse bootloader along with SecureSynapse? must be installed in the nodes' application flash memory. The command to execute is

java net.tinyos.signet.SecureSynapseInterface? -deploy <auth. security param.> <T-TimeSA T parameter> <encryption security param> <DoS protection security param> [-keep-keys] [-use-authentication] [-use-encryption] [-use-dos-protection]

A typical setting is -deploy 80 30 128 128 -use-authentication -use-encryption -use-dos-protection.

This command will generate the keys, and install all necessary stuff on the nodes detected by motelist command. The keys will be stored in the following files: $HOME/synapse-secret-keys.xml , $HOME/synapse-public-keys.bin . These nodes will be given an id starting from 1, in order of serial number.

  • Now all nodes can be disconnected from the pc, keeping the base station connected. If more than 1 nodes are connected, the one with the minimum serial number will be used as a base station. The command to execute in order to start the dissemination is

java net.tinyos.signet.SecureSynapseInterface? -dissem <application path> <block size> <application id> [-use-key-refresh [-low-overhead]] [-format-nodes] [-format-bs] [-use-authentication] [-use-encryption] [-use-dos-protection]

Block size MUST currently be set to 800 to match Synapse configuration. Application path points to the directory containing the "build" directory of the application to disseminate. Application ID is a hexadecimal, 16-bit long, user-defined ID. If "-use-key-refresh" option is given, some keys are disseminated in order to replace the keys used for the signature. If "-low-overhead" option is given, just a fraction of the keys are updated, in order to minimize the overhead. Nodes must be formatted after deployment, using the "-format-nodes" option. The base station must be formatted at least the first time, using the option "-format-bs".

So a typical setting for the first invocation of this command is

java net.tinyos.signet.SecureSynapseInterface? -dissem <app path> 800 1 -format-bs -format-nodes -use-authentication -use-encryption -use-dos-protection

The application to disseminate will be transfered to the base station node, SecureSynapse? will be installed and first of all the nodes will be formatted, then the dissemination will start. When the dissemination finishes, the disseminated application will be loaded.

Detailed HOWTO

SecureSynapseInterface? is just a high-level interface that manages in a parallel fashion all nodes connected to the pc. Lower level control tools are:

  • Java application: net.tinyos.signet.SynapseKeyStorage?
  • Java application: net.tinyos.signet.KeyVolumeManagerClient?
  • Java application: net.tinyos.signet.FlashManagerClient?
  • Java application: net.tinyos.signet.SecurityTaggerV0
  • Java application: net.tinyos.signet.SecurityEncrypterV0
  • Java application: net.tinyos.signet.Suino
  • Bash script: ihex_to_binary.sh
  • Bash script: get_tags_size.sh
  • TinyOS SDK tools

SynapseKeyStorage? tool

This tool manages the private key storage and permits to export the public keys. This tool generates and uses the configuration file "$HOME/synapse-config.txt". The invocation syntax is the following:

 java net.tinyos.signet.SynapseKeyStorage [-generate <# of security bits for authentication> <#of uses per key> <# of security bits for encryption> <# of security bits for DoS protection> <filename>] [-get-public <key storage filename> <destination filename>]

If the "generate" option is given, the private keys are generated, depending on the given security parameters and stored in the given file. If the "get-public" options is given, the public keys are generated from the private keys and stored in the given file.

Typically the command is invoked as following

 java net.tinyos.signet.SynapseKeyStorage -generate 80 30 128 128 $HOME/synapse-secret-keys.xml
 java net.tinyos.signet.SynapseKeyStorage -get-public $HOME/synapse-secret-keys.xml $HOME/synapse-public-keys.bin

KeyVolumeManagerClient? tool

This tool is used to store and retrieved keys from the nodes' flash memory, communicating with the TinyOS application KeyVolumeManager?, which must be installed on the node in order to use this tool. The invocation syntax is the following:

 java net.tinyos.signet.KeyVolumeManagerClient [-comm <source>] [-verbose] [-progress] [-upload <public key file>] [-download <output file>]

If the "upload" option is given, the public keys contained in the given file are uploaded in the node. If the "download" option is given, the public keys contained in the node are downloaded in the given file.

An example of invocation is the following

 java net.tinyos.signet.KeyVolumeManagerClient -comm serial@/dev/ttyUSB0:telosb -progress -upload $HOME/synapse-public-keys.bin

FlashManagerClient? tool

This tool is used to format, store and retrieve applications from the nodes' flash memory. This tool communicates with the TinyOS application FlashManager?, which must be installed on the node in order to use this tool. The invocation syntax is the following:

 java net.tinyos.signet.FlashManagerClient [-comm <source>] [-verbose] [-progress] [-print-table] [-format] [-readid <partition ID,4 digits radix 16> <output file>] [-writefile <desired partition ID, 4 digits radix 16> <local filename> <program start offset radix, 4 digits radix 16>]

If the "print-table" option is given, then the partition table is printed on standard output. If the "format" option is given, then the node's flash is formatted. If the "readid" option is given, then the partition with given ID is read and stored in the given file. If the "writefile" option is given, then the given file is stored in a new partition with the given ID. Multiple partition with the same ID can coexists on the node's flash memory, and the last will be always used when required. The program start offset indicates the offset at the beginning of the file where the executable code starts (this is useful when the security tags are prefixed to the application code).

SecurityTaggerV0 tool

This tool is used to generate the security tags necessary for the authentication functionality. The invocation syntax is the following:

 java net.tinyos.signet.SecurityTaggerV0 [-sign <keys filename> <block size> <inputfile> <outputfile> [-update-keys [-low-overhead]] [-use-key-refresh] ]

The only command executable with this tool is the "sign" command. The "keys filename" parameter is the name of the file containing the private keys (i.e. the one generated with the SynapseKeyStorage? tool). Block size must be 800, as defined in the Synapse application. Inputfile is the file containing the binary code of the application. This file is obtained using the ihex_to_binary script. Outputfile is the generated file.

SecurityEncrypterV0 tool

This tool is used to encrypt a file, using the AES block cipher in OFB operation mode. The invocation syntax is the following:

 java net.tinyos.signet.SecurityEncrypterV0 <private keys file> <inputfile> <outputfile>

Suino tool

This tool is used in order to communicate with the Synapse Base Station. So the Synapse application, compiled with the IS_BASESTATION flag, must be installed on the node in order to communicate with this tool. The invocation syntax is the following:

 java net.tinyos.signet.Suino [-comm <source>] < --prepare | --format | --reset | --load <app.id> | --transfer <app.id> | --alive >

Commands description:

  • Prepare: stops dissemination, prepares the network for other commands as format, reset or load.
  • Format: all nodes in the network (except the base station) format their flash memory (Synapse is then re-stored). Use FlashManager? to format the base station.
  • Reset: all nodes in the network reboot.
  • Load: all nodes in the network (except the base station) load the application corresponding to the given id.
  • Transfer: the application with the given ID in the base station's flash memory is disseminated. The command returns when all the nodes in the network ended receiving the application.
  • Alive: check whether Synapse Base Station is installed. This command waits indefinitely for a response from the node, which should be immediate.

Bash tools

The ihex_to_binary script has the following invocation syntax:

 ihex_to_binary.sh <ihex file>

where "ihex file" is the application to disseminate, in ihex format. This tool generates a <ihex file>.compact.binary file, which contains the application to disseminate, in binary format.

The get_tags_size script has the following invocation syntax:

 get_tags_size.sh <tagged file> <untagged file>

where <untagged file> usually is the application binary file, and <tagged file> is the file obtained using the SecurityTaggerV0 tool. This tool simply calculates the difference between the size of these two files, to obtain the size of the security tags. This size can then be used as the parameter to provide to the FlashManager? tool.