trezor-firmware/protob/messages.proto

/*
	Messages for TREZOR communication

	Author: Marek Palatinus <slush@satoshilabs.com>

	Version: 0.6
*/


// Some sugar for easier handling in Multibit
option java_package = "org.multibit.hd.hardware.trezor.protobuf";
option java_outer_classname = "TrezorMessage";

import "types.proto";

/*
	Mapping between Trezor wire identifier (int) and protobuf message
*/
enum MessageType {
	MessageType_Initialize = 0 [(wire_in) = true];
	MessageType_Ping = 1 [(wire_in) = true];
	MessageType_Success = 2 [(wire_out) = true];
	MessageType_Failure = 3 [(wire_out) = true];
	MessageType_ChangePin = 4 [(wire_in) = true];
	MessageType_WipeDevice = 5 [(wire_in) = true];
	MessageType_FirmwareErase = 6 [(wire_in) = true];
	MessageType_FirmwareUpload = 7 [(wire_in) = true];
	MessageType_GetEntropy = 9 [(wire_in) = true];
	MessageType_Entropy = 10 [(wire_out) = true];
	MessageType_GetPublicKey = 11 [(wire_in) = true];
	MessageType_PublicKey = 12 [(wire_out) = true];
	MessageType_LoadDevice = 13 [(wire_in) = true];
	MessageType_ResetDevice = 14 [(wire_in) = true];
	MessageType_SignTx = 15 [(wire_in) = true];
	MessageType_SimpleSignTx = 16 [(wire_in) = true];
	MessageType_Features = 17 [(wire_out) = true];
	MessageType_PinMatrixRequest = 18 [(wire_out) = true];
	MessageType_PinMatrixAck = 19 [(wire_in) = true];
	MessageType_Cancel = 20 [(wire_in) = true];
	MessageType_TxRequest = 21 [(wire_out) = true];
	MessageType_TxInput = 23 [(wire_in) = true];
	MessageType_TxOutput = 24 [(wire_in) = true];
	MessageType_ApplySettings = 25 [(wire_in) = true];
	MessageType_ButtonRequest = 26 [(wire_out) = true];
	MessageType_ButtonAck = 27 [(wire_in) = true];
	MessageType_GetAddress = 29 [(wire_in) = true];
	MessageType_Address = 30 [(wire_out) = true];
	MessageType_EntropyRequest = 35 [(wire_out) = true];
	MessageType_EntropyAck = 36 [(wire_in) = true];
	MessageType_SignMessage = 38 [(wire_in) = true];
	MessageType_VerifyMessage = 39 [(wire_in) = true];
	MessageType_MessageSignature = 40 [(wire_out) = true];
	MessageType_PassphraseRequest = 41 [(wire_out) = true];
	MessageType_PassphraseAck = 42 [(wire_in) = true];
	MessageType_EstimateTxSize = 43 [(wire_in) = true];
	MessageType_TxSize = 44 [(wire_out) = true];
	MessageType_RecoveryDevice = 45 [(wire_in) = true];
	MessageType_WordRequest = 46 [(wire_out) = true];
	MessageType_WordAck = 47 [(wire_in) = true];	
	MessageType_DebugLinkDecision = 100 [(wire_debug_in) = true];
	MessageType_DebugLinkGetState = 101 [(wire_debug_in) = true];
	MessageType_DebugLinkState = 102 [(wire_debug_out) = true];
	MessageType_DebugLinkStop = 103 [(wire_debug_in) = true];
	MessageType_DebugLinkLog = 104 [(wire_debug_out) = true];
}

// ****************************************************************************
//
// Basic message
//

// Reset device to default state and ask for device details
//
// Response: Features
message Initialize {
}

// Response object for Initialize.
message Features {
	optional bytes vendor = 1;				// Name of the manufacturer, e.g. "bitcointrezor.com"
	optional uint32 major_version = 2;			// Major version of the device, e.g. 1
	optional uint32 minor_version = 3;			// Minor version of the device, e.g. 0
	optional uint32 bugfix_version = 4;
	optional bool bootloader_mode = 5;
	optional bytes device_id = 6 [(binary) = true];		// Device's unique identifier
	optional bool pin_protection = 7;			// True if Trezor is covered by PIN
	optional bool passphrase_protection = 8;		// True if node/mnemonic is covered by passphrase
	optional bytes language = 9;
	optional bytes label = 10 [(binary) = true];
	repeated CoinType coins = 11;
	optional bool initialized = 12;			// True if device cointains seed
}

// Overwrites only filled fields of the structure
message ApplySettings {
	optional bytes language = 1;
	optional bytes label = 2 [(binary) = true];
}

// Starts workflow for setting/changing the PIN
// Response: ButtonRequest, PinMatrixRequest
message ChangePin {
	optional bool remove = 1;	// Set True if want to remove PIN protection
}

// Test if device is live, device will send back the message on success
//
// Response: None or Success
message Ping {
	optional bytes message = 1;	// Message will be sent back in Success message
	optional bool button_protection = 2; // Ask for button press
	optional bool pin_protection = 3;	// Ask for PIN if set
	optional bool passphrase_protection = 4;	// Ask for passphrase if set
}

