com.sun.spot.peripheral.ota
Interface IOTACommandHelper

public interface IOTACommandHelper

IOTACommandHelper Each IOTACommand is passed an instance of this interface at execution to help it communicate with the remote SpotClient.

Field Summary

static int	COMMAND_OFFSET The offset into a command string at which the command-defining character is found
static int	DEVICE_SECURITY_LEVEL When a SPOT's admin command processor is receiving commands from a remote source, sensitive commands are verified using the digital signature of the SDK installation to which the SPOT is tied, and a timestamp to protect against replay attacks.
static int	PARAMETER_OFFSET The offset into a command string at which the parameters start

Method Summary

void	doDefaultCommand(String cmd, DataInputStream params) Invoke the default behaviour for one of the built-in commands.
String	getBootloaderIdentificationString()
DataOutputStream	getDataOutputStream() Answer a data output stream for sending information to the host.
boolean	isRemote()
void	receiveDataWithFlowControl(long dataSize, OutputStream outputStream) Receive bulk data with flow control.
void	replaceSuiteFile(DataInputStream params, String filename, int virtualAddress) Replace a suite file.
void	sendDataWithCRC(byte[] data, int offset, int length) Send data to the host with a CRC checksum appended.
void	sendErrorDetails(String msg) Notify the host that an error has occurred.
void	sendPrompt() Send a bootloader prompt to a remote SpotClient.

Field Detail

DEVICE_SECURITY_LEVEL

static final int DEVICE_SECURITY_LEVEL

When a SPOT's admin command processor is receiving commands from a remote source, sensitive commands are verified using the digital signature of the SDK installation to which the SPOT is tied, and a timestamp to protect against replay attacks. The sensitivity of commands is measured on a scale of 1 to 5, where lower numbers indicate more sensitive commands.

Informally, this scale is used as follows for the built-in commands:

• 1 commands which change state (start VM and set time)
• 2 commands which change the SPOT's future behaviour (flash app, flash lib, changes to the public key, and set startup command line params)
• 3 not used
• 4 commands that retrieve information (get system property, get config page, get file info)
• 5 commands for communication and identification (attention, closedown and blink (note that this is "closedown" as in "stop talking to this remote command source" rather than closing down the SPOT itself))

DEVICE_SECURITY_LEVEL defaults to 2, so that commands with a security level of 2 or lower are verified. You can rebuild the library with different values to change the security level.

See also ISignatureVerifier.MAX_CLOCK_SKEW which defines how many milliseconds the timestamp may be different from the SPOT's clock before a command fails verification.

Further notes: when apps and libraries are flashed, the command is verified, but not the data. Thus attackers could write arbitrary data to the flash. Note that a a subsequent attempt to start such an application would fail verification. Such techniques could be used for for DOS attacks, which aren't considered by the current security model.

See Also:

Constant Field Values

COMMAND_OFFSET

static final int COMMAND_OFFSET

The offset into a command string at which the command-defining character is found

See Also:

Constant Field Values

PARAMETER_OFFSET

static final int PARAMETER_OFFSET

The offset into a command string at which the parameters start

See Also:

Constant Field Values

Method Detail

sendPrompt

void sendPrompt()
                throws IOException

Send a bootloader prompt to a remote SpotClient. Normally used to indicate that the current command has been successfully processed. Call sendErrorDetails(String) if an error occurs.

Throws:

IOException

sendErrorDetails

void sendErrorDetails(String msg)
                      throws IOException

Notify the host that an error has occurred. If you call this, do not also call sendPrompt().

Parameters:

msg - the error message for the host

Throws:

IOException

getDataOutputStream

DataOutputStream getDataOutputStream()

Answer a data output stream for sending information to the host.

Returns:

the DataOutputStream

receiveDataWithFlowControl

void receiveDataWithFlowControl(long dataSize,
                                OutputStream outputStream)
                                throws IOException

Receive bulk data with flow control. This flow control ensures that failure to process data quickly doesn't cause buffering that uses excessive memory. See IAdminTarget.flashFile(Flashable, String, byte[]) inside the Spot Client code for more details of the corresponding host-side functionality.

Parameters:

dataSize -

outputStream -

Throws:

IOException

isRemote

boolean isRemote()

Returns:

whether the SPOT is locally or remotely connected to its host

replaceSuiteFile

void replaceSuiteFile(DataInputStream params,
                      String filename,
                      int virtualAddress)
                      throws IOException

Replace a suite file. This is a specialised helper method, only intended to be used in the implementation of the flash app and flash lib commands.

Parameters:

params - the params supplied with the IOTACommand

filename - the name of the FlashFile to replace (currently either "app" or "lib")

virtualAddress - the virtual address at which the FlashFile should be mapped after restart (currently either ConfigPage.APP_VIRTUAL_ADDRESS or ConfigPage.LIBRARY_VIRTUAL_ADDRESS)

Throws:

IOException

doDefaultCommand

void doDefaultCommand(String cmd,
                      DataInputStream params)
                      throws IOException

Invoke the default behaviour for one of the built-in commands. Intended for add-in commands that have replaced one of the default commands to extend its behaviour and want to invoke the default behaviour at some point.

Parameters:

cmd - the name of the command

params - the parameters that were supplied with the IOTACommand

Throws:

IOException

getBootloaderIdentificationString

String getBootloaderIdentificationString()

Returns:

the bootloader identification string that will be sent in response to synchronisation commands

sendDataWithCRC

void sendDataWithCRC(byte[] data,
                     int offset,
                     int length)
                     throws IOException

Send data to the host with a CRC checksum appended. See Utils.putDataWithCRC(DataOutputStream, byte[], int, int) and Utils.getDataWithCRC(DataInputStream).

Parameters:

data - byte array of data to send

offset - offset into data at which to start sending

length - number of bytes from data to send

Throws:

IOException