arno/trezor-firmware
1
0
Fork 0
mirror of https://github.com/trezor/trezor-firmware.git synced 2025-01-24 06:11:06 +00:00
Code Issues Releases Wiki Activity

add documentation, remove TxInput/TxOutput messages, use TxAck instead

Browse Source
This commit is contained in:
Pavol Rusnak 2014-03-25 19:20:36 +01:00
parent df45b3cf06
commit 52f360ab12
5 changed files with 450 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
protob/config.proto
View File

@ -1,29 +1,29 @@
// /**
// This file defines the configuration format for initializing the * Configuration format for TREZOR plugin
// Trezor browser plugin. *
// * @author Marek Palatinus <slush@satoshilabs.com>
* @version 1.0
*/
import "google/protobuf/descriptor.proto"; import "google/protobuf/descriptor.proto";
/**
* Device Descriptor used in Configuration
*/
message DeviceDescriptor { message DeviceDescriptor {
optional uint32 vendor_id = 1; optional uint32 vendor_id = 1; // USB vendor ID
optional uint32 product_id = 2; optional uint32 product_id = 2; // USB product ID
optional bytes serial_number = 3; optional string serial_number = 3; // USB serial number
optional bytes path = 4; optional string path = 4; // USB device path
} }
/**
* Plugin Configuration
*/
message Configuration { message Configuration {
// regexes of allowed/forbidden urls repeated string whitelist_urls = 1; // allowed URLs for plugin
repeated bytes whitelist_urls = 1; repeated string blacklist_urls = 2; // forbidden URLs for plugin
repeated bytes blacklist_urls = 2; required google.protobuf.FileDescriptorSet wire_protocol = 3; // compiled specification of write protocol (serialized using "protoc -o")
repeated DeviceDescriptor known_devices = 4; // descriptors of allowed devices
// compiled specification of the wire protocol, serialized optional uint32 valid_until = 5; // expiration timestamp
// FileDescriptorSet can be generated with `protoc -o`
required google.protobuf.FileDescriptorSet wire_protocol = 3;
// descriptors of allowed devices
repeated DeviceDescriptor known_devices = 4;
// timestamp of expiration
optional uint32 valid_until = 5;
} }

558
protob/messages.proto
View File