// Response object defining success of the previous request
message Success {
	optional bytes message = 1;	// May contain human readable description of the action or request-specific payload
}

// Response object defining failure of the previous request
message Failure {
	optional FailureType code = 1;		// May contain computer-readable definition of the error state
	optional bytes message = 2;		// May contain human-readable message of the error state
}

// Message can be sent by the *device* as a resopnse to any request.
// Device is waiting for HW button press. No action is required from computer
// Computer should respond with ButtonAck message or Cancel to cancel
// the original request.
message ButtonRequest {
	optional ButtonRequestType code = 1;
	optional bytes data = 2 [(binary) = true];
}

// Computer agrees to wait for HW button press.
message ButtonAck {
}

// Message can be sent by the *device* as a response to any request.
// Message asks computer to send back PinMatrixAck with the password encoded in pin matrix scheme.
//
// Response: PinMatrixAck, Cancel
message PinMatrixRequest {
	optional bytes message = 1;	// Human readable message
}

// Message is sent by the computer as a response to PinMatrixRequest previously sent by the device.
message PinMatrixAck {
	required bytes pin = 1;		// User must write down the password for accessing the device.
}

// Message is sent as a cancel response to ButtonRequest, PinMatrixRequest and PassphraseRequest
message Cancel {
}

// Device request encryption passphrase
message PassphraseRequest {
}

// Computer sends passphrase to device.
message PassphraseAck {
	required bytes passphrase = 1 [(binary) = true];
}

// Request a sample of random data generated by hardware RNG. May be used
// for tests of internal RNG.
//
// Response: PinMatrixRequest, Entropy, Failure
message GetEntropy {
	required uint32 size = 1;	// Size of randomly generated buffer
}

// Response to GetEntropy request contains random data generated by internal HRNG.
message Entropy {
	required bytes entropy = 1 [(binary) = true];	// Stream of generated bytes
}

// Ask device for public key corresponding of address_n path. This may be used for generating
// public keys on the computer independently to the device.
//
// Response: PublicKey, Failure
message GetPublicKey {
	repeated uint32 address_n = 1;
}

// Contains public key derived from device's seed.
message PublicKey {
	required HDNodeType node = 1;	// BIP32 node public key + chaincode
}

message GetAddress {
	repeated uint32 address_n = 1;	// Parameter for address generation algorithm to derive the address from the master node
	optional bytes coin_name = 2 [default='Bitcoin'];
}

message Address {
	required bytes address = 1;	// Bitcoin address in base58 encoding corresponding to GetAddress(n) call
}

// Request device to wipe all sensitive data and settings.
// Device will be turned to uninitialized state.
//
// Response: ButtonRequest
message WipeDevice {
}

// Load seed and related internal settings from computer to the device. Existing seed is overwritten.
//
// Response: Success, ButtonRequest, PinMatrixRequest, Failure
message LoadDevice {
	optional bytes mnemonic = 1;	// Seed encoded as a mnemonic (12 english words)
	optional HDNodeType node = 2;
	optional bytes pin = 3;		// Set PIN protection for important actions
	optional bool passphrase_protection = 4;
	optional bytes language = 5 [default='english'];
	optional bytes label = 6 [(binary) = true];
	optional bool skip_checksum = 7; // Do not test mnemonic for valid BIP39 checksum
}

// Request device to do full-reset, to generate new seed
// and ask user for new settings (PIN).
// Workflow is splitted into ResetDevice/EntropyRequest to be sure
// that entropy provided by device isn't calculated on base of computer provided
// entropy.
//
//
// Response: EntropyRequest, PinMatrixRequest, Failure
message ResetDevice {
	optional bool display_random = 1;	// If set, displays entropy generated by the device used
						// for generating the seed *before* asking
						// for additional entropy from computer
	optional uint32 strength = 2 [default=128]; // Strength of seed in bits
	optional bool passphrase_protection = 3;
	optional bool pin_protection = 4;
	optional bytes language = 5 [default='english'];
	optional bytes label = 6 [(binary) = true];						
}

// Asks for additional Entropy from host computer
message EntropyRequest {
}

// Provide additional entropy for seed generation function.
message EntropyAck {
	optional bytes entropy = 1 [(binary) = true];	// Recommended to provide 256 bits (32 bytes) of random data.
}

// Starts workflow of asking user for specific words of his mnemonic.
// This may be used for safe recovery of lost device
// using mnemonic on untrusted computer.
message RecoveryDevice {
	optional uint32 word_count = 1;	// How many words is in mnemonic sentence?
	optional bool passphrase_protection = 2;
	optional bool pin_protection = 3;
	optional bytes language = 4 [default='english'];
	optional bytes label = 5 [(binary) = true];
	optional bool enforce_wordlist = 6;	// Trezor enforces BIP39 wordlist						
}

