From 52f360ab12cdf15a86561036bbf3dd66bfbf15f5 Mon Sep 17 00:00:00 2001 From: Pavol Rusnak Date: Tue, 25 Mar 2014 19:20:36 +0100 Subject: [PATCH] add documentation, remove TxInput/TxOutput messages, use TxAck instead --- protob/config.proto | 42 +-- protob/messages.proto | 602 +++++++++++++++++++++++++----------------- protob/storage.proto | 34 +-- protob/types.proto | 107 +++++--- signer/config.json | 2 +- 5 files changed, 473 insertions(+), 314 deletions(-) diff --git a/protob/config.proto b/protob/config.proto index 0f14f7563..51b03a7de 100644 --- a/protob/config.proto +++ b/protob/config.proto @@ -1,29 +1,29 @@ -// -// This file defines the configuration format for initializing the -// Trezor browser plugin. -// +/** + * Configuration format for TREZOR plugin + * + * @author Marek Palatinus + * @version 1.0 + */ import "google/protobuf/descriptor.proto"; +/** + * Device Descriptor used in Configuration + */ message DeviceDescriptor { - optional uint32 vendor_id = 1; - optional uint32 product_id = 2; - optional bytes serial_number = 3; - optional bytes path = 4; + optional uint32 vendor_id = 1; // USB vendor ID + optional uint32 product_id = 2; // USB product ID + optional string serial_number = 3; // USB serial number + optional string path = 4; // USB device path } +/** + * Plugin Configuration + */ message Configuration { - // regexes of allowed/forbidden urls - repeated bytes whitelist_urls = 1; - repeated bytes blacklist_urls = 2; - - // compiled specification of the wire protocol, serialized - // 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; + repeated string whitelist_urls = 1; // allowed URLs for plugin + repeated string blacklist_urls = 2; // forbidden URLs for plugin + 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 + optional uint32 valid_until = 5; // expiration timestamp } diff --git a/protob/messages.proto b/protob/messages.proto index c3fb2867c..14bbe1391 100644 --- a/protob/messages.proto +++ b/protob/messages.proto @@ -1,21 +1,19 @@ -/* - Messages for TREZOR communication - - Author: Marek Palatinus - - Version: 0.6 -*/ - - -// Some sugar for easier handling in Multibit +/** + * Messages for TREZOR communication + * + * @author Marek Palatinus + * @version 0.6 + */ + +// 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 -*/ +/** + * Mapping between Trezor wire identifier (uint) and a protobuf message + */ enum MessageType { MessageType_Initialize = 0 [(wire_in) = true]; MessageType_Ping = 1 [(wire_in) = true]; @@ -38,8 +36,7 @@ enum MessageType { 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_TxAck = 22 [(wire_in) = true]; MessageType_ApplySettings = 25 [(wire_in) = true]; MessageType_ButtonRequest = 26 [(wire_out) = true]; MessageType_ButtonAck = 27 [(wire_in) = true]; @@ -56,7 +53,7 @@ enum MessageType { 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_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]; @@ -64,354 +61,467 @@ enum MessageType { MessageType_DebugLinkLog = 104 [(wire_debug_out) = true]; } -// **************************************************************************** -// -// Basic message -// +//////////////////// +// Basic messages // +//////////////////// -// Reset device to default state and ask for device details -// -// Response: Features +/** + * Request: Reset device to default state and ask for device details + * @next Features + */ message Initialize { } -// Response object for Initialize. +/** + * Response: Reports various information about the device + * @prev Initialize + */ message Features { - 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 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 bool bootloader_mode = 5; - optional string device_id = 6; // 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 string language = 9; - optional string label = 10; - repeated CoinType coins = 11; - optional bool initialized = 12; // True if device cointains seed - optional bytes revision = 13; - optional bytes bootloader_hash = 14; -} - -// Overwrites only filled fields of the structure + 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 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 bool bootloader_mode = 5; // is device in bootloader mode? + optional string device_id = 6; // device's unique identifier + optional bool pin_protection = 7; // is device protected by PIN? + optional bool passphrase_protection = 8; // is node/mnemonic encrypted using passphrase? + optional string language = 9; // device language + optional string label = 10; // device description label + repeated CoinType coins = 11; // supported coins + optional bool initialized = 12; // does device contain seed? + optional bytes revision = 13; // SCM revision of firmware + optional bytes bootloader_hash = 14; // hash of the bootloader +} + +/** + * Request: change language and/or label of the device + * @next Success + * @next Failure + * @next ButtonRequest + * @next PinMatrixRequest + */ message ApplySettings { optional string language = 1; 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 { - 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 -// -// Response: None or Success +/** + * Request: Test if the device is alive, device sends back the message in Success response + * @next Success + */ message Ping { - optional string 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 + optional string message = 1; // message to send back in Success message + optional bool button_protection = 2; // ask for button press + optional bool pin_protection = 3; // ask for PIN if set in device + 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 { - 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 { - optional FailureType code = 1; // May contain computer-readable definition of the error state - optional string message = 2; // May contain human-readable message of the error state + optional FailureType code = 1; // computer-readable definition 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 -// Computer should respond with ButtonAck message or Cancel to cancel -// the original request. +/** + * Response: Device is waiting for HW button press. + * @next ButtonAck + * @next Cancel + */ message ButtonRequest { optional ButtonRequestType code = 1; 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 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 +/** + * Response: Device is asking computer to show PIN matrix and awaits PIN encoded using this matrix scheme + * @next PinMatrixAck + * @next Cancel + */ message PinMatrixRequest { 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 { - 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 { } -// Device request encryption passphrase +/** + * Response: Device awaits encryption passphrase + * @next PassphraseAck + * @next Cancel + */ message PassphraseRequest { } -// Computer sends passphrase to device. +/** + * Request: Send passphrase back + * @prev PassphraseRequest + */ message PassphraseAck { required string passphrase = 1; } -// Request a sample of random data generated by hardware RNG. May be used -// for tests of internal RNG. -// -// Response: PinMatrixRequest, Entropy, Failure +/** + * Request: Request a sample of random data generated by hardware RNG. May be used for testing. + * @next ButtonRequest + * @next Entropy + * @next Failure + */ 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 { - 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. -// -// Response: PublicKey, Failure +/** + * Request: Ask device for public key corresponding to address_n path + * @next PassphraseRequest + * @next PublicKey + * @next Failure + */ 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 { - 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 { - 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']; } +/** + * Response: Contains address derived from device private seed + * @prev GetAddress + */ 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. -// -// Response: ButtonRequest +/** + * Request: Request device to wipe all sensitive data and settings + * @next ButtonRequest + */ message WipeDevice { } -// Load seed and related internal settings from computer to the device. Existing seed is overwritten. -// -// Response: Success, ButtonRequest, PinMatrixRequest, Failure +/** + * Request: Load seed and related internal settings from the computer + * @next ButtonRequest + * @next Success + * @next Failure + */ message LoadDevice { - optional string mnemonic = 1; // Seed encoded as a mnemonic (12 english words) - optional HDNodeType node = 2; - optional string pin = 3; // Set PIN protection for important actions - optional bool passphrase_protection = 4; - optional string language = 5 [default='english']; - optional string label = 6; - 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 + optional string mnemonic = 1; // seed encoded as BIP-39 mnemonic (12, 18 or 24 words) + optional HDNodeType node = 2; // BIP-32 node + optional string pin = 3; // set PIN protection + optional bool passphrase_protection = 4; // enable master node encryption using passphrase + optional string language = 5 [default='english']; // device language + optional string label = 6; // device label + optional bool skip_checksum = 7; // do not test mnemonic for valid BIP-39 checksum +} + +/** + * Request: Ask device to do initialization involving user interaction + * @next EntropyRequest + * @next 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 string language = 5 [default='english']; - optional string label = 6; -} - -// Asks for additional Entropy from host computer + optional bool display_random = 1; // display entropy generated by the device before asking for additional entropy + optional uint32 strength = 2 [default=128]; // strength of seed in bits + optional bool passphrase_protection = 3; // enable master node encryption using passphrase + optional bool pin_protection = 4; // enable PIN protection + optional string language = 5 [default='english']; // device language + optional string label = 6; // device label +} + +/** + * Response: Ask for additional entropy from host computer + * @prev ResetDevice + * @next EntropyAck + */ message EntropyRequest { } -// Provide additional entropy for seed generation function. +/** + * Request: Provide additional entropy for seed generation function + * @prev EntropyRequest + * @next ButtonRequest + */ 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 -// using mnemonic on untrusted computer. +/** + * Request: Start recovery workflow asking user for specific words of mnemonic + * Used to recovery device safely even on untrusted computer. + * @next WordRequest + */ 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 string language = 4 [default='english']; - optional string label = 5; - 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. + optional uint32 word_count = 1; // number of words in BIP-39 mnemonic + optional bool passphrase_protection = 2; // enable master node encryption using passphrase + optional bool pin_protection = 3; // enable PIN protection + optional string language = 4 [default='english']; // device language + optional string label = 5; // device label + optional bool enforce_wordlist = 6; // enforce BIP-39 wordlist during the process +} + +/** + * 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 { } +/** + * Request: Computer replies with word from the mnemonic + * @prev WordRequest + * @next WordRequest + * @next Success + * @next Failure + */ message WordAck { - required string word = 1; // One word of mnemonic on asked position + required string word = 1; // one word of mnemonic on asked position } -// **************************************************************************** -// -// Messages related to transaction signing -// +////////////////////////////// +// Message signing messages // +////////////////////////////// +/** + * Request: Ask device to sign message + * @next MessageSignature + * @next Failure + */ message SignMessage { - repeated uint32 address_n = 1; - required bytes message = 2; - optional string coin_name = 3 [default='Bitcoin']; + repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node + required bytes message = 2; // message to be signed + optional string coin_name = 3 [default='Bitcoin']; // coin to use for signing } +/** + * Request: Ask device to verify message + * @next Success + * @next Failure + */ message VerifyMessage { - optional string address = 1; - optional bytes signature = 2; - optional bytes message = 3; + optional string address = 1; // address to verify + optional bytes signature = 2; // signature to verify + optional bytes message = 3; // message to verify } +/** + * Response: Signed message + * @prev SignMessage + */ message MessageSignature { - optional string address = 1; - optional bytes signature = 2; -} - -// 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 + optional string address = 1; // address used to sign the message + optional bytes signature = 2; // signature of the message +} + +////////////////////////////////// +// Transaction signing messages // +////////////////////////////////// + +/** + * Request: Estimated size of the transaction + * This behaves exactly like SignTx, which means that it can ask using TxRequest + * This call is non-blocking (except possible PassphraseRequest to unlock the seed) + * @next TxSize + * @next 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 string coin_name = 3 [default='Bitcoin']; + required uint32 outputs_count = 1; // number of transaction outputs + required uint32 inputs_count = 2; // number of transaction inputs + optional string coin_name = 3 [default='Bitcoin']; // coin to use } -// Result of EstimateTxSize +/** + * Response: Estimated size of the transaction + * @prev EstimateTxSize + */ 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 -// -// Response: TxRequest, PinMatrixRequest, Failure +/** + * Request: Ask device to sign transaction + * @next PinMatrixRequest + * @next TxRequest + * @next 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 string 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 + required uint32 outputs_count = 1; // number of transaction outputs + required uint32 inputs_count = 2; // number of transaction inputs + optional string coin_name = 3 [default='Bitcoin']; // coin to use +} + +/** + * Request: Simplified transaction signing + * This method doesn't support streaming, so there are hardware limits in number of inputs and outputs. + * In case of success, the result is returned using TxRequest message. + * @next PinMatrixRequest + * @next TxRequest + * @next Failure + */ message SimpleSignTx { - repeated TxInputType inputs = 1; - repeated TxOutputType outputs = 2; - repeated TransactionType transactions = 3; - optional string 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. + repeated TxInputType inputs = 1; // transaction inputs + repeated TxOutputType outputs = 2; // transaction outputs + repeated TransactionType transactions = 3; // transactions whose outputs are used to build current inputs + optional string coin_name = 4 [default='Bitcoin']; // coin to use +} + +/** + * Response: Device asks for information for signing transaction or returns the last result + * If request_index is set, device awaits TxAck message (with fields filled in according to request_type) + * If signature_index is set, 'signature' contains signed input of signature_index's input + * @prev SignTx + * @prev SimpleSignTx + * @prev TxAck + */ 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; // If signed_index>=0, represent signature of the signed_index input - optional bytes serialized_tx = 5; // 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 -// - + optional uint32 request_index = 1; // device expects TxAck message from the computer + optional RequestType request_type = 2; // what should be filled in TxAck message? + optional uint32 signature_index = 3; // 'signature' field contains signed input of this index + optional bytes signature = 4; // signature of the signature_index input + 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? +} + +/** + * Request: Reported transaction data + * @prev TxRequest + * @next TxRequest + */ +message TxAck { + optional TransactionType tx = 1; +} + +///////////////////////// +// Bootloader messages // +///////////////////////// + +/** + * Request: Ask device to erase its firmware + * @next Success + * @next Failure + */ message FirmwareErase { } +/** + * Request: Send firmware in binary form to the device + * @next Success + * @next Failure + */ message FirmwareUpload { - required bytes payload = 1; // Firmware to flash into device + required bytes payload = 1; // firmware to be loaded into device } -// **************************************************************************** -// -// Debug* messages are used only on DebugLink interface (separated from USB HID) -// +///////////////////////////////////////////////////////////// +// Debug messages (only available if DebugLink is enabled) // +///////////////////////////////////////////////////////////// -// Virtually "press" the button on the device. -// Message is available only on debugging connection and device must support "debug_link" feature. -// -// Response: Success +/** + * Request: "Press" the button on the device + * @next Success + */ 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. -// -// Response: DebugLinkState +/** + * Request: Computer asks for device state + * @next DebugLinkState + */ 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 { - optional bytes layout = 1; // Raw buffer of display - optional string pin = 2; // Current PIN, blank if PIN is not set/enabled - optional string matrix = 3; // Current PIN matrix - optional string mnemonic = 4; // Current mnemonic format - optional HDNodeType node = 5; // Current node (BIP32 format) - optional bool passphrase_protection = 6; // Is passphrase_protection set? - optional string reset_word = 7; // Word on display during ResetDevice workflow - optional bytes reset_entropy = 8; // Current entropy of ResetDevice 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 -} - -// Ask device to shutdown/restart + optional bytes layout = 1; // raw buffer of display + optional string pin = 2; // current PIN, blank if PIN is not set/enabled + optional string matrix = 3; // current PIN matrix + optional string mnemonic = 4; // current BIP-39 mnemonic + optional HDNodeType node = 5; // current BIP-32 node + optional bool passphrase_protection = 6; // is node/mnemonic encrypted using passphrase? + optional string reset_word = 7; // word on device display during 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 uint32 recovery_word_pos = 10; // index of mnemonic word the device is expecting during RecoveryDevice workflow +} + +/** + * Request: Ask device to restart + */ message DebugLinkStop { } +/** + * Response: Device wants host to log event + */ message DebugLinkLog { optional uint32 level = 1; optional string bucket = 2; diff --git a/protob/storage.proto b/protob/storage.proto index 7de4a3426..2b37ea1e2 100644 --- a/protob/storage.proto +++ b/protob/storage.proto @@ -1,24 +1,26 @@ -/* - Structure of Storage area of TREZOR +/** + * Storage area of TREZOR + * + * @author Marek Palatinus + * @version 1 + */ - Author: Marek Palatinus - - Version: 0.1 -*/ - -// Some sugar for easier handling in Multibit +// Sugar for easier handling in Multibit option java_package = "org.multibit.hd.hardware.trezor.protobuf"; option java_outer_classname = "TrezorStorage"; import "types.proto"; +/** + * Internal persistent storage of device + */ message Storage { - required uint32 version = 1; - optional HDNodeType node = 2; - optional string mnemonic = 3; - optional bool passphrase_protection = 4; // whether node_serialized or mnemonic are encrypted (protected by passphrase) - optional uint32 pin_failed_attempts = 5; - optional string pin = 6; - optional string language = 7; - optional string label = 8; + required uint32 version = 1; // version of storage + optional HDNodeType node = 2; // BIP-32 node (mnemonic cannot be used if this is present) + optional string mnemonic = 3; // BIP-39 mnemonic (node cannot be used if this is present) + optional bool passphrase_protection = 4; // whether to require passphrase to decrypt node or stretch mnemonic + optional uint32 pin_failed_attempts = 5; // number of failed PIN attempts + optional string pin = 6; // current PIN + optional string language = 7; // current language + optional string label = 8; // device label } diff --git a/protob/types.proto b/protob/types.proto index 7739e9319..450633dc7 100644 --- a/protob/types.proto +++ b/protob/types.proto @@ -1,24 +1,30 @@ -/* - Types for TREZOR communication - - Author: Marek Palatinus - - Version: 0.6 -*/ - -// Some sugar for easier handling in Multibit +/** + * Types for TREZOR communication + * + * @author Marek Palatinus + * @version 0.6 + */ + +// Sugar for easier handling in Multibit option java_package = "org.multibit.hd.hardware.trezor.protobuf"; option java_outer_classname = "TrezorType"; import "google/protobuf/descriptor.proto"; +/** + * Options for specifying message direction and type of wire (normal/debug) + */ extend google.protobuf.EnumValueOptions { - 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_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_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 } +/** + * Type of failures returned by Failure message + * @used_in Failure + */ enum FailureType { Failure_UnexpectedMessage = 1; Failure_ButtonExpected = 2; @@ -34,18 +40,29 @@ enum FailureType { 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 { PAYTOADDRESS = 0; 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 { TXINPUT = 0; TXOUTPUT = 1; + TXMETA = 2; } +/** + * Type of button request + * @used_in ButtonRequest + */ enum ButtonRequestType { ButtonRequest_Other = 1; ButtonRequest_FeeOverThreshold = 2; @@ -57,14 +74,24 @@ enum ButtonRequestType { ButtonRequest_SignTx = 8; } +/** + * Type of PIN request + * @used_in PinMatrixRequest + */ enum PinMatrixRequestType { PinMatrixRequestType_Current = 1; PinMatrixRequestType_NewFirst = 2; 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 { required uint32 depth = 1; required uint32 fingerprint = 2; @@ -74,6 +101,10 @@ message HDNodeType { optional bytes public_key = 6; } +/** + * Structure representing Coin + * @used_in Features + */ message CoinType { optional string coin_name = 1; optional string coin_shortcut = 2; @@ -81,33 +112,49 @@ message CoinType { optional uint64 maxfee_kb = 4; } +/** + * Structure representing transaction input + * @used_in SimpleSignTx + * @used_in TransactionType + */ message TxInputType { - repeated uint32 address_n = 1; // Parameter for address generation algorithm to derive the address from the master node - 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 - optional bytes script_sig = 4; // Script signature - optional uint32 sequence = 5 [default=0xffffffff]; + 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 uint32 prev_index = 3; // index of previous output to spend + optional bytes script_sig = 4; // script signature + optional uint32 sequence = 5 [default=0xffffffff]; // sequence } +/** + * Structure representing transaction output + * @used_in SimpleSignTx + * @used_in TransactionType + */ message TxOutputType { - optional string address = 1; // Target bitcoin address in base58 encoding - repeated uint32 address_n = 2; // Has higher priority than "address". - required uint64 amount = 3; // Amount to send in satoshis - required ScriptType script_type = 4; // Select output script type - repeated bytes script_args = 5; // Provide additional parameters for the script (its script-depended) + optional string address = 1; // target coin address in Base58 encoding + 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 spend in satoshis + required ScriptType script_type = 4; // output script type + 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 -// and for compiling TxOutput for signing. +/** + * Structure representing compiled transaction output + * @used_in TransactionType + */ message TxOutputBinType { required uint64 amount = 1; required bytes script_pubkey = 2; } +/** + * Structure representing transaction + * @used_in SimpleSignTx + */ message TransactionType { - optional uint32 version = 1 [default=1]; + optional uint32 version = 1; repeated TxInputType inputs = 2; repeated TxOutputBinType outputs = 3; - optional uint32 lock_time = 4 [default=0]; + repeated TxOutputType our_outputs = 4; + optional uint32 lock_time = 5; } diff --git a/signer/config.json b/signer/config.json index b00d0fe54..4f649184b 100644 --- a/signer/config.json +++ b/signer/config.json @@ -9,7 +9,7 @@ ], "known_devices": [ ["0x534c", "0x0001", "Trezor"], - ["0x10c4", "0xea80", "Trezor Shield"] + ["0x10c4", "0xea80", "Trezor Shield"] ], "valid_days": 15 }