@ -1,21 +1,19 @@
/* /**
Messages for TREZOR communication * Messages for TREZOR communication
*
* @author Marek Palatinus <slush@satoshilabs.com>
* @version 0.6
*/
Author: Marek Palatinus <slush@satoshilabs.com> // Sugar for easier handling in Multibit
Version: 0.6
*/
// Some sugar for easier handling in Multibit
option java_package = "org.multibit.hd.hardware.trezor.protobuf"; option java_package = "org.multibit.hd.hardware.trezor.protobuf";
option java_outer_classname = "TrezorMessage"; option java_outer_classname = "TrezorMessage";
import "types.proto"; import "types.proto";
/* /**
Mapping between Trezor wire identifier (int) and protobuf message * Mapping between Trezor wire identifier (uint) and a protobuf message
*/ */
enum MessageType { enum MessageType {
MessageType_Initialize = 0 [(wire_in) = true]; MessageType_Initialize = 0 [(wire_in) = true];
MessageType_Ping = 1 [(wire_in) = true]; MessageType_Ping = 1 [(wire_in) = true];
@ -38,8 +36,7 @@ enum MessageType {
MessageType_PinMatrixAck = 19 [(wire_in) = true]; MessageType_PinMatrixAck = 19 [(wire_in) = true];
MessageType_Cancel = 20 [(wire_in) = true]; MessageType_Cancel = 20 [(wire_in) = true];
MessageType_TxRequest = 21 [(wire_out) = true]; MessageType_TxRequest = 21 [(wire_out) = true];
MessageType_TxInput = 23 [(wire_in) = true]; MessageType_TxAck = 22 [(wire_in) = true];
MessageType_TxOutput = 24 [(wire_in) = true];
MessageType_ApplySettings = 25 [(wire_in) = true]; MessageType_ApplySettings = 25 [(wire_in) = true];
MessageType_ButtonRequest = 26 [(wire_out) = true]; MessageType_ButtonRequest = 26 [(wire_out) = true];
MessageType_ButtonAck = 27 [(wire_in) = true]; MessageType_ButtonAck = 27 [(wire_in) = true];
@ -56,7 +53,7 @@ enum MessageType {
MessageType_TxSize = 44 [(wire_out) = true]; MessageType_TxSize = 44 [(wire_out) = true];
MessageType_RecoveryDevice = 45 [(wire_in) = true]; MessageType_RecoveryDevice = 45 [(wire_in) = true];
MessageType_WordRequest = 46 [(wire_out) = true]; MessageType_WordRequest = 46 [(wire_out) = true];
MessageType_WordAck = 47 [(wire_in) = true]; MessageType_WordAck = 47 [(wire_in) = true];
MessageType_DebugLinkDecision = 100 [(wire_debug_in) = true]; MessageType_DebugLinkDecision = 100 [(wire_debug_in) = true];
MessageType_DebugLinkGetState = 101 [(wire_debug_in) = true]; MessageType_DebugLinkGetState = 101 [(wire_debug_in) = true];
MessageType_DebugLinkState = 102 [(wire_debug_out) = true]; MessageType_DebugLinkState = 102 [(wire_debug_out) = true];
@ -64,354 +61,467 @@ enum MessageType {
MessageType_DebugLinkLog = 104 [(wire_debug_out) = true]; MessageType_DebugLinkLog = 104 [(wire_debug_out) = true];
} }
// **************************************************************************** ////////////////////
// // Basic messages //
// Basic message ////////////////////
//
// Reset device to default state and ask for device details /**
// * Request: Reset device to default state and ask for device details
// Response: Features * @next Features
*/
message Initialize { message Initialize {
} }
// Response object for Initialize. /**
* Response: Reports various information about the device
* @prev Initialize
*/
message Features { message Features {
optional string vendor = 1; // Name of the manufacturer, e.g. "bitcointrezor.com" optional string 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 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 minor_version = 3; // minor version of the device, e.g. 0
optional uint32 patch_version = 4; // Patch version of the device, e.g. 0 optional uint32 patch_version = 4; // patch version of the device, e.g. 0
optional bool bootloader_mode = 5; optional bool bootloader_mode = 5; // is device in bootloader mode?
optional string device_id = 6; // Device's unique identifier optional string device_id = 6; // device's unique identifier
optional bool pin_protection = 7; // True if Trezor is covered by PIN optional bool pin_protection = 7; // is device protected by PIN?
optional bool passphrase_protection = 8; // True if node/mnemonic is covered by passphrase optional bool passphrase_protection = 8; // is node/mnemonic encrypted using passphrase?
optional string language = 9; optional string language = 9; // device language
optional string label = 10; optional string label = 10; // device description label
repeated CoinType coins = 11; repeated CoinType coins = 11; // supported coins
optional bool initialized = 12; // True if device cointains seed optional bool initialized = 12; // does device contain seed?
optional bytes revision = 13; optional bytes revision = 13; // SCM revision of firmware
optional bytes bootloader_hash = 14; optional bytes bootloader_hash = 14; // hash of the bootloader
} }
// Overwrites only filled fields of the structure /**
* Request: change language and/or label of the device
* @next Success
* @next Failure
* @next ButtonRequest
* @next PinMatrixRequest
*/
message ApplySettings { message ApplySettings {
optional string language = 1; optional string language = 1;
optional string label = 2; optional string label = 2;
} }
// Starts workflow for setting/changing the PIN /**
// Response: ButtonRequest, PinMatrixRequest * Request: Starts workflow for setting/changing/removing the PIN
* @next ButtonRequest
* @next PinMatrixRequest
*/
message ChangePin { message ChangePin {
optional bool remove = 1; // Set True if want to remove PIN protection optional bool remove = 1; // is PIN removal requested?
} }
// Test if device is live, device will send back the message on success /**
// * Request: Test if the device is alive, device sends back the message in Success response
// Response: None or Success * @next Success
*/
message Ping { message Ping {
optional string message = 1; // Message will be sent back in Success message optional string message = 1; // message to send back in Success message
optional bool button_protection = 2; // Ask for button press optional bool button_protection = 2; // ask for button press
optional bool pin_protection = 3; // Ask for PIN if set optional bool pin_protection = 3; // ask for PIN if set in device
optional bool passphrase_protection = 4; // Ask for passphrase if set optional bool passphrase_protection = 4; // ask for passphrase if set in device
} }
// Response object defining success of the previous request /**
* Response: Success of the previous request
*/
message Success { message Success {
optional string message = 1; // May contain human readable description of the action or request-specific payload optional string message = 1; // human readable description of action or request-specific payload
} }
// Response object defining failure of the previous request /**
* Response: Failure of the previous request
*/
message Failure { message Failure {
optional FailureType code = 1; // May contain computer-readable definition of the error state optional FailureType code = 1; // computer-readable definition of the error state
optional string message = 2; // May contain human-readable message of the error state optional string message = 2; // 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 * Response: Device is waiting for HW button press.
// Computer should respond with ButtonAck message or Cancel to cancel * @next ButtonAck
// the original request. * @next Cancel
*/
message ButtonRequest { message ButtonRequest {
optional ButtonRequestType code = 1; optional ButtonRequestType code = 1;
optional string data = 2; optional string data = 2;
} }
// Computer agrees to wait for HW button press. /**
* Request: Computer agrees to wait for HW button press
* @prev ButtonRequest
*/
message ButtonAck { 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: Device is asking computer to show PIN matrix and awaits PIN encoded using this matrix scheme
// * @next PinMatrixAck
// Response: PinMatrixAck, Cancel * @next Cancel
*/
message PinMatrixRequest { message PinMatrixRequest {
optional PinMatrixRequestType type = 1; optional PinMatrixRequestType type = 1;
} }
// Message is sent by the computer as a response to PinMatrixRequest previously sent by the device. /**
* Request: Computer responds with encoded PIN
* @prev PinMatrixRequest
*/
message PinMatrixAck { message PinMatrixAck {
required string pin = 1; // User must write down the password for accessing the device. required string pin = 1; // matrix encoded PIN entered by user
} }
// Message is sent as a cancel response to ButtonRequest, PinMatrixRequest and PassphraseRequest /**
* Request: Abort last operation that required user interaction
* @prev ButtonRequest
* @prev PinMatrixRequest
* @prev PassphraseRequest
*/
message Cancel { message Cancel {
} }
// Device request encryption passphrase /**
* Response: Device awaits encryption passphrase
* @next PassphraseAck
* @next Cancel
*/
message PassphraseRequest { message PassphraseRequest {
} }
// Computer sends passphrase to device. /**
* Request: Send passphrase back
* @prev PassphraseRequest
*/
message PassphraseAck { message PassphraseAck {
required string passphrase = 1; required string passphrase = 1;
} }
// Request a sample of random data generated by hardware RNG. May be used /**
// for tests of internal RNG. * Request: Request a sample of random data generated by hardware RNG. May be used for testing.
// * @next ButtonRequest
// Response: PinMatrixRequest, Entropy, Failure * @next Entropy
* @next Failure
*/
message GetEntropy { message GetEntropy {
required uint32 size = 1; // Size of randomly generated buffer required uint32 size = 1; // size of requested entropy
} }
// Response to GetEntropy request contains random data generated by internal HRNG. /**
* Response: Reply with random data generated by internal RNG
* @prev GetEntropy
*/
message Entropy { message Entropy {
required bytes entropy = 1; // Stream of generated bytes required bytes entropy = 1; // stream of random 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. * Request: Ask device for public key corresponding to address_n path
// * @next PassphraseRequest
// Response: PublicKey, Failure * @next PublicKey
* @next Failure
*/
message GetPublicKey { message GetPublicKey {
repeated uint32 address_n = 1; repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
} }
// Contains public key derived from device's seed. /**
* Response: Contains public key derived from device private seed
* @prev GetPublicKey
*/
message PublicKey { message PublicKey {
required HDNodeType node = 1; // BIP32 node public key + chaincode required HDNodeType node = 1; // BIP32 public node
} }
/**
* Request: Ask device for address corresponding to address_n path
* @next PassphraseRequest
* @next Address
* @next Failure
*/
message GetAddress { message GetAddress {
repeated uint32 address_n = 1; // Parameter for address generation algorithm to derive the address from the master node repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
optional string coin_name = 2 [default='Bitcoin']; optional string coin_name = 2 [default='Bitcoin'];
} }
/**
* Response: Contains address derived from device private seed
* @prev GetAddress
*/
message Address { message Address {
required string address = 1; // Bitcoin address in base58 encoding corresponding to GetAddress(n) call required string address = 1; // Coin address in Base58 encoding
} }
// Request device to wipe all sensitive data and settings. /**
// Device will be turned to uninitialized state. * Request: Request device to wipe all sensitive data and settings
// * @next ButtonRequest
// Response: ButtonRequest */
message WipeDevice { message WipeDevice {
} }
// Load seed and related internal settings from computer to the device. Existing seed is overwritten. /**
// * Request: Load seed and related internal settings from the computer
// Response: Success, ButtonRequest, PinMatrixRequest, Failure * @next ButtonRequest
* @next Success
* @next Failure
*/
message LoadDevice { message LoadDevice {
optional string mnemonic = 1; // Seed encoded as a mnemonic (12 english words) optional string mnemonic = 1; // seed encoded as BIP-39 mnemonic (12, 18 or 24 words)
optional HDNodeType node = 2; optional HDNodeType node = 2; // BIP-32 node
optional string pin = 3; // Set PIN protection for important actions optional string pin = 3; // set PIN protection
optional bool passphrase_protection = 4; optional bool passphrase_protection = 4; // enable master node encryption using passphrase
optional string language = 5 [default='english']; optional string language = 5 [default='english']; // device language
optional string label = 6; optional string label = 6; // device label
optional bool skip_checksum = 7; // Do not test mnemonic for valid BIP39 checksum optional bool skip_checksum = 7; // do not test mnemonic for valid BIP-39 checksum
} }
// Request device to do full-reset, to generate new seed /**
// and ask user for new settings (PIN). * Request: Ask device to do initialization involving user interaction
// Workflow is splitted into ResetDevice/EntropyRequest to be sure * @next EntropyRequest
// that entropy provided by device isn't calculated on base of computer provided * @next Failure
// entropy. */
//
//
// Response: EntropyRequest, PinMatrixRequest, Failure
message ResetDevice { message ResetDevice {
optional bool display_random = 1; // If set, displays entropy generated by the device used optional bool display_random = 1; // display entropy generated by the device before asking for additional entropy
// for generating the seed *before* asking optional uint32 strength = 2 [default=128]; // strength of seed in bits
// for additional entropy from computer optional bool passphrase_protection = 3; // enable master node encryption using passphrase
optional uint32 strength = 2 [default=128]; // Strength of seed in bits optional bool pin_protection = 4; // enable PIN protection
optional bool passphrase_protection = 3; optional string language = 5 [default='english']; // device language
optional bool pin_protection = 4; optional string label = 6; // device label
optional string language = 5 [default='english'];
optional string label = 6;
} }
// Asks for additional Entropy from host computer /**
* Response: Ask for additional entropy from host computer
* @prev ResetDevice
* @next EntropyAck
*/
message EntropyRequest { message EntropyRequest {
} }
// Provide additional entropy for seed generation function. /**
* Request: Provide additional entropy for seed generation function
* @prev EntropyRequest
* @next ButtonRequest
*/
message EntropyAck { message EntropyAck {
optional bytes entropy = 1; // Recommended to provide 256 bits (32 bytes) of random data. optional bytes entropy = 1; // 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 * Request: Start recovery workflow asking user for specific words of mnemonic
// using mnemonic on untrusted computer. * Used to recovery device safely even on untrusted computer.
* @next WordRequest
*/
message RecoveryDevice { message RecoveryDevice {
optional uint32 word_count = 1; // How many words is in mnemonic sentence? optional uint32 word_count = 1; // number of words in BIP-39 mnemonic
optional bool passphrase_protection = 2; optional bool passphrase_protection = 2; // enable master node encryption using passphrase
optional bool pin_protection = 3; optional bool pin_protection = 3; // enable PIN protection
optional string language = 4 [default='english']; optional string language = 4 [default='english']; // device language
optional string label = 5; optional string label = 5; // device label
optional bool enforce_wordlist = 6; // Trezor enforces BIP39 wordlist optional bool enforce_wordlist = 6; // enforce BIP-39 wordlist during the process
} }
// 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. * Response: Device is waiting for user to enter word of the mnemonic
* Its position is shown only on device's internal display.
* @prev RecoveryDevice
* @prev WordAck
*/
message WordRequest { message WordRequest {
} }
/**
* Request: Computer replies with word from the mnemonic
* @prev WordRequest
* @next WordRequest
* @next Success
* @next Failure
*/
message WordAck { message WordAck {
required string word = 1; // One word of mnemonic on asked position required string word = 1; // one word of mnemonic on asked position
} }
// **************************************************************************** //////////////////////////////
// // Message signing messages //
// Messages related to transaction signing //////////////////////////////
//
/**
* Request: Ask device to sign message
* @next MessageSignature
* @next Failure
*/
message SignMessage { message SignMessage {
repeated uint32 address_n = 1; repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
required bytes message = 2; required bytes message = 2; // message to be signed
optional string coin_name = 3 [default='Bitcoin']; optional string coin_name = 3 [default='Bitcoin']; // coin to use for signing
} }
/**
* Request: Ask device to verify message
* @next Success
* @next Failure
*/
message VerifyMessage { message VerifyMessage {
optional string address = 1; optional string address = 1; // address to verify
optional bytes signature = 2; optional bytes signature = 2; // signature to verify
optional bytes message = 3; optional bytes message = 3; // message to verify
} }
/**
* Response: Signed message
* @prev SignMessage
*/
message MessageSignature { message MessageSignature {
optional string address = 1; optional string address = 1; // address used to sign the message
optional bytes signature = 2; optional bytes signature = 2; // signature of the message
} }
// Estimate size of the transaction //////////////////////////////////
// This call behaves exactly like SignTx, // Transaction signing messages //
// 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. * Request: Estimated size of the transaction
// * This behaves exactly like SignTx, which means that it can ask using TxRequest
// Response: TxRequest, TxSize, Failure * This call is non-blocking (except possible PassphraseRequest to unlock the seed)
* @next TxSize
* @next Failure
*/
message EstimateTxSize { message EstimateTxSize {
required uint32 outputs_count = 1; // Count of outputs of the transaction required uint32 outputs_count = 1; // number of transaction outputs
required uint32 inputs_count = 2; // Count of inputs of the transaction required uint32 inputs_count = 2; // number of transaction inputs
optional string coin_name = 3 [default='Bitcoin']; optional string coin_name = 3 [default='Bitcoin']; // coin to use
} }
// Result of EstimateTxSize /**
* Response: Estimated size of the transaction
* @prev EstimateTxSize
*/
message TxSize { message TxSize {
optional uint32 tx_size = 1; // Size of transaction in bytes optional uint32 tx_size = 1; // estimated size of transaction in bytes
} }
// Request the device to sign the transaction /**
// * Request: Ask device to sign transaction
// Response: TxRequest, PinMatrixRequest, Failure * @next PinMatrixRequest
* @next TxRequest
* @next Failure
*/
message SignTx { message SignTx {
required uint32 outputs_count = 1; // Count of outputs of the transaction required uint32 outputs_count = 1; // number of transaction outputs
required uint32 inputs_count = 2; // Count of inputs of the transaction required uint32 inputs_count = 2; // number of transaction inputs
optional string coin_name = 3 [default='Bitcoin']; optional string coin_name = 3 [default='Bitcoin']; // coin to use
} }
// Request a simplified workflow of signing. /**
// This method doesn't support streaming, * Request: Simplified transaction signing
// so there may be hardware limits * This method doesn't support streaming, so there are hardware limits in number of inputs and outputs.
// in number of inputs and outputs. * In case of success, the result is returned using TxRequest message.
// * @next PinMatrixRequest
// This simplified workflow should not be used * @next TxRequest
// in production, it is designed mainly for debug purposes. * @next Failure
// */
// When everything is fine, Success.message contains
// serialized transaction.
//
// Response: Success, PinMatrixRequest, Failure
message SimpleSignTx { message SimpleSignTx {
repeated TxInputType inputs = 1; repeated TxInputType inputs = 1; // transaction inputs
repeated TxOutputType outputs = 2; repeated TxOutputType outputs = 2; // transaction outputs
repeated TransactionType transactions = 3; repeated TransactionType transactions = 3; // transactions whose outputs are used to build current inputs
optional string coin_name = 4 [default='Bitcoin']; optional string coin_name = 4 [default='Bitcoin']; // coin to use
} }
// 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) * Response: Device asks for information for signing transaction or returns the last result
// with details of index's input. * If request_index is set, device awaits TxAck message (with fields filled in according to request_type)
// If signed_index is set, 'signature' contains signed input of signed_index's input. * If signature_index is set, 'signature' contains signed input of signature_index's input
* @prev SignTx
* @prev SimpleSignTx
* @prev TxAck
*/
message TxRequest { message TxRequest {
optional int32 request_index = 1; // If >=0, device expects TxInput/TxOutput message from the computer optional uint32 request_index = 1; // device expects TxAck message from the computer
optional RequestType request_type = 2; // Ask for TxInput or TxOutput? optional RequestType request_type = 2; // what should be filled in TxAck message?
optional int32 signed_index = 3; // If >=0, 'signature' contains signed input of this input optional uint32 signature_index = 3; // 'signature' field contains signed input of this index
optional bytes signature = 4; // If signed_index>=0, represent signature of the signed_index input optional bytes signature = 4; // signature of the signature_index input
optional bytes serialized_tx = 5; // Part of serialized and signed transaction optional bytes serialized_tx = 5; // part of serialized and signed transaction
optional bytes tx_hash = 6; // tx_hash of requested transaction
optional bool finished = 7; // is this the last TxRequest?
} }
// Transaction onput for SignTx workflow. It is response to TxRequest message sent by device. /**
// * Request: Reported transaction data
// Response: TxRequest, Failure * @prev TxRequest
message TxInput { * @next TxRequest
required TxInputType input = 1; */
message TxAck {
optional TransactionType tx = 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). // Bootloader messages //
message TxOutput { /////////////////////////
required TxOutputType output = 1;
}
// ****************************************************************************
//
// Bootloader messages
//
/**
* Request: Ask device to erase its firmware
* @next Success
* @next Failure
*/
message FirmwareErase { message FirmwareErase {
} }
/**
* Request: Send firmware in binary form to the device
* @next Success
* @next Failure
*/
message FirmwareUpload { message FirmwareUpload {
required bytes payload = 1; // Firmware to flash into device required bytes payload = 1; // firmware to be loaded into device
} }
// **************************************************************************** /////////////////////////////////////////////////////////////
// // Debug messages (only available if DebugLink is enabled) //
// 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. * Request: "Press" the button on the device
// * @next Success
// Response: Success */
message DebugLinkDecision { message DebugLinkDecision {
required bool yes_no = 1; // True for "confirm", False for "cancel" 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. /**
// * Request: Computer asks for device state
// Response: DebugLinkState * @next DebugLinkState
*/
message DebugLinkGetState { message DebugLinkGetState {
} }
// Response object reflecting device's current state. It can be received only over debug link connection. /**
* Response: Device current state
* @prev DebugLinkGetState
*/
message DebugLinkState { message DebugLinkState {
optional bytes layout = 1; // Raw buffer of display optional bytes layout = 1; // raw buffer of display
optional string pin = 2; // Current PIN, blank if PIN is not set/enabled optional string pin = 2; // current PIN, blank if PIN is not set/enabled
optional string matrix = 3; // Current PIN matrix optional string matrix = 3; // current PIN matrix
optional string mnemonic = 4; // Current mnemonic format optional string mnemonic = 4; // current BIP-39 mnemonic
optional HDNodeType node = 5; // Current node (BIP32 format) optional HDNodeType node = 5; // current BIP-32 node
optional bool passphrase_protection = 6; // Is passphrase_protection set? optional bool passphrase_protection = 6; // is node/mnemonic encrypted using passphrase?
optional string reset_word = 7; // Word on display during ResetDevice workflow optional string reset_word = 7; // word on device display during ResetDevice workflow
optional bytes reset_entropy = 8; // Current entropy of ResetDevice workflow optional bytes reset_entropy = 8; // current entropy during ResetDevice workflow
optional string recovery_fake_word = 9; // (Fake) Word on display during RecoveryDevice workflow optional string recovery_fake_word = 9; // (fake) word on display during RecoveryDevice workflow
optional uint32 recovery_word_pos = 10; // Index of mnemonic word the device is expecting optional uint32 recovery_word_pos = 10; // index of mnemonic word the device is expecting during RecoveryDevice workflow
} }
// Ask device to shutdown/restart /**
* Request: Ask device to restart
*/
message DebugLinkStop { message DebugLinkStop {
} }
/**
* Response: Device wants host to log event
*/
message DebugLinkLog { message DebugLinkLog {
optional uint32 level = 1; optional uint32 level = 1;
optional string bucket = 2; optional string bucket = 2;

34
protob/storage.proto
View File

@ -1,24 +1,26 @@
/* /**
Structure of Storage area of TREZOR * Storage area of TREZOR
*
* @author Marek Palatinus <slush@satoshilabs.com>
* @version 1
*/
Author: Marek Palatinus <slush@satoshilabs.com> // Sugar for easier handling in Multibit
Version: 0.1
*/
// Some sugar for easier handling in Multibit
option java_package = "org.multibit.hd.hardware.trezor.protobuf"; option java_package = "org.multibit.hd.hardware.trezor.protobuf";
option java_outer_classname = "TrezorStorage"; option java_outer_classname = "TrezorStorage";
import "types.proto"; import "types.proto";
/**
* Internal persistent storage of device
*/
message Storage { message Storage {
required uint32 version = 1; required uint32 version = 1; // version of storage
optional HDNodeType node = 2; optional HDNodeType node = 2; // BIP-32 node (mnemonic cannot be used if this is present)
optional string mnemonic = 3; optional string mnemonic = 3; // BIP-39 mnemonic (node cannot be used if this is present)
optional bool passphrase_protection = 4; // whether node_serialized or mnemonic are encrypted (protected by passphrase) optional bool passphrase_protection = 4; // whether to require passphrase to decrypt node or stretch mnemonic
optional uint32 pin_failed_attempts = 5; optional uint32 pin_failed_attempts = 5; // number of failed PIN attempts
optional string pin = 6; optional string pin = 6; // current PIN
optional string language = 7; optional string language = 7; // current language
optional string label = 8; optional string label = 8; // device label
} }

105
protob/types.proto
View File

@ -1,24 +1,30 @@
/* /**
Types for TREZOR communication * Types for TREZOR communication
*
* @author Marek Palatinus <slush@satoshilabs.com>
* @version 0.6
*/
Author: Marek Palatinus <slush@satoshilabs.com> // Sugar for easier handling in Multibit
Version: 0.6
*/
// Some sugar for easier handling in Multibit
option java_package = "org.multibit.hd.hardware.trezor.protobuf"; option java_package = "org.multibit.hd.hardware.trezor.protobuf";
option java_outer_classname = "TrezorType"; option java_outer_classname = "TrezorType";
import "google/protobuf/descriptor.proto"; import "google/protobuf/descriptor.proto";
/**
* Options for specifying message direction and type of wire (normal/debug)
*/
extend google.protobuf.EnumValueOptions { extend google.protobuf.EnumValueOptions {
optional bool wire_in = 50002; // message can be transmitted via wire from PC to TREZOR optional bool wire_in = 50002; // message can be transmitted via wire from PC to TREZOR
optional bool wire_out = 50003; // message can be transmitted via wire from TREZOR to PC optional bool wire_out = 50003; // message can be transmitted via wire from TREZOR to PC
optional bool wire_debug_in = 50004; // message can be transmitted via debug wire from PC to TREZOR optional bool wire_debug_in = 50004; // message can be transmitted via debug wire from PC to TREZOR
optional bool wire_debug_out = 50005; // message can be transmitted via debug wire from TREZOR to PC optional bool wire_debug_out = 50005; // message can be transmitted via debug wire from TREZOR to PC
} }
/**
* Type of failures returned by Failure message
* @used_in Failure
*/
enum FailureType { enum FailureType {
Failure_UnexpectedMessage = 1; Failure_UnexpectedMessage = 1;
Failure_ButtonExpected = 2; Failure_ButtonExpected = 2;
@ -34,18 +40,29 @@ enum FailureType {
Failure_FirmwareError = 99; Failure_FirmwareError = 99;
} }
// Specifies which script will be used for given transaction output. /**
* Type of script which will be used for transaction output
* @used_in TxOutputType
*/
enum ScriptType { enum ScriptType {
PAYTOADDRESS = 0; PAYTOADDRESS = 0;
PAYTOSCRIPTHASH = 1; PAYTOSCRIPTHASH = 1;
} }
// Specifies which kind of information is required by transaction signing process /**
* Type of information required by transaction signing process
* @used_in TxRequest
*/
enum RequestType { enum RequestType {
TXINPUT = 0; TXINPUT = 0;
TXOUTPUT = 1; TXOUTPUT = 1;
TXMETA = 2;
} }
/**
* Type of button request
* @used_in ButtonRequest
*/
enum ButtonRequestType { enum ButtonRequestType {
ButtonRequest_Other = 1; ButtonRequest_Other = 1;
ButtonRequest_FeeOverThreshold = 2; ButtonRequest_FeeOverThreshold = 2;
@ -57,14 +74,24 @@ enum ButtonRequestType {
ButtonRequest_SignTx = 8; ButtonRequest_SignTx = 8;
} }
/**
* Type of PIN request
* @used_in PinMatrixRequest
*/
enum PinMatrixRequestType { enum PinMatrixRequestType {
PinMatrixRequestType_Current = 1; PinMatrixRequestType_Current = 1;
PinMatrixRequestType_NewFirst = 2; PinMatrixRequestType_NewFirst = 2;
PinMatrixRequestType_NewSecond = 3; PinMatrixRequestType_NewSecond = 3;
} }
// Structure of BIP32 (hierarchical deterministic) node /**
// Used for imports of private key into the device and exporting public key out of device * Structure representing BIP32 (hierarchical deterministic) node
* Used for imports of private key into the device and exporting public key out of device
* @used_in PublicKey
* @used_in LoadDevice
* @used_in DebugLinkState
* @used_in Storage
*/
message HDNodeType { message HDNodeType {
required uint32 depth = 1; required uint32 depth = 1;
required uint32 fingerprint = 2; required uint32 fingerprint = 2;
@ -74,6 +101,10 @@ message HDNodeType {
optional bytes public_key = 6; optional bytes public_key = 6;
} }
/**
* Structure representing Coin
* @used_in Features
*/
message CoinType { message CoinType {
optional string coin_name = 1; optional string coin_name = 1;
optional string coin_shortcut = 2; optional string coin_shortcut = 2;
@ -81,33 +112,49 @@ message CoinType {
optional uint64 maxfee_kb = 4; optional uint64 maxfee_kb = 4;
} }
/**
* Structure representing transaction input
* @used_in SimpleSignTx
* @used_in TransactionType
*/
message TxInputType { message TxInputType {
repeated uint32 address_n = 1; // Parameter for address generation algorithm to derive the address from the master node repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node
required bytes prev_hash = 2; // Hash of previous transaction output to spend by this input required bytes prev_hash = 2; // hash of previous transaction output to spend by this input
required uint32 prev_index = 3; // Index of previous output to spend required uint32 prev_index = 3; // index of previous output to spend
optional bytes script_sig = 4; // Script signature optional bytes script_sig = 4; // script signature
optional uint32 sequence = 5 [default=0xffffffff]; optional uint32 sequence = 5 [default=0xffffffff]; // sequence
} }
/**
* Structure representing transaction output
* @used_in SimpleSignTx
* @used_in TransactionType
*/
message TxOutputType { message TxOutputType {
optional string address = 1; // Target bitcoin address in base58 encoding optional string address = 1; // target coin address in Base58 encoding
repeated uint32 address_n = 2; // Has higher priority than "address". repeated uint32 address_n = 2; // BIP-32 path to derive the key from master node; has higher priority than "address"
required uint64 amount = 3; // Amount to send in satoshis required uint64 amount = 3; // amount to spend in satoshis
required ScriptType script_type = 4; // Select output script type required ScriptType script_type = 4; // output script type
repeated bytes script_args = 5; // Provide additional parameters for the script (its script-depended) repeated bytes script_args = 5; // additional parameters for the script (script-dependent)
} }
// Transaction output with script pubkey in binary form. /**
// This is used for obtaining hashes of existing transactions * Structure representing compiled transaction output
// and for compiling TxOutput for signing. * @used_in TransactionType
*/
message TxOutputBinType { message TxOutputBinType {
required uint64 amount = 1; required uint64 amount = 1;
required bytes script_pubkey = 2; required bytes script_pubkey = 2;
} }
/**
* Structure representing transaction
* @used_in SimpleSignTx
*/
message TransactionType { message TransactionType {
optional uint32 version = 1 [default=1]; optional uint32 version = 1;
repeated TxInputType inputs = 2; repeated TxInputType inputs = 2;
repeated TxOutputBinType outputs = 3; repeated TxOutputBinType outputs = 3;
optional uint32 lock_time = 4 [default=0]; repeated TxOutputType our_outputs = 4;
optional uint32 lock_time = 5;
} }

2
signer/config.json
View File

@ -9,7 +9,7 @@
], ],
"known_devices": [ "known_devices": [
["0x534c", "0x0001", "Trezor"], ["0x534c", "0x0001", "Trezor"],
["0x10c4", "0xea80", "Trezor Shield"] ["0x10c4", "0xea80", "Trezor Shield"]
], ],
"valid_days": 15 "valid_days": 15
} }