// This message indicates that device is asking user for some word of his mnemonic.
// Position of the word is displayed only on device's internal display.
message WordRequest {
}

message WordAck {
	required bytes word = 1 [(binary)=true];	// One word of mnemonic on asked position
}

// ****************************************************************************
//
// Messages related to transaction signing
//

message SignMessage {
	repeated uint32 address_n = 1;
	required bytes message = 2 [(binary) = true];
	optional bytes coin_name = 3 [default='Bitcoin'];
}

message VerifyMessage {
	optional bytes address = 1;
	optional bytes signature = 2 [(binary) = true];
	optional bytes message = 3 [(binary) = true];
}

message MessageSignature {
	optional bytes address = 1;
	optional bytes signature = 2 [(binary) = true];
}

// Estimate size of the transaction
// This call behaves exactly like SignTx,
// which means that it can ask for TxInput and TxInput.
// This call is non-blocking (except possible PassphraseRequest
// to unlock the seed) and returns estimated size of transaction
// in bytes.
//
// Response: TxRequest, TxSize, Failure
message EstimateTxSize {
	required uint32 outputs_count = 1;		// Count of outputs of the transaction
	required uint32 inputs_count = 2;		// Count of inputs of the transaction
	optional bytes coin_name = 3 [default='Bitcoin'];
}

// Result of EstimateTxSize
message TxSize {
	optional uint32 tx_size = 1;	// Size of transaction in bytes
}

// Request the device to sign the transaction
//
// Response: TxRequest, PinMatrixRequest, Failure
message SignTx {
	required uint32 outputs_count = 1;		// Count of outputs of the transaction
	required uint32 inputs_count = 2;		// Count of inputs of the transaction
	optional bytes coin_name = 3 [default='Bitcoin'];
}

// Request a simplified workflow of signing.
// This method doesn't support streaming,
// so there may be hardware limits
// in number of inputs and outputs.
//
// This simplified workflow should not be used
// in production, it is designed mainly for debug purposes.
//
// When everything is fine, Success.message contains
// serialized transaction.
//
// Response: Success, PinMatrixRequest, Failure
message SimpleSignTx {
	repeated TxInputType inputs = 1;
	repeated TxOutputType outputs = 2;
	repeated TransactionType transactions = 3;
	optional bytes coin_name = 4 [default='Bitcoin'];
}

// Sent by the device as a response for SignTx. Device asks for information for signing transaction.
// If request_index is set, device asks for TxInput/TxOutput message (depends on request_type)
// with details of index's input.
// If signed_index is set, 'signature' contains signed input of signed_index's input.
message TxRequest {
	optional int32 request_index = 1;			// If >=0, device expects TxInput/TxOutput message from the computer
	optional RequestType request_type = 2;		// Ask for TxInput or TxOutput?
	optional int32 signed_index = 3;			// If >=0, 'signature' contains signed input of this input
	optional bytes signature = 4 [(binary) = true];		// If signed_index>=0, represent signature of the signed_index input
	optional bytes serialized_tx = 5 [(binary) = true];	// Part of serialized and signed transaction
}

// Transaction onput for SignTx workflow. It is response to TxRequest message sent by device.
//
// Response: TxRequest, Failure
message TxInput {
	required TxInputType input = 1;
}

// Transaction output for SignTx workflow. It is response to TxRequest message sent by the device.
// This contains all data necessary to build transaction output (script_pubkey).
message TxOutput {
	required TxOutputType output = 1;
}

// ****************************************************************************
//
// Bootloader messages
//

message FirmwareErase {
}

message FirmwareUpload {
	required bytes payload = 1 [(binary) = true];		// Firmware to flash into device
}

// ****************************************************************************
//
//	Debug* messages are used only on DebugLink interface (separated from USB HID)
//

// Virtually "press" the button on the device.
// Message is available only on debugging connection and device must support "debug_link" feature.
//
// Response: Success
message DebugLinkDecision {
	required bool yes_no = 1;				// True for "confirm", False for "cancel"
}

// When sent over debug link connection, computer asks for some internal information of the device.
//
// Response: DebugLinkState
message DebugLinkGetState {
}

// Response object reflecting device's current state. It can be received only over debug link connection.
message DebugLinkState {
	optional bytes layout = 1 [(binary) = true];		// Raw buffer of display
	optional bytes pin = 2;					// Current PIN, blank if PIN is not set/enabled
	optional bytes matrix = 3;				// Current PIN matrix
	optional bytes mnemonic = 4;				// current mnemonic format
	optional HDNodeType node = 5;				// current node (BIP32 format)
	optional bool passphrase_protection = 6;
	optional bytes word = 7;		// What word is on display in RecoveryDevice/ResetDevice workflow
	optional int32 word_pos = 8;	// Which word of mnemonic do the device expect
	optional bytes entropy = 9;		// Return current entropy of ResetDevice workflow
}

// Ask device to shutdown/restart
message DebugLinkStop {
}

message DebugLinkLog {
	optional uint32 level = 1;
	optional bytes bucket = 2;
	optional bytes text = 3;
}