wiki:SCU

SCU - Secure Code Update Cookbook

This document includes instructions how to install and to run the Secure Code Update protocol.

Table of Contents

  1. Introduction
  2. Installation
    1. Hardware and Software Requirements
  3. Running a Secure Code Update session
    1. Shortest HOWTO
    2. Short HOWTO
    3. Detailed HOWTO
  4. Native island integration
  5. Possible demonstration

Introduction

Updating the code running on Wireless Sensor Network (WSN) nodes is a necessary service, which can be used to remove bugs or to add new functionalities after the sensors have been deployed.

In open, public, untrusted, or even hostile environments, protecting the code update operation against adversarial interference is an essential requirement. Otherwise, an insecure code update may provide an adversary with a backdoor rendering any security mechanism useless, and may even become a serious risk for the owner.

There are mainly three security aspects to be considered in the desing of a Secure Code Update (SCU) mechanism. First, a SCU mechanism shall only allow the load of authentic code images into the nodes' memory. Second, a SCU mechanism must detect the dissemination of a modified or corrupted code image as early as possible. The need is to avoid unnecessary energy consumption due to the propagation of a corrupted image over multiple hops and to the re-transmission of its pages. Finally, a SCU mechanism must keep the secrecy of a code image being disseminated. The need is to prevent eavesdroppers from gaining information on the content of the code image.

Installation

Hardware and Software Requirements

Installing the SCU protocol requires the following hardware tools and software packages:

  • At least 2 TelosB sensor nodes

We assume that the installation PC is running a Linux operating system and the TinyOS-2.x has been installed and configured properly on it. We skip the installation of TinyOS here and refer to TinyOS-2.x if needed. We describe the installation and configuration steps in the following for the Ubuntu operating system.

This is the structure of the content of the SCU software package:

  • 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.
    • scu.extra
      TinyOS extra required to compile any application you want to disseminate.

Running a Secure Code Update session

First of all the application that you want to disseminate must be built, using the given scu extra. So the file scu.extra must be moved into the support/make directory under the root directory of your TinyOS 2.x installation.

Then you can compile the application you want to disseminate by moving into the application directory and running

make telosb scu

At this point you can follow one of the following HOWTOs:

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 retrieve 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.

Complete example

The following script (where the two foreach loops over the nodes are not valid bash syntax, but just pseudocode) executes all the operations necessary for the network deployment, and for a subsequent Secure Code update operation.

#APPLICATION_IHEX=path to the ihex file of the application to disseminate. This must have been obtained using the scu extra
#APP_ID=Define a 16-bit, hexadecimal ID for the application
#BS_ID=Id of the base station node
#BS_LOCATION=Location of the base station node, e.g./dev/ttyUSB0

source init_variables_scu.sh 

# Compile tools

cd scu-contrib/apps/KeyVolumeManager/
make telosb
cd -

cd scu-contrib/apps/FlashManager/
make telosb
cd -

# Generate keys

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

# Store keys on nodes

foreach node; do
        cd scu-contrib/apps/KeyVolumeManager/
        make telosb reinstall.$NODE_ID bsl,$NODE_LOCATION
        cd -

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

# Install Synapse on nodes
cd scu-contrib/apps/Synapse/
make SECURITY_BITS=80 SECURITY_BITS_LOG=7 IS_NODE=TRUE USE_AUTHENTICATION=TRUE USE_CI_ENCRYPTION=TRUE USE_DOS_PROTECTION=TRUE telosb
foreach node; do
        make telosb reinstall.$NODE_ID bsl,$NODE_LOCATION
done
cd -

# Extract binary from ihex
scu-contrib/tos/lib/signet/synapse/scripts/ihex_to_binary.sh $APPLICATION_IHEX

# Encrypt binary
java net.tinyos.signet.SecurityEncrypterV0 $HOME/synapse-secret-keys.xml $APPLICATION_IHEX.compact.binary $APPLICATION_IHEX.encrypted

# Generate authentication tags
java net.tinyos.signet.SecurityTaggerV0 -sign $HOME/synapse-secret-keys.xml 800 $APPLICATION_IHEX.encrypted $APPLICATION_IHEX.signed #[-update-keys [-low-overhead]] [-use-key-refresh] ]

# Upload on Base station, formatting flash
cd scu-contrib/apps/FlashManager/
make telosb reinstall.$BS_ID bsl,$BS_LOCATION
cd -
java net.tinyos.signet.FlashManagerClient -comm serial@$BS_LOCATION:telosb -progress -print-table -format -writefile $APP_ID $APPLICATION_IHEX.signed $(scu-contrib/tos/lib/signet/synapse/scripts/get_tags_size $APPLICATION_IHEX.signed $APPLICATION_IHEX.encrypted)

# Install Synapse on Base station
cd scu-contrib/apps/Synapse/
make SECURITY_BITS=80 SECURITY_BITS_LOG=7 IS_BASESTATION=TRUE USE_AUTHENTICATION=TRUE USE_CI_ENCRYPTION=TRUE USE_DOS_PROTECTION=TRUE telosb
make telosb reinstall.$BS_ID bsl,$BS_LOCATION
cd -

# Format network
java net.tinyos.signet.Suino -comm serial@$BS_LOCATION:telosb --prepare
sleep 3 # Wait for command execution

java net.tinyos.signet.Suino -comm serial@$BS_LOCATION:telosb --format
sleep 80 # Wait 80s for format execution

# Disseminate application
java net.tinyos.signet.Suino -comm serial@$BS_LOCATION:telosb --transfer $APP_ID
sleep 3
# Load disseminated application
java net.tinyos.signet.Suino -comm serial@$BS_LOCATION:telosb --prepare
sleep 3 # Wait for command execution
java net.tinyos.signet.Suino -comm serial@$BS_LOCATION:telosb --load $APP_ID

Native island integration

Secure Code Update technology can be integrated with the SENSEI native gateway providing a web service resource able to handle the dissemination of new software images.

The web service needs to be defined to accept the POST of a new image in a defined XML format containing, besides the encrypted binary and the signature of the image, other management metadata; the web service itself reacts to the reception of the new code image by uploading it to the SCU BaseStation? and starting the dissemination.

Upon completion of the dissemination a status code coherent with the result of the operation will be returned by the web service to the client.

Possible demonstration

A demonstration of the SCU module can be performed in the following way:

  • Deploy the network that will be used in the demonstration by installing in every node the keys and by formatting their flash memory.
  • Decide which applications should be disseminated
  • Spread the nodes across the space used for the demonstration
  • Disseminate one at a time all the applications and demonstrate each one's functionality
  • Once all the applications are disseminated it is possible to switch between any of those applications without disseminating them again.
Last modified 11 years ago Last modified on Feb 28, 2011, 4:32:47 PM