= SCU - Secure Code Update Cookbook = 

TODO:
* Upload SCU software package
* Test procedure on other environments

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

[[PageOutline(2-3,Table of Contents,inline)]]

== Introduction ==

== Architectural Overview ==

== Installation ==

=== Hardware and Software Requirements
Installing the SCU protocol requires the following hardware tools and software packages:

 * [http://www.ubuntu.com/ Linux PC] This guide has been tested using Ubuntu 8.10 and 10.04
 * [http://docs.tinyos.net/index.php/Getting_started TinyOS-2.x SDK] 
 * SCU software package
 * At least 2 TelosB sensor nodes


Appunti:
Config files in 
CONFIG_FILE=HOME_PATH+"/synapse-config.txt";
SECRET_KEYS_FILE=HOME_PATH+"/synapse-secret-keys.xml";
PUBLIC_KEYS_FILE=HOME_PATH+"/synapse-public-keys.bin";

Security bits configured during deployment

== Running a Secure Code Update session ==


=== 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
	These nodes will be given 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
* TinyOS SDK tools



==== SynapseKeyStorage tool

 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>]


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

==== KeyVolumeManagerClient tool

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

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

==== FlashManagerClient tool

 java net.tinyos.signet.FlashManagerClient [-comm <source>] [-verbose] [-progress] [-print-table] [-format] [-read <read_addr> <read_size> <output filename>] [-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>]

==== SecurityTaggerV0 tool

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

==== SecurityEncrypterV0 tool

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

==== Suino tool

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